z/OS

DFSORT Application Programming Guide

SC26-7523-03

z/OS

DFSORT Application Programming Guide

SC26-7523-03

Note Before using this information and the product it supports, be sure to read the general information under Notices on page 793.

Fourth Edition, September 2008

| This edition applies to Version 1 Release 10 of z/OS (5694-A01) and to all subsequent releases and modifications | until otherwise indicated in new editions. | This edition replaces SC26752302.
IBM welcomes your comments. A form for readers comments may be provided at the back of this publication, or you may address your comments to the following address: International Business Machines Corporation Department 55JA, Mail Station P384 2455 South Road Poughkeepsie, NY 12601-5400 United States of America FAX (United States & Canada): 1+845+432-9405 FAX (Other Countries): Your International Access Code +1+845+432-9405 IBMLink (United States customers only): IBMUSM10(MHVRCFS) Internet e-mail: [email protected] World Wide Web: http://www.ibm.com/servers/eserver/zseries/zos/webqs.html If you would like a reply, be sure to include your name, address, telephone number, or FAX number. Make sure to include the following in your comment or note: v Title and order number of this document v Page number or topic related to your comment When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. Copyright International Business Machines Corporation 1973, 2006. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents
Figures . . . . . . . . . . . . . . . ix Tables . . . . . . . . . . . . . . . xi About this document . . . . . . . . xiii
How to use this document . . . . . . . . . xiii Required product knowledge . . . . . . . . xiv Referenced documents . . . . . . . . . . xiv Accessing z/OS DFSORT documents on the Internet xv Using LookAt to look up message explanations . . xv Notational conventions . . . . . . . . . . xvi Using the JOB Statement . . . . . . . . . . Using the EXEC Statement . . . . . . . . . Specifying EXEC Statement Cataloged Procedures Specifying EXEC/DFSPARM PARM Options . . Aliases for PARM Options . . . . . . . . Using DD Statements . . . . . . . . . . . Duplicate Ddnames. . . . . . . . . . . Shared Tape Units . . . . . . . . . . . System DD Statements . . . . . . . . . Program DD Statements . . . . . . . . . 27 27 27 29 60 61 64 64 64 66

Summary of Changes . . . . . . . . xix

| Summary of Changes for SC26-7523-03 z/OS | Version 1 Release 10 . . . . . . . . . . . xix New Information . . . . . . . . . . . xix | Operational Changes that may Require User | Action . . . . . . . . . . . . . . . xx |
Summary of Changes for SC26-7523-02 z/OS Version 1 Release 8 (PTFs - April, 2006) . . . . New Information . . . . . . . . . . Operational Changes that may Require User Action . . . . . . . . . . . . . Summary of Changes for SC26-7523-01 z/OS Version 1 Release 6 (PTFs - December, 2004) . . New Information . . . . . . . . . . Operational Changes that may Require User Action . . . . . . . . . . . . . . . xxi . xxi . xxvi . xxvi . xxvi . xxx

Chapter 3. Using DFSORT Program Control Statements . . . . . . . . . 81

Using Program Control Statements . . . . . . 82 Control Statement Summary . . . . . . . . . 83 Describing the Primary Task . . . . . . . . 83 Including or Omitting Records . . . . . . . 83 Reformatting and Editing Records . . . . . . 83 Producing Multiple Output and Reports and Converting Records. . . . . . . . . . . 84 Invoking Additional Functions and Options . . 84 Using Symbols . . . . . . . . . . . . 84 General Coding Rules . . . . . . . . . . . 84 Continuation Lines . . . . . . . . . . . 86 Inserting Comment Statements . . . . . . . 88 Coding Restrictions . . . . . . . . . . . 89 ALTSEQ Control Statement . . . . . . . . . 89 Altering EBCDIC Collating SequenceExamples 90 DEBUG Control Statement . . . . . . . . . 92 Specifying Diagnostic OptionsExamples . . . 97 END Control Statement . . . . . . . . . . 97 Discontinue Reading Control StatementsExamples . . . . . . . . . . 97 INCLUDE Control Statement . . . . . . . . 98 Relational Condition . . . . . . . . . . 101 Comparisons . . . . . . . . . . . . 101 Including Records in the Output Data SetComparison Examples. . . . . . . . 110 Substring Comparison Tests . . . . . . . 112 Including Records in the Output Data SetSubstring Comparison Example . . . . 114 Bit Logic Tests . . . . . . . . . . . . 114 Method 1: Bit Operator Tests . . . . . . . 114 Padding and Truncation . . . . . . . . . 116 Including Records in the Output Data SetBit Operator Test Examples . . . . . . . . . 116 Method 2: Bit Comparison Tests . . . . . . 117 Including Records in the Output Data SetBit Comparison Test Examples . . . . . . . . 118 Date Comparisons . . . . . . . . . . . 119 Including Records in the Output Data SetDate Comparisons . . . . . . . . . . . . 122 Numeric Tests . . . . . . . . . . . . 122 Including Records in the Output Data Set--Numeric Tests . . . . . . . . . . 124

Chapter 1. Introducing DFSORT . . . . 1

DFSORT Overview . . . . . . . . . . DFSORT on the Web . . . . . . . . . . DFSORT FTP Site . . . . . . . . . . . Invoking DFSORT . . . . . . . . . . How DFSORT Works . . . . . . . . . Operating Systems . . . . . . . . . Control Fields and Collating Sequences . . Cultural Environment Considerations . . . DFSORT Processing . . . . . . . . . Input Data SetsSORTIN and SORTINnn . . Output Data SetsSORTOUT and OUTFIL . . Data Set Considerations . . . . . . . . Sorting or Copying Records . . . . . . Merging Records . . . . . . . . . Data Set Notes and Limitations . . . . . HFS File Considerations . . . . . . . . Installation Defaults . . . . . . . . . Migrating to DFSORT from Other Sort Products DFSORT Messages and Return Codes . . . Use Blockset Whenever Possible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 4 4 4 5 5 5 7 7 11 12 12 12 13 13 16 16 22 22 23

Chapter 2. Invoking DFSORT with Job Control Language . . . . . . . . . . 25

Using the JCL . . . . . . . . . . . . . 25

Copyright IBM Corp. 1973, 2006

iii

INCLUDE/OMIT Statement Notes . . . INREC Control Statement . . . . . . . INREC Statement Notes . . . . . . . Reformatting Records Before Processing Examples . . . . . . . . . . . . MERGE Control Statement . . . . . . . Specifying a MERGE or COPYExamples MODS Control Statement . . . . . . . Identifying User Exit RoutinesExamples . OMIT Control Statement . . . . . . . Omitting Records from the Output Data SetExample . . . . . . . . . . OPTION Control Statement . . . . . . Aliases for OPTION Statement Options. . Specifying DFSORT Options or COPYExamples . . . . . . . . . OUTFIL Control Statements . . . . . . OUTFIL Statements Notes . . . . . . OUTFIL FeaturesExamples . . . . . OUTREC Control Statement . . . . . . OUTREC Statement Notes . . . . . . Reformatting Records After Processing Examples . . . . . . . . . . . . RECORD Control Statement . . . . . . Describing the Record Format and LengthExamples . . . . . . . . SORT Control Statement . . . . . . . . SORT/MERGE Statement Notes . . . . Specifying a SORT or COPYExamples . SUM Control Statement . . . . . . . . SUM Statement Notes . . . . . . . Adding Summary FieldsExamples . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. 124 . 125 . 147 . . . . . . 149 156 159 160 163 163

. 166 . 167 . 216 . . . . . . 217 221 340 344 365 386

. 387 . 394 . . . . . . . 397 398 406 406 408 410 411

Chapter 4. Using Your Own User Exit Routines . . . . . . . . . . . . . 413

User Exit Routine Overview . . . . . . . DFSORT Program Phases . . . . . . . . Functions of Routines at User Exits . . . . . DFSORT Input/User Exit/Output Logic Examples . . . . . . . . . . . . . Opening and Initializing Data Sets . . . . Modifying Control Fields . . . . . . . Inserting, Deleting, and Altering Records . . Summing Records . . . . . . . . . . Handling Special I/O . . . . . . . . VSAM User Exit Functions . . . . . . . Determining Action when Intermediate Storage Is Insufficient . . . . . . . . . . . Closing Data Sets . . . . . . . . . . Terminating DFSORT . . . . . . . . . Addressing and Residence Modes for User Exits How User Exit Routines Affect DFSORT Performance . . . . . . . . . . . . . Summary of Rules for User Exit Routines . . . Loading User Exit Routines . . . . . . User Exit Linkage Conventions . . . . . Dynamically Link-Editing User Exit Routines Assembler User Exit Routines (Input Phase User Exits) . . . . . . . . . . . . . . . E11 User Exit: Opening Data Sets/Initializing Routines . . . . . . . . . . . . . . 413 . 414 . 416 . . . . . . . 416 417 418 418 418 418 419

E15 User Exit: Passing or Changing Records for Sort and Copy Applications . . . . . . . E16 User Exit: Handling Intermediate Storage Miscalculation . . . . . . . . . . . . E17 User Exit: Closing Data Sets . . . . . . E18 User Exit: Handling Input Data Sets . . . E19 User Exit: Handling Output to Work Data Sets . . . . . . . . . . . . . . . E61 User Exit: Modifying Control Fields . . . Assembler User Exit Routines (Output Phase User Exits) . . . . . . . . . . . . . . . . E31 User Exit: Opening Data Sets/Initializing Routines . . . . . . . . . . . . . . E32 User Exit: Handling Input to a Merge Only E35 User Exit: Changing Records . . . . . . E37 User Exit: Closing Data Sets . . . . . . E38 User Exit: Handling Input Data Sets . . . E39 User Exit: Handling Output Data Sets . . . Sample Routines Written in Assembler . . . . . E15 User Exit: Altering Record Length . . . . E16 User Exit: Sorting Current Records When NMAX Is Exceeded . . . . . . . . . . E35 User Exit: Altering Record Length . . . . E61 User Exit: Altering Control Fields . . . . COBOL User Exit Routines . . . . . . . . . COBOL User Exit Requirements . . . . . . COBOL User Exit Routines (Input Phase User Exit) COBOL E15 User Exit: Passing or Changing Records for Sort . . . . . . . . . . . COBOL User Exit Routines (Output Phase User Exit) . . . . . . . . . . . . . . . . COBOL E35 User Exit: Changing Records . . . Sample Routines Written in COBOL . . . . . . COBOL E15 User Exit: Altering Records . . . COBOL E35 User Exit: Inserting Records . . . E15/E35 Return Codes and EXITCK . . . . . .

424 427 427 427 431 432 433 434 434 435 438 439 439 440 440 441 441 442 443 443 445 445 451 451 456 456 457 458

Chapter 5. Invoking DFSORT from a Program . . . . . . . . . . . . . 461

Invoking DFSORT Dynamically . . . . . . What Are System Macro Instructions? . . . . Using System Macro Instructions . . . . . . Using JCL DD Statements . . . . . . . . Overriding DFSORT Control Statements from Programs . . . . . . . . . . . . . . Invoking DFSORT With the 24-Bit Parameter List Providing Program Control Statements . . . Invoking DFSORT With The Extended Parameter List . . . . . . . . . . . . . . . . Providing Program Control Statements . . . Writing the Macro Instruction . . . . . . . Parameter List Examples . . . . . . . Restrictions for Dynamic Invocation . . . . . Merge Restriction . . . . . . . . . . Copy Restrictions . . . . . . . . . . . . . . 461 461 461 462

. 462 463 . 463 . . . . . . . 470 470 473 473 477 477 477

. 419 . 419 . 419 419 . . . . 420 420 421 421 423

Chapter 6. Using ICETOOL. . . . . . 479

Overview. . . . . . . . . . ICETOOL/DFSORT Relationship . ICETOOL JCL Summary . . . . . . . . . . . . . . . . . 480 . 480 . 481

. 423 . 423

iv

z/OS V1R10.0 DFSORT Application Programming Guide

ICETOOL Operator Summary . . Complete ICETOOL Examples . . Using Symbols . . . . . . . Invoking ICETOOL . . . . . Putting ICETOOL to Use . . . Job Control Language for ICETOOL . JCL Restrictions . . . . . . ICETOOL Statements . . . . . . General Coding Rules . . . . COPY Operator . . . . . . . Operand Descriptions . . . . COPY Examples . . . . . . COUNT Operator . . . . . . . Operand Descriptions . . . . COUNT Examples . . . . . . DEFAULTS Operator . . . . . . Operand Descriptions . . . . DEFAULTS Example . . . . . DISPLAY Operator . . . . . . Simple Report . . . . . . . Tailored Report . . . . . . . Sectioned Report . . . . . . Operand Descriptions . . . . DISPLAY Examples . . . . . MODE Operator . . . . . . . Operand Descriptions . . . . MODE Example . . . . . . OCCUR Operator . . . . . . . Simple Report . . . . . . . Tailored Report . . . . . . . Operand Descriptions . . . . OCCUR Examples . . . . . . RANGE Operator . . . . . . . Operand Descriptions . . . . RANGE Example . . . . . . SELECT Operator . . . . . . . Operand Descriptions . . . . SELECT Examples . . . . . . SORT Operator . . . . . . . . Operand Descriptions . . . . SORT Examples . . . . . . SPLICE Operator . . . . . . . Operand Descriptions . . . . SPLICE Examples . . . . . . STATS Operator . . . . . . . Operand Descriptions . . . . STATS Example . . . . . . UNIQUE Operator . . . . . . Operand Descriptions . . . . UNIQUE Example . . . . . . VERIFY Operator . . . . . . . Operand Descriptions . . . . VERIFY Example . . . . . . Calling ICETOOL from a Program . TOOLIN Interface . . . . . . Parameter List Interface . . . . ICETOOL Notes and Restrictions . . ICETOOL Return Codes . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

481 482 483 483 484 487 489 490 490 491 491 493 494 495 497 497 498 499 502 503 504 505 505 531 546 547 547 548 549 550 551 560 563 564 565 566 568 571 575 575 577 579 584 587 603 603 604 605 605 606 607 607 608 609 609 609 615 616

Field and Constant Symbols Overview . . . . DFSORT Example . . . . . . . . . . SYMNAMES DD Statement . . . . . . . SYMNOUT DD Statement . . . . . . . . SYMNAMES Statements . . . . . . . . . Comment and Blank Statements . . . . . Symbol Statements . . . . . . . . . Keyword Statements . . . . . . . . . Using SYMNOUT to Check Your SYMNAMES Statements . . . . . . . . . . . . Using Symbols in DFSORT Statements . . . . SORT and MERGE . . . . . . . . . SUM . . . . . . . . . . . . . . INCLUDE and OMIT . . . . . . . . . INREC and OUTREC . . . . . . . . . OUTFIL . . . . . . . . . . . . . Using Symbols in ICETOOL Operators . . . . COUNT . . . . . . . . . . . . . DISPLAY . . . . . . . . . . . . . OCCUR . . . . . . . . . . . . . RANGE . . . . . . . . . . . . . SELECT . . . . . . . . . . . . . SPLICE . . . . . . . . . . . . . STATS, UNIQUE and VERIFY . . . . . . ICETOOL Example . . . . . . . . . Notes for Symbols . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . .

617 618 620 620 620 620 621 630 633 633 634 635 635 636 638 641 641 641 642 642 642 642 642 642 644

Chapter 8. Using Extended Function Support . . . . . . . . . . . . . . 647

Using EFS . . . . . . . . . . . . . . Addressing and Residence Mode of the EFS Program . . . . . . . . . . . . . . . How EFS Works . . . . . . . . . . . . DFSORT Program Phases . . . . . . . . DFSORT Calls to Your EFS Program . . . . . What You Can Do with EFS . . . . . . . . Opening and Initializing Data Sets . . . . . Examining, Altering, or Ignoring Control Statements . . . . . . . . . . . . . Processing User-Defined Data Types with EFS Program User Exit Routines . . . . . . . Supplying Messages for Printing to the Message Data Set . . . . . . . . . . . . . . Terminating DFSORT . . . . . . . . . . Closing Data Sets and Housekeeping . . . . Structure of the EFS Interface Parameter List . . . Action Codes . . . . . . . . . . . . Control Statement Request List . . . . . . Control Statement String Sent to the EFS program . . . . . . . . . . . . . . Control Statement String Returned by the EFS Program . . . . . . . . . . . . . . EFS Formats for SORT, MERGE, INCLUDE, and OMIT Control Statements . . . . . . . . D1 Format on FIELDS Operand . . . . . . D2 Format on COND Operand . . . . . . Length of Original Control Statement . . . . Length of the Altered Control Statement . . . EFS Program Context Area . . . . . . . . Extract Buffer Offsets List . . . . . . . . Record Lengths List . . . . . . . . . .
Contents

647 648 648 649 649 654 655 655 657 657 657 657 657 659 660 660 662 663 663 664 666 666 666 666 666

Chapter 7. Using Symbols for Fields and Constants . . . . . . . . . . . 617

Information Flags . . . . . . . . . Message List . . . . . . . . . . EFS Program Exit Routines . . . . . . . EFS01 and EFS02 Function Description . . EFS01 User Exit Routine . . . . . . . EFS02 User Exit Routine . . . . . . . Addressing and Residence Mode of EFS Program User Exit Routines . . . . . EFS Program Return Codes You Must Supply Record Processing Order . . . . . . . How to Request a SNAP Dump . . . . . EFS Program Example . . . . . . . . DFSORT Initialization Phase: . . . . . DFSORT Termination Phase . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

667 668 669 669 670 671 673 674 674 676 677 677 679

Chapter 9. Improving Efficiency . . . 681

Improving Performance . . . . . . . . . . Design Your Applications to Maximize Performance . . . . . . . . . . . . . . Directly Invoke DFSORT Processing . . . . . Plan Ahead When Designing New Applications Specify Efficient Sort/Merge Techniques . . . Specify Input/Output Data Set Characteristics Accurately . . . . . . . . . . . . . Use Extended Format Data Sets . . . . . . Use DFSMSrmm-Managed Tapes, or ICETPEX Specify Devices that Improve Elapsed Time . . Use Options that Enhance Performance . . . . Use DFSORTs Fast, Efficient Productivity Features . . . . . . . . . . . . . . Avoid Options that Degrade Performance . . . Use Main Storage Efficiently . . . . . . . Allocate Temporary Work Space Efficiently . . Use Hipersorting . . . . . . . . . . . Sort with Data Space . . . . . . . . . . Use Memory Object Sorting . . . . . . . Use ICEGENER Instead of IEBGENER . . . . ICEGENER Return Codes . . . . . . . . Use DFSORTs Performance Booster for The SAS System . . . . . . . . . . . . . . . Use DFSORTs BLDINDEX Support . . . . . . 681 682 682 682 683 683 684 685 685 685 687 688 689 692 694 694 695 696 699 699 699

Example 7. Sort with COBOL E15, EXEC PARM and MSGDDN . . . . . . . . . . . . Example 8. Sort with Dynamic Link-Editing of Exits . . . . . . . . . . . . . . . Example 9. Sort with the Extended Parameter List Interface . . . . . . . . . . . . Example 10. Sort with OUTFIL . . . . . . Example 11. Sort with Pipes and OUTFIL SPLIT Example 12. Sort with INCLUDE and LOCALE Example 13: Sort with HFS Files . . . . . . Example 14. Sort with IFTHEN . . . . . . Merge Examples . . . . . . . . . . . . Example 1. Merge with EQUALS . . . . . . Example 2. Merge with LOCALE and OUTFIL Copy Examples . . . . . . . . . . . . . Example 1. Copy with EXEC PARMs, SKIPREC, MSGPRT and ABEND . . . . . . . . . Example 2. Copy with INCLUDE and VLSHRT Example 3. Copy with OUTREC, PARSE and BUILD . . . . . . . . . . . . . . ICEGENER Example . . . . . . . . . . . ICETOOL Example . . . . . . . . . . .

710 712 713 716 718 718 719 720 722 722 723 724 725 726 726 728 729

Appendix A. Using Work Space

. . . 731
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731 731 732 732 732 732 733 734 735 736 737 737 738 738

Introduction . . . . . . . . . . . Hiperspace . . . . . . . . . . . Work Data Set Devices . . . . . . . Disk and Tape Devices . . . . . . Number of Devices . . . . . . . Non-Synchronous Storage Subsystems . Allocation of Work Data Sets . . . . . Dynamic Allocation of Work Data Sets . Dynamic Over-Allocation of Work Space JCL Allocation of Work Data Sets . . . Disk Capacity Considerations . . . . . Exceeding Disk Work Space Capacity . Tape Capacity Considerations . . . . . Exceeding Tape Work Space Capacity .

Appendix B. Specification/Override of DFSORT Options . . . . . . . . . . 741

Main Features of Sources of DFSORT Options DFSPARM Data Set . . . . . . . . EXEC Statement PARM Options . . . . SORTCNTL Data Set . . . . . . . . SYSIN Data Set . . . . . . . . . . Parameter Lists . . . . . . . . . . Override Tables . . . . . . . . . Directly Invoked DFSORT . . . . . . . Notes to Directly Invoked DFSORT Table . Program Invoked DFSORT with the Extended Parameter List . . . . . . . . . . . Notes to Extended Parameter List Table . Program Invoked DFSORT with the 24-Bit Parameter List . . . . . . . . . . . Notes to 24-Bit List Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742 742 742 743 743 743 743 744 752

Chapter 10. Examples of DFSORT Job Streams . . . . . . . . . . . . . . 701

Summary of Examples . . . . . . . . . Storage Administrator Examples . . . . . . REXX Examples . . . . . . . . . . . CLIST Examples . . . . . . . . . . . Sort Examples . . . . . . . . . . . . Example 1. Sort with ALTSEQ . . . . . . Example 2. Sort with OMIT, SUM, OUTREC, DYNALLOC and ZDPRINT . . . . . . Example 3. Sort with ISCII/ASCII Tapes . . Example 4. Sort with E15, E35, FILSZ, AVGRLEN and DYNALLOC . . . . . . Example 5. Called sort with SORTCNTL, CHALT, DYNALLOC and FILSZ . . . . . Example 6. Sort with VSAM Input/Output, DFSPARM and Option Override . . . . . . . . . . . 701 702 702 703 703 703

. 704 . 705 . 706 . 707 . 709

. 752 . 760 . 760 . 768

Appendix C. Data Format Descriptions 769

DFSORT Data Formats . . . . . . . . . . 769

| Where DFSORT Formats Can be Used . . . . . 776

vi

z/OS V1R10.0 DFSORT Application Programming Guide

DFSORT Formats for COBOL Data Types .

. 778

Processing of Error Abends with A-Type Messages 789 CTRx Abend processing . . . . . . . . . . 789

Appendix D. EBCDIC and ISCII/ASCII Collating Sequences . . . . . . . . 781

EBCDIC . . ISCII/ASCII . . . . . . . . . . . . . . . . . . . . . . . . . . 781 . 783

Appendix F. Accessibility . . . . . . 791

Using assistive technologies . . . . . Keyboard navigation of the user interface . z/OS information . . . . . . . . . . . . . . . . 791 . 791 . 791

Appendix E. DFSORT Abend Processing . . . . . . . . . . . . 787

Checkpoint/Restart . . . . DFSORT Abend Categories . . Abend Recovery Processing for Abends . . . . . . . . . . . . . . . . . . Unexpected . . . . . . . . . 787 . 788 . 788

Notices . . . . . . . . . . . . . . 793
Programming Interface Information . Trademarks . . . . . . . . . . . . . . . . . . 794 . 794

Index . . . . . . . . . . . . . . . 795

Contents

vii

viii

z/OS V1R10.0 DFSORT Application Programming Guide

Figures
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. Control Fields . . . . . . . . . . . . 6 Record Processing Order . . . . . . . . 9 Using ICETOOL to List Installation Defaults 18 Syntax Diagram for EXEC PARM . . . . . 31 Aliases for MSGPRT/MSGCON Options 46 Control Statement Format . . . . . . . . 85 Continuation Line Format . . . . . . . . 87 Valid and Invalid Decimal Constants 105 Valid and Invalid Character String Constants 107 Valid and Invalid Hexadecimal Constants 109 Sample Records . . . . . . . . . . . 112 Syntax Diagram for the Option Control Statement . . . . . . . . . . . . . 167 OUTFIL Processing Order . . . . . . . 226 Examples of Notation for Binary Fields 400 Examples of DFSORT Input/User Exit/Output Logic . . . . . . . . . . 415 E18 User Exit Example . . . . . . . . 431 E38 User Exit Example . . . . . . . . 439 E39 User Exit Example . . . . . . . . 440 E15 User Exit Example . . . . . . . . 441 E16 User Exit Example . . . . . . . . 441 E35 User Exit Example . . . . . . . . 442 E61 User Exit Example . . . . . . . . 443 E15 DFSORT Interface with COBOL . . . . 447 LINKAGE SECTION Code Example for E15 (Fixed-Length Records) . . . . . . . . 448 LINKAGE SECTION Code Example for E15 (Variable-Length Record) . . . . . . . . 448 E35 Interface with COBOL . . . . . . . 452 LINKAGE SECTION Code Example for E35 (Fixed-Length Records) . . . . . . . . 453 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. LINKAGE SECTION Code Example for E35 (Variable-Length Records) . . . . . . . COBOL E15 Routine Example (FLR) . . . . COBOL E35 Routine Example (VLR) The 24-Bit Parameter List . . . . . . . The Extended Parameter List . . . . . . Specifying the Main Storage Option (24-Bit Parameter List) . . . . . . . . . . . Specifying E32 and ESTAE Routine (24-Bit Parameter List) . . . . . . . . . . . The 24-Bit Parameter List in Main Storage Coding a 24-Bit Parameter List . . . . . . Coding an Extended Parameter List . . . . Simple ICETOOL Job . . . . . . . . . Parameter List for Parameter List Interface ICETOOL Parameter List Interface Example JCL for Parameter List Interface Program Example . . . . . . . . . . . . . Relationship Between DFSORT and an EFS Program . . . . . . . . . . . . . EFS Program Calls for a Sort . . . . . . EFS Program Calls for a Merge or Copy Control Statement Processing Sequence EFS Interface Parameter List . . . . . . Information Flags . . . . . . . . . . DFSORT Register Convention . . . . . . Calling Sequence to EFS02 by DFSORT EFS Record Processing Sequence for a Sort or Merge . . . . . . . . . . . . . . EFS Record Processing Sequence for a Copy Faster Sorting with COBOL . . . . . . . 453 457 458 465 471 474 474 475 476 477 483 610 613 615 649 650 651 656 658 667 670 672 675 676 686

Copyright IBM Corp. 1973, 2006

ix

z/OS V1R10.0 DFSORT Application Programming Guide

Tables
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. Related documents . . . . . . . . . Referenced documents . . . . . . . Options That Can Ease Migration . . . . FILSZ Variations Summary . . . . . . Aliases for PARM Options . . . . . . DD Statement Parameters Used by DFSORT DCB Subparameters Used by DFSORT . . Compare Field Formats and Lengths Permissable Field-to-Field Comparisons for INCLUDE/OMIT (Group 1) . . . . . Permissable Field-to-Field Comparisons for INCLUDE/OMIT (Group 2) . . . . . Permissible Field-to-Constant Comparisons for INCLUDE/OMIT . . . . . . . . Decimal Numbers for Current Date . . . Decimal Numbers for Future Dates . . . Decimal Numbers for Past Dates . . . . Valid and Invalid Strings with Double-Byte Data . . . . . . . . . . . . . Character Strings for Current Date . . . Character Strings for Future Dates . . . Character Strings for Past Dates . . . . Bit Comparison Example 2: Results for Selected Field Values . . . . . . . . Bit Comparison Example 3: Results for Selected Field Values . . . . . . . . Bit Comparison Example 2: Results for Selected Field Values . . . . . . . . Bit Comparison Example 3: Results for Selected Field Values . . . . . . . . Permissible Comparisons for Dates . . . Logic Table for INCLUDE/OMIT. . . . . Examples of Valid and Invalid Column Alignment . . . . . . . . . . . Examples of Valid and Invalid Blank Separation . . . . . . . . . . . Examples of Valid and Invalid Binary Zero Separation . . . . . . . . . . . Examples of Valid and Invalid Character String Separation . . . . . . . . . Examples of Valid and Invalid Hexadecimal String Separation . . . . . . . . . Example of DYNSPC Primary Space . . . FILSZ Variations Summary . . . . . . SIZE Variations Summary . . . . . . SDB=LARGE Block Sizes for Tape Output Data Sets . . . . . . . . . . . . Aliases for OPTION Statement Options Current date constants . . . . . . . Future Date Constants . . . . . . . Past Date Constants . . . . . . . . Current time constants . . . . . . . p,m,Y2x Output . . . . . . . . . . p,m,Y2x(c) Output . . . . . . . . . p,m,Y2xP Output . . . . . . . . . Edit Field Formats and Lengths . . . . . xiv . xiv . 22 . 41 . 61 62 . 63 102 . 103 52. . 103 . . . . . . . . 104 105 106 106 107 108 108 109 53. 54. 55. 56. 57. 58. 59. 60. . 116 61. . 117 62. . 118 . 119 . 121 . 125 . 130 . 131 . 131 . 131 . . . . 132 178 183 184 63. 64. 65. 66. 67. 68. 69. 70. 71. 72. 73. 74. 75. . 200 217 . 249 . 250 . 251 . 252 . 259 . 260 . 261 . 261 76. 77. 78. 79. 43. 44. 45. 46. 47. 48. 49. 50. 51. Edit Mask Patterns . . . . . . . . . . Edit Mask Signs . . . . . . . . . . Digits Needed for Numeric Fields . . . . Edit Mask Output Field Lengths . . . . . To Output Field Lengths . . . . . . . . Digits for TOTAL Fields . . . . . . . . Control Field Formats and Lengths . . . . Summary Field Formats and Lengths Functions of Routines at Program User Exits (Sort) . . . . . . . . . . . . . . Functions of Routines at Program User Exits (Copy and Merge) . . . . . . . . . . E15 User Exit Parameter List . . . . . . E32 User Exit Parameter List . . . . . . E35 User Exit Parameter List . . . . . . E15 Without a SORTIN Data Set . . . . . E15 With a SORTIN Data Set Before End of Input . . . . . . . . . . . . . . E15 With a SORTIN Data Set After End of Input . . . . . . . . . . . . . . E35 With a SORTOUT or OUTFIL Data Set Before End of Input . . . . . . . . . E35 Without a SORTOUT or OUTFIL Data Set Before End of Input . . . . . . . . . E35 With a SORTOUT or OUTFIL Data Set After End of Input . . . . . . . . . . E35 without a SORTOUT or OUTFIL Data Set After End of Input . . . . . . . . . . Aliases for Message Option . . . . . . . Obtaining Various Statistics . . . . . . . Creating Multiple Versions/Combinations of Data Sets . . . . . . . . . . . . . JCL Statements for ICETOOL . . . . . . Attributes of Edit Masks . . . . . . . . Edit Mask Patterns . . . . . . . . . . Return Area Lengths/Operation-Specific Values . . . . . . . . . . . . . . Functions of an Extended Function Support (EFS) Program . . . . . . . . . . . D1 Format Returned by an EFS Program Correlator Identifier and D2 Format Returned by an EFS Program . . . . . . . . . Original and Altered Control Statements Number of Tracks per Cylinder for Disk Devices . . . . . . . . . . . . . Minimum Storage Required for Various File Sizes . . . . . . . . . . . . . . Work Space Requirements for Various Input Characteristics . . . . . . . . . . . Number of Tracks per Cylinder for Disk Devices . . . . . . . . . . . . . Work Space Requirements of the Various Tape Techniques . . . . . . . . . . . . Directly Invoked DFSORT Option Specification/Override . . . . . . . . 264 266 267 267 273 318 401 409 417 417 425 435 437 459 459 459 459 460 460 460 468 484 485 487 509 509 611 654 664 665 678 684 733 737 737 738 745

Copyright IBM Corp. 1973, 2006

xi

80. 81. 82.

Extended Parameter List DFSORT Option Specification/Override . . . . . . . 24-Bit List DFSORT Option Specification/Override . . . . . . . Allowed with Frequently Used Data Types

. 753 . 761 776

83. 84. 85. 86.

Allowed with Other Data Types . . . Equivalent DFSORT formats for various COBOL data types . . . . . . . . EBCDIC Collating Sequence . . . . ISCII/ASCII Collating Sequence . . .

. . . .

. 777 . 778 . 781 . 783

xii

z/OS V1R10.0 DFSORT Application Programming Guide

About this document

This document is intended to help you to sort, merge, and copy data sets using DFSORT. This document is not designed to teach you how to use DFSORT, but is for programmers who already have a basic understanding of DFSORT, and need a task-oriented guide and reference to its functions and options. If you are a new user, 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 to know to begin using DFSORT quickly, with step-by-step examples and illustrations.

How to use this document

The various sections of this document present related information grouped according to tasks you want to do. The first three chapters of the document explain what you need to know to invoke and use DFSORTs primary record-processing functions. The remaining chapters explain more specialized features. The appendixes 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 DFSORT processing. It describes how DFSORT works, discusses data set formats and limitations, and explains how installation defaults can affect your DFSORT applications. v Chapter 2, Invoking DFSORT with Job Control Language, on page 25, explains how to use job control language (JCL) to run your DFSORT jobs. It explains how to code JOB, EXEC, and DD statements, and how you can use cataloged procedures and EXEC PARM options to simplify your JCL and override installation defaults. v Chapter 3, Using DFSORT Program Control Statements, on page 81, presents the DFSORT control statements you use to sort, merge, and copy data. It explains 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 produce multiple output data sets and reports. It explains how to write statements that direct DFSORT to use your own routines during processing. v Chapter 4, Using Your Own User Exit Routines, on page 413, describes how to use DFSORTs program exits to call your own routines during program processing. You can write routines to delete, insert, alter, and summarize records, and you can incorporate your own error-recovery routines. v Chapter 5, Invoking DFSORT from a Program, on page 461, describes how you use a system macro instruction to initiate DFSORT processing from your own assembler program. It also lists specific restrictions on invoking DFSORT from PL/I and COBOL. v Chapter 6, Using ICETOOL, on page 479, describes how to use the multi-purpose DFSORT utility ICETOOL. It explains the JCL and operators you can use to perform a variety of tasks with ICETOOL. v Chapter 7, Using Symbols for Fields and Constants, on page 617, explains how to define symbols and use them in DFSORT control statements and ICETOOL operators. v Chapter 8, Using Extended Function Support, on page 647, explains how to use the Extended Function Support (EFS) interface to tailor control statements, to handle user-defined data types and collating sequences, and to have DFSORT issue customized informational messages during processing.
Copyright IBM Corp. 1973, 2006

| |

xiii

v Chapter 9, Improving Efficiency, on page 681, recommends ways with which you can maximize DFSORT processing efficiency. This chapter covers a wide spectrum of improvements you can make, from designing individual applications for efficient processing at your site to using DFSORT features such as Hipersorting, dataspace sorting, and ICEGENER. v Chapter 10, Examples of DFSORT Job Streams, on page 701, contains annotated example job streams for sorting, merging, and copying records. v Appendix A, Using Work Space, on page 731, explains main storage considerations and how to estimate the amount of intermediate storage you might require when sorting data. v Appendix B, Specification/Override of DFSORT Options, on page 741, contains a series of tables you can use to find the order of override for similar options that are specified in different sources. v Appendix C, Data Format Descriptions, on page 769, gives examples of the assembled data formats. v Appendix D, EBCDIC and ISCII/ASCII Collating Sequences, on page 781, lists the collating sequences from low to high order for EBCDIC and ISCII/ASCII characters. v Appendix E, DFSORT Abend Processing, on page 787, describes the ESTAE recovery routine for processing abends, and the Checkpoint/Restart facility. v Notices on page 793, includes the notices, Programming Interface information, and the trademark list.

Required product knowledge

To use this document effectively, you should be familiar with the following information: v Job control language (JCL) v Data management v Tape and disk hardware You should also be familiar with the information presented in the following related documents:
Table 1. Related documents Document Title z/OS DFSORT Messages, Codes and Diagnosis Guide z/OS MVS JCL Reference z/OS MVS JCL Users Guide z/OS DFSMS Using Data Sets z/OS DFSMS Using Magnetic Tapes Document Order Number SC26-7525 SA22-7597 SA22-7598 SC26-7410 SC26-7412

Referenced documents
This document refers to the following documents:
Table 2. Referenced documents Document title z/OS DFSMSdfp Checkpoint/Restart Order number SC26-7401

xiv

z/OS V1R10.0 DFSORT Application Programming Guide

Table 2. Referenced documents (continued) Document title z/OS DFSMS Macro Instructions for Data Sets z/OS DFSMS Using Data Sets z/OS MVS JCL Reference z/OS MVS JCL Users Guide z/OS MVS Programming: Assembler Services Reference IAR-XCT z/OS DCE Application Development Reference z/OS Program Directory z/OS UNIX System Services Users Guide Order number SC26-7408 SC26-7410 SA22-7597 SA22-7598 SA22-7607 SC24-5908 GI10-0670 SA22-7801

The z/OS DFSORT Application Programming Guide is a part of a more extensive DFSORT library. These documents can help you work with DFSORT more effectively. | | | | | | | | |
Task Planning For and Customizing DFSORT Learning to Use DFSORT Diagnosing Failures and Interpreting Messages Tuning DFSORT Publication Title Order Number

z/OS DFSORT Installation and SC26-7524 Customization z/OS DFSORT: Getting Started SC26-7527 z/OS DFSORT Messages, Codes and Diagnosis Guide z/OS DFSORT Tuning Guide SC26-7525 SC26-7526

Accessing z/OS DFSORT documents on the Internet

In addition to making softcopy documents available on CD-ROM, IBM provides access to unlicensed z/OS softcopy documents on the Internet. To find z/OS documents on the Internet, first go to the z/OS home page: http://www.ibm.com/ servers/eserver/zseries/zos From this Web site, you can link directly to the z/OS softcopy documents by selecting the Library icon. You can also link to the IBM Publications Center to order printed documentation.

Using LookAt to look up message explanations

LookAt is an online facility that lets you look up explanations for most of the IBM messages you encounter, as well as for some system abends and codes. Using LookAt to find information is faster than a conventional search because in most cases LookAt goes directly to the message explanation. You can use LookAt from these locations to find IBM message explanations for z/OS elements and features, z/VM, z/VSE, and Clusters for AIX and Linux: v The Internet. You can access IBM message explanations directly from the LookAt Web site at www.ibm.com/servers/eserver/zseries/zos/bkserv/lookat/. v Your z/OS TSO/E host system. You can install code on your z/OS systems to access IBM message explanations using LookAt from a TSO/E command line (for example: TSO/E prompt, ISPF, or z/OS UNIX System Services).
About this document

xv

v Your Microsoft Windows workstation. You can install LookAt directly from the z/OS Collection (SK3T-4269) or the z/OS and Software Products DVD Collection (SK3T-4271) and use it from the resulting Windows graphical user interface (GUI). The command prompt (also known as the DOS > command line) version can still be used from the directory in which you install the Windows version of LookAt. v Your wireless handheld device. You can use the LookAt Mobile Edition from www.ibm.com/servers/eserver/zseries/zos/bkserv/lookat/lookatm.html with a handheld device that has wireless access and an Internet browser. You can obtain code to install LookAt on your host system or Microsoft Windows workstation from: v A CD in the z/OS Collection (SK3T-4269). v The z/OS and Software Products DVD Collection (SK3T-4271). v The LookAt Web site (click Download and then select the platform, release, collection, and location that suit your needs). More information is available in the LOOKAT.ME files available during the download process.

Notational conventions
The syntax diagrams in this document are designed to make coding DFSORT program control statements simple and unambiguous. The lines and arrows represent a path or flowchart that connects operators, parameters, and delimiters in the order and syntax in which they must appear in your completed statement. Construct a statement by tracing a path through the appropriate diagram that includes all the parameters you need, and code them in the order that the diagram requires you to follow. Any path through the diagram gives you a correctly coded statement, 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 on the next line or at an indicated spot.

A continuation line begins with a single arrowhead.

v Strings in upper-case letters, and punctuation (parentheses, apostrophes, and so on), 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 this document. v Strings in all lowercase letters represent information that you supply.

xvi

z/OS V1R10.0 DFSORT Application Programming Guide

Notational Conventions
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.

Required Optional

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

Operator

Required Choice 1 Required Choice 2 Required Choice 3

Optional Choice 1 Optional Choice 2

If one choice within the stack lies on the main path (as in the example above, left), you must specify one of the alternatives. If the stack is placed below the main path (as in the example above, right), then selections are optional, and you can choose either one or none of them. v The repeat symbol shows where you can return to an earlier position in the syntax diagram to specify a parameter more than once (see the first example below), to specify more than one choice at a time from the same stack (see the second example below), or to nest parentheses (see the third example below).

, a,b,c

, Choice-1 Choice-2 Choice-3

Do not interpret a repeat symbol to mean that you can specify incompatible parameters. For instance, do not specify both ABEND and NOABEND in the same EXEC statement, or attempt to nest parentheses incorrectly. Use any punctuation or delimiters that appear within the repeat symbol to separate repeated items. v A double arrowhead at the end of a line indicates the end of the syntax diagram.

About this document

xvii

Notational Conventions

xviii

z/OS V1R10.0 DFSORT Application Programming Guide

Summary of Changes
This document contains terminology, maintenance, and editorial changes. Technical changes or additions to the text and illustrations are indicated by a vertical line to the left of each change. You might notice changes in the style and structure of some content in this documentfor example, more specific headings for notes, such as Tip and Requirement. The changes are ongoing improvements to the consistency and retrievability of information in DFSORT documents. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Summary of Changes for SC26-7523-03 z/OS Version 1 Release 10

This document contains information that was previously presented in DFSORT Application Programming Guide, SC26-7523-02. The following sections summarize the changes to that information.

New Information
This edition includes the following new enhancements:

Installation Options
ICEPRMxx members in concatenated PARMLIB can now be used to specify changes to DFSORTs installation options. Each ICEPRMxx member can contain options to be changed for any or all of DFSORTs eight installation environments (JCL, INV, TSO, TSOINV and TD1-TD4). Up to ten ICEPRMxx members can be activated by a START ICEOPT started task command. The options in the activated members will be merged with the ICEMAC defaults at run-time. A different ICEPRMxx member, or combination of ICEPRMxx members, for different LPARs can be activated at IPL time by including a START ICEOPT command in an appropriate COMMNDxx member in PARMLIB, or at any time by issuing a START ICEOPT command from the console. ICEPRMxx members are now the recommended way to change DFSORT installation defaults since they are easier to use and more flexible then the old method using the ICEMAC macro and usermods. However, the old method is still supported. The ICETOOL DEFAULTS operator can be used at any time to produce a report showing the merged PARMLIB/ICEMAC installation default values for each environment that will be used at run-time, as well as the active ICEPRMxx and ICEMAC values.

VSAM Extended Address Volume

DFSORT now supports VSAM input and output data sets on Extended Address Volumes to the extent that z/OS supports these data sets.

Improvements in Performance and Resource Usage and Reporting

Memory object sorting can now be used for DFSORT applications that use the INREC, OUTREC or SUM functions.
Copyright IBM Corp. 1973, 2006

xix

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

The channel programs associated with DFSORTs input, output and work data sets can now reside above 16 megabytes virtual. Total storage usage for dataspace sorting can now be controlled with the EXPMAX, EXPRES and EXPOLD installation options. DFSORT now provides new fields ICEMNVLX, ICEMNVLY and ICEMNVLZ in its SMF type 16 record to aid in tuning main storage usage. The information DFSORT passes to the termination exit (ICETEXIT) now includes setting ICEPTST flag bit 6 on if the phase TCB timings are not valid.

Syntax for Run-Time Parameters

DFSORT now allows additional syntactical forms for all of its PARM and control statement run-time parameters. Any parameter of the form keyword=value can now also be specified as keyword(value) or keyword=(value). Any parameter of the form keyword=(list) can now also be specified as keyword(list).

Improved Diagnostics
DFSORT now provides additional information in messages ICE098I, ICE253I and ICE254I to aid in diagnosing and correcting out-of-space conditions associated with message ICE046A. DFSORT now provides specific reason codes and associated documentation to aid in diagnosing and correcting errors associated with the following messages: ICE017A, ICE018A, ICE024A, ICE042A, ICE043A, ICE109A, ICE126A and ICE251A.

Operational Changes that may Require User Action

The following are operational changes that may require user action for existing DFSORT/ICETOOL applications that use certain functions as specified:

DFSORT ISPF and ISMF Panels Removed

The English and Japanese ISPF panels, and the ISMF Sort operator, have been removed. These facilities are no longer available.

Installation Options
ICEPRMxx members are now the recommended way to change DFSORT installation defaults since they are easier to use and more flexible then the old method using the ICEMAC macro and usermods. However, the old method is still supported.

Dataspace Sorting
The existing EXPMAX, EXPOLD and EXPRES installation options now apply to dataspace sorting as well as to memory object sorting and Hipersorting

IOMAXBF Default Changed

The IBM-supplied default for the existing IOMAXBF installation option has been changed from 33554432 (32 MB) to 35651584 (34 MB).

STIMER Option Ignored

The STIMER installation option, and the STIMER and NOSTIMER run-time options, are now ignored. These options are no longer meaningful since DFSORT now uses the TIMEUSED service rather than the STIMER service to monitor processor time.

xx

z/OS V1R10.0 DFSORT Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | |

ICEDTEX Macro
Previously, fields ICEDSBKA, ICEDSBKB and ICEDSBKC in the ICEDTEX macro provided statistics on expanded storage pages available for dataspace sorting, while fields ICEDSBTA, ICEDSBTB and ICEDSBTC provided total expanded and central storage pages available for dataspace sorting. Since this level of DFSORT and z/OS no longer supports expanded storage, fields ICEDSBKA, ICEDSBKB and ICEDSBKC are no longer relevant and have been removed. If you have an ICETEXIT program that uses fields ICEDSBKA, ICEDSBKB and ICEDSBKC, you should remove any references to those fields (you can change your program to use fields ICEDSBTA, ICEDSBTB and ICEDSBTC instead) and recompile your program before using it with this level of DFSORT.

Output Data Set Allocation

Previously, if an allocation of 0 primary tracks was specified for a SORTOUT or OUTFIL output data set, at least 1 primary track was allocated. In this release, if an allocation of 0 primary tracks is specified for a SORTOUT or OUTFIL data set, 0 primary tracks will be allocated provided that: v The application is a SORT v An E35 exit is not specified v No records are to be written to the output data set. For this situation, if the output data set was allocated with 0 secondary tracks, it will not have any space available. Thus, any subsequent attempt to add records to that data set will fail with an out of space condition unless you explicitly specify a space allocation for that data set.

Summary of Changes for SC26-7523-02 z/OS Version 1 Release 8 (PTFs - April, 2006)
This document contains information that was previously presented in z/OS DFSORT Application Programming Guide, SC26-7523-01. The following sections summarize the changes to that information.

New Information
This edition includes the following new enhancements:

INCLUDE and OMIT Enhancements

COND now allows you to compare date fields in various formats to past and future dates (relative to the date of your DFSORT run) using new DATEn+r, DATEn-r, DATEn(c)+r, DATEn(c)-r, DATEnP+r, DATEnP-r, YDATEn+r and YDATEn-r constants. &DATEn+r, &DATEn-r , &DATEn(c)+r, &DATEn(c)-r, &DATEnP+r and &DATEnP-r can be used as aliases for DATEn+r, DATEn-r, DATEn(c)+r, DATEn(c)-r, DATEnP+r and DATEnP-r, respectively. COND now allows you to test a field for numerics (field,EQ,NUM) or non-numerics (field,NE,NUM) in character (FS), zoned decimal (ZD) or packed decimal (PD) format. COND now allows you to use &DATEn, &DATEn(c) and &DATEnP as aliases for DATEn, DATEn(c) and DATEnP, respectively.

Summary of Changes

xxi

INREC and OUTREC Enhancements

PARSE and IFTHEN PARSE are new options that allow you to extract variable position/length fields into fixed-length parsed fields defined as %nn fields. PARSE gives you powerful new capabilities for handling variable fields such as delimited fields, comma separated values (CSV), tab separated values, blank separated values, keyword separated fields, null-terminated strings, and many other types. You can use various PARSE options to define the rules for extracting variable fields into up to one hundred %nn fixed-length parsed fields (%00-%99), and then use these %nn fields where you can use p,m fields in BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and FIELDS. You can edit, convert, justify, squeeze, translate, and do arithmetic with %nn fields. BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and FIELDS now allow you to use a new JFY option to left-justify or right-justify the data in a field. For a left-justified field, leading blanks are removed and the characters from the first nonblank to the last nonblank are shifted left, with blanks inserted on the right if needed. For a right-justified field, top trailing blanks are removed and the characters from the last nonblank to the first nonblank are shifted right, with blanks inserted on the left if needed. Optionally for JFY, specific leading and trailing characters can be changed to blanks before justification begins, a leading string can be inserted, a trailing string can be inserted, and the output length can be changed. BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and FIELDS now allow you to use a new SQZ option to left-squeeze or right-squeeze the data in a field. For a left-squeezed field, all blanks are removed and the characters from the first nonblank to the last nonblank are shifted left, with blanks inserted on the right if needed. For a right-squeezed field, all blanks are removed and the characters from the last nonblank to the first nonblank are shifted right, with blanks inserted on the left if needed. Optionally for SQZ, specific characters can be changed to blanks before squeezing begins, a leading string can be inserted, a trailing string can be inserted, a string can be inserted wherever a group of blanks is removed between the first nonblank and the last nonblank, blanks can be kept as is between paired apostrophes or paired quotes, and the output length can be changed. BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and FIELDS now allow you to insert past and future dates (relative to the date of your DFSORT run) into your records in various forms using new DATEn+r, DATEn-r, DATEn(c)+r, DATEn(c)-r, DATEnP+r and DATEnP-r constants. &DATEn+r, &DATEn-r, &DATEn(c)+r, &DATEn(c)-r, &DATEnP+r and &DATEnP-r can be used as aliases for DATEn+r, DATEn-r, DATEn(c)+r, DATEn(c)-r, DATEnP+r and DATEnP-r, respectively. BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and FIELDS now allow you to use FL format to convert 4-byte or 8-byte hexadecimal floating-point values to integer values. BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and FIELDS now allow you to use new TO=PDF and TO=PDC options to convert numeric values to PD values with F or C for the positive sign, respectively. The TO=PDC option is equivalent to the existing TO=PD option.

xxii

z/OS V1R10.0 DFSORT Application Programming Guide

BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and FIELDS now allow you to use &DATEn, &DATEn(c), &DATEnP, &YDDD=(abc), &YDDDNS=(ab), &TIMEn, &TIMEn(c) and &TIMEnP as aliases for DATEn, DATEn(c), DATEnP, YDDD=(abc), YDDDNS=(ab), TIMEn, TIMEn(c) and TIMEnP, respectively. IFTHEN WHEN now allows you to compare date fields in various formats to past and future dates (relative to the date of your DFSORT run) using new DATEn+r, DATEn-r, DATEn(c)+r, DATEn(c)-r, DATEnP+r, DATEnP-r, YDATEn+r, and YDATEn-r constants. &DATEn+r, &DATEn-r, &DATEn(c)+r, &DATEn(c)-r, &DATEnP+r and &DATEnP-r can be used as aliases for DATEn+r, DATEn-r, DATEn(c)+r, DATEn(c)-r, DATEnP+r and DATEnP-r, respectively. IFTHEN WHEN now allows you to test a field for numerics (field,EQ,NUM) or non-numerics (field,NE,NUM) in character (FS), zoned decimal (ZD) or packed decimal (PD) format. IFTHEN WHEN now allows you to use &DATEn, &DATEn(c) and &DATEnP as aliases for DATEn, DATEn(c) and DATEnP, respectively.

OUTFIL Enhancements
BLKCCH1 is a new report option that allows you to avoid forcing a page eject at the start of the report header; the ANSI carriage control character of 1 (page eject) in the first line of the report header (HEADER1) is replaced with a blank. BLKCCH2 is a new report option that allows you to avoid forcing a page eject at the start of the first page header; the ANSI carriage control character of 1 (page eject) in the first line of the first page header (HEADER2) is replaced with a blank. BLKCCT1 is a new report option that allows you to avoid forcing a page eject at the start of the report trailer; the ANSI carriage control character of 1 (page eject) in the first line of the report trailer (TRAILER1) is replaced with a blank. SPLIT1R is a new option that allows you to write contiguous groups of records in one rotation among multiple output data sets. A specified number of records is written to each output data set and extra records are written to the last output data set. PARSE and IFTHEN PARSE are new options that allow you to extract variable position/length fields into fixed-length parsed fields defined as %nn fields. PARSE gives you powerful new capabilities for handling variable fields such as delimited fields, comma separated values (CSV), tab separated values, blank separated values, keyword separated fields, null-terminated strings, and many other types. You can use various PARSE options to define the rules for extracting variable fields into up to one hundred %nn fixed-length parsed fields (%00-%99), and then use these %nn fields where you can use p,m fields in BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and OUTREC. You can edit, convert, justify, squeeze, translate, and do arithmetic with %nn fields. BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and OUTREC now allow you to use a new JFY option to left-justify or right-justify the data in a field. For a left-justified field, leading blanks are removed and the characters from the first nonblank to the last nonblank are shifted left, with blanks inserted on the right if needed. For a right-justified field, trailing blanks are removed and the characters from the last nonblank to the first nonblank are shifted right, with blanks inserted on the left if needed.
Summary of Changes

xxiii

Optionally for JFY, specific leading and trailing characters can be changed to blanks before justification begins, a leading string can be inserted, a trailing string can be inserted, and the output length can be changed. BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and OUTREC now allow you to use a new SQZ option to left-squeeze or right-squeeze the data in a field. For a left-squeezed field, all blanks are removed and the characters from the first nonblank to the last nonblank are shifted left, with blanks inserted on the right if needed. For a right-squeezed field, all blanks are removed and the characters from the last nonblank to the first nonblank are shifted right, with blanks inserted on the left if needed. Optionally for SQZ, specific characters can be changed to blanks before squeezing begins, a leading string can be inserted, a trailing string can be inserted, a string can be inserted wherever a group of blanks is removed between the first nonblank and the last nonblank, blanks can be kept as is between paired apostrophes or paired quotes, and the output length can be changed. BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and OUTREC now allow you to insert past and future dates (relative to the date of your DFSORT run) into your records in various forms using new DATEn+r, DATEn-r, DATEn(c)+r, DATEn(c)-r, DATEnP+r and DATEnP-r constants. &DATEn+r, &DATEn-r, &DATEn(c)+r, &DATEn(c)-r, &DATEnP+r and &DATEnP-r can be used as aliases for DATEn+r, DATEn-r, DATEn(c)+r, DATEn(c)-r, DATEnP+r and DATEnP-r, respectively. TRAILERx, BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and OUTREC now allow you to use FL format to convert 4-byte or 8-byte hexadecimal floating-point values to integer values. TRAILERx, HEADERx, BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and OUTREC now allow you to use new TO=PDF and TO=PDC options to convert numeric values to PD values with F or C for the positive sign, respectively. The TO=PDC option is equivalent to the existing TO=PD option. BUILD, OVERLAY, IFTHEN BUILD, IFTHEN OVERLAY and OUTREC now allow you to use &DATEn, &DATEn(c), &DATEnP, &YDDD=(abc), &YDDDNS=(ab), &TIMEn, &TIMEn(c) and &TIMEnP as aliases for DATEn, DATEn(c), DATEnP, YDDD=(abc), YDDDNS=(ab), TIMEn, TIMEn(c) and TIMEnP, respectively. INCLUDE, OMIT and IFTHEN WHEN now allow you to compare date fields in various formats to past and future dates (relative to the date of your DFSORT run) using new DATEn+r, DATEn-r, DATEn(c)+r, DATEn(c)-r, DATEnP+r, DATEnP-r, YDATEn+r, and YDATEn-r constants. &DATEn+r, &DATEn-r, &DATEn(c)+r, &DATEn(c)-r, &DATEnP+r and &DATEnP-r can be used as aliases for DATEn+r, DATEn-r, DATEn(c)+r, DATEn(c)-r, DATEnP+r and DATEnP-r, respectively. INCLUDE, OMIT and IFTHEN WHEN now allow you to test a field for numerics (field,EQ,NUM) or non-numerics (field,NE,NUM) in character (FS), zoned decimal (ZD) or packed decimal (PD) format. INCLUDE, OMIT and IFTHEN WHEN now allow you to use &DATEn, &DATEn(c) and &DATEnP as aliases for DATEn, DATEn(c) and DATEnP, respectively.

xxiv

z/OS V1R10.0 DFSORT Application Programming Guide

Symbol Enhancements
A symbol can now be used for a %nn parsed field. For example, if Account,%01 is defined in SYMNAMES, Account can be used for %01. A symbol for %nn can be used in DFSORT control statements where %nn can be used. A symbol for %nn results in substitution of %nn. A symbol can now be used for an output column. For example, if Start_address,18 is defined in SYMNAMES, Start_address: can be used for 18:. symbol: can be used in DFSORT control statements where c: can be used. A symbol for p or p,m or p,m,f results in substitution of p: for symbol: (output column). A symbol can now be used for a new system symbol string constant. symbol,Sstring can be used to define a string containing any combination of EBCDIC characters and system symbols you want to use to form a character string. For example, if whererun,S &JOBNAME. on &SYSPLEX is defined in SYMNAMES, whererun can be used for the resulting constant. You can use dynamic system symbols such as &JOBNAME, &DAY, and so on, system-defined static system symbols such as &SYSNAME, &SYSPLEX, and so on, and installation-defined static system symbols specified by your installation in an IEASYMxx member of SYS1.PARMLIB. A symbol for a system symbol string can be used in DFSORT and ICETOOL control statements where a symbol for a character string can be used. DFSORT will replace each system symbol in Sstring with its substitution text to create a character string in the format Cnew_string.

ICETOOL Enhancements
DISPLAY now allows you to use FL format to convert 4-byte or 8-byte hexadecimal floating-point values to integer values. DISPLAY and OCCUR now allow you to use a new TBETWEEN(n) option to specify the number of blanks between title elements (title, page number, date, time). SELECT and SPLICE now allow you to use an INREC statement to reformat your records before they are selected or spliced. All of the operands of the INREC statement (PARSE, BUILD, OVERLAY, IFTHEN, IFOUTLEN and FIELDS) are now available with SELECT and SPLICE.

SORT and MERGE Enhancements

The maximum length for a PD or ZD sort or merge field has been raised to 256.

SUM Enhancements
The maximum position for the end of a sum field has been raised to 32752.

Other Enhancements
DFSORT supports large physical sequential data sets for input, output and work data sets. DSA can now be specified as a run-time option. This allows you to adjust the maximum amount of storage available to DFSORT for dynamic storage adjustment of individual Blockset sort applications when SIZE/MAINSIZE=MAX is in effect. DFSORT now accepts and ignores zero values in the starting and ending address of the RECORD statement image in the 24-bit Parameter List. You can set these

Summary of Changes

xxv

addresses to zero if you dont want to pass a control statement to DFSORT using the third and fourth words of the parameter list.

Operational Changes that may Require User Action

The following are operational changes that may require user action for existing DFSORT/ICETOOL applications that use certain functions as specified:

New reserved words for symbols

The following are new DFSORT/ICETOOL reserved words (uppercase only, as shown), which are no longer allowed as symbols: DATE1..., DATE2..., DATE3..., PDC and PDF. If you used these words as symbols, you must change them to other words, such as lowercase or mixed case forms (for example, Date1p, date3(/) or pdc).

FL Conversion
DFSORTs INREC, OUTREC and OUTFIL statements, and ICETOOLs DISPLAY operator, can now convert FL (hexadecimal floating-point) values to integer values, providing you are running in z/Architecture mode. If you use FL in INREC, OUTREC, OUTFIL or DISPLAY when running in ESA/390 mode, FL will be recognized and the error messages issued may be different than those issued previously when FL was not allowed in INREC, OUTREC, OUTFIL or DISPLAY. If you want to use FL in INREC, OUTREC, OUTFIL or DISPLAY, you must be running in z/Architecture mode.

OUTREC Statement with SELECT or SPLICE

DFSORT will now issue error message ICE652A and terminate if an OUTREC statement is used with ICETOOLs SELECT or SPLICE operator. This will make it easier to identify this error condition. Note: If ABEND is in effect, DFSORT will ABEND with U0652, but will not issue ICE652A If you want to reformat your records after SELECT or SPLICE processing, use an OUTFIL statement rather than an OUTREC statement.

Summary of Changes for SC26-7523-01 z/OS Version 1 Release 6 (PTFs - December, 2004)
This document contains information that was previously presented in z/OS DFSORT Application Programming Guide, SC26-7523-00. The following sections summarize the changes to that information.

New Information
This edition includes the following new enhancements:

ICETOOL Enhancements
ICETOOLs DISPLAY, OCCUR, RANGE, SELECT, SPLICE, STATS, UNIQUE and VERIFY operators now allow you to use larger numeric values for ON and BREAK fields. PD, ZD and FS fields can now be up to 31 digits (or more in some cases). BI and FI fields can now be up to 8 bytes (or more in some cases).

xxvi

z/OS V1R10.0 DFSORT Application Programming Guide

ICETOOLs RANGE operator now allows you to use larger decimal values for the HIGHER(n), LOWER(n), EQUAL(n) and NOTEQUAL(n) options. These values can now be up to 31 digits. ICETOOLs DISPLAY, OCCUR, RANGE, SELECT, SPLICE, STATS and UNIQUE operators now allow you to use new UFF (unsigned free form) and SFF (signed free form) formats for ON and BREAK fields. UFF extracts a positive numeric value from a free form field (for example, $1234.56 is treated as +123456). SFF extracts a positive or negative value from a free form field (for example, (1,234.56) is treated as -123456). ICETOOLs DISPLAY and OCCUR operators now allow you to use new DC1-DC3 (TOD date), DE1-DE3 (ETOD date), TC1-TC4 (TOD time) and TE1-TE4 (ETOD time) formats for ON and BREAK fields. These new formats produce meaningful representations of TOD and ETOD date and time values. ICETOOLs DISPLAY and OCCUR operators now allow you to specify multiline headings for the columns of your reports. You can specify one, two or three line headings with the HEADER option. ICETOOLs DISPLAY and OCCUR operators now allow you to use new edit masks G1-G6 to display numeric values with 4 decimal digits in various ways. ICETOOLs DISPLAY and OCCUR operators now allow you to use new YDDD(abc) and YDDDNS(abc) options to insert the year (yyyy) and day of the year (ddd) of your ICETOOL run into your titles in various forms. ICETOOLs COUNT operator now allows you to use a new RC4 option to set RC=4 (instead of RC=12) or RC=0 based on the count of records in a data set. ICETOOLs SPLICE operator now allows you to use a new KEEPBASE option to keep the base records as well as the spliced records. ICETOOLs SPLICE operator now allows you to use new VLENMAX or VLENOVLY options to set the length of spliced records to the maximum of the base or overlay record length, or to the overlay record length.

OUTFIL Enhancements
OUTFIL now allows you to reformat records in one of the following three ways using unedited, edited, or converted input fields and a variety of constants: v BUILD or OUTREC: The existing OUTREC parameter, or its new alias of BUILD, allows you to reformat each record by specifying all of its items one by one. BUILD or OUTREC gives you complete control over the items you want in your reformatted OUTFIL records and the order in which they appear. You can delete, rearrange and insert fields and constants. v OVERLAY: The new OVERLAY parameter allows you to reformat each record by specifying just the items that overlay specific columns. Overlay lets you change specific existing columns without affecting the entire record. v IFTHEN clauses: The new IFTHEN clauses allow you to reformat different records in different ways by specifying how BUILD or OVERLAY items are applied to records that meet given criteria. IFTHEN clauses let you use sophisticated conditional logic to choose how different record types are reformatted.

Summary of Changes

xxvii

OUTFIL OUTREC, as well as BUILD, OVERLAY, and IFTHEN, now allows you to use larger numeric values for fields and decimal constants to be edited, converted or used in arithmetic expressions. PD, ZD and FS fields, and decimal constants, can now be up to 31 digits. BI and FI fields can now be up to 8 bytes. OUTFIL OUTREC, as well as BUILD, OVERLAY, and IFTHEN, now allows you to use new UFF (unsigned free form) and SFF (signed free form) formats for fields to be edited, converted or used in arithmetic expressions. OUTFIL OUTREC, as well as BUILD, OVERLAY, and IFTHEN, now allows you to use new DC1-DC3 (TOD date), DE1-DE3 (ETOD date), TC1-TC4 (TOD time) and TE1-TE4 (ETOD time) formats for fields to be edited, converted or used in arithmetic expressions. These new formats produce meaningful representations of TOD and ETOD date and time values. OUTFIL OUTREC, as well as BUILD, OVERLAY, and IFTHEN, now allows you to use a set field in the CHANGE option (for example, 1,2,CHANGE=(4,CFY,C0001,CVV,21,4)). OUTFIL OUTREC, as well as BUILD, OVERLAY and IFTHEN, now allows you to restart the sequence number when the binary value of a specified field changes (for example, SEQNUM,5,ZD,RESTART=(11,4)). OUTFIL OUTREC, as well as BUILD, OVERLAY, and IFTHEN, now allows you to use DATE, DATE=(abcd), DATENS=(abc), YDDD=(abc), YDDDNS=(ab), TIME, TIME=(abc) and TIMENS=(ab) options to insert the date and time of your DFSORT run into your records in various forms. OUTFIL OUTREC, as well as BUILD, OVERLAY, and IFTHEN, now allows you to use new TO=ZDC and TO=ZDF options to convert numeric values to ZD values with C or F for the positive sign, respectively. The TO=ZDF option is equivalent to the existing TO=ZD option. OUTFIL INCLUDE and OMIT now allow you to use larger FS values for compare fields. These values can now be up to 32 digits. OUTFIL INCLUDE and OMIT now allow you to use larger decimal constants for comparison to BI and FI fields. Decimal constants can now be up to +18446744073709551615 for comparison to BI fields. Decimal constants can now be between -9223372036854775808 and +9223372036854775807 for comparison to FI fields. OUTFIL INCLUDE and OMIT now allow you to use new UFF (unsigned free form) and SFF (signed free form) formats for compare fields. A UFF or SFF field can be compared to a UFF, SFF, FS, CSL or CST field or to a decimal constant. OUTFIL TRAILERx now allows you to use larger numeric values for statistical fields (total, maximum, minimum, average). PD, ZD and FS fields, and decimal constants, can now be up to 31 digits. BI and FI fields can now be up to 8 bytes. OUTFIL TRAILERx now allows you to use new UFF (unsigned free form) and SFF (signed free form) formats for statistical fields (total, maximum,minimum, average). OUTFIL TRAILERx now allows you to use TO=fo and fo (to) options to convert statistical fields (total, maximum, minimum, average) and counts to BI, FI, PD, ZD, ZDC, ZDF or FS output values.

xxviii

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL TRAILERx now allows you to use COUNT+n=(edit), COUNT+n=(to), COUNT-n=(edit) and COUNT-n=(to) to add or subtract n from a count to be edited or converted (for example, COUNT+1=(TO=ZD)). OUTFIL HEADERx and TRAILERx now allow you to insert hexadecimal strings (Xyy...yy or nXyy...yy) in your headers and trailers. OUTFIL HEADERx and TRAILERx now allow you to use new YDDD=(abc) and YDDDNS=(ab) options to insert the year (yyyy) and day of the year (ddd) of your DFSORT run in your headers and trailers. OUTFIL HEADERx and TRAILERx now allow you to use PAGE=(edit) and PAGE=(to) to edit or convert the page number (for example, PAGE=(M11,LENGTH=3)).

INREC and OUTREC Enhancements

INREC and OUTREC now allow you to reformat records in one of the following three ways using unedited, edited, or converted input fields and a variety of constants: v BUILD or FIELDS: The existing FIELDS parameter, or its new alias of BUILD, allows you to reformat each record by specifying all of its items one by one. BUILD or FIELDS gives you complete control over the items you want in your reformatted INREC or OUTREC records and the order in which they appear. You can delete, rearrange and insert fields and constants. v OVERLAY: The new OVERLAY parameter allows you to reformat each record by specifying just the items that overlay specific columns. Overlay lets you change specific existing columns without affecting the entire record. v IFTHEN clauses: The new IFTHEN clauses allow you to reformat different records in different ways by specifying how BUILD or OVERLAY items are applied to records that meet given criteria. IFTHEN clauses let you use sophisticated conditional logic to choose how different record types are reformatted. INREC and OUTREC now allow you to use larger numeric values for fields and decimal constants to be edited, converted or used in arithmetic expressions. PD, ZD and FS fields, and decimal constants, can now be up to 31 digits. BI and FI fields can now be up to 8 bytes. INREC and OUTREC now allow you to use new UFF (unsigned free form) and SFF (signed free form) formats for fields to be edited, converted or used in arithmetic expressions. INREC and OUTREC now allow you to use new DC1-DC3 (TOD date), DE1-DE3 (ETOD date), TC1-TC4 (TOD time) and TE1-TE4 (ETOD time) formats for fields to be edited, converted or used in arithmetic expressions. These new formats produce meaningful representations of TOD and ETOD date and time values. INREC and OUTREC now allow you to use a set field in the CHANGE option. INREC and OUTREC now allow you to restart the sequence number when the binary value of a specified field changes. INREC and OUTREC now allow you to use new TO=ZDC and TO=ZDF options to convert numeric values to ZD values with C or F for the positive sign, respectively. The TO=ZDF option is equivalent to the existing TO=ZD option.

Summary of Changes

xxix

INREC and OUTREC now allow you to use new DATE, DATE=(abcd), DATENS=(abc), YDDD=(abc), YDDDNS=(ab), TIME, TIME=(abc) and TIMENS=(ab) options to insert the date and time of your DFSORT run into your records in various forms.

SORT and MERGE Enhancements

SORT and MERGE now allow you to use larger FS values for control fields. These values can now be up to 32 digits. SORT and MERGE now allow you to use new UFF (unsigned free form) and SFF (signed free form) formats for control fields. SORT and MERGE now allow you to use other characters besides + (plus) as a positive sign in control field values for CSL, CST, ASL, and AST formats. A (minus) sign is treated as negative and any other sign (for example, blank) is treated as positive.

INCLUDE and OMIT Enhancements

INCLUDE and OMIT now allow you to use larger FS values for compare fields. These values can now be up to 32 digits. INCLUDE and OMIT now allow you to use larger decimal constants for comparison to BI and FI fields. Decimal constants can now be up to +18446744073709551615 for comparison to BI fields. Decimal constants can now be between -9223372036854775808 and +9223372036854775807 for comparison to FI fields. INCLUDE and OMIT now allow you to use new UFF (unsigned free form) and SFF (signed free form) formats for compare fields. A UFF or SFF field can be compared to a UFF, SFF, FS, CSL or CST field or to a decimal constant.

SUM Enhancement
SUM now allows you to use larger ZD values for sum fields. These values can now be up to 31 digits

Other Enhancements
For sort and copy applications with concatenated variable-length input data sets for SORTIN, DFSORT now uses the largest LRECL it finds in the concatenation. DFSORT now allows control statements in SYSIN and SORTCNTL to contain labels up to 70 characters, and allows any character in the label. DFSORT now ignores statements with a label followed only by blanks.

Operational Changes that may Require User Action

The following are operational changes that may require user action for existing DFSORT/ICETOOL applications that use certain functions as specified:

Return Area for ICETOOL STATS Operator

In order to handle larger numbers, ICETOOL will now return 16-byte PD values rather than 8-byte PD values in the return area for the STATS operator. If you have programs that call ICETOOL and use the returned STATS values, change the DCs for those values from PL8 to PL16 and recompile the programs before running them against this level of DFSORT/ICETOOL.

xxx

z/OS V1R10.0 DFSORT Application Programming Guide

16-Byte FS Fields
In order to handle larger FS fields (a sign and up to 31 digits), DFSORT and ICETOOL will now treat a 16-byte FS field as having a maximum of 16 digits, rather than 15 digits. For ICETOOLs DISPLAY and OCCUR operators, ON and BREAK fields for 16-byte FS values may result in different formatting for the output reports. You can use the new U15 formatting item to limit these values to 15 digits instead of 16 digits. For example, ON(11,16,FS,U15). For INREC, OUTREC and OUTFIL OUTREC, 16-byte FS values may be edited or converted differently for output. You can use EDIT=(pattern) or LENGTH=n to change the length of the output fields, if appropriate. For example, 11,16,FS,EDIT=(SIIIIIIIIIIIIIIT),SIGNS=(+,-).

TO=BI and TO=FI for 10-digit values

In order to handle larger numbers, INREC, OUTREC and OUTFIL OUTREC will create an 8-byte field instead of a 4-byte field when TO=BI or TO=FI is used for a 10-digit value. You can use LENGTH=n to change the length of the output fields, if appropriate. For example, 11,10,ZD,TO=BI,LENGTH=4

New reserved words for symbols

The following are new DFSORT/ICETOOL reserved words (uppercase only, as shown), which are no longer allowed as symbols: DC1, DC2, DC3, DE1, DE2, DE3, SFF, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, UFF, ZDC, and ZDF. If you used these words as symbols, you must change them to other words, such as lowercase or mixed case forms (for example, dc1 or Dc1).

Summary of Changes

xxxi

xxxii

z/OS V1R10.0 DFSORT Application Programming Guide

Chapter 1. Introducing DFSORT

DFSORT Overview . . . . . . . . . . . . 1 DFSORT on the Web . . . . . . . . . . . . 4 DFSORT FTP Site . . . . . . . . . . . . . 4 Invoking DFSORT . . . . . . . . . . . . 4 How DFSORT Works . . . . . . . . . . . 5 Operating Systems . . . . . . . . . . . 5 Control Fields and Collating Sequences . . . . 5 Cultural Environment Considerations . . . . . 7 DFSORT Processing . . . . . . . . . . . 7 Input Data SetsSORTIN and SORTINnn . . . . 11 Output Data SetsSORTOUT and OUTFIL . . . . 12 Data Set Considerations . . . . . . . . . . 12 Sorting or Copying Records . . . Merging Records . . . . . . Data Set Notes and Limitations . . General Considerations . . . Padding and Truncation . . . QSAM Considerations . . . . VSAM Considerations . . . . HFS File Considerations . . . . . Installation Defaults . . . . . . Migrating to DFSORT from Other Sort DFSORT Messages and Return Codes Use Blockset Whenever Possible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 13 13 13 14 15 15 16 16 22 22 23

DFSORT Overview
This chapter introduces IBM z/OS DFSORT Licensed Program 5694-A01. DFSORT is intended to run in problem state and in a user key ( that is, key 8 or higher). 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 the information you will use to merge them and that they are in the same order required 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 processing simultaneously: You can control which records to keep in the final output data set of a DFSORT run by using INCLUDE and OMIT statements in your application. These statements work like filters, testing each record against criteria that you supply and retaining only the ones you want for the output data set. For example, you might choose to work only with records that have a value of Kuala Lumpur in the field reserved for office location. Or perhaps you want to leave out any record dated after 2001 if it also contains a value greater than 20 for the number of employees. You can parse, edit, and reformat your records before or after other processing by using INREC and OUTREC statements. INREC and OUTREC statements support a wide 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. For variable fields, such as delimited fields, comma separated values (CSV), tab separated values, blank separated values, keyword separated fields,
Copyright IBM Corp. 1973, 2006

DFSORT Overview
null-terminated strings (and many other types), you define rules that allow DFSORT to extract the relevant data into fixed parsed fields, and then use the parsed fields as you would use fixed fields. Insertion of blanks, zeros, strings, current date, future date, past date, current time, sequence numbers, decimal constants, and the results of arithmetic expressions before, between, and after the input fields in the reformatted records. Sophisticated conversion capabilities, such as hexadecimal display, conversion of EBCDIC letters from lowercase to uppercase or uppercase to lowercase, conversion of characters using the ALTSEQ translation 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 and shift right). Sophisticated editing capabilities, such as control of the way numeric fields are presented with respect to length, leading or suppressed zeros, thousands separators, decimal points, leading and trailing positive and negative signs, and so on. Twenty-seven pre-defined editing masks are available for commonly used numeric editing patterns, encompassing many of the numeric notations used throughout the world. In addition, a virtually unlimited number of numeric editing patterns are available via user-defined editing masks. Transformation of SMF, TOD, and ETOD date and time values to more usable forms. Transformation of various forms of two-digit year dates to various forms of four-digit year dates using a specified fixed or sliding century window. 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).

v v v

You can create the reformatted INREC or OUTREC records in one of the following three ways: v By building the entire record one item at a time. v By only overlaying specific columns. v By using sophisticated conditional logic to choose how different records are built or overlaid. You can sum numeric information from many records into one record with the SUM statement. For example, if you want to know the total amount of a yearly payroll, you can add the values for a field containing salaries from the records of all your employees. You can create one or more output data sets for a sort, copy, or merge application from a single pass over one or more input data sets by using OUTFIL control statements. You can use multiple OUTFIL statements, with each statement specifying the OUTFIL processing to be performed for one or more output data sets. OUTFIL processing begins after all other processing ends (that is, after processing for exits, options, and other control statements). OUTFIL statements support 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, records that are not selected for any subset can be saved in a separate output data set.

z/OS V1R10.0 DFSORT Application Programming Guide

DFSORT Overview
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. For fixed 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, null-terminated strings (and many other types), you define rules that allow DFSORT to extract the relevant data into fixed parsed fields, and then use the parsed fields as you would use fixed fields. Insertion of blanks, zeros, strings, current date, future date, past date, current time, sequence numbers, decimal constants, and the results of arithmetic expressions before, between, and after the input fields in the reformatted records. Sophisticated conversion capabilities, such as hexadecimal display, conversion of EBCDIC letters from lowercase to uppercase or uppercase to lowercase, conversion of characters using the ALTSEQ translation 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 and shift right). Sophisticated editing capabilities, such as control of the way numeric fields are presented with respect to length, leading or suppressed zeros, thousands separators, decimal points, leading and trailing positive and negative signs, and so on. Twenty-seven pre-defined editing masks are available for commonly used numeric editing patterns, encompassing many of the numeric notations used throughout the world. In addition, a virtually unlimited number of numeric editing patterns are available via user-defined editing masks. Transformation of SMF, TOD, and ETOD date and time values to more usable forms. Transformation of two-digit year dates to various forms of four-digit year dates using a specified fixed or sliding century window. 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). v Creation of the reformatted records in one of the following three ways: By building the entire record one item at a time. By only overlaying specific columns. By using sophisticated conditional logic to choose how different records are built or overlaid. Highly detailed three-level (report, page, and section) reports containing a variety of report elements you can specify (for example, current date, current time, edited or converted page numbers, character strings, and blank lines) or derive from the input records (for example, character fields; unedited, edited, or converted numeric input fields; edited or converted record counts; and edited or converted totals, maximums, minimums, and averages for numeric input fields). Creation of multiple output records from each input record, with or without intervening blank output records. Repetition and sampling of data records. Splitting of data records in rotation among a set of output data sets.

v v v

Chapter 1. Introducing DFSORT

DFSORT Overview
You can control DFSORT functions with other control statements by specifying alternate collating sequences, invoking user exit routines, overriding installation defaults, and so on. You can direct DFSORT to pass control during run time to routines you design and write yourself. For example, you can write user exit routines to summarize, insert, delete, shorten, or otherwise alter records during processing. However, keep in mind that the extensive editing capabilities provided by the INCLUDE, OMIT, INREC, OUTREC, SUM, and OUTFIL statements can eliminate the need to write user exit routines. You can write your own routines to correct I/O errors that DFSORT does not handle, or to perform any necessary abnormal end-of-task operation before DFSORT terminates. You can write an EFS (Extended Function Support) program to intercept DFSORT control statements and PARM options for modification prior to use by DFSORT or to provide alternate sequence support for user-defined data. You can define and use a symbol for any field, constant, or output column that is recognized in a DFSORT control statement or ICETOOL operator. This makes it easy to create and reuse collections of symbols (that is, mappings) representing information associated with various record layouts. You can use system symbols (for example, &JOBNAME.) in your symbol constants. See Chapter 7, Using Symbols for Fields and Constants, on page 617.

DFSORT on the Web

For articles, online documents, news, tips, techniques, examples, and more, visit the DFSORT home page at:
http://www.ibm.com/storage/dfsort

DFSORT FTP Site

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

Invoking DFSORT
You 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 a cataloged procedure (for example, SORTD). See Chapter 2, Invoking DFSORT with Job Control Language, on page 25. TSO users can allocate the needed ddnames (for example, SYSOUT, SORTIN, SORTOUT and SYSIN), and invoke DFSORT using a calling method equivalent to 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. See Chapter 10, Examples of DFSORT Job Streams, on page 701 for examples of invoking DFSORT from REXX and CLISTs.

z/OS V1R10.0 DFSORT Application Programming Guide

Invoking DFSORT
v With a program written in basic assembler language using a system macro instruction. See Chapter 5, Invoking DFSORT from a Program, on page 461. v With programs written in either COBOL or PL/I with a special facility of the language. See the programmers guide describing the compiler version available at your location. v With the ICETOOL utility. See Chapter 6, Using ICETOOL, on page 479. In this document, the term directly invoked means that DFSORT is not initiated from another program. The term program invoked means that DFSORT is initiated from another program.

How DFSORT Works

This section contains a list of the operating systems supported by DFSORT and an explanation of how DFSORT uses control fields and collating sequences to sort, merge, and copy the records of a data set. The Blockset technique is DFSORTs most efficient technique for sorting, merging and copying data sets. DFSORT uses the Blockset technique whenever possible to take advantage of its highly optimized internal algorithms and efficient utilization of IBM hardware. If Blockset cannot be used, DFSORT uses another of its techniques Peerage/Vale or Conventional.

Operating Systems
| | | | DFSORT runs under control of your z/OS operating system and must be initiated according to the appropriate conventions. Additionally, DFSORT runs under z/OS when it is running as a guest under z/VM. DFSORT is compatible with all of the IBM processors supported by z/OS. In addition to any device supported by z/OS for program residence, DFSORT also operates with any device QSAM or VSAM uses for input or output.

Control Fields and Collating Sequences

You define control fields to identify the information you want DFSORT to sort or merge. When thinking of the contents of your data sets, you probably think of names, dates, account numbers, or similar pieces of useful information. For example, when sorting your data sets, you might choose to arrange your records in alphabetical 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 a control field to manipulate with DFSORT. DFSORT uses the control fields you define as keys in processing. A key is a concept, such as family name, that you have in mind when you design a record processing 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 to that information in a form that can be used by DFSORT to identify and sort, or merge the records. For all practical purposes, you can think of keys as equivalent to the control fields DFSORT uses in processing. To arrange your records in a specific order, identify one or more control fields of your records to use as keys. The sequence in which you list the control fields becomes the order of priority DFSORT uses to arrange your records. The first
Chapter 1. Introducing DFSORT

How DFSORT Works

control field you specify is called the major control field. Subsequent control fields are called minor control fields, as in first, second, third minor control fields, and so on. If two or more records have identical values for the first control field, they are arranged according to the values in the second. Records with identical values for the first and second are arranged according to the third, and so on, until a difference is found or no more control fields are available. Records with identical values for all the control fields specified retain their original input 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 original input order for records with identical values for all control fields by specifying EQUALS. Control fields may overlap, or be contained within other control fields (such as a three-digit area code, within a 10-digit telephone number). They do not need to be contiguous but must be located within the first 32752 bytes of the record (see Figure 1).

Record

Control field 3

Control field 4

Control field 1 (major)

Control field 2

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

DFSORT offers several standard collating sequences. You can choose to arrange your records according to these standard collating sequences or according to a collating sequence defined in the active locale. Conceptually, a collating sequence is a specific arrangement of character priority used to determine which of two values in the same control field of two different records should come first. DFSORT uses EBCDIC, the standard IBM collating sequence, or the ISCII/ASCII collating sequence when sorting or merging records. If locale processing is in effect, DFSORT will use the collating sequence defined in the active locale. The collating sequence for character data and binary data is absolute; character and binary fields are not interpreted as having signs. For packed decimal, zoned decimal, fixed-point, normalized floating-point, and the signed numeric data formats, collating is algebraic; each quantity is interpreted as having an algebraic sign. You can modify the standard EBCDIC sequence to collate differently if, for example, you want to allow alphabetic collating of national characters. An alternate collating sequence can be defined with the ALTSEQ installation option, or you can define it yourself at run-time with the ALTSEQ program control statement. You can also specify a modified collating sequence with an E61 user exit or with an EFS program. You can specify the LOCALE installation or run-time option to use an active locales collating rules.

z/OS V1R10.0 DFSORT Application Programming Guide

Cultural Environment Considerations

Cultural Environment Considerations

DFSORTs collating behavior can be modified according to your cultural environment. Your cultural environment is defined to DFSORT using the X/Open** locale model. A locale is a collection of data grouped into categories that describes the information about your cultural environment. The collate category of a locale is a collection of sequence declarations that defines the relative order between collating elements (single character and multi-character collating elements). The sequence declarations define the collating rules. The cultural environment is established by selecting the active locale. The active locale affects the behavior of locale-sensitive functions. In particular, the active locales collating rules affect DFSORTs SORT, MERGE, INCLUDE, and OMIT processing as follows: v Sort and Merge DFSORT produces sorted or merged records for output according to the collating rules defined in the active locale. This provides sorting and merging for singleor multi-byte character data based on defined collating rules that retain the cultural and local characteristics of a language. v Include and Omit DFSORT includes or omits records for output according to the collating rules defined in the active locale. This provides inclusion or omission for single- or multi-byte character data based on defined collating rules that retain the cultural and local characteristics of a language. Note: Locale processing is not used for IFTHEN WHEN constants or compare fields. The DFSORT option LOCALE specifies whether locale processing is to be used and, if so, designates the active locale. Only one locale can be active at a time for any DFSORT application.

DFSORT Processing
| You must prepare job control language (JCL) statements and DFSORT program control statements to invoke DFSORT processing. JCL statements (see Chapter 5, Invoking DFSORT from a Program, on page 461) are processed by your operating system. They describe your data sets to the operating system and initiate DFSORT processing. DFSORT program control statements (see Chapter 3, Using DFSORT Program Control Statements, on page 81) are processed by the DFSORT program. They describe the functions you want to perform and invoke the processing you request. A sort application usually requires intermediate storage as working space during the program run. This storage can be one of the following: 1. Hiperspace, using DFSORTs Hipersorting feature. 2. Work data setseither allocated dynamically by DFSORTs DYNALLOC facility or specified by the user, using JCL DD statements. If specified by the user, the intermediate storage devices and the amount of work space must be indicated. Methods for determining the amount of work space to allocate are explained in Appendix A, Using Work Space, on page 731. 3. A combination of Hiperspace and work data sets. Merge and copy applications do not require intermediate storage.
Chapter 1. Introducing DFSORT

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

z/OS V1R10.0 DFSORT Application Programming Guide

DFSORT Processing

Sorting or Copying

Merging

SORTIN

SORTINnn

SKIPREC

E15

E15

E32

INCLUDE / OMIT

ST OP AFT

INCLUDE / OMIT

INREC

INREC

SORT / SUM T or COPY

MERGE / SUM

OUTREC

OUTREC

E35

E35

E35

E35

SORTOUT

OUTFIL input records

SORTOUT

OUTFIL input records

OUTFIL STARTREC OUTFIL SAMPLE OUTFIL ENDREC

OUTFIL STARTREC OUTFIL SAMPLE OUTFIL ENDREC

OUTFIL INCLUDE OUTFIL OMIT OUTFIL SAVE OUTFIL PARSE OUTFIL OUTREC, BUILD, OVERLAY, or IFTHEN OUTFIL FTOV OUTFIL VTOF or CONVERT OUTFIL VLFILL OUTFIL VLTRIM OUTFIL REPEAT OUTFIL Reports

OUTFIL INCLUDE OUTFIL OMIT OUTFIL SAVE OUTFIL PARSE OUTFIL OUTREC, BUILD, OVERLAY, or IFTHEN OUTFIL FTOV OUTFIL VTOF or CONVERT OUTFIL VLFILL OUTFIL VLTRIM OUTFIL REPEAT OUTFIL Reports OUTFIL SPLIT OUTFIL SPLITBY OUTFIL SPLIT1R OUTFIL Data Sets

OUTFIL SPLIT OUTFIL SPLITBY OUTFIL SPLIT1R OUTFIL Data Sets

Figure 2. Record Processing Order

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

Chapter 1. Introducing DFSORT

DFSORT Processing
1. DFSORT first checks whether you supplied a SORTIN data set for SORT and COPY jobs or SORTINnn data sets for MERGE jobs. If so, DFSORT reads the input 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 invoke DFSORT from a program with the address of an E15 user exit in the parameter list, because SORTIN will be ignored.) DFSORT can use a COBOL E15 routine if you specified the E15 user exit in the MODS statement. v If no SORTINnn data sets are present for a MERGE job, you must use an E32 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. DFSORT deletes records until the SKIPREC count is satisfied. Eliminating records before 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, DFSORT transfers control to the user exit routine. You can use a COBOL E15 routine if the E15 user exit is specified in the MODS statement. The E15 routine can insert, 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, the INCLUDE/OMIT fields you specify must apply to the current format rather than to the original format. If you use the INCLUDE or OMIT statements to delete unnecessary records before SORT, MERGE, or COPY processing, your jobs run more efficiently. 5. For SORT or COPY jobs, DFSORT performs processing specified with the STOPAFT option. Record input stops after the maximum number of records (n) you specify have been accepted. DFSORT accepts records for processing if they are: v Read from SORTIN or inserted by E15 v Not deleted by SKIPREC v Not deleted by E15 v Not deleted by an INCLUDE or OMIT statement. 6. DFSORT performs processing specified in an INREC statement. Data records are parsed, edited and reformatted according to the options specified. If you reformatted the records before this step, the INREC fields you specify must apply to the current format rather than to the original format. 7. DFSORT performs processing specified in the SORT, MERGE, or OPTION COPY 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 records and deletes duplicates. If you reformatted the records before this step, the SORT or MERGE and SUM fields you specify must apply to the current format rather than to the original format. 8. DFSORT performs processing specified in an OUTREC statement. Data records are parsed, edited and reformatted according to the options specified. If you reformatted the records before this step, the OUTREC fields you specify must apply to the current format rather than to the original format.

10

z/OS V1R10.0 DFSORT Application Programming Guide

DFSORT Processing
9. If an E35 user exit is present, DFSORT transfers control to your user exit routine after all statement processing (except OUTFIL) is completed. If you reformatted the records, the E35 user exit receives the records in the current format rather than in the original format. You can use a COBOL E35 routine if you specify the E35 user exit in the MODS statement. You can use the E35 exit routine to add, delete, or reformat records. If SORTOUT and OUTFIL data sets are not present, the E35 exit must dispose of all the records because DFSORT treats these records as deleted. (This is also true if you do not specify OUTFIL data sets and DFSORT is invoked with the address of an E35 user exit in the parameter list, because SORTOUT will be ignored.) 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 the record indicated by STARTREC, ends with the record indicated by ENDREC, and is sampled according to the records indicated by SAMPLE. v DFSORT performs processing specified with the INCLUDE, OMIT, or SAVE option. Records are included or omitted from the OUTFIL data sets according to the criteria specified. v DFSORT performs processing specified with the PARSE, OUTREC (or BUILD), OVERLAY, IFTHEN, FTOV, VTOF (or CONVERT), VLFILL, VLTRIM and REPEAT options. Data records are parsed, edited, reformatted, converted and repeated according to the options specified. v DFSORT performs processing specified with the LINES, HEADER1, TRAILER1, HEADER2, TRAILER2, SECTIONS, NODETAIL, BLKCCH1, BLKCCH2, BLKCCT1 and REMOVECC options. Data records are reformatted and report records are generated for the OUTFIL data sets. v DFSORT performs SPLIT, SPLITBY, or SPLIT1R processing. Records are distributed among the OUTFIL data sets as evenly as possible. v DFSORT writes your OUTFIL records to the appropriate OUTFIL data sets.

Input Data SetsSORTIN and SORTINnn

DFSORT processes two types of input data sets, referred to as the SORTIN data set (or just SORTIN) and the SORTINnn data sets (or just SORTINnn). The SORTIN DD statement specifies the input data set (or concatenated input data sets) for a sort or copy application. If a SORTIN DD statement is present, it will be used by default for a sort or copy application unless you invoke DFSORT from a program with the address of an E15 user exit in the parameter list. The SORTINnn DD statements (where nn can be 00 to 99) specify the data sets for a merge application. If a SORTINnn DD statement is present, it will be used by default for a merge application unless you invoke DFSORT from a program with the address of an E32 user exit in the parameter list. Data Set Considerations on page 12 contains general information about input data sets. For specific information about the SORTIN data set, see SORTIN DD Statement on page 68. For specific information about the SORTINnn data sets, see SORTINnn DD Statement on page 70.

Chapter 1. Introducing DFSORT

11

Output Data SetsSORTOUT and OUTFIL

Output Data SetsSORTOUT and OUTFIL

DFSORT processes two types of output data sets, referred to as the SORTOUT data set (or just SORTOUT) and the OUTFIL data sets. The SORTOUT DD statement specifies the single non-OUTFIL output data set for a sort, copy, or merge application. OUTFIL processing does not apply to SORTOUT. If a SORTOUT DD statement is present, it will be used by default for a sort, copy, or merge application unless you invoke DFSORT from a program with the address of an E35 user exit in the parameter list. The FNAMES and FILES parameters of one or more OUTFIL statements specify the ddnames of the OUTFIL data sets for a sort, copy, or merge application. The parameters specified for each OUTFIL statement define the OUTFIL processing to be performed for the OUTFIL data sets associated with that statement. Each ddname specified must have a corresponding DD statement. Although the ddname SORTOUT can actually be used for an OUTFIL data set, the term SORTOUT will be used to denote the single non-OUTFIL output data set. Data Set Considerations contains general information about output data sets. For specific information about the SORTOUT data set, see SORTOUT and OUTFIL DD Statements on page 74. For specific information about the OUTFIL data sets, see SORTOUT and OUTFIL DD Statements on page 74 and OUTFIL Control Statements on page 221.

Data Set Considerations

You must define any data sets you provide for DFSORT according to the conventions your operating system requires. You can use the label checking facilities of the operating system during DFSORT processing. See Application Development Guide for details. | | | | You must describe all data sets (except those allocated with the DYNALLOC parameter) in DD statements. You must place the DD statements in the operating system input stream with the job step that allocates data sets for DFSORT processing.

Sorting or Copying Records

Input to a sort or copy application can be a blocked or unblocked QSAM or VSAM data set containing fixed- or variable-length records. QSAM input data sets can be concatenated even if they are on dissimilar devices. See SORTIN DD Statement on page 68 for the restrictions that apply. Output from a sort or copy application can be blocked or unblocked QSAM or VSAM data sets, regardless of whether the input is QSAM or VSAM. Unless OUTFIL is used to convert variable input to fixed output, or fixed input to variable output, an output data set must be the same type (fixed or variable) as the input data set. Hierarchical File System (HFS) files are supported as input and output for sort and copy applications.

12

z/OS V1R10.0 DFSORT Application Programming Guide

Data Set Considerations

Merging Records
Input to a merge application can be up to 100 blocked or unblocked QSAM or VSAM data sets containing fixed- or variable-length records. The input data sets can be either QSAM or VSAM, but not both. The records in all input data sets must already be sorted in the same order as that required for output. Output from a merge application can be blocked or unblocked QSAM or VSAM data sets, regardless of whether the input is QSAM or VSAM. Unless OUTFIL is used to convert variable input to fixed output, or fixed output to variable output, an output data set must be the same type (fixed or variable) as the input data set. Hierarchical File System (HFS) files are supported as input and output for merge applications.

Data Set Notes and Limitations

There are some considerations and limitations that you need to be aware of. These are described in the following sections. For more information about specific DFSORT data sets, see Using DD Statements on page 61.

General Considerations
Variable-length records are processed with a record descriptor word (RDW) in positions 1-4, so the data starts in position 5. Fixed-length records are processed without an RDW, so the data starts in position 1. Control statement positions should be specified accordingly. Your records can be EBCDIC, ISCII/ASCII, Japanese, and data types you define yourself. To process Japanese data types with DFSORT, you can use the IBM Double Byte Character Set Ordering Support Program (DBCS Ordering), Licensed Program 5665-360, Release 2.0, or you can use locale processing with the appropriate locale. Input and output data sets must be on devices that can be used with QSAM or VSAM. Standard system data management rules apply to all data set processing. In particular: v Be aware that when using fixed standard record format for input data sets, the first short block is treated like an End of Volume. See z/OS DFSMS Using Data Sets for more details. v Be aware that, in some cases, if a DD statement specifies a data set for output that is extended to a second or subsequent volume, and another DD statement within the same step requests the same data set, only the records on the first volume will be read, and incorrect output will result. Specifically, when a new output data set is allocated with a unit count and volume count greater than one, but specifies no volume serial numbers, one volume is allocated. If a second or succeeding DD statement within the same step requests the same data set, the same volume is allocated to it. If this job step extends the output data set to more volumes, this new volume information is not available to the second or succeeding DD statement. Thus, you should not use different DDs for a data set to be used for output and then input in the same step, unless the data set cannot be extended to a second

Chapter 1. Introducing DFSORT

13

Data Set Considerations

or subsequent volume, or is allocated with the guaranteed space attribute in the storage class. See z/OS MVS JCL Reference, SA22-7597 and z/OS DFSMS Using Data Sets, SC26-7410 for more details. The maximum record length DFSORT can handle is subject to the following limitations: v Record length can never exceed the maximum record length you specify. v Variable-length records are limited to 32756 bytes. v v v v VSAM variable-length records are limited to 32752 bytes. Fixed-length records are limited to 32760 bytes. Variable block-spanned records are limited to 32767 bytes. For a tape work data set sort, the maximum record length is limited to 32752 bytes with NOEQUALS in effect and to 32748 bytes with EQUALS in effect.

Note: If AQ format is specified, or CH format is specified and the CHALT option is in effect, the maximum record length for variable-length records is 32767 bytes, less the length of the control fields. The number of records that can be sorted using a given amount of storage is reduced by: v Processing control fields of different formats v Large numbers of control fields v Large numbers of intermediate data sets. Providing an Extended Function Support program with an EFS01 routine can limit the record length that can be used when processing variable-length records. The minimum block length for tape work data sets is 18 bytes; the minimum record length is 14 bytes.

Padding and Truncation

You can control the action that DFSORT takes when the SORTOUT LRECL is smaller than the SORTIN/SORTINnn LRECL with the TRUNC option as described in OPTION Control Statement on page 167. DFSORT truncates fixed-length records on the right when the SORTOUT LRECL is smaller than the SORTIN/SORTINnn LRECL provided that: v The application is not a conventional merge or tape work data set sort. v TRUNC=RC16 is not in effect. You can control the action that DFSORT takes when a variable-length output record is longer than the LRECL of the SORTOUT or OUTFIL data set to which it is to be written by using the VLLONG or NOVLLONG option as described in OPTION Control Statement on page 167. You can control the action that DFSORT takes when the SORTOUT LRECL is larger than the SORTIN/SORTINnn LRECL with the PAD option as described in OPTION Control Statement on page 167. DFSORT pads fixed-length records with binary zeros on the right when the SORTOUT LRECL is larger than the SORTIN LRECL provided that: v The Blockset technique is selected. v The application is a sort or copy.

14

z/OS V1R10.0 DFSORT Application Programming Guide

Data Set Considerations

v PAD=RC16 is not in effect. DFSORT does not pad or truncate records returned from an E15 or E35 user exit since it expects the exit to pad or truncate each record appropriately. You can use INREC, OUTREC, and OUTFIL to pad, truncate, and reformat records. See INREC Control Statement on page 125 and OUTREC Control Statement on page 365 for details. See Use ICEGENER Instead of IEBGENER on page 696 for information about padding and truncating with ICEGENER. For more information about Blockset and other DFSORT techniques, see Specify Efficient Sort/Merge Techniques on page 683.

QSAM Considerations
v If you use DSN=NULLFILE on your DD statement for an input data set, a system restriction prevents DFSORT from using the EXCP access method. v Empty input data sets can be used. v If any of the input data sets are on tape without standard labels, DCB parameters must be specified on their DD statements. v ISO/ANSI Version 1 tape files can only be used as inputnever as output. v DFSORT sets appropriate BUFNO values for the input and output data sets; specifying BUFNO in the DD statements for these data sets has no effect. See SORTIN DD Statement on page 68 for additional considerations.

VSAM Considerations
v You can have DFSORT process VSAM records as fixed-length (F) or variable-length (V). When you use VSAM input, DFSORT selects fixed-length processing if you specify RECORD TYPE=F or variable-length processing if you specify RECORD TYPE=V. If you do not specify RECORD TYPE=x, DFSORT selects the record type to use according to the rules described in the discussion of the TYPE operand in RECORD Control Statement on page 394. The record type selected affects how the records are treated, and how control statement positions should be specified, as follows: Variable-length processing: An RRDS, KSDS, ESDS or VRRDS can always be processed as variable-length. For VSAM input, DFSORT reads each record and prepends a record descriptor word (RDW) to it. For VSAM output, DFSORT removes the RDW before writing each record. Since DFSORT uses an RDW in positions 1-4 to process variable-length records, the data starts in position 5. Control statement positions should be specified accordingly. Fixed-length processing: An RRDS can always be processed as fixed-length. A KSDS, ESDS or VRRDS used for input should only be processed as fixed-length if all of its records have a length equal to the maximum record size defined for the cluster. Otherwise, input records which are shorter than the maximum record size are padded with bytes that may or may not be zeros (that is, garbage bytes). DFSORT does not use an RDW to process fixed-length records, so the data starts in position 1. Control statement positions should be specified accordingly. v If a data set is password protected, passwords can be entered at the console or (with some restrictions) through routines at user exits E18, E38, and E39. Note: Passwords cannot be handled in this way for OUTFIL data sets.
Chapter 1. Introducing DFSORT

15

Data Set Considerations

v If VSAMIO and RESET are in effect, a data set defined with REUSE can be used for both input and output for a sort; that is, the data set can be sorted in-place. v A data set used for input or output must have been previously defined. v If VSAMEMT is in effect, an empty input data set is processed as having zero records. v VSAM data sets must not be concatenated (system restriction). v VSAM and non-VSAM input data sets must not be specified together for a sort, merge or copy application. v If output is a VSAM key-sequenced data set (KSDS), the key must be the first control field (or the key fields must be in the same order as the first control field). VSAM does not allow you to store records with duplicate primary keys. v Any VSAM exit function available for input data sets can be used except EODAD. See the description of E18 use with VSAM in Chapter 4, Using Your Own User Exit Routines, on page 413. v You must build the VSAM exit list with the VSAM EXLST macro instruction giving the addresses of your routines that handle VSAM exit functions. v When processing variable-length records with VSAM input and non-VSAM output, the output LRECL must be at least 4 bytes greater than the maximum record size defined for the cluster. Non-VSAM variable-length records have a record descriptor word (RDW) field 4 bytes long at the beginning of each record, but VSAM records do not. The record size defined for the VSAM cluster is therefore 4 bytes less than the non-VSAM LRECL. v An output data set defined without REUSE is processed as MOD. v If RESET is in effect, an output data set defined with REUSE is processed as NEW. If NORESET is in effect, an output data set defined with REUSE is processed as MOD. v DFSORT cannot access VSAM data sets in RLS mode, that is, RLS=CR and RLS=NRI are not supported for VSAM input and output data sets.

HFS File Considerations

Hierarchical File System (HFS) files can be used for input and output, but are only supported by the Blockset technique. If Blockset is not selected for a DFSORT application that uses HFS files, DFSORT will issue an error message and terminate. You should be familiar with the information found in z/OS UNIX System Services Users Guide regarding HFS files if you use them. DFSORT uses BSAM to access HFS files and is thus subject to all of the capabilities and restrictions that entails, as described in z/OS DFSMS Using Data Sets.

Installation Defaults
| | | | | | | | | | When your system programmers installed DFSORT, they selected separate sets of installation defaults for the following eight installation environments: ICEAM1 (JCL) is the batch direct invocation environment. This set of installation defaults is used at run time when DFSORT is invoked directly (that is, not through programs) by batch jobs, provided that an enabled time-of-day installation environment (ICETDx) is not activated. is the batch program invocation environment. This set of installation defaults is used at run time when

ICEAM2 (INV)

16

z/OS V1R10.0 DFSORT Application Programming Guide

Installation Defaults
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | ICEAM3 (TSO) DFSORT is invoked through batch programs, provided that an enabled time-of-day installation environment (ICETDx) is not activated. is the TSO direct invocation environment. This set of installation defaults is used at run time when DFSORT is invoked directly (that is, not through programs) by foreground TSO users, provided that an enabled time-of-day installation environment (ICETDx) is not activated. is the TSO program invocation environment. This set of installation defaults is used at run time when DFSORT is invoked through programs by foreground TSO users, provided that an enabled time-of-day installation environment (ICETDx) is not activated. is the first time-of-day installation environment. This set of installation defaults is used at run time when it is activated for the time-of-day of the run, provided it is enabled by the installation environment (ICEAMx) in effect. is the second time-of-day installation environment. This set of installation defaults is used at run time when it is activated for the time-of-day of the run, provided it is enabled by the installation environment (ICEAMx) in effect. is the third time-of-day installation environment. This set of installation defaults is used at run time when it is activated for the time-of-day of the run, provided it is enabled by the installation environment (ICEAMx) in effect. is the fourth time-of-day installation environment. This set of installation defaults is used at run time when it is activated for the time-of-day of the run, provided it is enabled by the installation environment (ICEAMx) in effect.

ICEAM4 (TSOINV)

ICETD1 (TD1)

ICETD2 (TD2)

ICETD3 (TD3)

ICETD4 (TD4)

The selected installation defaults can affect the way your applications run, and in many cases can be overridden by specifying the appropriate run-time parameters (see Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details). This document assumes that DFSORT is running with the installation defaults it was delivered with (that is, with the IBM-supplied installation defaults). You can use an ICETOOL job similar to the following one to display a report of the installation defaults to be used at run-time.

Chapter 1. Introducing DFSORT

17

Installation Defaults
//DFRUN JOB A402,PROGRAMMER //LISTDEF EXEC PGM=ICETOOL //TOOLMSG DD SYSOUT=A //DFSMSG DD SYSOUT=A //SHOWDEF DD SYSOUT=A //TOOLIN DD * DEFAULTS LIST(SHOWDEF) /* Figure 3. Using ICETOOL to List Installation Defaults

See Chapter 6, Using ICETOOL, on page 479 and DEFAULTS Operator on page 497 for more information on using ICETOOL and the DEFAULTS operator. The functions of the available installation options are summarized below. z/OS DFSORT Installation and Customization contains complete descriptions of the available installation options, as well as planning considerations and general information about installing DFSORT. Step-by-step installation procedures are listed in the z/OS Program Directory. Parameter | | | | | | | Function

INV|JCL|TSO|TSOINV|TD1|TD2|TD3|TD4 Specifies the invocation installation environment (ICEAMx) or time-of-day installation environment (ICETDx) for which this set of installation defaults is to be used. ENABLE day ABCODE ALTSEQ ARESALL ARESINV CFW CHALT CHECK Specifies whether ICETDx installation defaults are to be used if activated for this ICEAMx installation environment. Specifies the time ranges for each day of the week when this ICETDx installation environment is to be activated. Specifies the ABEND code used when DFSORT abends for a critical error. Specifies changes to the ALTSEQ translation table. Specifies the number of bytes reserved above 16MB virtual for system use. Specifies the number of bytes reserved above 16MB virtual for the invoking program when DFSORT is program invoked. Specifies whether DFSORT can use cache fast write when processing work data sets. Translates format CH as well as format AQ, or translates format AQ only. Specifies whether record count checking is suppressed for applications that use an E35 user exit routine without an output data set. Specifies whether DFSORT can use control interval access for VSAM data sets. Specifies the library for COBOL E15 and E35 routines. Specifies whether a SORTDIAG DD statement is to be simulated for DFSORT applications. Specifies the maximum amount of storage available to DFSORT for dynamic storage adjustment of Blockset sort applications.

CINV COBEXIT DIAGSIM DSA

18

z/OS V1R10.0 DFSORT Application Programming Guide

Installation Defaults
DSPSIZE DYNALOC | | DYNAUTO DYNSPC Specifies the maximum amount of data space to use for dataspace sorting. Specifies the default values for device name and number of work data sets to be dynamically allocated. These default values are used in conjunction with the DYNAUTO installation option and the DYNALLOC run-time option. Specifies whether work data sets are dynamically allocated automatically. Specifies the total default primary space allocation for all of the dynamically allocated work data sets when the file size is unknown. Specifies the name of a user-written Extended Function Support program to be called by DFSORT. Specifies whether the order of records that collate identically is preserved from input to output. Specifies the action taken if DFSORT encounters a critical error. Specifies whether DFSORT deletes its ESTAE recovery routine early or uses it for the entire run. Specifies whether DFSORT terminates or continues when it receives certain invalid return codes from E15 or E35 user exit routines. Specifies the maximum total amount of available storage to be used at any one time by all Hipersorting and memory object sorting applications. Specifies the maximum total amount of old storage to be used at any one time by all Hipersorting and memory object sorting applications. Specifies the minimum amount of available storage to be reserved for use by non-Hipersorting and non-memory object sorting applications. Specifies whether DFSORT treats run-time options FILSZ=n and SIZE=n as exact or estimated file sizes. Specifies the name that ICEGENER is to use to transfer control to the IEBGENER system utility. (ICEGENER is DFSORTs facility for IEBGENER jobs.) Specifies the action to be taken by ICEGENER for LRECL padding. Specifies the action to be taken by ICEGENER for LRECL truncation. Specifies the maximum amount of Hiperspace to use for Hipersorting. Specifies a percentage which represents the approximate amount of data compaction achieved by using the Improved Data Recording Capability feature of IBM tape devices that support compaction. Specifies whether DFSORT passes control to your sites ICEIEXIT routine. Specifies whether the checkpoint/restart facility is ignored if it is
Chapter 1. Introducing DFSORT

EFS EQUALS ERET ESTAE EXITCK

EXPMAX

EXPOLD

EXPRES

FSZEST GENER

GNPAD GNTRUNC HIPRMAX IDRCPCT

IEXIT IGNCKPT

19

Installation Defaults
requested at run-time and the Blockset technique (which does not support the checkpoint/restart facility) can be used. IOMAXBF LIST LISTX LOCALE MAXLIM MINLIM MOSIZE MSGCON MSGDDN MSGPRT NOMSGDD NULLOFL NULLOUT ODMAXBF OUTREL OUTSEC OVERRGN OVFLO PAD PARMDDN RESALL RESET RESINV Specifies an upper limit to the amount of buffer space to be used for SORTIN, SORTINnn and SORTOUT data sets. Specifies whether DFSORT prints control statements. Specifies whether DFSORT prints control statements returned by an Extended Function Support program. Specifies whether locale processing is to be used and, if so, designates the active locale. Specifies an upper limit to the amount of main storage available to DFSORT below 16MB virtual. Specifies a lower limit to the amount of main storage available to DFSORT. Specifies the maximum size of a memory object to use for memory object sorting Specifies the class of program messages DFSORT writes to the master console. Specifies an alternate name for the message data set. Specifies the class of program messages DFSORT writes to the message data set. Specifies whether DFSORT terminates or continues when the message data set is required but is not available. Specifies the action to be taken by DFSORT when there are no data records for an OUTFIL data set. Specifies the action to be taken by DFSORT when there are no records for the SORTOUT data set. Specifies an upper limit to the amount of buffer space to be used for each OUTFIL data set. Specifies whether unused temporary output data set space is released. Specifies whether DFSORT uses automatic secondary allocation for output data sets that are temporary or new. Specifies the amount of main storage above the REGION value available to Blockset. Specifies the action to be taken by DFSORT when BI, FI, PD or ZD summary fields overflow. Specifies the action to be taken by DFSORT for LRECL padding. Specifies an alternate ddname for the DFSORT DFSPARM data set. Reserves storage for system and application use when SIZE/MAINSIZE=MAX is in effect. Specifies whether DFSORT processes a VSAM output data set defined with REUSE as a NEW or MOD data set. Reserves storage for programs invoking DFSORT when SIZE/MAINSIZE=MAX is in effect.

20

z/OS V1R10.0 DFSORT Application Programming Guide

Installation Defaults
SDB Specifies whether DFSORT should use the system-determined optimum block size for output data sets when the block size is zero. Specifies whether DFSORT and ICETOOL should use the system-determined optimum block size for message and list data sets when the block size is zero. Specifies the maximum amount of main storage available to DFSORT. Specifies whether DFSORT produces SMF type-16 records. Specifies whether DFSORT uses the reformatted record length for the SORTOUT LRECL. Specifies whether DFSORT searches a system or private library for the modules used with a tape work data set sort or Conventional merge. Specifies the action to be taken by DFSORT when incomplete spanned records are detected. Specifies a user SVC number for DFSORT. Specifies whether DFSORT treats numeric 0 and +0 values as signed (that is, different) or unsigned (that is, the same). Specifies whether DFSORT passes control to your sites ICETEXIT routine. Specifies an upper limit to the total amount of main storage above and below 16MB virtual available to DFSORT when SIZE/MAINSIZE=MAX is in effect. Specifies the action to be taken by DFSORT for LRECL truncation. Specifies whether the sequence of output records is verified. Specifies whether virtual allocation of work data sets is accepted. Specifies whether DFSORT truncates long variable-length output records. Specifies whether DFSORT pads short variable-length compare fields. Specifies whether DFSORT continues processing if a short variable-length control field, compare field or summary field is found. Specifies the number of VSAM buffers DFSORT can use. Specifies whether DFSORT accepts an empty VSAM input data set. Specifies whether DFSORT allows a VSAM data set defined with REUSE to be sorted in-place. Specifies whether unused temporary work data set space is released. Specifies whether DFSORT uses automatic secondary allocation for temporary work data sets. Specifies the sliding or fixed century window.

SDBMSG

SIZE SMF SOLRF SORTLIB

SPANINC | SVC SZERO TEXIT TMAXLIM

TRUNC VERIFY VIO VLLONG VLSCMP VLSHRT

VSAMBSP VSAMEMT VSAMIO WRKREL WRKSEC Y2PAST

Chapter 1. Introducing DFSORT

21

Installation Defaults
ZDPRINT Specifies whether DFSORT produces printable numbers from positive ZD fields that result from summarization.

Tables showing all the possible sources of specification and order of override for each option are shown in Appendix B, Specification/Override of DFSORT Options, on page 741.

Migrating to DFSORT from Other Sort Products

| | | | | | | | | If you are migrating to DFSORT, you should run an ICETOOL DEFAULTS report to review the installation defaults set at your site. In particular, the options shown in the table that follows can make DFSORT operate more like other sort products, thus making migration easier. The installation options, described in z/OS DFSORT Installation and Customization, change the way DFSORT works globally by default. The run-time options, described in Chapter 2, Invoking DFSORT with Job Control Language, on page 25 and Chapter 3, Using DFSORT Program Control Statements, on page 81, can be used to override the installation defaults for specific jobs.
Table 3. Options That Can Ease Migration Installation ABCODE=MSG/n DYNALOC=(d,n) DYNAUTO=YES/IGNWKDD/NO DYNSPC=n EQUALS=YES/NO/VBLKSET EXITCK=STRONG/WEAK FSZEST=YES/NO NOMSGDD=QUIT/ALL/CRITICAL/NONE PARMDDN=ddname RESET=YES/NO SORTLIB=SYSTEM/PRIVATE SZERO=YES/NO VLLONG=YES/NO VLSCMP=YES/NO VSAMEMT=YES/NO VSAMIO=YES/NO ZDPRINT=YES/NO SZERO/NOSZERO VLLONG/NOVLLONG VLSCMP/NOVLSCMP VSAMEMT/NVSAMEMT VSAMIO/NOVSAMIO ZDPRINT/NZDPRINT RESET/NORESET DYNALLOC=(d,n) DYNALLOC=(d,n) DYNSPC=n EQUALS/NOEQUALS EXITCK=STRONG/WEAK FILSZ=n/En/Un Run-Time

DFSORT Messages and Return Codes

You can determine, during installation or run-time, whether DFSORT writes messages to the message data set, to the master console, or to both. You can also direct an Extended Function Support program to write messages to the message data set. Messages written to the message data set can be either critical error messages, informational error messages, or diagnostic messages, as determined during installation or run-time.

22

z/OS V1R10.0 DFSORT Application Programming Guide

DFSORT Messages and Return Codes

Messages written to the master console can be either critical error messages or informational error messages, as determined during installation. See z/OS DFSORT Messages, Codes and Diagnosis Guide for complete information about DFSORT messages. For successful completion, DFSORT passes back a return code of 0 or 4 to the operating system or the invoking program. For unsuccessful completion due to an unsupported operating system, DFSORT passes back a return code of 24 to the operating system or the invoking program. For unsuccessful completion with NOABEND in effect, DFSORT passes back a return code of 16 or 20 to the operating system or the invoking program. For unsuccessful completion with ABEND in effect, DFSORT issues a user abend with the appropriate code as specified by the ABCODE installation option (either the error message number or a number between 1 and 99). The meanings of the return codes that DFSORT passes back (in register 15) are: 0 4 Successful completion. DFSORT completed successfully. Successful completion. DFSORT completed successfully, and: v OVFLO=RC4 was in effect and summary fields overflowed, or v PAD=RC4 was in effect and the SORTOUT LRECL was larger than the SORTIN/SORTINnn LRECL (LRECL padding), or v TRUNC=RC4 was in effect and the SORTOUT LRECL was smaller than the SORTIN/SORTINnn LRECL (LRECL truncation), or v SPANINC=RC4 was in effect and one or more incomplete spanned records was detected, or v NULLOUT=RC4 was in effect and there were no records for the SORTOUT data set, or v NULLOFL=RC4 was in effect and there were no data records for an OUTFIL data set. 16 | 20 Unsuccessful completion. DFSORT detected an error that prevented it from completing successfully. Message data set missing. Installation option NOMSGDD=QUIT was in effect and neither a message data set DD statement nor a SYSOUT DD statement was provided. Unsupported operating system. This release of DFSORT does not support this operating system.

24

Use Blockset Whenever Possible

Blockset is DFSORTs most efficient technique. It supports many features not supported by DFSORTs less efficient Peerage/Vale and Conventional techniques (see ICE189A in z/OS DFSORT Messages, Codes and Diagnosis Guide for a list of these features). DFSORT always selects Blockset for a copy application. DFSORT selects Blockset for a sort or merge application unless something prevents it from doing so (see ICE800I in z/OS DFSORT Messages, Codes and Diagnosis Guide for a list of reasons Blockset cannot be used). Note: Blockset cannot be used to process BDAM data sets.
Chapter 1. Introducing DFSORT

23

Use Blockset Whenever Possible

Message ICE143I indicates whether Blockset or a less efficient technique was selected for a particular run. If Blockset was not selected for a sort or merge application, check the reason code in message ICE800I, which indicates the reason Blockset could not be used. If you did not get message ICE800I, add the following DD statements to your application and rerun it:
//SORTDIAG DD DUMMY //SYSOUT DD SYSOUT=*

If possible and appropriate, remove the obstacle that is causing Blockset not to be selected.

24

z/OS V1R10.0 DFSORT Application Programming Guide

Chapter 2. Invoking DFSORT with Job Control Language

Using the JCL . . . . . . . . . . . . . Using the JOB Statement . . . . . . . . . . Using the EXEC Statement . . . . . . . . . Specifying EXEC Statement Cataloged Procedures SORT Cataloged Procedure . . . . . . . SORTD Cataloged Procedure . . . . . . Specifying EXEC/DFSPARM PARM Options . . Aliases for PARM Options . . . . . . . . Using DD Statements . . . . . . . . . . . Duplicate Ddnames. . . . . . . . . . . Shared Tape Units . . . . . . . . . . . System DD Statements . . . . . . . . . Program DD Statements . . . . . . . . . 25 27 27 27 27 28 29 60 61 64 64 64 66 SORTLIB DD Statement . . . . . SYMNAMES DD and SYMNOUT DD Statements . . . . . . . . . . SORTIN DD Statement . . . . . SORTINnn DD Statement . . . . . SORTWKdd DD Statement . . . . SORTOUT and OUTFIL DD Statements SORTCKPT DD Statement . . . . SORTCNTL DD Statement . . . . DFSPARM DD Statement . . . . . SORTDKdd DD Statement . . . . SORTDIAG DD Statement . . . . SORTSNAP DD Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 . . . . . . . . . . . 68 68 70 72 74 76 76 77 79 79 79

Using the JCL

Your operating system uses the job control language (JCL) you supply with your DFSORT program control statements to: v Identify you as an authorized user v Allocate the necessary resources to run your job v Run your job v Return information to you about the results v Terminate your job. | You must supply JCL statements with every DFSORT job you submit. Required JCL includes a JOB statement, an EXEC statement, and several DD statements. The statements you need and their exact form depend upon whether you: v Use an EXEC statement in the input job stream or a system macro instruction within another program to invoke DFSORT v Use EXEC statement cataloged procedures to invoke DFSORT v Specify various DFSORT control statements or PARM options v Want to use program exits to activate routines of your own | v Use dynamic link-editing v Want to see diagnostic messages. The JCL statements and their functions are listed below. Details on coding the individual statements are presented in subsequent sections. JCL Statement //JOBLIB DD //STEPLIB DD //SORTLIB DD //SYSOUT DD1 //SYMNAMES DD Description Defines your program link library if it is not already known to the system Same as //JOBLIB DD Defines the data set that contains special load modules if it is not already known to the system Defines the message data set Defines the SYMNAMES data set containing statements to be used for symbol processing

Copyright IBM Corp. 1973, 2006

25

Using the JCL

//SYMNOUT DD //SORTIN DD1 //SORTINnn DD1 //SORTOUT DD //outfil DD //SORTWKdd DD1 //DFSPARM DD1 //SYSIN DD //SORTCNTL DD
1 1

Defines the data set in which SYMNAMES statements and the symbol table are to be listed Defines the input data set for a sort or copy Defines the input data sets for a merge Defines the SORTOUT output data set for a sort, merge, or copy Defines an OUTFIL output data set for a sort, merge, or copy Defines intermediate storage data sets for a sort Contains DFSORT PARM options and program control statements Contains DFSORT program control statements Same as //SYSIN DD Specifies that all messages and program control statements be printed Defines the data set for checkpoint records Defines the data set for output from a system ABEND dump routine Same as //SYSUDUMP DD Same as //SYSUDUMP DD Defines the snap dump data set dynamically allocated by DFSORT Defines the data set containing exit routines (as specified in the MODS program control statement).

//SORTDIAG DD //SORTCKPT DD //SYSUDUMP DD //SYSMDUMP DD //SYSABEND DD //SORTSNAP DD //ddname

The following DD statements are necessary only for dynamic link-editing of exit routines //SYSPRINT DD //SYSUT1 DD //SYSLIN DD //SYSLMOD DD //SORTMODS DD
1

Defines the message data set for the linkage editor Defines the intermediate storage data set for the linkage editor Defines the data set for control information for the linkage editor Defines the data set for output from the linkage editor Defines the temporary partitioned data set for user exit routines from SYSIN.

These are the default ddnames with which DFSORT was delivered. SYSOUT and DFSPARM may have been changed during DFSORT installation. You can change all of the indicated ddnames at run time. For override information, see Appendix B, Specification/Override of DFSORT Options, on page 741.

26

z/OS V1R10.0 DFSORT Application Programming Guide

Using The JOB Statement

Using the JOB Statement

The JOB statement is the first JCL statement of your job. It must contain a valid job name in the name field and the word JOB in the operation field. All parameters in the operand field are optional, although your site may have made information such as account number and the name of the programmer mandatory:
//jobname JOB accounting information, programmers name, etc.

Using the EXEC Statement

The EXEC statement is the first JCL statement of each job step or of each procedure step in a cataloged procedure. It identifies DFSORT to the operating system. You can also specify DFSORT options on the EXEC statement. The format of the EXEC statement is:

//stepname EXEC

PGM= SORT ICEMAN PROC= SORT SORTD SORT SORTD

,
, PARM = options

, other parameters

If you use a cataloged procedure (discussed in detail below), specify PROC=SORT or PROC=SORTD. You can omit PROC= and simply specify SORT or SORTD. However, PROC= can remind you that a cataloged procedure is being used. If you do not use a cataloged procedure, use PGM= either with the actual name of the sort module (ICEMAN) or with one of its aliases: SORT, IERRCO00, or IGHRCO00. Be sure that the alias has not been changed at your site.

Specifying EXEC Statement Cataloged Procedures

A cataloged procedure is a set of JCL statements, including DD statements, that has been assigned a name and placed in a partitioned data set called the procedure library. Two cataloged procedures are supplied with the program: SORT and SORTD. Specify them in the first parameter of the EXEC statement by PROC=SORT, PROC=SORTD, or simply SORT or SORTD.

SORT Cataloged Procedure

You can use the supplied SORT cataloged procedure when you include user routines that require link-editing. Using this procedure without using link-edited user routines is inefficient because the SORT cataloged procedure allocates linkage editor data sets whether or not you include user routines. When you specify EXEC PROC=SORT or EXEC SORT, the following JCL statements are generated:

Chapter 2. Invoking DFSORT with Job Control Language

27

Using The EXEC Statement

//SORT //STEPLIB //SORTLIB //SYSOUT //SYSPRINT //SYSLMOD //SYSLIN //SYSUT1 //

EXEC DD DD DD DD DD DD DD

PGM=ICEMAN DSNAME=yyy,DISP=SHR DSNAME=xxx,DISP=SHR SYSOUT=A DUMMY DSNAME=&GOSET,UNIT=SYSDA,SPACE=(3600,(20,20,1)) DSNAME=&LOADSET,UNIT=SYSDA,SPACE=(80,(10,10)) DSNAME=&SYSUT1,SPACE=(1024,(60,20)), UNIT=(SYSDA,SEP=(SORTLIB,SYSLMOD,SYSLIN))

00 10 20 30 40 50 60 70 80

Line 00 10

Explanation The stepname of the procedure is SORT. This EXEC statement initiates the program, which is named ICEMAN. The STEPLIB DD statement defines the data set containing the DFSORT program modules. If DFSORT was installed as part of the normal system link libraries, the STEPLIB DD statement is unnecessary. It is needed only if DFSORT resides in a separate link library which is not part of the link list. (Your installations system programmers can give you this information.) The STEPLIB DD statement shown assumes that the data set name represented by yyy is cataloged. The SORTLIB DD statement defines a private data set containing the modules needed for a sort using tape work files or a merge using the Conventional technique. The data set is cataloged, and the data set name represented by xxx was specified at installation time; it can be SYS1.SORTLIB. If the modules were installed in a system library and installation option SORTLIB=SYSTEM is used, the SORTLIB DD statement is unnecessary and is ignored unless dynamic link of user exits is used.

20

30 40 50

Defines an output data set for system use (messages). It is directed to system output class A. Defines SYSPRINT as a dummy data set because linkage editor diagnostic output is not required. Defines a data set for linkage editor output. Any system disk device is acceptable for the output. Space for 20 records with an average length of 3600 bytes is requested; this is the primary allocation. Space for 20 more records is requested if the primary space allocation is not sufficient; this is the secondary allocation, which is requested each time primary space is exhausted. The last value is space for a directory, which is required because SYSLMOD is a new partitioned data set. The SYSLIN data set is used by the program for linkage editor control statements. It is created on any system disk device, and it has space for 10 records with an average length of 80 bytes. If the primary space allocation is exhausted, additional space is requested in blocks large enough to contain 10 records. No directory space is necessary. The SYSUT1 DD statement defines a work data set for the linkage editor.

60

70/80

SORTD Cataloged Procedure

You can use the supplied SORTD cataloged procedure when you do not include user routines or when you include user routines that do not require link-editing.

28

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

When you specify EXEC PROC=SORTD or EXEC SORTD, the following JCL statements are generated:
//SORT EXEC PGM=ICEMAN //STEPLIB DD DSNAME=yyy,DISP=SHR //SORTLIB DD DSNAME=xxx,DISP=SHR //SYSOUT DD SYSOUT=A 00 10 20 30

Line 00 10

Explanation The stepname of the SORTD procedure is SORT The STEPLIB DD statement defines the data set containing the DFSORT program modules. If DFSORT was installed as part of the normal system link libraries, the STEPLIB DD statement is unnecessary. It is needed only if DFSORT resides in a separate link library which is not part of the link list. (Your installations system programmers can give you this information.) The STEPLIB DD statement shown assumes that the data set name represented by yyy is cataloged. The SORTLIB DD statement defines a private data set that contains the modules needed for a sort using tape work files or a merge that uses the Conventional technique. The data set name of the program subroutine library, represented by xxx, is specified at installation time; it can be SYS1.SORTLIB. If the modules were installed in a system library and installation option SORTLIB=SYSTEM is used, then the SORTLIB DD statement is unnecessary and is ignored unless dynamic link edit of user exits is used.

20

30

Directs messages to system output class A

Specifying EXEC/DFSPARM PARM Options

When you invoke DFSORT with JCL, you can specify some DFSORT options on the PARM parameter of the EXEC statement as illustrated on the following page. These options include EFS, LIST, NOLIST, LISTX, NOLISTX, MSGPRT, and MSGDDN, which are ignored if specified in an OPTION statement in SYSIN. Full override and applicability details are listed in Appendix B, Specification/Override of DFSORT Options, on page 741. If you use the DFSPARM DD statement instead, you can specify both EXEC PARM options and DFSORT control statements in a single source data set that overrides all other sources. See DFSPARM DD Statement on page 77. Details of aliases for PARM options are given under the description of individual options. Aliases for PARM Options on page 60 summarizes the available aliases. | | | | | DFSORT accepts but does not process the following EXEC/DFSPARM PARM options: BALANCE, BALN, BIAS=value, BMSG, CASCADE, CMP=value, CPU, CRCX, DEBUG, DIAG, ELAP, EXCPVR=value, IO, INCOR=value, INCORE=value, LRGSORT, L6=value, L7=value, NOCOMMAREA, NOINC, NOIOERR, NOSTIMER, OPT=value, OSCL, PEER, POLY, PRINT121 and STIMER. Note: If DEBUG is specified as the first value in a DFSPARM statement, it will be interpreted as a DEBUG control statement rather than as a DFSPARM PARM option.

Chapter 2. Invoking DFSORT with Job Control Language

29

Using The EXEC Statement

| | | | | | | | | | An option shown in the form parameter=value can also be specified in the equivalent form parameter(value) or parameter=(value). For example, the following are equivalent: v DYNALLOC=SYSDA v DYNALLOC(SYSDA) v DYNALLOC=(SYSDA) An option shown in the form parameter=(list) can also be specified in the equivalent form parameter(list). For example, the following are equivalent: v DYNALLOC=(SYSDA,5) v DYNALLOC(SYSDA,5)

30

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

|
,PARM=

, ABEND NOABEND ARESALL= n nK nM AVGRLEN=n BSAM CINV NOCINV COBEXIT= COB1 COB2 DSA=n DSPSIZE= MAX n DYNALLOC = d (,n) (d,n) OFF DYNSPC=n EFS= name NONE EQUALS NOEQUALS E15=COB E35=COB FILSZ= x Ex Ux HIPRMAX= OPTIMAL n p% LIST NOLIST LISTX NOLISTX LOCALE= name CURRENT NONE MSGDDN=ddname MOSIZE= MAX n %p MSGPRT= ALL CRITICAL NONE NULLOUT= RC0 RC4 RC16 ODMAXBF= n nK nM OUTREL NOOUTREL

Figure 4. Syntax Diagram for EXEC PARM (Part 1 of 3)

Chapter 2. Invoking DFSORT with Job Control Language

31

Using The EXEC Statement

OVFLO=

RC0 RC4 RC16 PAD= RC0 RC4 RC16 RESALL= n nK nM RESET NORESET SDB= LARGE YES INPUT NO SIZE= n nK nM MAX MAX-m MAX-mK MAX-mM SKIPREC=z SOLRF NOSOLRF SPANINC= RC0 RC4 RC16 STOPAFT=n SZERO NOSZERO TRUNC= RC0 RC4 RC16 VERIFY NOVERIFY VLLONG NOVLLONG VLSCMP NOVLSCMP VLSHRT NOVLSHRT VSAMEMT NOVSAMENT VSAMIO NOVSAMIO

Figure 4. Syntax Diagram for EXEC PARM (Part 2 of 3)

32

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

WRKREL NOWRKREL WRKSEC NOWRKSEC Y2PAST= s f ZDPRINT NZDPRINT

Figure 4. Syntax Diagram for EXEC PARM (Part 3 of 3)

ABEND or NOABEND

ABEND NOABEND

Temporarily overrides the ERET installation option, which specifies whether DFSORT abends or terminates with a return code of 16 if your sort, copy, or merge is unsuccessful. ABEND specifies that if your sort, copy, or merge is unsuccessful, DFSORT abends with a user completion code equal to the appropriate message number or with a user-defined number between 1 and 99, as set during installation with installation option ABCODE=n. When DEBUG ABEND is in effect, a user abend code of zero may be issued when a tape work data set sort or Conventional merge is unsuccessful. NOABEND specifies that an unsuccessful sort, copy, or merge terminates with a return code of 16. Note: RC16=ABE and NORC16 can be used instead of ABEND and NOABEND, respectively. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options ARESALL

ARESALL=

n nK nM

Chapter 2. Invoking DFSORT with Job Control Language

33

Using The EXEC Statement

Temporarily overrides the ARESALL installation option, which specifies the number of bytes to be reserved above 16MB virtual for system use. For more information, see the discussion of the ARESALL option in OPTION Control Statement on page 167. n specifies that n bytes of storage are to be reserved. Limit: 8 digits. nK specifies that n times 1024 bytes of storage are to be reserved. Limit: 5 digits. nM specifies that n times 1048576 bytes of storage are to be reserved. Limit: 2 digits. Note: RESERVEX=value can be used instead of ARESALL=value. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. AVGRLEN

AVGRLEN=n

Specifies the average input record length in bytes for variable-length record sort applications. For more information, see the discussion of the AVGRLEN option in OPTION Control Statement on page 167. n specifies the average input record length. The value for n must be between 4 and 32767 and must include the 4 byte record descriptor word (RDW).

Note: L5=n can be used instead of AVGRLEN=n. Default: If AVGRLEN=n is not specified, DFSORT will use one-half of the maximum record length as the average record length. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. BSAM

BSAM

Temporarily bypasses the EXCP access method normally used for input and output data sets. BSAM is ignored for VSAM input and output data sets. Note that if Blockset is not selected and BSAM processing is used with concatenated SORTIN input and both null and non-null data sets are specified, all null data sets must precede all non-null data sets; otherwise, the results are unpredictable.

34

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

Attention: This option can degrade performance. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. CINV or NOCINV

CINV NOCINV

Temporarily overrides the CINV installation option, which specifies whether DFSORT can use control interval access for VSAM data sets. For more information, see the explanation of the CINV option in OPTION Control Statement on page 167. CINV NOCINV directs DFSORT to use control interval access when possible for VSAM data sets. directs DFSORT not to use control interval access.

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. COBEXIT

COBEXIT=

COB1 COB2

Temporarily overrides the COBEXIT installation option, which specifies the library for COBOL E15 and E35 routines. COB1 specifies that COBOL E15 and E35 routines are run with the OS/VS COBOL run-time library or, in some cases, with no COBOL run-time library. COBEXIT=COB1 is obsolete, but is still available for compatibility reasons. Note that Language Environment is the only run-time library for COBOL supported by IBM service. COB2 specifies that COBOL E15 and E35 routines are run with either the VS COBOL II run-time library or the Language Environment run-time library. Note that Language Environment is the only run-time library for COBOL supported by IBM service.

Chapter 2. Invoking DFSORT with Job Control Language

35

Using The EXEC Statement

Note: The DFSORT documents only discuss the Language Environment run-time library, and assume that COBEXIT=COB2 is in effect. Although it is possible to run with older run-time libraries, and with COBEXIT=COB1, these are not recommended or discussed, and are not supported by IBM service. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. DSA

DSA=n

Temporarily overrides the DSA installation option, which specifies the maximum amount of storage available to DFSORT for dynamic storage adjustment of a Blockset sort application when SIZE/MAINSIZE=MAX is in effect. For more information, see the discussion of the DSA option in OPTION Control Statement on page 167. n specifies that DFSORT can dynamically adjust storage to improve performance, subject to a limit of n MB. n must be n value between 0 and 2000. If n is less than or equal to the TMAXLIM value in effect, n is set to 0 to indicate that storage will not be dynamically adjusted.

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. DSPSIZE

DSPSIZE=

MAX n

Temporarily overrides the DSPSIZE installation option which specifies the maximum amount of data space to be used for dataspace sorting. For more information, see the discussion of the DSPSIZE option in OPTION Control Statement on page 167. MAX specifies that DFSORT dynamically determines the maximum amount of data space to be used for dataspace sorting. In this case, DFSORT bases its data space usage on the size of the file being sorted and the paging activity of the system. specifies the maximum amount, in megabytes, of data space to be used for dataspace sorting. n must be a value between 0 and 9999. The actual amount of data space used does not exceed n, but may be less depending on the size of the file being sorted and the paging activity of the system.

36

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

| If n is zero, dataspace sorting is not used. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. DYNALLOC

DYNALLOC = d (,n) (d,n)

Specifies that DFSORT dynamically allocates needed work space. You do not need to calculate and use JCL to specify the amount of work space needed by the program. For more information, see the discussion of the DYNALLOC option in OPTION Control Statement on page 167 and Appendix A, Using Work Space, on page 731 d specifies the device name. You can specify any IBM disk or tape device supported by your operating system in the same way you would specify it in the JCL UNIT parameter. You can also specify a group name, such as DISK or SYSDA. -For best performance, specify an emulated 33909 device (such as a RAMAC-) or another highspeed IBM disk device, and avoid specifying- a tape, virtual (VIO) or real 33909 device. n specifies the maximum number of requested work data sets. If you specify more than 255, a maximum of 255 data sets is used. If you specify 1 and the Blockset technique is selected, a maximum of 2 data sets is used. If you specify more than 32 and the Blockset technique is not selected, a maximum of 32 data sets is used. Note: For optimum allocation of resources such as virtual storage, avoid specifying a large number of work data sets unnecessarily. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. DYNALLOC=OFF | | |
DYNALLOC=OFF

Directs DFSORT not to allocate intermediate workspace dynamically. It overrides installation option DYNAUTO=YES or the DYNALLOC parameter
Chapter 2. Invoking DFSORT with Job Control Language

37

Using The EXEC Statement

(without OFF) specified at run-time. For more information, see the discussion of the DYNALLOC option in OPTION Control Statement on page 167. OFF directs DFSORT not to allocate intermediate workspace dynamically. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. DYNSPC

DYNSPC=n

Temporarily overrides the DYNSPC installation option, which specifies the total default primary space allocation for all of the dynamically allocated work data sets when the input file size is unknown. That is, when DFSORT cannot determine the input file size for a sort application and the number of records is not supplied by a FILSZ or SIZE value. For more information, see the discussion of the DYNSPC option in OPTION Control Statement on page 167. n specifies the total default primary space, in megabytes, to be allocated for all dynamically allocated work data sets (n is not the primary space for each data set). n must be a value between 1 and 65535. Do not specify a value which exceeds the available disk space, because this causes dynamic allocation to fail for sort applications that use this value. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. EFS

EFS=

name NONE

Temporarily overrides the EFS installation option, which specifies whether DFSORT passes control to an EFS program. See Chapter 8, Using Extended Function Support, on page 647 for more information on EFS. name NONE means no call will be made to the EFS program. Note: If you use locale processing for SORT, MERGE, INCLUDE, or OMIT fields, you must not use an EFS program. DFSORTs locale processing specifies the name of the EFS program that will be called to interface with DFSORT.

38

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

may eliminate the need for an EFS program. See OPTION Control Statement on page 167 for information related to locale processing. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. EQUALS or NOEQUALS

EQUALS NOEQUALS

Temporarily overrides the EQUALS installation option, which specifies whether the original sequence of records that collate identically for a sort or a merge should be preserved from input to output. For more information, see the discussion of the EQUALS and NOEQUALS options in OPTION Control Statement on page 167. EQUALS NOEQUALS specifies that the original sequence must be preserved. specifies that the original sequence need not be preserved.

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. E15=COB

E15=COB

Specifies that your E15 routine is written in COBOL and temporarily overrides the MODS statement for E15. If you specify E15=COB but do not identify an E15 module with a MODS statement, the E15=COB is ignored. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. E35=COB

E35=COB

Specifies that your E35 routine is written in COBOL and temporarily overrides the MODS statement for E35. If you specify E35=COB but do not identify an E35 module with a MODS statement, the E35=COB is ignored.
Chapter 2. Invoking DFSORT with Job Control Language

39

Using The EXEC Statement

Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. FILSZ

FILSZ=

x Ex Ux

Specifies either the exact number of records to be sorted or merged, or an estimate of the number of records to be sorted. This record count is used by DFSORT for two purposes: 1. To check that the actual number of records sorted or merged is equal to the exact number of records expected. FILSZ=x causes this check to be performed and results in termination with message ICE047A if the check fails. 2. To determine the input file size for a sort application. DFSORT performs calculations based on the user supplied record count and other parameters (such as AVGRLEN) to estimate the total number of bytes to be sorted. This value is important for sort applications, since it is used for several internal optimizations as well as for dynamic work data set allocation (see OPTION DYNALLOC). If no input record count (or only an estimate) is supplied for the sort application, DFSORT attempts to automatically compute the file size to be used for the optimizations and allocations. The type of FILSZ value specified (x, Ex, Ux, or none) controls the way DFSORT performs the above two functions, and can have a significant effect on performance and work data set allocation. See Specify Input/Output Data Set Characteristics Accurately on page 683 and Allocation of Work Data Sets on page 733 for more information on file size considerations. x specifies the exact number of records to be sorted or merged. This value is always used for both the record check and file size calculations. FILSZ=x can be used to force DFSORT to perform file size calculations based on x, and to cause DFSORT to terminate the sort or merge application if x is not exact. If installation option FSZEST=NO is in effect and FILSZ=x is specified, DFSORT terminates if the actual number of records is different from the specified value (x), the actual number of records placed in the IN field of message ICE047A (or message ICE054I) before termination. However, if installation option FSZEST=YES is in effect, DFSORT treats FILSZ=x like FILSZ=Ex; it does not terminate when the actual number of records does not equal x. The specified value (x) must take into account the number of records in the input data sets, records to be inserted or deleted by exit E15 or E32, and records to be deleted by the INCLUDE/OMIT statement, SKIPREC, and STOPAFT. x must be changed whenever the number of records to be sorted or merged changes in any way.

40

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

FILSZ=0 causes Hipersorting, dataspace sorting, and dynamic allocation of work space not to be used, and results in termination with the message ICE047A unless the number of records sorted or merged is 0. Limit: 28 digits (15 significant digits) Ex specifies an estimated number of records to be sorted. This value is not used for the record check. It is used for file size calculations, but only if DFSORT could not automatically compute the file size. In all other cases, this value is ignored by DFSORT. See Dynamic Allocation of Work Data Sets on page 734 for details on exactly when FILSZ=Ex is used or ignored by DFSORT. The specified value (x) should take into account the number of records in the input data sets, records to be inserted or deleted by exit E15, and records to be deleted by the INCLUDE/OMIT statement, SKIPREC, and STOPAFT. x should be changed whenever the number of records to be sorted changes significantly. FILSZ=E0 will always be ignored. Limit: 28 digits (15 significant digits) Ux specifies the number of records to be sorted. This value is not used for the record check, but is always used for file size calculations. FILSZ=Ux can be used to force DFSORT to perform file size calculations based on x, while avoiding termination if x is not exact. The FSZEST installation option has no effect on FILSZ=Ux processing. The specified value (x) should take into account the number of records in the input data sets, records to be inserted or deleted by exit E15, and records to be deleted by the INCLUDE/OMIT statement, SKIPREC, and STOPAFT. x should be changed whenever the number of records to be sorted changes significantly. FILSZ=U0 causes Hipersorting, dataspace sorting, and dynamic allocation of work space not to be used, and can cause degraded performance or termination with the message ICE046A, if the actual number of records to be sorted is significantly larger than 0. Limit: 28 digits (15 significant digits) Table 4 summarizes: the differences for the three FILSZ variations
Table 4. FILSZ Variations Summary. FILSZ=n is equivalent to FILSZ=En if installation option FSZEST=YES is specified. FILSZ=n Number of records Applications Terminate if wrong? Use for file size calculation? Exact Sort, merge Yes Yes FILSZ=Un Estimate Sort No Yes FILSZ=En Estimate Sort No When DFSORT cannot compute file size

n includes records: In input data sets Inserted/deleted by E15 Yes Yes Yes Yes Yes Yes

Chapter 2. Invoking DFSORT with Job Control Language

41

Using The EXEC Statement

Table 4. FILSZ Variations Summary (continued). FILSZ=n is equivalent to FILSZ=En if installation option FSZEST=YES is specified. FILSZ=n Inserted by E32 Deleted by INCLUDE/OMIT statement Deleted by SKIPREC Deleted by STOPAFT Yes Yes Yes Yes FILSZ=Un No Yes Yes Yes FILSZ=En No Yes Yes Yes

Update n when number of records changes: Effects of n=0

In any way

Significantly

Significantly

Hipersorting and Hipersorting and None DYNALLOC not DYNALLOC not used used

Note: Using the FILSZ parameter to supply inaccurate information to DFSORT can negatively affect DFSORTs performance, and when work space is dynamically allocated, can result in wasted disk space or termination with message ICE083A or ICE046A. Therefore, it is important to update the record count value whenever the number of records to be sorted changes significantly. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. HIPRMAX

HIPRMAX=

OPTIMAL n p%

Temporarily overrides the HIPRMAX installation option, which specifies the maximum amount of Hiperspace to be used for Hipersorting. For more information, see the discussion of the HIPRMAX option in OPTION Control Statement on page 167. OPTIMAL n specifies that DFSORT determines dynamically the maximum amount of Hiperspace to be used for Hipersorting. specifies that DFSORT determines dynamically the maximum amount of Hiperspace to be used for Hipersorting, subject to a limit of nMB. n must be a value between 0 and 32767. If n is 0, Hipersorting is not used. specifies that DFSORT determines dynamically the maximum amount of hiperspace to be used for Hipersorting, subject to a limit of p percent of an appropriate portion of central storage. p must be a value between 0 and 100. If p is 0, Hipersorting is

%p

42

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

| not used. The value calculated for p% is limited to 32767MB, and is rounded down to the nearest MB. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. LIST or NOLIST

LIST NOLIST

Temporarily overrides the LIST installation option, which specifies whether DFSORT program control statements should be written to the message data set. See z/OS DFSORT Messages, Codes and Diagnosis Guide for full details on use of the message data set. LIST NOLIST specifies that all DFSORT control statements are printed on the message data set. specifies that DFSORT control statements are not printed.

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. LISTX or NOLISTX

LISTX NOLISTX

Temporarily overrides the LISTX installation option, which specifies whether DFSORT writes to the message data set the program control statements returned by an EFS program. See z/OS DFSORT Messages, Codes and Diagnosis Guide for full details on use of the message data set. LISTX NOLISTX specifies that control statements returned by an EFS program are printed to the message data set. specifies that control statements returned by an EFS program are not printed to the message data set.

Notes: 1. If EFS=NONE is in effect after final override rules have been applied, NOLISTX will be set in effect. 2. LISTX and NOLISTX can be used independently of LIST and NOLIST. 3. For more information on printing EFS control statements, see z/OS DFSORT Messages, Codes and Diagnosis Guide.

Chapter 2. Invoking DFSORT with Job Control Language

43

Using The EXEC Statement

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. LOCALE

LOCALE=

name CURRENT NONE

Temporarily overrides the LOCALE installation option, which specifies whether locale processing is to be used and, if so, designates the active locale. For more information, see the discussion of the LOCALE option in OPTION Control Statement on page 167. name specifies that locale processing is to be used and designates the name of the locale to be made active during DFSORT processing. The locales are designated using a descriptive name. For example, to set the active locale to represent the French language and the cultural conventions of Canada, specify LOCALE=FR_CA. You can specify up to 32 characters for the descriptive locale name. The locale names themselves are not case-sensitive. See Using Locales for complete locale naming conventions. You can use IBM-supplied and user-defined locales. The state of the active locale prior to DFSORT being entered will be restored on DFSORTs completion. CURRENT specifies that locale processing is to be used, and the current locale active when DFSORT is entered will remain the active locale during DFSORT processing. specifies that locale processing is not to be used. DFSORT will use the binary encoding of the code page defined for your data for collating and comparing.

NONE

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. MOSIZE

MOSIZE=

MAX n %p

44

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

Temporarily overrides the MOSIZE installation option, which specifies the maximum size of a memory object to be used for memory object sorting. For more information, see the discussion of the MOSIZE option in OPTION Control Statement on page 167. MAX n specifies that DFSORT determines dynamically the maximum size of a memory object to be used for memory object sorting. specifies that DFSORT determines dynamically the maximum size of a memory object to be used for memory object sorting, subject to a limit of nMB. n must be a value between 0 and 2147483646. If n is 0, memory object sorting is not used. specifies that DFSORT determines dynamically the maximum size of a memory object to be used for memory object sorting, subject to a limit of p percent of the available central storage. p must be a value between 0 and 100. If p is 0, memory object sorting is not used. The value calculated for p% is limited to 2147483646MB, and is rounded down to the nearest MB.

%p

| |

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. MSGDDN

MSGDDN=ddname

Temporarily overrides the MSGDDN installation option, which specifies an alternate ddname for the message data set. For more information, see the discussion of the MSGDDN option in OPTION Control Statement on page 167. The ddname can be any 1- through 8-character name, but must be unique within the job step; do not use a name that is used by DFSORT (for example, SORTIN). If the ddname specified is not available at run-time, SYSOUT is used instead. For details on using the message data set, see z/OS DFSORT Messages, Codes and Diagnosis Guide. Note: MSGDD=ddname can be used instead of MSGDDN=ddname. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. MSGPRT

Chapter 2. Invoking DFSORT with Job Control Language

45

Using The EXEC Statement

MSGPRT= ALL CRITICAL NONE

Temporarily overrides the MSGPRT installation option, which specifies the class of messages to be written to the message data set. See z/OS DFSORT Messages, Codes and Diagnosis Guide for full details on use of the message data set. ALL specifies that all messages except diagnostic messages ICE800I to ICE999I are printed on the message data set. Control statements are printed only if LIST is in effect.

CRITICAL specifies that only critical messages are printed on the message data set. Control statements are printed only if LIST is in effect. NONE specifies that no messages or control statements are printed. Note: The forms FLAG(I)|FLAG(U)|NOFLAG, and MSG={NO|NOF|AB|AP|AC|CB|CC|CP|PC|SC|SP} are also accepted. The following table lists the equivalent MSGPRT/MSGCON specifications for these alternate forms:
Option NO NOF AB AP AC CB CC CP PC SC SP NOFLAG FLAG(I) FLAG(U) MSGPRT NONE NONE ALL ALL NONE CRITICAL NONE CRITICAL ALL ALL CRITICAL NONE ALL CRITICAL MSGCON NONE NONE ALL CRITICAL ALL CRITICAL CRITICAL CRITICAL ALL CRITICAL ALL CRITICAL CRITICAL CRITICAL

Figure 5. Aliases for MSGPRT/MSGCON Options

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. NULLOUT

46

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

NULLOUT= RC0 RC4 RC16

Temporarily overrides the NULLOUT installation option, which specifies the action to be taken by DFSORT when there are no records for the SORTOUT data set. For more information, see the discussion of the NULLOUT option in OPTION Control Statement on page 167. RC0 specifies that DFSORT should issue message ICE173I, set a return code of 0, and continue processing when there are no records for the SORTOUT data set. specifies that DFSORT should issue message ICE173I, set a return code of 4, and continue processing when there are no records for the SORTOUT data set. specifies that DFSORT should issue message ICE206A, terminate, and give a return code of 16 when there are no records for the SORTOUT data set.

RC4

RC16

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. ODMAXBF

ODMAXBF=

n nK nM

Temporarily overrides the ODMAXBF installation option, which specifies the maximum buffer space DFSORT can use for each OUTFIL data set. For more information, see the discussion of the ODMAXBF option in OPTION Control Statement on page 167. n specifies that a maximum of n bytes of buffer space is to be used for each OUTFIL data set. If you specify less than 262144, 262144 is used. If you specify more than 16777216, 16777216 is used. Limit: 8 digits nK specifies that a maximum of n times 1024 bytes of buffer space is to be used for each OUTFIL data set. If you specify less than 256K, 256K is used. If you specify more than 16384K, 16384K is used. Limit: 5 digits nM specifies that a maximum of n times 1048576 bytes of buffer space is to be used for each OUTFIL data set. If you specify 0M, 256K is used. If you specify more than 16M, 16M is used.
Chapter 2. Invoking DFSORT with Job Control Language

47

Using The EXEC Statement

Limit: 2 digits Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. OUTREL or NOOUTREL

OUTREL NOOUTREL

Temporarily overrides the OUTREL installation option, which specifies whether unused temporary output data set space is to be released. OUTREL specifies that unused temporary output data set space is released. NOOUTREL specifies that unused temporary output data set space is not released. Note: RLSOUT and NORLSOUT can be used instead of OUTREL and NOOUTREL, respectively. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. OVFLO

OVFLO=

RC0 RC4 RC16

Temporarily overrides the OVFLO installation option, which specifies the action to be taken by DFSORT when BI, FI, PD or ZD summary fields overflow. For more information, see the discussion of the OVFLO option in OPTION Control Statement on page 167. RC0 specifies that DFSORT should issue message ICE152I (once), set a return code of 0 and continue processing when summary fields overflow. RC4 specifies that DFSORT should issue message ICE152I (once), set a return code of 4 and continue processing when summary fields overflow. RC16 specifies that DFSORT should issue message ICE195A, terminate and give a return code of 16 when summary fields overflow.

48

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. PAD

PAD=

RC0 RC4 RC16

Temporarily overrides the PAD installation option, which specifies the action to be taken by DFSORT when the SORTOUT LRECL is larger than the SORTIN/SORTINnn LRECL, for the cases where DFSORT allows LRECL padding. For more information, see the discussion of the PAD option in OPTION Control Statement on page 167. RC0 specifies that DFSORT should issue message ICE171I (once), set a return code of 0 and continue processing when the SORTOUT LRECL is larger than the SORTIN/SORTINnn LRECL. RC4 specifies that DFSORT should issue message ICE171I, set a return code of 4 and continue processing when the SORTOUT LRECL is larger than the SORTIN/SORTINnn LRECL. RC16 specifies that DFSORT should issue message ICE196A, terminate and give a return code of 16 when the SORTOUT LRECL is larger than the SORTIN/SORTINnn LRECL. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. RESALL

RESALL=

n nK nM

Temporarily overrides the RESALL installation option, which specifies the number of bytes to be reserved in a REGION for system use when SIZE/MAINSIZE=MAX is in effect. For more information, see the discussion of the RESALL option in OPTION Control Statement on page 167. n specifies that n bytes of storage are to be reserved. If you specify less than 4096, 4096 is used. Limit: 8 digits.

Chapter 2. Invoking DFSORT with Job Control Language

49

Using The EXEC Statement

nK specifies that n times 1024 bytes of storage are to be reserved. If you specify less than 4K, 4K is used. Limit: 5 digits. nM specifies that n times 1048576 bytes of storage are to be reserved. If you specify 0M, 4K is used. Limit: 2 digits. Note: RESERVE=value can be used instead of RESALL=value. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. RESET or NORESET

RESET NORESET

Temporarily overrides the RESET installation option, which specifies whether DFSORT should process a VSAM output data set defined with REUSE as a NEW or MOD data set. RESET specifies that DFSORT processes a VSAM output data set defined with REUSE as a NEW data set. The high-used RBA is reset to zero and the output data set is effectively treated as an initially empty cluster. specifies that DFSORT processes a VSAM output data set defined with REUSE as a MOD data set. The high-used RBA is not reset and the output data set is effectively treated as an initially non-empty cluster.

NORESET

Note: A VSAM output data set defined without REUSE is processed as a MOD data set. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SDB

SDB=

LARGE YES INPUT NO

50

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

Temporarily overrides the SDB installation option, which specifies whether DFSORT should use the system-determined optimum block size for output data sets when the block size is specified as zero or defaulted to zero. For more information, see the discussion of the SDB option in OPTION Control Statement on page 167. LARGE specifies that DFSORT is to use the system-determined optimum block size for an output data set when its block size is zero. SDB=LARGE allows DFSORT to select a block size greater than 32760 bytes for a tape output data set, when appropriate. YES specifies that DFSORT is to use the system-determined optimum block size for an output data set when its block size is zero, but is to limit the selected block size to a maximum of 32760 bytes. INPUT specifies that DFSORT is to use the system-determined optimum block size for an output data set when its block size is zero, but is to limit the selected block size to a maximum of 32760 bytes if the input block size is less than or equal to 32760 bytes. NO specifies that DFSORT is not to use the system-determined optimum block size. Note: SDB, SDB=ON, and SDB=SMALL can be used instead of SDB=YES. NOSDB and SDB=OFF can be used instead of SDB=NO. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SIZE

SIZE=

n nK nM MAX MAX-m MAX-mK MAX-mM

Temporarily overrides the SIZE installation option, which specifies the amount of main storage available to DFSORT. For more information, see the discussion of the MAINSIZE option in OPTION Control Statement on page 167. n specifies that n bytes of storage are to be allocated. If you specify more than 2097152000, 2097152000 is used. Limit: 10 digits. nK specifies that n times 1024 bytes of storage are to be allocated. If you specify more than 2048000K, 2048000K is used.
Chapter 2. Invoking DFSORT with Job Control Language

51

Using The EXEC Statement

Limit: 7 digits. nM specifies that n times 1048576 bytes of storage are to be allocated. If you specify more than 2000M, 2000M is used. Limit: 4 digits. MAX instructs DFSORT to calculate the amount of virtual storage available and allocate an amount of storage up to the TMAXLIM or DSA value when Blockset is selected, or up to the MAXLIM value when Blockset is not selected. MAX-m specifies the RESALL value (m) in bytes. MAX-m instructs DFSORT to calculate the amount of storage available and allocate this amount up to the MAX value minus the amount of storage reserved for system and application use (RESALL). If you specify less than 4096 for m, 4096 is used. Limit for m: 8 digits. MAX-mK specifies the RESALL value (m times 1024) in KBs. MAX-mK instructs DFSORT to calculate the amount of storage available and allocate this amount up to the MAX value minus the amount of storage reserved for system and application use (RESALL). If you specify less than 4K for m, 4K is used. Limit for m: 5 digits. MAX-mM specifies the RESALL value (m times 1048576) in s. MAX-mM instructs the program to calculate the amount of storage available and allocate this amount up to the MAX value minus the amount of storage reserved for system and application use (RESALL). If you specify 0M for m, 4K is used. Limit for m: 2 digits. Note: The forms SIZE(value), CORE=value, and CORE(value) can be used instead of SIZE=value. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SKIPREC

SKIPREC=z

Specifies the number of records (z) you want to skip (delete) before starting to sort or copy the input data set. SKIPREC is typically used to bypass records

52

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

not processed from the previous DFSORT job. For more information, see the discussion of the SKIPREC option in OPTION Control Statement on page 167. z specifies the number of records to be skipped. Limit: 28 digits (15 significant digits). Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SOLRF or NOSOLRF

SOLRF NOSOLRF

Temporarily overrides the SOLRF installation option, which specifies whether DFSORT should set the SORTOUT LRECL to the reformatted record length when the SORTOUT LRECL is unknown. For more information, see the discussion of the SOLRF and NOSOLRF options in OPTION Control Statement on page 167. SOLRF specifies that DFSORT should use the reformatted record length for the SORTOUT LRECL when the SORTOUT LRECL is not specified or available. NOSOLRF specifies that DFSORT should not use the reformatted record length for the SORTOUT LRECL. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SPANINC

SPANINC=

RC0 RC4 RC16

Temporarily overrides the SPANINC installation option, which specifies the action to be taken by DFSORT when one or more incomplete spanned records are detected in a variable spanned input data set. For more information, see the discussion of the SPANINC option in OPTION Control Statement on page 167.

Chapter 2. Invoking DFSORT with Job Control Language

53

Using The EXEC Statement

RC0 specifies that DFSORT should issue message ICE197I (once), set a return code of 0 and eliminate all incomplete spanned records it detects. RC4 specifies that DFSORT should issue message ICE197I (once), set a return code of 4 and eliminate all incomplete spanned records it detects. RC16 specifies that DFSORT should issue message ICE204A, terminate and give a return code of 16 when an incomplete spanned record is detected. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741 | STOPAFT

STOPAFT=n

Specifies the maximum number of records you want accepted for sorting or copying (that is, read from SORTIN or inserted by E15 and not deleted by SKIPREC, E15, or an INCLUDE/OMIT statement). For more information, see the discussion of the STOPAFT option in OPTION Control Statement on page 167. n specifies the maximum number of records to be accepted. Limit: 28 digits (15 significant digits). Note: If you specify (1) FILSZ=x in the EXEC PARM, or (2) SIZE=x or FILSZ=x on the OPTION or SORT statement, and the number of records accepted for processing does not equal x, DFSORT issues an error message and terminates unless installation option FSZEST=YES was specified. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SZERO or NOSZERO

SZERO NOSZERO

Temporarily overrides the SZERO installation option, which specifies+ whether DFSORT should treat numeric 0 and 0 values as signed (that is, different) or unsigned (that is, the same) for collation, comparisons, editing, conversions, minimums and maximums. For more information, see the discussion of the SZERO and NOSZERO options in OPTION Control Statement on page 167.

54

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

SZERO specifies that DFSORT should treat numeric zero values as signed. NOSZERO specifies that DFSORT should treat numeric zero values as unsigned. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. TRUNC

TRUNC=

RC0 RC4 RC16

Temporarily overrides the TRUNC installation option, which specifies the action to be taken by DFSORT when the SORTOUT LRECL is smaller than the SORTIN/SORTINnn LRECL, for the cases where DFSORT allows LRECL truncation. For more information, see the discussion of the TRUNC option in OPTION Control Statement on page 167. RC0 specifies that DFSORT should issue message ICE171I, set a return code of 0 and continue processing when the SORTOUT LRECL is smaller than the SORTIN/SORTINnn LRECL. RC4 specifies that DFSORT should issue message ICE171I, set a return code of 4 and continue processing when the SORTOUT LRECL is smaller than the SORTIN/SORTINnn LRECL. RC16 specifies that DFSORT should issue message ICE196A, terminate and give a return code of 16 when the SORTOUT LRECL is smaller than the SORTIN/SORTINnn LRECL. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. VERIFY or NOVERIFY

VERIFY NOVERIFY

Temporarily overrides the VERIFY installation option, which specifies whether sequence checking of the final output records must be performed.

Chapter 2. Invoking DFSORT with Job Control Language

55

Using The EXEC Statement

VERIFY specifies that sequence checking is performed. NOVERIFY specifies that sequence checking is not performed. Notes: 1. Using VERIFY can degrade performance. 2. SEQ=YES can be used instead of VERIFY. SEQ=NO can be used instead of NOVERIFY. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. VLLONG or NOVLLONG

VLLONG NOVLLONG

Temporarily overrides the VLLONG installation option, which specifies whether DFSORT is to truncate long variable-length output records. For more information, see the discussion of the VLLONG and NOVLLONG options in OPTION Control Statement on page 167. VLLONG specifies that DFSORT truncates long variable-length output records to the LRECL of the SORTOUT or OUTFIL data set. NOVLLONG specifies that DFSORT terminates if a long variable-length output record is found. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. VLSCMP or NOVLSCMP

VLSCMP NOVLSCMP

Temporarily overrides the VLSCMP installation option, which specifies whether DFSORT is to pad short variable-length INCLUDE/OMIT compare fields with binary zeroes. For more information, see the discussion of the VLSCMP and NOVLSCMP options in OPTION Control Statement on page 167.

56

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

VLSCMP specifies that short variable-length compare fields are padded with binary zeros. NOVLSCMP specifies that short variable-length compare fields are not padded. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. VLSHRT or NOVLSHRT

VLSHRT NOVLSHRT

Temporarily overrides the VLSHRT installation option, which specifies whether DFSORT is to continue processing if a short variable-length SORT/MERGE control field, INCLUDE/OMIT compare field, or SUM summary field is found. For more information, see the discussion of the VLSHRT and NOVLSHRT options in OPTION Control Statement on page 167. VLSHRT specifies that DFSORT continues processing if a short control field or compare field is found. NOVLSHRT specifies that DFSORT terminates if a short control field or compare field is found. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. VSAMEMT or NVSAMEMT

VSAMEMT NVSAMEMT

Temporarily overrides the VSAMEMT installation option, which specifies whether DFSORT should accept an empty VSAM input data set. VSAMEMT specifies that DFSORT accepts an empty VSAM input data set and processes it as having zero records.

NVSAMEMT specifies that DFSORT terminates if an empty VSAM input data set is found. Note: VSAMEMT=YES can be used instead of VSAMEMT. VSAMEMT=NO can be used instead of NVSAMEMT.
Chapter 2. Invoking DFSORT with Job Control Language

57

Using The EXEC Statement

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741 VSAMIO or NOVSAMIO

VSAMIO NOVSAMIO

Temporarily overrides the VSAMIO installation option, which specifies whether DFSORT should allow a VSAM data set defined with REUSE to be sorted in-place. VSAMIO specifies that DFSORT can use the same VSAM data set for input and output: when all of the following conditions are met v The application is a sort. v RESET is in effect. v The VSAM data set was defined with REUSE. These conditions ensure that the VSAM data set is processed as NEW for output and will contain the sorted input records; that is it will be sorted in-place. DFSORT terminates if the same VSAM data set is specified for input and output, and any of the above conditions are not met. NOVSAMIO specifies that DFSORT terminates if the same VSAM data set is specified for input and output.

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. WRKREL or NOWRKREL

WRKREL NOWRKREL

Temporarily overrides the WRKREL installation option, which specifies whether unused temporary SORTWKdd data set space will be released. WRKREL specifies that unused space is released. NOWRKREL specifies that unused space is not released.

58

z/OS V1R10.0 DFSORT Application Programming Guide

Using The EXEC Statement

Notes: 1. If you have dedicated certain volumes for SORTWKdd data sets, and you do not want unused temporary space to be released, you should specify NOWRKREL. 2. If WRKREL is in effect, DFSORT releases space for the SORTWKdd data sets just prior to termination. Space is released only for those SORTWKdd data sets that were used for the sort application. 3. RELEASE=OFF and RLS=0 can be used instead of NOWRKREL. RELEASE=ON and RLS=n (n greater than 0) can be used instead of WRKREL. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. WRKSEC or NOWRKSEC

WRKSEC NOWRKSEC

Temporarily overrides the WRKSEC installation option, which specifies whether DFSORT uses automatic secondary allocation for temporary JCL SORTWKdd data sets. WRKSEC specifies that automatic secondary allocation for temporary JCL SORTWKdd data sets is used and that 25 percent of the primary allocation will be used as the secondary allocation. NOWRKSEC specifies that automatic secondary allocation for temporary JCL SORTWKdd data sets is not used. Note: SECOND=OFF and SEC=0 can be used instead of NOWRKSEC. SECOND=ON and SEC=n (n greater than 0) can be used instead of WRKSEC. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. Y2PAST

Y2PAST=

s f

Chapter 2. Invoking DFSORT with Job Control Language

59

Using The EXEC Statement

Temporarily overrides the Y2PAST installation option, which specifies the sliding (s) or fixed (f) century window. The century window is used with DFSORTs Y2 formats to correctly interpret two-digit year data values as four-digit year data values. s specifies the number of years DFSORT is to subtract from the current year to set the beginning of the sliding century window. Since the Y2PAST value is subtracted from the current year, the century window slides as the current year changes. For example, Y2PAST=81 would set a century window of 1925-2024 in 2006 and 1926-2025 in 2007. s must be a value between 0 and 100. specifies the beginning of the fixed century window. For example, Y2PAST=1962 would set a century window of 1962-2061. f must be a value between 1000 and 3000.

Note: CENTWIN=value can be used instead of Y2PAST=value. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. ZDPRINT or NZDPRINT

ZDPRINT NZDPRINT

Temporarily overrides the ZDPRINT installation option, which specifies whether positive zoned-decimal (ZD) fields resulting from summing must be converted to printable numbers. For more information, see the discussion of the ZDPRINT and NZDPRINT options in OPTION Control Statement on page 167. ZDPRINT means convert positive ZD summation results to printable numbers. NZDPRINT means do not convert positive ZD summation results to printable numbers. Note: ZDPRINT=YES can be used instead of ZDPRINT. ZDPRINT=NO can be used instead of NZDPRINT. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741.

Aliases for PARM Options

For compatibility reasons, the following EXEC/DFSPARM PARM options can be specified by using the aliases listed below. See the indicated PARM options for complete details.

60

z/OS V1R10.0 DFSORT Application Programming Guide

Aliases for PARM Options

Table 5. Aliases for PARM Options Alias CENTWIN=value CORE=value FLAG(I) FLAG(U) L5=value MSG=value MSGDD=value NOFLAG NORC16 NORLSOUT NOSDB RC16=ABE RELEASE=ON RELEASE=OFF RESERVE=value RESERVEX=value RLS=n RLS=0 RLSOUT SDB SDB=ON SDB=OFF SDB=SMALL SEC=n SEC=0 SECOND=ON SECOND=OFF SEQ=YES SEQ=NO VSAMEMT=YES VSAMEMT=NO ZDPRINT=YES ZDPRINT=NO PARM Option Y2PAST=value SIZE=value MSGPRT=ALL MSGPRT=CRITICAL AVGRLEN=value MSGPRT=value MSGDDN=value MSGPRT=NONE NOABEND NOOUTREL SDB=NO ABEND WRKREL NOWRKREL RESALL=value ARESALL=value WRKREL NOWRKREL OUTREL SDB=YES SDB=YES SDB=NO SDB=YES WRKSEC NOWRKSEC WRKSEC NOWRKSEC VERIFY NOVERIFY VSAMEMT NVSAMEMT ZDPRINT NZDPRINT

Using DD Statements
A DFSORT job always requires DD statements after the EXEC statement. DD: statements fall into two categories v System DD statements (discussed in detail in System DD Statements on page 64)

Chapter 2. Invoking DFSORT with Job Control Language

61

Using DD Statements
v Program DD statements (discussed in detail in Program DD Statements on page 66). System DD statements, and some program DD statements, are usually supplied automatically when you use a cataloged procedure. Others you must always supply yourself. The DD statement parameters, the conditions under which they are required, and the default values, are summarized in Table 6. The subparameters of the DCB parameter (a DD statement parameter) are described similarly in Table 7 on page 63. Notes: 1. Performance is enhanced if the LRECL subparameter of the DCB is accurately specified for variable-length records. The maximum input record length you can specify for your particular configuration is given in Data Set Notes and Limitations on page 13. 2. When using DFSORT applications, FREE=CLOSE cannot be used on any DD statements except DFSPARM.
Table 6. DD Statement Parameters Used by DFSORT Parameter {AMP | BUFSP} When Required When password-protected VSAM data sets are used and the password is supplied through E18, E38, or E39. Required when 7-track tape is used; for input on tape without standard labels; and when the default values are not applicable. When the default value is not applicable. Parameter Values Default Value

Minimum buffer pool value None. given when creating the data set.

DCB

Specifies information used (See separate to fill the data control block subparameters in Table 7 on (DCB) associated with the page 63.) data set. Indicates the status and disposition of the data set. The system assumes (NEW, DELETE). The system assigns a unique name.

DISP DSNAME or DSN

When the DD statement Specifies the fully qualified defines a labeled input data or temporary name of the set (for example, SORTIN), data set. or when the data set being created is to be kept or cataloged (for example, SORTOUT), or passed to another step. When the default value is not applicable. When the DD statement defines a new data set on disk. When the input data set is neither cataloged nor passed or when the data set is being created. Specifies information about labeling and retention for the data set.

LABEL

The system assumes standard labeling.

SPACE

Specifies the amount of None. space needed to contain the data set. Specifies (symbolically or actually) the type and quantity of I/O units required by the data set. None.

UNIT

62

z/OS V1R10.0 DFSORT Application Programming Guide

Using DD Statements
Table 6. DD Statement Parameters Used by DFSORT (continued) Parameter VOLUME or VOL When Required When the input data set is neither cataloged nor passed, for multireel input or when the output data set is on disk and is to be kept or cataloged. Parameter Values Specifies information used to identify the volume or volumes occupied by the data set. Default Value None.

Table 7. DCB Subparameters Used by DFSORT Subparameter BUFOFF Condition When Required When processing data in ISCII/ASCII format. Subparameter Values Specifies the length of the buffer offset or specifies that the buffer offset is the block length indicator. Specifies the density at which the tape was recorded. Specifies that the tape processed is in ISCII/ASCII format. Specifies whether data set is compacted. System default option. 800 bpi Default Value

DEN

When the data set is located on a 7-track tape unit. When processing data in ISCII/ASCII format. When the data set is located on a tape device with IDRC and system IDRC is not used. When the DCB parameter is required and the default value is not suitable except on SORTWKdd statements.

OPTCD

TRTCH

BLKSIZE 1, 2

Specifies the maximum v For old data sets, the length (in bytes) of the value in the data set physical records in the data label. set. v For new output data sets, appropriate values based on the input data set or RECORD statement values. Specifies the maximum length (in bytes) of the logical records in the data set. Unless SDB=NO is in effect, Blockset uses the system-determined optimum block size when the output data set block size is zero. Applications which require a specific output data set block size should be changed to specify that block size EXPLICITY. v No default if input on unlabeled tape or BLP or NSL specified.

LRECL 2, 3

RECFM

Specifies the format of the records in the data set.

1. See SORTIN DD Statement on page 68 and SORTINnn DD Statement on page 70. 2. This is the only subparameter allowed for DD * data sets. 3. For padding and truncating fixed-length records, see Data Set Notes and Limitations on page 13. Chapter 2. Invoking DFSORT with Job Control Language

63

Using DD Statements

Duplicate Ddnames
If you specify a particular ddname (such as SORTIN) more than once within the same step, DFSORT uses the first ddname and ignores subsequent duplicates. Processing continues normally. In addition, SORTIN0, SORTIN1...SORTIN9 can be specified instead of SORTIN00, SORTIN01...SORTIN09, respectively. If you specify both SORTINn and SORTIN0n in the same job step, DFSORT treats them as duplicates, and ignores each usage after the first. For example, SORTIN2 and SORTIN02 are treated as duplicates and only SORTIN2 is used. Note: For a Conventional merge, SORTINn will not be recognized because of the existing restriction which allows only SORTIN01, SORTIN02...SORTIN16. Duplicates of these accepted ddnames will be ignored. Duplicate OUTFIL ddnames are ignored at the OUTFIL statement level as explained in OUTFIL Statements Notes on page 340.

Shared Tape Units

The following pairs of DFSORT data sets can be assigned to a single tape unit: v The SORTIN data set and the SORTWK01 data set (tape work data set sorts only) v The SORTIN data set and the SORTOUT data set or one OUTFIL data set (sort applications only). If you want to associate the SORTIN data set with SORTWK01, you can include the parameter UNIT=AFF=SORTIN in the DD statement for SORTWK01. The AFF subparameter causes the system to place the data set on the same unit as the dataset with the ddname following the subparameter (SORTIN, in this case). In the same way, you can associate the SORTIN data set with the SORTOUT data set or an OUTFIL data set by including UNIT=AFF=SORTIN in the SORTOUT or OUTFIL DD statement. SORTINnn tape data sets must all be on different tape units because they are read concurrently. SORTOUT and OUTFIL tape data sets must all be on different tape units because they are written concurrently.

System DD Statements
If you choose not to use the SORT or SORTD cataloged procedures to invoke DFSORT, you might need to supply system DD statements in your input job stream (See also the following section for DD statements dedicated to DFSORT, such as SORTIN). The DD statements contained in the cataloged procedure (or provided by you) are: //JOBLIB DD //STEPLIB DD //SYSIN DD Defines your program link library if it is not already known to the system. Same as //JOBLIB DD. Contains DFSORT control statements, comment statements, blank statements and remarks when DFSORT is invoked with JCL rather than by another program. It can also contain user exit routines, in object deck format, to be link-edited by DFSORT.

64

z/OS V1R10.0 DFSORT Application Programming Guide

Using DD Statements
v If you use DFSPARM, then SYSIN is not necessary unless your job requires link-editing. v The SYSIN data set usually resides in the input stream; however, it can be defined as a sequential data set or as a member of a partitioned data set. v The data set must be defined with a RECFM of F or FB. The LRECL can be 80, or more (when valid). If the LRECL is greater than 80, DFSORT will use the first 80 bytes of each record. If user exit routines are in SYSIN, the LRECL must be 80. v DFSORT supports concatenated SYSIN data sets to the extent that the system supports like concatenated data sets for BSAM. Refer to z/OS DFSMS Using Data Sets for further information about like concatenated data sets. Note: The OPTION statement keywords EFS, LIST, NOLIST, LISTX, NOLISTX, LOCALE, MSGPRT, MSGDDN, SMF, SORTDD, SORTIN, and SORTOUT are used only when they are passed by an extended parameter list or when in the DFSPARM data set. If they are specified on an OPTION statement read from the SYSIN or SORTCNTL data set, the keyword is recognized, but the parameters are ignored. If you use the DFSPARM DD statement instead, you can specify both EXEC PARM options and DFSORT control statements in a single source data set that overrides all other sources. See DFSPARM DD Statement on page 77. If v v v user exit routines are in SYSIN, make sure that: The LRECL of SYSIN is 80. The END statement is the last control statement. The user exit routines are arranged in numeric order (for example, E11 before E15). v The user exit routines are supplied immediately after the END control statement. v Nothing follows the last object deck in SYSIN. v A SORTMODS DD statement is included. If DFSORT is program invoked, and you supply the DFSORT control statements through the 24-bit or extended parameter list, SORTCNTL, or DFSPARM, SYSIN remains the source of user exit routines placed in the system input stream. //SYSOUT DD Identifies the DFSORT message data set. The default ddname is SYSOUT, but you can specify an alternate ddname for the message data set using the MSGDDN installation or run-time option.
Chapter 2. Invoking DFSORT with Job Control Language

65

Using DD Statements
Always supply a DD statement for the message data set if a catalogued procedure is not used. (If you are invoking DFSORT from a COBOL program and are using the ddname SYSOUT for the message data set, the use of DISPLAY in your COBOL program can produce uncertain printing results.) DFSORT uses RECFM=FBA, LRECL=121, and the specified BLKSIZE for the message data set. If the BLKSIZE you specify is not a multiple of 121, DFSORT uses BLKSIZE=121. If you do not specify the BLKSIZE, DFSORT selects the block size as directed by the SDBMSG installation option (see z/OS DFSORT Installation and Customization). If you use a temporary or permanent message data set, it is best to specify a disposition of MOD to ensure you see all messages and control statements in the message data set. //SYSUDUMP DD //SYSMDUMP DD //SYSABEND DD Defines the data set for output from a system ABEND dump routine. Same as //SYSUDUMP DD. Same as //SYSUDUMP DD.

If you are using the supplied SORT cataloged procedure, the DD statements below are automatically supplied. If you are not using the SORT cataloged procedure and you are using the linkage editor, you must supply the following: DD statements //SYSPRINT DD //SYSUT1 DD //SYSLIN DD //SYSLMOD DD Contains messages from the linkage editor. Defines the intermediate storage data set for the linkage editor. Defines a data set for control information for the linkage editor. Defines a data set for output from the linkage editor.

Note: If you do not include user routines, or if you include user routines that do not require link-editing, you can use the supplied SORTD cataloged procedure. If you include user routines that require link-editing, you can use the SORT cataloged procedure.

Program DD Statements
Even if you use the SORT or SORTD cataloged procedure to invoke DFSORT, you might need to supply additional dedicated DD statements. The following list summarizes each of these statements, and a more detailed explanation of each one follows. //SORTLIB DD //SYMNAMES DD Defines the data set that contains special load modules for DFSORT. Can usually be omitted. Defines the SYMNAMES data set containing statements to be used for symbol processing. Required only if symbol processing is to be performed.

66

z/OS V1R10.0 DFSORT Application Programming Guide

Using DD Statements
//SYMNOUT DD Defines the data set in which SYMNAMES statements and the symbol table are to be listed. Optional if SYMNAMES DD is specified. Otherwise ignored. Defines the input data set for a sorting or copying application. Will not be used for a merging application. Defines the input data sets for a merging application. Will not be used for a sorting or copying application. Defines intermediate storage data sets. Usually needed for a sorting application unless dynamic allocation is requested. Will not be used for a copying or merging application. Defines the SORTOUT output data set for a sorting, merging, or copying application. Defines an OUTFIL output data set for a sorting, merging, or copying application. Defines the data set used to store the information that the system needs to restart the sort from the last checkpoint. This is only needed if you are using the checkpoint facility. Defines the data set from which additional or changed DFSORT control statements can be read when DFSORT is program-invoked. Defines the data set from which both additional or changed DFSORT program control statements and EXEC statement PARM options can be read when DFSORT is directly invoked or program invoked. Defines the data set used for a VIO SORTWKdd allocation by DFSORT if it is dynamically reallocated; SORTDKdd must never be specified in the job stream. Specifies that all messages and control statements are printed. Used primarily for diagnostics and debugging. Defines the snap dump data set dynamically allocated by DFSORT. SORTSNAP must never be specified in the job stream. Defines a temporary partitioned data set. This temporary data set must be large enough to contain all your user exit routines that appear in SYSIN for a given application. If none of your routines appear in SYSIN, this statement is not required. If your routines are in libraries, you must include DD statements defining the libraries.

//SORTIN DD

//SORTINnn DD

//SORTWKdd DD

//SORTOUT DD //outfil DD //SORTCKPT DD

//SORTCNTL DD

//DFSPARM DD

//SORTDKdd DD

//SORTDIAG DD

//SORTSNAP DD

//SORTMODS DD

Chapter 2. Invoking DFSORT with Job Control Language

67

Using DD Statements
DFSORT temporarily transfers the user exit routines in SYSIN to the data set defined by this DD statement before they are link-edited for processing.

SORTLIB DD Statement
The SORTLIB DD statement can usually be omitted. This statement describes the data set that contains special DFSORT load modules. | | | | | When Required: If installation option SORTLIB=PRIVATE is in effect or dynamic link edit of user exits is specified v For sort applications using tape work data sets v For merge applications for which Blockset cannot be used (see message ICE800I). The SORTLIB installation option determines whether DFSORT searches a system library or private library for the load modules required by tape work data set sorts and Conventional merges. Example 1 SORTLIB DD Statement:
//SORTLIB DD DSNAME=USORTLIB,DISP=SHR

This example shows DD statement parameters that define a previously cataloged input data set: DSNAME causes the system to search the catalog for a data set with the name USORTLIB. When the data set is found, it is associated with the ddname SORTLIB. The control program obtains the unit assignment and volume serial number from the catalog and, if the volume is not already mounted, writes a mounting message to the operator. indicates that the data set existed before this job step, that it should be kept after this job step, and that it can be used concurrently by several jobs (SHR). None of the jobs should change the data set in any way.

DISP

For information on the parameters used in the SORTLIB DD statement, the conditions under which they are required, and the default values assumed if a parameter is not included, see Table 6 on page 62. The subparameters of the DCB parameter are described in the same detail in Table 7 on page 63. For more detailed information, see z/OS MVS JCL Reference and z/OS MVS JCL Users Guide

SYMNAMES DD and SYMNOUT DD Statements

See Chapter 7, Using Symbols for Fields and Constants, on page 617 for details.

SORTIN DD Statement
The SORTIN DD statement describes the characteristics of the data set in which the records to be sorted or copied reside and also indicates its location. When Required: A SORTIN DD statement is required for all sort or copy applications, unless you provide an E15 user exit that supplies all input to DFSORT and include a RECORD statement in the program control statements. The SORTIN DD statement is ignored if your program invokes DFSORT and passes the address of your E15 user exit in the parameter list. Data Set Characteristics: DFSORT accepts empty and null non-VSAM data sets, and DUMMY data sets, for sorting and copying (be sure to supply RECFM, LRECL

68

z/OS V1R10.0 DFSORT Application Programming Guide

Using DD Statements
and BLKSIZE). DFSORT also accepts empty VSAM data sets for sorting and copying provided VSAMEMT is in effect. For non-VSAM data sets, DFSORT examines the DS1LSTAR field in the format-1 DSCB to determine whether the data set is empty or null. If DS1LSTAR is zero, DFSORT treats the data set as empty or null. If the data set is a null multivolume data set and the DS1IND80 flag is off in the format-1 DSCB of the first volume of the multivolume data set, DFSORT opens the data set for output to force an end of file (EOF) mark before using the data set for input. Note that a null data set is one that has been newly created, but never successfully closed. Null data sets cannot be processed successfully for a tape work data set sort. The System Code field in the data set label in the disk Volume Table of Contents (DSCB in the VTOC) indicates a data set created by the VSE operating system if it contains the letters DOS or VSE within it. Such data sets are never treated as null; however, they may be empty. DFSORT cannot process VSE disk data sets that do not have DOS or VSE within the System Code field. DFSORT may set what it considers to be appropriate values for missing attributes (RECFM, LRECL, BLKSIZE) of input data sets based on other attributes, or may terminate due to a missing attribute. If a missing attribute results in termination, or you dont want to use a missing attribute set by DFSORT, specify that attribute explicitly (for example, specify RECFM=VB). See Data Set Considerations on page 12 for additional considerations. The following rules apply to concatenated data sets: v RECFM must be either all fixed-length or all variable-length for the data sets in the concatenation. v BLKSIZE can vary. However, if a tape data set has the largest block size and is not first in the concatenation, you must specify BLKSIZE explicitly on its DD statement in the following two situations: Blockset is selected and the tape data set has a block size greater than 32760 bytes, but the block size is not available from DFSMSrmm or ICETPEX. Blockset is not selected. v With fixed-length records, LRECL must be the same for all data sets. With variable-length records, LRECL can vary. However: If Blockset is selected: If a tape data set has the largest LRECL and is not first in the concatenation, you must specify LRECL explicitly on its DD statement if the LRECL is not available from DFSMSrmm or ICETPEX. If Blockset is not selected, the first data set in the concatenation must have the largest LRECL (LRECL can be specified explicitly on its DD statement). v If the data sets are on unlike devices, you cannot use the EXLST parameter at user exit E18. v If Blockset is not selected and BSAM is used, all null data sets must precede all non-null data sets; otherwise, the results are unpredictable. v DFSORT forces an EOF mark on all null data sets whose format-1 DSCB DS1IND80 flag is off before using BSAM to process the null data sets. v If you define a data set using the DUMMY parameter, do not concatenate other data sets to it; the system ignores data sets concatenated to a DUMMY data set. v VSAM data sets must not be concatenated (system restriction). v Input cannot consist of both VSAM and non-VSAM data sets. General Coding Notes:
Chapter 2. Invoking DFSORT with Job Control Language

69

Using DD Statements
v For a copy application, the SORTIN data set should not be the same as the SORTOUT data set or any OUTFIL data set because this can cause lost or incorrect data or unpredictable results. v For a sort application, the SORTIN data set should not be the same as any SORTWKdd data set because this can cause lost or incorrect data or unpredictable results. The SORTIN data set can be the same as the SORTOUT data set or an OUTFIL data set, but this situation can lead to the loss of the data set if the sort application does not end successfully. v FREE=CLOSE cannot be specified. User labels are not copied. Example 2 SORTIN DD Statement:
//SORTIN DD DSNAME=INPUT,DISP=SHR

This example shows DD statement parameters that define a previously cataloged input data set: DSNAME causes the system to search the catalog for a data set with the name INPUT. When the data set is found, it is associated with the ddname SORTIN. The control program obtains the unit assignment and volume serial number from the catalog and, if the volume is not already mounted, writes a mounting message to the operator. DISP indicates that the data set existed before this job step, that it should be kept after this job step, and that it can be used concurrently by several jobs (SHR). None of the jobs should change the data set in any way.

Example 3 Volume Parameter on SORTIN DD:

//SORTIN // DD DSN=SORTIN,DISP=(OLD,KEEP),UNIT=3490, VOL=SER=(75836,79661,72945)

If the input data set is contained on more than one reel of magnetic tape, the VOLUME parameter must be included on the SORTIN DD statement to indicate the serial numbers of the tape reels. In this example, the input data set is on three reels that have serial numbers 75836, 79661, and 72945. If a data set is not on a disk or on a standard-labeled tape, you must specify DCB parameters in its DD statement.

SORTINnn DD Statement
The SORTINnn DD statements describe the characteristics of the data sets in which records to be merged reside and indicate the locations of these data sets. When Required: SORTINnn DD statements are always needed for a merge, unless the merge is invoked from another program and all input is supplied through a routine at user exit E32. Data Set Characteristics: Input data sets can be either non-VSAM or VSAM, but not both. DFSORT accepts empty and null non-VSAM data sets, and DUMMY data sets, for merging (be sure to supply RECFM, LRECL and BLKSIZE). DFSORT also accepts empty VSAM data sets for merging provided VSAMEMT is in effect. For non-VSAM data sets, DFSORT examines the DS1LSTAR field in the format-1 DSCB to determine whether the data set is null or empty. If DS1LSTAR is zero, DFSORT treats the data set as null or empty. A null data set is one that has been newly created but never successfully closed. Null data sets cannot be processed successfully by the Conventional merge technique.

70

z/OS V1R10.0 DFSORT Application Programming Guide

Using DD Statements
RECFM must be the same for all input data sets. BLKSIZE can vary, but for a Conventional merge, SORTIN01 must specify the largest block size. With fixed-length records, LRECL must be the same for all data sets. With variable-length records, LRECL can vary. Data sets can be multivolume but not concatenated. If a SORTINnn data set is multivolume and null, DFSORT forces an EOF mark on the data set before use. DFSORT may set what it considers to be appropriate values for missing attributes (RECFM, LRECL, BLKSIZE) of input data sets based on other attributes, or may terminate due to a missing attribute. If a missing attribute results in termination, or you dont want to use a missing attribute set by DFSORT, specify that attribute explicitly (for example, specify RECFM=VB). See Data Set Notes and Limitations on page 13 for additional considerations. General Coding Notes: v A SORTINnn data set should not be the same as the SORTOUT data set or any OUTFIL data set because this can cause lost or incorrect data or unpredictable results. v You can merge up to 100 data sets with Blockset merge or up to 16 data sets with Conventional merge. If Conventional merge is selected, check message ICE800I for the reason Blockset could not be used and correct the indicated condition, if possible. With Blockset merge, nn can be any integer from 00 (the initial zero is optional) to 99, in any order. Blockset merge treats ddnames of the form SORTINn and SORTIN0n as duplicates, and ignores any occurrences after: the first. For example, if you have
//SORTIN4 DD . . . //SORTIN04 DD . . .

the SORTIN04 DD will be ignored. With Conventional merge, nn can range from 01 to 16. The first number you use must be 01 and the remainder must follow in numeric order. Numbers cannot be skipped. Conventional merge cannot use ddnames of the form SORTIN0-SORTIN9, SORTIN00 or SORTIN17-SORTIN99. v FREE=CLOSE cannot be specified. User labels are not copied. Example 4 SORTIN01-03 DD Statements (Merge):
//SORTIN01 DD DSNAME=MERGE1,VOLUME=SER=000111,DISP=OLD, // LABEL=(,NL),UNIT=3590, // DCB=(RECFM=FB,LRECL=80,BLKSIZE=32000) //SORTIN02 DD DSNAME=MERGE2,VOLUME=SER=000121,DISP=OLD, // LABEL=(,NL),UNIT=3590, // DCB=(RECFM=FB,LRECL=80,BLKSIZE=32000) //SORTIN03 DD DSNAME=MERGE3,VOLUME=SER=000131,DISP=OLD, // LABEL=(,NL),UNIT=3590, // DCB=(RECFM=FB,LRECL=80,BLKSIZE=32000)

Example 5 SORTIN01-02 DD Statements (Merge):

Chapter 2. Invoking DFSORT with Job Control Language

71

Using DD Statements
//SORTIN01 DD DSNAME=INPUT1,VOLUME=SER=000101, // UNIT=3390,DISP=OLD //SORTIN02 DD DSNAME=INPUT2,VOLUME=SER=000201, // UNIT=3390,DISP=OLD * *DCB PARAMETERS *SUPPLIED FROM *LABELS

SORTWKdd DD Statement
The SORTWKdd DD statements describe the characteristics of the data sets used as intermediate storage areas for records to be sorted; they also indicate the location of these data sets. Up to 255 SORTWKdd DD statements can be specified. However, if you specify more than 32 and the Blockset technique is not selected, only the first 32 are used. When Required: One or more SORTWKdd statements are required for each sort application (but not a merge or copy), unless: v Input can be contained in main storage v Dynamic work space allocation has been requested (DYNALLOC) v dataspace sorting, Hipersorting, or memory object sorting is used. For information on using work data sets, see Appendix A, Using Work Space, on page 731. Diagnostic message ICE803I gives information on intermediate storage allocation and use. Devices: SORTWKdd data sets can be on disk or on tape, but not both. Disk types can be mixed. Tape must be nine-track unless input is on seven-track tape, in which case work tapes can (but need not) be seven-track. General Coding Notes: v Unless the input file is very large, two or three SORTWKdd data sets are usually sufficient. Two or three large SORTWKdd data sets are preferable to several small data sets. Placing each SORTWKdd data set on a separate device can improve performance. For optimum allocation of resources such as virtual storage, avoid specifying a large number of work data sets unnecessarily. v A SORTWKdd data set should not be the same as the SORTIN data set, the SORTOUT data set, any OUTFIL data set, or any other SORTWKdd data set because this can cause lost or incorrect data or unpredictable results. v Cylinder allocation is preferable for performance reasons. Temporary SORTWKdd data sets allocated in tracks or blocks (without ROUND) are readjusted to cylinders by DFSORT. v For disk work data sets, any valid ddname of the form SORTWKdd or SORTWKd can be used (for example, SORTWK01, SORTWKC3, SORTWK2, SORTWK#5, SORTWKA, SORTWKXY and so on). The ddnames can be in any order. SORTWKd and SORTWK0d are not treated as duplicate ddnames (for example, SORTWK5 and SORTWK05 will both be used if specified, as will SORTWKQ and SORTWK0Q). If you specify more than 255 ddnames and the Blockset technique is selected, only the first 255 ddnames are used. If you specify more than 32 ddnames and the Blockset technique is not selected, only the first 32 ddnames are used.

72

z/OS V1R10.0 DFSORT Application Programming Guide

Using DD Statements
v For tape work data sets, at least three SORTWKdd data sets must be specified. The first three ddnames must be SORTWK01, SORTWK02 and SORTWK03. Subsequent ddnames, if specified, must be in order from SORTWK04 through SORTWK32, with no numbers skipped, v FREE=CLOSE cannot be specified. v Spool, dummy, pipe, and HFS data sets, and HFS files, must not be specified as work data sets. v Parameters relating to ISCII/ASCII data should not be included for tape work data sets. Disk Work Data Set Coding Notes: v Data sets must be physical sequential; they cannot be partitioned or extended format. v The SPLIT cylinder parameter must not be specified. v If no secondary allocation is requested for temporary SORTWKdd data sets, automatic secondary allocation will be used unless NOWRKSEC is in effect. (Secondary allocation is limited to 12 work data sets in the Peerage and Vale sorting techniques only.) v If the data set is allocated to VIO, there is no automatic secondary allocation. v Secondary allocation can be requested for work data sets. For the Peerage and Vale sorting techniques only, secondary allocation is limited to the first 12 work data sets; if more work data sets are defined, they are used with only the primary allocation. v DFSORT uses only the space on the first volume specified for a multivolume data set. Space on the second and subsequent volumes is not used. Multivolume SORTWKdd data sets are, therefore, treated as single-volume SORTWKdd data sets. | | | | | v DFSORT work data sets can exceed 65536 cylinders if allocated as large format data sets on disk devices. Dynamically allocated disk work data sets are automatically allocated by DFSORT as large format. DSNTYPE=LARGE must be specified on SORTWKdd DD statements to allocate JCL work data sets as large format. v If primary space is fragmented, all but the first fragment are handled as secondary space. Virtual I/O: If a SORTWKdd data set is specified on a virtual device: v With VIO=NO: DFSORT performs dynamic reallocation using the ddname SORTDKdd on a real device with the same device type as the virtual device. If a real device corresponding to the virtual device is not available in the system, DFSORT terminates with an ICE083A message; see z/OS DFSORT Messages, Codes and Diagnosis Guide for more information about this error. Non-VIO SORTWKdd data sets are also reallocated when VIO SORTWKdd data sets are present. v With VIO=YES: the virtual device is used; performance may be degraded. v DFSORT work data sets cannot be allocated as large format data sets if VIO is used. The following is an example of a SORTWKdd DD statement using a disk work: data set Example 6 SORTWK01 DD Statement, Disk Work Data Set:
//SORTWK01 DD SPACE=(CYL,(15,5)),UNIT=3390

| |

Chapter 2. Invoking DFSORT with Job Control Language

73

Using DD Statements
If you use the checkpoint/restart facility and need to make a deferred restart, you must make the following additions to the above statement so that the sort work data set is not lost:
DSNAME=name1,DISP=(NEW,DELETE,CATLG)

Thus the same SORTWKdd DD statement for a deferred restart would be:
//SORTWK01 DD DSNAME=name1,UNIT=3390,SPACE=(CYL,(15,5)), // DISP=(NEW,DELETE,CATLG)

The following is an example of SORTWKdd DD statements using three tape devices. Example 7 SORTWK01-03 DD Statement, Tape Intermediate Storage:
//SORTWK01 DD //SORTWK02 DD //SORTWK03 DD UNIT=3480,LABEL=(,NL) UNIT=3480,LABEL=(,NL) UNIT=3480,LABEL=(,NL)

If DFSORT terminates unsuccessfully and the above DD statements have been specified, the intermediate storage data sets remain in the system until the step has been successfully rerun or until the data sets have been deleted by some other means. These parameters specify unlabeled data sets on three 3480 tape units. Because the DSNAME parameters are omitted, the system assigns unique names.

SORTOUT and OUTFIL DD Statements

The SORTOUT and OUTFIL DD statements describe the characteristics of the data sets in which the processed records are to be placed and indicate their location. The SORTOUT DD statement specifies the single non-OUTFIL output data set for a sort, copy, or merge application. OUTFIL processing does not apply to SORTOUT. The FNAMES and FILES parameters of one or more OUTFIL statements specify the ddnames of the OUTFIL data sets for a sort, copy, or merge application. The parameters specified for each OUTFIL statement define the OUTFIL processing to be performed for the OUTFIL data sets associated with that statement. For specific information about OUTFIL processing, see OUTFIL Control Statements on page 221. Although the ddname SORTOUT can actually be used for an OUTFIL data set, the term SORTOUT will be used to denote the single non-OUTFIL output data set. When Required: Each ddname specified in an OUTFIL statement requires a corresponding DD statement for that OUTFIL data set. If you do not specify OUTFIL statements, a SORTOUT DD statement is required unless you provide an E35 user exit that disposes of all output. A SORTOUT DD statement is ignored if your program invokes DFSORT and passes the address of an E35 user exit in the parameter list. If you specify OUTFIL statements, you do not have to specify a SORTOUT DD statement or an E35 user exit, although you can use either or both. Data Set Characteristics: See Data Set Considerations on page 12 for additional considerations.

74

z/OS V1R10.0 DFSORT Application Programming Guide

SORTOUT and OUTFIL DD Statements

Block size: Unless SDB=NO is in effect, Blockset uses the system-determined optimum block size in most cases when the output data set block size is zero. See the discussion of the SDB option in OPTION Control Statement on page 167 for complete details about DFSORTs use of system-determined block size. For some jobs, the selection of a larger output data set block size can require an increase in the amount of storage needed for successful DFSORT processing. Applications which require a specific output data set block size should be changed to specify that block size explicitly. If SDB=NO is in effect, DFSORT selects an appropriate (though not necessarily optimum) block size for the output data set based on the available attributes from the output data set, the input data set, and the RECORD statement. The output data set block size will not necessarily be the same as the input block size. Reblockable Indicator: DFSORT sets the reblockable indicator in the output data set label when Blockset is selected and v DFSORT sets the system-determined optimum block size for the output data set (see Block size) or v Allocation sets the system-determined optimum block size for the output data set before DFSORT gets control. General Coding Notes: v For a copy application, neither the SORTOUT data set nor any OUTFIL data set should be the same as the SORTIN data set because this can cause lost or incorrect data or unpredictable results. v For a merge application, neither the SORTOUT data set nor any OUTFIL data set should be the same as any SORTINnn data set because this can cause lost or incorrect data or unpredictable results. v For a sort application, the SORTOUT data set or an OUTFIL data set can be the same as the SORTIN data set, but this situation can lead to the loss of the data set if the sort application does not end successfully. v An OUTFIL data set should not be the same as the SORTOUT data set or any other OUTFIL data set because this can cause lost or incorrect data or unpredictable results. v Do not specify OPTCD=W for a full function IBM 3480 tape unit; it is overridden. For a 3480 operating in 3420 compatibility mode (specified as 3400-9), the OPTCD=W request is not overridden, but performance might be degraded. v If no secondary allocation is requested for a temporary or new output data set, automatic secondary allocation will be used unless NOOUTSEC is in effect. v The RECFM, LRECL, and BLKSIZE in a tape label are used only for a tape output data set with DISP=MOD, a DD volser present, and an AL, SL, or NSL label, when appropriate. v FREE=CLOSE cannot be specified. v See the discussion of the SOLRF and NOSOLRF options in OPTION Control Statement on page 167 for information related to the SORTOUT LRECL. Example 8 SORTOUT DD Statement:

Chapter 2. Invoking DFSORT with Job Control Language

75

SORTOUT and OUTFIL DD Statements

//SORTOUT DD DSN=C905460.OUTPT,UNIT=3390,SPACE=(CYL,5), // DISP=(NEW,CATLG)

DISP specifies the data set unknown to the operating system (NEW) and catalogs (CATLG) it under the name C905460.OUTPT. DSNAME specifies that the data set is called C905460.OUTPT. SPACE requests five cylinders of storage for the data set. UNIT Indicates that the data set is on a 3390.

SORTCKPT DD Statement
The SORTCKPT data set can be allocated on any device that operates with the Basic Sequential Access Method (BSAM). Processing must be restarted only from the last checkpoint taken. Example 9 SORTCKPT DD Statement:
//SORTCKPT DD DSNAME=CHECK,VOLUME=SER=000123, // DSP=(NEW,KEEP),UNIT=3480

When you allocate the SORTCKPT data set, you must include at least one work data set. If the CKPT operand is specified on the OPTION or SORT control statement, more intermediate storage could be required. If you want to use the Checkpoint/Restart Facility, refer to Checkpoint/Restart on page 787.

SORTCNTL DD Statement
The SORTCNTL data set can be used to supply DFSORT control statements, comment statements, blank statements, and remarks when DFSORT is invoked from another program (written, for example, in COBOL or PL/I). v The SORTCNTL data set usually resides in the input stream, but can be defined as a sequential data set or as a member of a partitioned data set. v The data set must be defined with RECFM of F or FB. The LRECL can be 80, or more (when valid). If the LRECL is greater than 80, DFSORT will use the first 80 bytes of each record. v DFSORT supports concatenated SORTCNTL data sets to the extent that the system supports like concatenated data sets for BSAM. Refer to z/OS DFSMS Using Data Sets for further information about like concatenated data sets. v When DFSORT is invoked from a PL/I program, the SORTCNTL or DFSPARM data set must not be used to supply a new RECORD control statement. Example 10 SORTCNTL DD Statement:
//SORTCNTL DD * OPTION MAINSIZE=8M

Notes: 1. The OPTION statement keywords EFS, LIST, NOLIST, LISTX, NOLISTX, LOCALE, MSGPRT, MSGDDN, SMF, SORTDD, SORTIN, and SORTOUT are used only when they are passed by an extended parameter list or when in the

76

z/OS V1R10.0 DFSORT Application Programming Guide

SORTCNTL DD Statement
DFSPARM data set. If they are specified on an OPTION statement read from the SYSIN or SORTCNTL data set, the keyword is recognized, but the parameters are ignored. If your program invokes DFSORT more than once, you can direct DFSORT to read different versions of the SORTCNTL data set at each call. See the explanation of the SORTDD parameter in OPTION Control Statement on page 167. 2. If you use the DFSPARM DD statement instead of the SORTCNTL DD statement, you can specify both EXEC PARM options and DFSORT control statements in a single source data set that overrides all other sources. See DFSPARM DD Statement. For override rules, see Appendix B, Specification/Override of DFSORT Options, on page 741.

DFSPARM DD Statement
The DFSPARM DD statement can be used to supply DFSORT program control statements and EXEC statement PARM options from a single DD source. Because statements in the DFSPARM data set are read whether DFSORT is program invoked or directly invoked, you can specify EXEC PARM options when invoking DFSORT from another program (unlike SORTCNTL). DFSPARM accepts all DFSORT program control statements and all EXEC statement PARM options (including those ignored by SYSIN and SORTCNTL) and any equivalent options specified on a DFSORT OPTION statement. DFSPARM also accepts comment statements, blank statements, and remarks. For examples of using DFSPARM when you call DFSORT from a program, see Overriding DFSORT Control Statements from Programs on page 462. Full override and applicability details are listed below and in Appendix B, Specification/Override of DFSORT Options, on page 741. v If you use DFSPARM, SYSIN is not necessary unless your job requires link-editing. v The DFSPARM data set usually resides in the input stream, but it can be defined as a sequential data set or as a member of a partitioned data set. v The data set must be defined with RECFM of F or FB. The LRECL can be 80, or more (when valid). If the LRECL is greater than 80, DFSORT will use the first 80 bytes of each record. v DFSORT supports concatenated DFSPARM data sets to the extent that the system supports like concatenated data sets for BSAM. Refer to z/OS DFSMS Using Data Sets for further information about like concatenated data sets. v When DFSORT is invoked from a PL/I program, the SORTCNTL or DFSPARM data set must not be used to supply a new RECORD control statement. Note: The ddname DFSPARM is used throughout this document to refer to this data set source for EXEC PARM options and DFSORT program control statements. When your system programmers installed DFSORT, they might have changed this name to one more appropriate for your site with the PARMDDN installation option. However, DFSORT will always use a DFSPARM data set of present, unless a DD statement with the PARMDDN name is also present.

Chapter 2. Invoking DFSORT with Job Control Language

77

DFSPARM DD Statement
General Coding Notes: Coding of parameters in the DFSPARM DD statement follows the same rules used for the JCL EXEC statement PARM options and the program control statements specified in SYSIN or SORTCNTL. The following exceptions apply: v Labels are not allowed. v PARM options and program control statements cannot be mixed on the same line, but can be specified in any order on different lines. v PARM options must be specified without the PARM= keyword and without quote marks. v Commas (or semicolons) are accepted, but not required, to continue PARM options to another line. v Leading blanks are not required for PARM options, but at least one leading blank is required for program control statements. FREE=CLOSE can be used for applicable DFSPARM data sets (for example, with temporary and permanent sequential data sets, but not with DD * data sets). When DFSORT is called from another program, FREE=CLOSE causes the DFSPARM data set to be released when DFSORT returns to the caller. This allows another DFSPARM data set to be used for a subsequent call. For example, if a COBOL program contains three SORT verbs, the following would cause the control statements in DP1 to be used for the first SORT verb, the control statements in DP2 to be used for the second SORT verb, and the: control statements in DP3 to be used for the third SORT verb //DFSPARM DD DSN=DP1,DISP=SHR,FREE=CLOSE //DFSPARM DD DSN=DP2,DISP=SHR,FREE=CLOSE //DFSPARM DD DSN=DP3,DISP=SHR,FREE=CLOSE Without FREE=CLOSE, DP1 would be used for all three SORT verbs. Example 11 DFSPARM DD Statement:
//DFSPARM DD * SORT FIELDS=(1,2,CH,A),STOPAFT=300 ABEND OPTION SORTIN=DATAIN STOPAFT=500

In this example, the DFSPARM DD data set passes a DFSORT SORT statement, the ABEND and STOPAFT parameters equivalent to specifying PARM=ABEND,STOPAFT=500 in a JCL EXEC statement, and a DFSORT OPTION statement. Notes: 1. SORT and OPTION are control statements. ABEND and STOPAFT=500 are PARM options. 2. The PARM option STOPAFT=500 overrides the SORT control statement option STOPAFT=300. 3. When PARMDDN=DFSPARM is specified or defaulted v if a //DFSPARM DD data set is available at run-time, DFSORT will use it v if a //DFSPARM DD data set is not available at run-time, DFSORT will use a //$ORTPARM DD data set if available.

78

z/OS V1R10.0 DFSORT Application Programming Guide

DFSPARM DD Statement
Thus with PARMDDN=DFSPARM, you can choose to specify either a //DFSPARM DD data set or a //$ORTPARM DD data set for a particular DFSORT application. 4. When PARMDDN=ddname is specified v if a //ddname DD data set is available at run-time, DFSORT will use it v if a //ddname DD data set is not available at run-time, DFSORT will use a //DFSPARM DD data set if available. Thus with PARMDDN=ddname, you can choose to specify either a //ddname DD data set or a //DFSPARM DD data set for a particular DFSORT application. Example 12 DFSPARM DD Statement:
//DFSPARM DD * SORT FIELDS=(5,2,CH,D),SKIPREC=10 STOPAFT=100,BSAM,SKIPREC=5 OPTION SORTIN=DATAIN,SKIPREC=20

In this example, the DFSPARM DD data set contains a SORT program control statement, three PARM options on one line, and an OPTION program control statement. Note: Because PARM options override program control statements, DFSORT uses SKIPREC=5 and ignores the other SKIPREC specifications. For information on the parameters used in the DFSPARM DD statement, the conditions under which they are required, and any default values assumed if a parameter is omitted, see Specifying EXEC/DFSPARM PARM Options on page 29 and Chapter 3, Using DFSORT Program Control Statements, on page 81.

SORTDKdd DD Statement
| SORTWKdd data sets can be assigned to VIO. If the VIO installation option is specified or defaults to NO, SORTWKdd data sets are deallocated and reallocated by DFSORT using SORTDKdd ddnames. SORTDKdd ddnames are reserved for use by DFSORT.

SORTDIAG DD Statement
The SORTDIAG DD statement specifies that all messages, including diagnostic messages (ICE800I through ICE999I), and control statements are to be written to the message data set. The statement can be used for all DFSORT techniques and provides information on EXCP counts, intermediate storage allocation and use, and so on. The SORTDIAG DD statement has no effect on console messages. The statement is intended as a diagnostic tool. When SORTDIAG is used, a SYSOUT DD statement or a ddname DD statement (where ddname is the alternate message data set ddname specified during installation or run-time) should be provided. If installation option NOMSGDD=QUIT is in effect and neither an alternate message data set ddname statement nor a SYSOUT ddname statement is provided, DFSORT terminates with a return code of 20. Example 13 SORTDIAG DD Statement:
//SORTDIAG DD DUMMY

SORTSNAP DD Statement
The SORTSNAP DD statement defines the data set where the snap dumps requested by the ESTAE recovery routine, or the snap dumps requested before or
Chapter 2. Invoking DFSORT with Job Control Language

79

SORTSNAP DD Statement
after a call to an EFS program are printed. SORTSNAP is dynamically allocated by DFSORT whenever it is required. The ddname, SORTSNAP, is reserved for DFSORT.

80

z/OS V1R10.0 DFSORT Application Programming Guide

Chapter 3. Using DFSORT Program Control Statements

Using Program Control Statements . . . . . . 82 Control Statement Summary . . . . . . . . . 83 Describing the Primary Task . . . . . . . . 83 Including or Omitting Records . . . . . . . 83 Reformatting and Editing Records . . . . . . 83 Producing Multiple Output and Reports and Converting Records. . . . . . . . . . . 84 Invoking Additional Functions and Options . . 84 Using Symbols . . . . . . . . . . . . 84 General Coding Rules . . . . . . . . . . . 84 Continuation Lines . . . . . . . . . . . 86 Inserting Comment Statements . . . . . . . 88 Coding Restrictions . . . . . . . . . . . 89 EFS Restrictions When an EFS Program Is in Effect . . . . . . . . . . . . . . 89 Using Control Statements from Other IBM Programs . . . . . . . . . . . . . 89 ALTSEQ Control Statement . . . . . . . . . 89 Altering EBCDIC Collating SequenceExamples 90 Example 1 . . . . . . . . . . . . . 90 Example 2 . . . . . . . . . . . . . 91 Example 3 . . . . . . . . . . . . . 91 Example 4 . . . . . . . . . . . . . 91 Example 5 . . . . . . . . . . . . . 91 DEBUG Control Statement . . . . . . . . . 92 Specifying Diagnostic OptionsExamples . . . 97 Example 1 . . . . . . . . . . . . . 97 Example 2 . . . . . . . . . . . . . 97 END Control Statement . . . . . . . . . . 97 Discontinue Reading Control StatementsExamples . . . . . . . . . . 97 Example 1 . . . . . . . . . . . . . 97 Example 2 . . . . . . . . . . . . . 97 INCLUDE Control Statement . . . . . . . . 98 Relational Condition . . . . . . . . . . 101 Comparisons . . . . . . . . . . . . 101 Relational Condition Format . . . . . . 101 Padding and Truncation . . . . . . . . 109 Cultural Environment Considerations . . . 110 Including Records in the Output Data SetComparison Examples. . . . . . . . 110 Example 1 . . . . . . . . . . . . 110 Example 2 . . . . . . . . . . . . 110 Example 3 . . . . . . . . . . . . 111 Example 4 . . . . . . . . . . . . 111 Example 5 . . . . . . . . . . . . 112 Example 6 . . . . . . . . . . . . 112 Example 7 . . . . . . . . . . . . 112 Substring Comparison Tests . . . . . . . 112 Relational Condition Format . . . . . . 113 Including Records in the Output Data SetSubstring Comparison Example . . . . 114 Example . . . . . . . . . . . . . 114 Bit Logic Tests . . . . . . . . . . . . 114 Method 1: Bit Operator Tests . . . . . . . 114 Relational Condition Format . . . . . . 114
Copyright IBM Corp. 1973, 2006

Fields . . . . . . . . . . . . . . Mask . . . . . . . . . . . . . . Padding and Truncation . . . . . . . . . Including Records in the Output Data SetBit Operator Test Examples . . . . . . . . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Example 3 . . . . . . . . . . . . Method 2: Bit Comparison Tests . . . . . . Relational Condition Format . . . . . . Fields . . . . . . . . . . . . . . Bit Constant . . . . . . . . . . . . Padding and Truncation . . . . . . . . Including Records in the Output Data SetBit Comparison Test Examples . . . . . . . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Example 3 . . . . . . . . . . . . Date Comparisons . . . . . . . . . . . Relational Condition Format . . . . . . Including Records in the Output Data SetDate Comparisons . . . . . . . . . . . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Numeric Tests . . . . . . . . . . . . Relational Condition Format . . . . . . Including Records in the Output Data Set--Numeric Tests . . . . . . . . . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . INCLUDE/OMIT Statement Notes . . . . . INREC Control Statement . . . . . . . . . INREC Statement Notes . . . . . . . . . Reformatting Records Before Processing Examples . . . . . . . . . . . . . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Example 3 . . . . . . . . . . . . Example 4 . . . . . . . . . . . . Example 5 . . . . . . . . . . . . Example 6 . . . . . . . . . . . . Example 7 . . . . . . . . . . . . Example 8 . . . . . . . . . . . . Example 9 . . . . . . . . . . . . MERGE Control Statement . . . . . . . . . Specifying a MERGE or COPYExamples . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Example 3 . . . . . . . . . . . . Example 4 . . . . . . . . . . . . MODS Control Statement . . . . . . . . . Identifying User Exit RoutinesExamples . . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . OMIT Control Statement . . . . . . . . .

115 115 116 116 116 116 116 117 117 117 118 118 118 118 118 119 119 119 122 122 122 122 123 124 124 124 124 125 147 149 149 150 150 151 152 152 153 154 155 156 159 159 159 159 160 160 163 163 163 163

81

Using DFSORT Program Control Statements

Omitting Records from the Output Data SetExample . . . . . . . . . Example . . . . . . . . . . OPTION Control Statement . . . . . Aliases for OPTION Statement Options. Specifying DFSORT Options or COPYExamples . . . . . . . . Example 1 . . . . . . . . . Example 2 . . . . . . . . . Example 3 . . . . . . . . . Example 4 . . . . . . . . . Example 5 . . . . . . . . . Example 6 . . . . . . . . . Example 7 . . . . . . . . . Example 8 . . . . . . . . . Example 9 . . . . . . . . . OUTFIL Control Statements . . . . . OUTFIL Statements Notes . . . . . OUTFIL FeaturesExamples . . . . Example 1 . . . . . . . . . Example 2 . . . . . . . . . Example 3 . . . . . . . . . Example 4 . . . . . . . . . Example 5 . . . . . . . . . Example 6 . . . . . . . . . Example 7 . . . . . . . . . Example 8 . . . . . . . . . Example 9 . . . . . . . . . Example 10 . . . . . . . . . Example 11 . . . . . . . . . Example 12 . . . . . . . . . Example 13 . . . . . . . . . Example 14 . . . . . . . . . Example 15 . . . . . . . . . Example 16 . . . . . . . . . Example 17 . . . . . . . . . Example 18 . . . . . . . . . Example 19 . . . . . . . . . Example 20 . . . . . . . . . Example 21 . . . . . . . . . Example 22 . . . . . . . . . Example 23 . . . . . . . . . Example 24 . . . . . . . . . Example 25 . . . . . . . . . Example 26 . . . . . . . . . OUTREC Control Statement . . . . . OUTREC Statement Notes . . . . . Reformatting Records After Processing Examples . . . . . . . . . . . Example 1 . . . . . . . . . Example 2 . . . . . . . . . Example 3 . . . . . . . . . Example 4 . . . . . . . . . Example 5 . . . . . . . . . Example 6 . . . . . . . . . Example 7 . . . . . . . . . Example 8 . . . . . . . . . Example 9 . . . . . . . . . Example 10 . . . . . . . . . Example 11 . . . . . . . . . Example 12 . . . . . . . . . Example 13 . . . . . . . . . Example 14 . . . . . . . . . RECORD Control Statement . . . . . Describing the Record Format and LengthExamples . . . . . . . Example 1 . . . . . . . . . Example 2 . . . . . . . . . SORT Control Statement . . . . . . . SORT/MERGE Statement Notes . . . Specifying a SORT or COPYExamples Example 1 . . . . . . . . . Example 2 . . . . . . . . . Example 3 . . . . . . . . . Example 4 . . . . . . . . . Example 5 . . . . . . . . . Example 6 . . . . . . . . . SUM Control Statement . . . . . . . SUM Statement Notes . . . . . . Adding Summary FieldsExamples . . Example 1 . . . . . . . . . Example 2 . . . . . . . . . Example 3 . . . . . . . . . Example 4 . . . . . . . . . Example 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 363 365 386 387 387 388 388 388 388 389 389 390 390 390 391 391 392 392 394 397 397 397 398 406 406 406 406 407 407 407 407 408 410 411 411 411 411 412 412

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

166 166 167 216 217 217 217 218 218 218 219 219 220 220 221 340 344 344 345 345 347 350 351 352 352 353 353 354 355 355 356 356 357 357 358 358 358 359 360 361 362

Using Program Control Statements

Program control statements direct DFSORT in processing your records. Some program control statements are required while others are optional. You use the control statements to: v Indicate whether a sort, merge, or copy is performed. v Describe the control fields to be used. v v v v Indicate program exits for transferring control to your own routines. Describe DFSORT functions you want to have invoked. Describe input and output files. Indicate various options you want to use during processing.

You can supply program control statements to DFSORT from: v A SYSIN data set

82

z/OS V1R10.0 DFSORT Application Programming Guide

Using Program Control Statements

v v v v A SORTCNTL data set A DFSPARM data set A 24-Bit parameter list An extended parameter list

See Appendix B, Specification/Override of DFSORT Options, on page 741 for an explanation of when to use each source. | | This chapter begins with a summary of DFSORT program control statements and coding rules. A detailed description of each statement follows.

Control Statement Summary Describing the Primary Task

The only required program control statement in a DFSORT application is a SORT, MERGE, or OPTION statement that specifies whether you want to sort, merge, or copy records. (Copying can be specified on any of the three statements.) SORT Describes control fields if you are coding a sort application, or specifies a copy application. Indicates whether you want ascending or descending order for the sort. Describes control fields if you are coding a merge application, or specifies a copy application. Indicates whether you want ascending or descending order for the merge. Overrides installation defaults (such as EQUALS, CHALT, and CHECK) and supplies optional information (such as DYNALLOC and SKIPREC). Can specify a copy application.

MERGE

OPTION

Including or Omitting Records

You can specify whether certain records are included in the output data sets or omitted from them. INCLUDE OMIT OUTFIL Specifies that only records whose fields meet certain criteria are included. Specifies that any records whose fields meet certain criteria are deleted. Specifies the records to be included or omitted in multiple output data sets.

Reformatting and Editing Records

You can modify individual records by deleting and reordering fields and inserting blanks, zeros, or constants. INREC OUTREC OUTFIL Specifies how records are reformatted before they are sorted, copied, or merged. Specifies how records are reformatted after they are sorted, copied, or merged. Specifies how records are reformatted in multiple output data sets.

Chapter 3. Using DFSORT Program Control Statements

83

Control Statement Summary

Producing Multiple Output and Reports and Converting Records

You can produce multiple output data sets and reports, convert variable-length records to fixed-length records, and convert fixed-length records to variable-length records. OUTFIL Specifies the output data sets and which records are to appear in each. Specifies how records are to be converted from variable-length to fixed-length or from fixed-length to variable-length.

Invoking Additional Functions and Options

You can use the remaining control statements to perform a variety of tasks. ALTSEQ Specifies changes to the ALTSEQ translation table to be used for SORT, MERGE, INCLUDE or OMIT fields with format AQ, for INREC, OUTREC, and OUTFIL fields with TRAN=ALTSEQ, and for INREC, OUTREC, and OUTFIL WHEN=(logexp) fields with format AQ. Specifies various diagnostic options. Causes DFSORT to discontinue reading SYSIN, SORTCNTL, or DFSPARM. Specifies use of one or more user exit routines in a DFSORT application. See Chapter 4, Using Your Own User Exit Routines, on page 413 for information about user exit routines. Can be used to supply length and type information. Specifies that numeric summary fields in records with equal control fields are summed in one record and that the other records are deleted.

DEBUG END MODS

RECORD SUM

Using Symbols
You can define and use a symbol for any field or constant in the following DFSORT control statements: INCLUDE, INREC, MERGE, OMIT, OUTFIL, OUTREC, SORT and SUM. You can also use a symbol for an output column in the following DFSORT control statements: INREC, OUTFIL and OUTREC. This makes it easy to create and reuse collections of symbols (that is, mappings) representing information associated with various record layouts. You can use system symbols (for example, &JOBNAME.) in your symbol constants. See Chapter 7, Using Symbols for Fields and Constants, on page 617 for complete details.

General Coding Rules

See Inserting Comment Statements on page 88 for an explanation of how to use comment statements, blank statements, and remarks. DFSORT program control statements and EXEC PARM options can also be specified together in a user-defined DD data set. See DFSPARM DD Statement on page 77 for special coding conventions that apply to this DD source. All other DFSORT control statements have the same general format, shown in Figure 6 on page 85. The illustrated format does not apply to control statements you supply in a parameter list. See Chapter 5, Invoking DFSORT from a Program, on page 461 for information on the special rules that apply.

84

z/OS V1R10.0 DFSORT Application Programming Guide

General Coding Rules

Column 1 must be blank unless a label is present 72 73 (Label) Operation Operand (Remarks) 80 (Sequence or Identification)

(Continuation column)
Figure 6. Control Statement Format

The control statements are free-form; that is, the operation definer, operands, and comment field can appear anywhere in a statement, provided they appear in the proper order and are separated by one or more blank characters. Column 1 of each control statement must be blank, unless the first field is a label or a comment statement (see Inserting Comment Statements on page 88). v Label Field A label can be specified on any control statement in SYSIN or SORTCNTL. A label is never required. If present, a label must begin in column 1 with any character other than a blank or asterisk (*). A label can be 1 to 70 characters and ends when a blank character is found. Any character can be used in a label. A label followed only by blanks is printed but otherwise not processed. Labels cannot be specified in the parameter list, in DFSPARM or in continuation lines. To skip the label, specify one or more blanks starting in column 1. The following illustrates the use of control statements with and without labels:
OPTION EQUALS MYSORT SORT FIELDS=(5,4,CH,A) OUTREC FIELDS=(1,20,51,30) OUT_1 OUTFIL FNAMES=OUT1,INCLUDE=(5,1,CH,EQ,CA) OUT_2 OUTFIL FNAMES=OUT2,INCLUDE=(5,1,CH,EQ,CB)

| | | | | | |

v Operation Field This field can appear anywhere between column 2 and column 71 of the first line. It contains a word (for example, SORT or MERGE) that identifies the statement type to the program. In the example below, the operation definer, SORT, is in the operation field of the sample control statement. v Operand Field The operand field is composed of one or more operands separated by commas or semicolons. This field must follow the operation field, and be separated from it by at least one blank. No blanks are allowed within the parameters, but a blank is required at the end of all parameters. If the statement occupies more than one line, the operand must begin on the first line. Each operand has an operand definer, or parameter (a group of characters that identifies the operand type to DFSORT). A value or a list of values can be associated with a parameter. The five possible operand forms shown in this chapter are: parameter. Examples: CHALT, NOCHALT, REMOVECC parameter(c). Examples: DATE1(/), TIME2(:), Y2W(-) parameter=value. An operand shown in the form parameter=value can also be specified in the equivalent form parameter(value) or parameter=(value). Examples: AVGRLEN=100, AVGRLEN(100), and AVGRLEN=(100) are

Chapter 3. Using DFSORT Program Control Statements

85

General Coding Rules

| | | | | | | | | | | | | | | | | | | equivalent, DYNALLOC=SYSDA, DYNALLOC(SYSDA), and DYNALLOC=(SYSDA) are equivalent, SAMPLE=20, SAMPLE(20), and SAMPLE=(20) are equivalent. parameter=(list). An operand shown in the form parameter=(list) can also be specified in the equivalent form parameter(list). Examples: FIELDS=(21,5,CH,A) and FIELDS(21,5,CH,A) are equivalent, BUILD=(1,20,HEX) and BUILD(1,20,HEX) are equivalent. parameter=(value). An operand shown in the form parameter=(value) can also be specified in the equivalent form parameter(value). Examples: DATE=(4MD/) and DATE(4MD/) are equivalent, TIMENS=(12) and TIMENS(12) are equivalent, NOMATCH=(C'***') and NOMATCH(C'***') are equivalent. The following example illustrates the parameter, parameter=value and parameter=(list) forms.
SORT EQUALS,FORMAT=CH,FIELDS=(10,30,A),STOPAFT=1000

The following example illustrates the parameter, parameter(value), parameter(list) and parameter=(value) forms.
SORT EQUALS,FORMAT(CH),FIELDS(10,30,A),STOPAFT=(1000)

The two SORT statements above are equivalent. v Remark Field This field can contain any information. It is not required, but if it is present, it must be separated from the last operand field by at least one blank. v Continuation Column (72) Any character other than a blank in this column indicates that the present statement is continued on the next line. However, as long as the last character of the operand field on a line is a comma or semicolon or colon followed by a blank, the program assumes that the next line is a continuation line. The nonblank character in column 72 is required only when a remark field is to be continued or when an operand is broken at column 71. v Columns 73 through 80 This field can be used for any purpose.

Continuation Lines
The format of the DFSORT continuation line is shown in Figure 7 on page 87.

86

z/OS V1R10.0 DFSORT Application Programming Guide

General Coding Rules

Column 1 must be blank

16 72 73 80 Optional use

Continued operand or remarks

(Continuation column)
Figure 7. Continuation Line Format

The continuation column and columns 73 through 80 of a continuation line have the same purpose as they do on the first line of a control statement. Column 1 must be blank. A continuation line is treated as a logical extension of the preceding line. Either an operand or a remark field can begin on one line (referred to as line 1 in the bullets below) and continue on the next line (referred to as line 2 in the bullets below). The following are the rules for continuation illustrated with examples (these different types of continuation can be intermixed): v Implicit continuation in 2-71: If line 1 breaks at a comma-blank or semicolon-blank or colon-blank, DFSORT continues on line 2 with the first nonblank character it finds in columns 2-71. For example:
* 1 2 3 4 5 6 7 *23456789012345678901234567890123456789012345678901234567890123456789012 INCLUDE COND=(5,4,CH,EQ, CABCD) SORT FIELDS=(9, 3, ZD, A) OUTREC FIELDS=(1,27,2X, FIRST FIELD AND TWO BLANKS 51,2,BI,M11, SECOND FIELD 60:9,3,ZD,PD) THIRD FIELD

The above statements will be treated as if they were specified as:

INCLUDE COND=(5,4,CH,EQ,CABCD) SORT FIELDS=(9,3,ZD,A) OUTREC FIELDS=(1,27,2X,51,2,BI,M11,60:9,3,ZD,PD)

v Explicit continuation in 16: If line 1 breaks at column 71 with a nonblank in column 72, and columns 2-15 of line 2 are blank, DFSORT continues on line 2 with whatever character it finds in column 16 (blank or nonblank). For example:
* 1 2 3 4 5 6 7 *23456789012345678901234567890123456789012345678901234567890123456789012 INCLUDE COND=(5,4,CH,E* Q,CABCD) SORT FIELDS=(9,3,* ZD,A) OUTREC FIELDS=(1,80,CBLANK WITHIN A* LITERAL)

The above statements will be treated as if they were specified as:

INCLUDE COND=(5,4,CH,EQ,CABCD) SORT FIELDS=(9,3,ZD,A) OUTREC FIELDS=(1,80,CBLANK WITHIN A LITERAL)

Chapter 3. Using DFSORT Program Control Statements

87

General Coding Rules

Attention: You should only start with a blank in column 16 of line 2 if you need a blank as the first character of the continued operand, as shown in the OUTREC statement above. A blank in column 16 of line 2 will be included in the operand and will result in invalid syntax if incorrectly placed. For example:
* 1 2 3 4 5 6 7 *23456789012345678901234567890123456789012345678901234567890123456789012 SORT FIELDS=(5,4,Z* D,A) SUM FIELDS=(5,4,Z* D)

The above statements will be treated as if they were specified as:

SORT FIELDS=(5,4,ZD,A) SUM FIELDS=(5,4,Z D)

With the D in column 16 of line 2, we get ZD in the SORT statement. But with the D in column 17 of line 2, we get Z D in the SUM statement instead of ZD, resulting in a syntax error. v Explicit continuation in 2-15: If line 1 breaks at column 71 with a nonblank in column 72, and columns 2-15 of line 2 are nonblank, DFSORT continues on line 2 with the first nonblank character it finds in columns 2-15. For example:
* 1 2 3 4 5 6 7 *23456789012345678901234567890123456789012345678901234567890123456789012 INCLUDE COND=(5,4,CH,EQ,CAB* CD) SORT FIELDS=(9,3,* ZD,A) OUTREC FIELDS=(5,4,2X* ,9,3,ZD,M26,80:X)

The above statements will be treated as if they were specified as:

INCLUDE COND=(5,4,CH,EQ,CABCD) SORT FIELDS=(9,3,ZD,A) OUTREC FIELDS=(5,4,2X,9,3,ZD,M26,80:X)

v Remark continuation in 2-71: If a statement ends on line 1 with a blank before column 72 and a nonblank in column 72, DFSORT treats the first nonblank character it finds in columns 2-71 of line 2 as the start of a remark. For example:
* 1 2 3 4 5 6 7 *23456789012345678901234567890123456789012345678901234567890123456789012 SORT FIELDS=(9,3,ZD,A) THIS IS A * CONTINUED REMARK

Tip: A simpler way to do the same thing (without continuation) is to use a comment statement for line 2. For example:
* 1 2 3 4 5 6 7 *23456789012345678901234567890123456789012345678901234567890123456789012 SORT FIELDS=(9,3,ZD,A) THIS IS A * CONTINUED REMARK

Inserting Comment Statements

v Specify comment statements by coding an asterisk (*) in column 1. A comment statement is printed along with other DFSORT program control statements but is not otherwise processed. v A statement with blanks in columns 1 through 71 is treated as a comment statement. v Comment statements are allowed only in the DFSPARM, SYSIN, and SORTCNTL data sets.

88

z/OS V1R10.0 DFSORT Application Programming Guide

General Coding Rules

Coding Restrictions
The following rules apply to control statement preparation: v Operation definers and operands must be in uppercase EBCDIC. v Column 1 of each control statement can be used only for a label or for a comment statement that begins with an asterisk in column 1. v If present, a label must begin in column 1. Labels are allowed only in the SYSIN and SORTCNTL data sets. v The entire operation definer must be contained on the first line of a control statement. v The first operand must begin on the first line of a control statement. The last operand in a statement must be followed by at least one blank. v Blanks are not allowed in operands. Anything following a blank is considered part of the remark field. v Remarks are allowed only in the DFSPARM, SYSIN, and SORTCNTL data sets. v Commas, semicolons, and blanks can be used only as delimiters. They can be used in values only if the values are constants. v Each type of program control statement can appear only once within a single source (for example, the SYSIN data set).

EFS Restrictions When an EFS Program Is in Effect

In addition to the items above, the following restrictions apply to control statement preparation for an EFS program. v Non-DFSORT operation definers can be up to 8 bytes long. v An operation definer with no operands is allowed only if: It is supplied through SYSIN, SORTCNTL, or DFSPARM. It is the only operation definer on a line; column 72 must contain a blank.

Using Control Statements from Other IBM Programs

The INPFIL control statement, which is used by other IBM sort programs, is accepted but not processed. However, control statement errors can result from continuation of an INPFIL statement. The information contained in the INPFIL statement for other IBM sort programs is supplied to DFSORT with DD statements. Because DFSORT uses the OPTION control statement, OPTION control statements in any job streams from other IBM sort programs cause DFSORT to terminate unless the parameters from the other program conform to the DFSORT OPTION control statement parameters.

ALTSEQ Control Statement

, ALTSEQ CODE=( fftt )

The ALTSEQ control statement can be used to change the alternate translation table (ALTSEQ table). Any modifications you specify are applied to the standard EBCDIC translation table. The modified ALTSEQ table overrides the installation default ALTSEQ table (the shipped default is the EBCDIC translation table).
Chapter 3. Using DFSORT Program Control Statements

89

ALTSEQ Control Statement

The ALTSEQ table can be used in two ways as follows: v To apply an alternate collating sequence for SORT, MERGE, INCLUDE, or OMIT fields, or for INREC, OUTREC, or OUTFIL IFTHEN WHEN=(logexp) fields, with format AQ (or format CH with CHALT in effect). In this case, the ALTSEQ table is used to change only the order in which data is collated, not the data itself. If you specify AQ (or CH with CHALT) without specifying an ALTSEQ control statement, DFSORT uses the installation default ALTSEQ table. For example, if you want to specify that the character $ (X5B) is to collate at position XEA, after uppercase Z (XE9), you should specify:
ALTSEQ CODE=(5BEA)

v To convert characters for INREC, OUTREC, or OUTFIL OUTREC fields with TRAN=ALTSEQ. In this case, the ALTSEQ table is used to change the actual data. If you specify TRAN=ALTSEQ without specifying an ALTSEQ control statement, DFSORT uses the installation default ALTSEQ table. For example, if you want to change the character $ (X5B) to the character * (X5C), you should specify:
ALTSEQ CODE=(5B5C)

CODE

, CODE=( fftt )

Specifies the original and modified EBCDIC collating positions. ff tt specifies, in hexadecimal, the character whose position is to be changed in the ALTSEQ table. specifies, in hexadecimal, the new position the character is to occupy in the ALTSEQ table.

The order in which the parameters are specified is not important. Notes: 1. If CHALT is in effect, control fields with format CH are collated using the ALTSEQ table, in addition to those with format AQ. 2. If you use locale processing for SORT, MERGE, INCLUDE, or OMIT fields, you must not use CHALT. If you need alternate sequence processing for a particular field, use format AQ. 3. Using ALTSEQ can degrade performance. Default: Usually the installation option. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741.

Altering EBCDIC Collating SequenceExamples

Example 1
SORT FIELDS=(18,20,AQ,A) ALTSEQ CODE=(5BEA)

90

z/OS V1R10.0 DFSORT Application Programming Guide

ALTSEQ Control Statement

The character $ (X'5B') is to collate at position X'EA', that is, after uppercase Z (X'E9').

Example 2
MERGE FIELDS=(25,7,A,1,10,D),FORMAT=CH OPTION CHALT ALTSEQ CODE=(F0B0,F1B1,F2B2,F3B3,F4B4,F5B5,F6B6, F7B7,F8B8,F9B9)

The numerals 0 through 9 are to collate before uppercase letters (but after lowercase letters).

Example 3
SORT FIELDS=(55,8,AQ,A) ALTSEQ CODE=(C1F1,C2F2)

The uppercase A (X'C1') is to collate at the same position as the numeral 1 (X'F1') and the uppercase B (X'C2') is to collate at the same position as the numeral 2 (X'F2'). Note that this ALTSEQ statement does NOT cause collating of A before or after 1, or of B before or after 2.

Example 4
SORT FIELDS=(55,8,AQ,A) ALTSEQ CODE=(81C1,82C2,83C3,84C4,85C5,86C6,87C7, 88C8,89C9,91D1,92D2,93D3,94D4,95D5,96D6, 97D7,98D8,99D9,A2E2,A3E3,A4E4,A5E5,A6E6, A7E7,A8E8,A9E9)

Each lowercase letter is to collate at the same position as the corresponding uppercase letter. For example, the lowercase a (X'81') is to collate at the same position as the uppercase A (X'C1'). This results in case-insensitive collating.

Example 5
OPTION COPY ALTSEQ CODE=(0040) OUTREC FIELDS=(1,80,TRAN=ALTSEQ)

Each binary zero (X00) is changed to a space (X40).

Chapter 3. Using DFSORT Program Control Statements

91

DEBUG Control Statement

DEBUG Control Statement

, DEBUG ABEND NOABEND ABSTP BSAM CFW NOCFW CTRx=n , EFSDPAFT=( n , n )

EFSDPBFR=( EQUCOUNT ESTAE NOESTAE NOASSIST

The DEBUG control statement is not intended for regular use; only ABEND, NOABEND, and BSAM are of general interest. For a tape work sort or a Conventional merge, only the ABEND or NOABEND parameters of the DEBUG statement are used. For more information about problem diagnosis, see z/OS DFSORT Messages, Codes and Diagnosis Guide. ABEND or NOABEND

ABEND NOABEND

Temporarily overrides the ERET installation option, which specifies whether DFSORT abends or terminates with a return code of 16, if your sort, copy, or merge is unsuccessful. ABEND Specifies that if your sort, copy, or merge is unsuccessful, DFSORT abends with a user completion code equal to the appropriate message number or with a user-defined number between 1 and 99, as set during installation with installation option ABCODE=n. When DEBUG ABEND is in effect, a user abend code of zero might be issued when a tape work data set sort or Conventional merge is unsuccessful. NOABEND Specifies that an unsuccessful sort, copy, or merge terminates with a return code of 16.

92

z/OS V1R10.0 DFSORT Application Programming Guide

DEBUG Control Statement

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. ABSTP Prevents loss of needed information in a dump when Blockset terminates. This option overrides ERET, ABEND, and NOABEND. If the DFSORT application is unsuccessful, an abend is forced with a completion code equal to the appropriate message number, or with the user ABEND code set with installation option ABCODE=MSG or ABCODE=n. The message is not written if NOESTAE is in effect. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. BSAM

| |

BSAM

Temporarily bypasses the EXCP access method for input and output data sets. BSAM is ignored for VSAM input and output data sets. Attention: If Blockset is not selected and BSAM processing is used with concatenated SORTIN input, and both null and non-null data sets are specified, all null data sets must precede all non-null data sets; otherwise, the results are unpredictable. Attention: This option can degrade performance. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. CFW or NOCFW

CFW NOCFW

Temporarily overrides the CFW installation option, which specifies whether DFSORT can use cache fast write when processing SORTWKdd data sets that reside on devices connected to cached 3990 control units. CFW Specifies that DFSORT can use cache fast write when processing SORTWKdd data sets.

NOCFW Specifies that DFSORT cannot use cache fast write.

Chapter 3. Using DFSORT Program Control Statements

93

DEBUG Control Statement

Attention: The NOCFW option can degrade performance. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. CTRx

CTRx=n

Keeps a count of the input and output records, and abends with code 0C1 when the count reaches n. The numbers that can be assigned to x are: 2 3 4 5 Counts the input records being moved from the input buffer (not used for a copy). Counts the output records being moved to the output buffer (not used for a copy or merge). Counts the input records inserted by E15 (not used for Blockset). Counts the output records deleted by E35 (not used for Blockset).

Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. EFSDPAFT

, EFSDPAFT=( n )

Initiates a SNAP dump after a Major Call to an EFS program. Any combination of the numbers can be specified. The numbers have the following meanings: 2 3 4 5 Takes the SNAP dump after Major Call 2 to the EFS program. Takes the SNAP dump after Major Call 3 to the EFS program. Takes the SNAP dump after Major Call 4 to the EFS program. Takes the SNAP dump after Major Call 5 to the EFS program.

Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. EFSDPBFR

94

z/OS V1R10.0 DFSORT Application Programming Guide

DEBUG Control Statement

, EFSDPBFR=( n )

Initiates a SNAP dump before a Major Call to an EFS program. Any combination of the numbers can be specified. The numbers have the following meanings: 2 3 4 5 Takes the SNAP dump before Major Call 2 to the EFS program. Takes the SNAP dump before Major Call 3 to the EFS program. Takes the SNAP dump before Major Call 4 to the EFS program. Takes the SNAP dump before Major Call 5 to the EFS program.

Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. EQUCOUNT

EQUCOUNT

Determines the number of records having equal keys (that is, duplicate keys) which have been sorted by the Blockset technique (printed in message ICE184I). For variable-length records, EQUCOUNT can only be used with either Hiperspace (when Hipersorting is used) or work data sets. Notes: 1. Using EQUCOUNT can degrade performance. 2. ICETOOLs UNIQUE and OCCUR operators provide unique and non-unique key reporting capabilities that may be more useful for your application than EQUCOUNT. 3. If VLSHRT is in effect, EQUCOUNT will not be used. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. ESTAE or NOESTAE

ESTAE NOESTAE

Chapter 3. Using DFSORT Program Control Statements

95

DEBUG Control Statement

Temporarily overrides the ESTAE installation option, which determines whether DFSORT should delete its ESTAE recovery routine early or use it for the entire run. DFSORT normally establishes an ESTAE recovery routine at the beginning of a run. If an abend occurs and the ESTAE option is in effect, the system passes control to the recovery routine. The routine terminates the run after attempting to: v Print additional abend information v Continue a sort, merge, or copy application after successful SORTOUT output v Call the EFS program at Major Calls 4 and 5 for cleanup and housekeeping v Write an SMF record v Call the ICETEXIT termination exit. If an abend occurs and the ESTAE option is not in effect, these functions might not be performed. ESTAE specifies that DFSORT can use its ESTAE recovery routine for the entire run. NOESTAE specifies that DFSORT is to delete its ESTAE recovery routine at a point early in its processing. If DFSORT terminates or abends before this point is reached, it will not delete its ESTAE recovery routine; that is, NOESTAE will not be in effect. Note: See Appendix E, DFSORT Abend Processing, on page 787 for more information on the DFSORT ESTAE recovery routine. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options. NOASSIST

NOASSIST

DFSORT uses Sorting Instructions when possible. If you do not want to use these instructions, you can temporarily bypass them by specifying this parameter. Attention: This option can degrade performance. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741.

96

z/OS V1R10.0 DFSORT Application Programming Guide

DEBUG Control Statement

Specifying Diagnostic OptionsExamples

Example 1
SORT FIELDS=(1,4,CH,A) DEBUG EQUCOUNT

If the input records contain the following keys: KEYA, KEYA, KEYB, KEYB, KEYC, KEYD, KEYD, KEYE the following message will be issued: ICE184I THE NUMBER OF RECORDS SORTED WITH EQUAL KEYS IS 3 The three equal keys are KEYA, KEYB, and KEYD. Note: ICETOOLs UNIQUE and OCCUR operators provide full equal key reporting capabilities and should be used instead of EQUCOUNT.

Example 2
SORT FIELDS=(12,2,BI,D) DEBUG BSAM,ABEND

Directs DFSORT to use the BSAM access method for the SORTIN and SORTOUT data sets and to abend if the sort application is unsuccessful.

END Control Statement

END

The END control statement allows DFSORT to discontinue reading SYSIN, DFSPARM, or SORTCNTL before end of file (EOF). When you link-edit user exit routines dynamically, the END statement marks the end of the DFSORT control statements and the beginning of exit routine object decks in SYSIN.

Discontinue Reading Control StatementsExamples

Example 1
//SYSIN DD * SORT FIELDS=(1,6,A,28,5,D),FORMAT=CH RECORD TYPE=V,LENGTH=(200,,,,80) END OPTION DYNALLOC

Because the OPTION statement appears after the END statement, it is not read.

Example 2
//SYSIN DD * SORT FIELDS=(5,8,CH,A) MODS E15=(E15,1024,SYSIN,T) END object deck for E15 user exit here
Chapter 3. Using DFSORT Program Control Statements

97

INCLUDE Control Statement

The END statement precedes the E15 user exit routine object deck in SYSIN.

INCLUDE Control Statement

| |
INCLUDE COND= (logical expression) FORMAT=f ALL NONE

Use an INCLUDE statement if you want only certain records to appear in the output data set. The INCLUDE statement selects the records you want to include. You can specify either an INCLUDE statement or an OMIT statement in the same DFSORT run, but not both. The way in which DFSORT processes short INCLUDE/OMIT compare fields depends on the settings for VLSCMP/NOVLSCMP and VLSHRT/NOVLSHRT. A short field is one where the variable-length record is too short to contain the entire field, that is, the field extends beyond the record. For details about including or omitting short records, see the discussion of the VLSCMP and NOVLSCMP options in OPTION Control Statement on page 167. A logical expression is one or more relational conditions logically combined, based on fields in the input record, and can be represented at a high level as follows:

relational condition1 . , AND OR ,relational condition2

If the logical expression is true for a given record, the record is included in the output data set. Five types of relational conditions can be used as follows: 1. Comparisons: Compare two compare fields or a compare field and a decimal, hexadecimal, character, or current, future, or past date constant. For example, you can compare the first 6 bytes of each record with its last 6 bytes, and include only those records in which those fields are identical. Or you can compare a date field with todays date, yesterdays date, or tomorrows date, and include records accordingly. See Comparisons on page 101 for information about comparisons. 2. Substring Comparison Tests: Search for a constant within a field value or a field value within a constant.

98

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

For example, you can search the value in a 6-byte field for the character constant COK, and include only those records for which COK is found somewhere in the field. Or you can search the character constant CJ69,L92,J82 for the value in a 3-byte field, and include only those records for which CJ69, CL92, or CJ82 appears in the field. See Substring Comparison Tests on page 112 for information about substring comparison tests. 3. Bit Logic Tests: Test the state (on or off) of selected bits in a binary field using a bit or hexadecimal mask or a bit constant. For example, you can include only those records which have bits 0 and 2 on in a 1-byte field. Or you can include only those records which have bits 3 and 12 on and bits 6 and 8 off in a 2-byte field. See Bit Logic Tests on page 114 for information about bit logic tests. 4. Date Comparisons: Compare a two-digit year date field to a two-digit year date constant, a current, future or past two-digit year date, or to another two-digit year date field, using the century window in effect. For example, you can include only those records for which a Zyymm date field is between January 1996 and March 2005. Or you can include only those records for which a Pdddyy field is less than another Pdddyy field. Or you can include only those records for which a Cyyddd field is between todays date and 5 days earlier than todays date. See Date Comparisons on page 119 for information about date comparisons. 5. Numeric Tests: Test a field for numerics or non-numerics in character, zoned decimal or packed decimal format. For example, you can include only those records in which a 5-byte field contains only 0-9 characters (that is, numerics). Or you can include only those records in which a 9-byte field contains invalid ZD numeric data (that is, non-numerics). Or you can include only those records in which a 12-byte field contains valid PD numeric data (that is, numerics). See Numeric Tests on page 122 for information about numeric tests. By nesting relational conditions within parentheses, you can create logical expressions of higher complexity. Although comparisons, substring comparison tests, bit logic tests, date comparisons, and numeric tests are explained separately below for clarity, they can be combined to form logical expressions. The INCLUDE control statement differs from the INCLUDE parameter of the OUTFIL statement in the following ways: v The INCLUDE statement applies to all input records; the INCLUDE parameter applies only to the OUTFIL input records for its OUTFIL group. v FORMAT=f can be specified with the INCLUDE statement but not with the INCLUDE parameter. Thus, you can use FORMAT=f and p,m or p,m,f fields with the INCLUDE statement, but you must only use p,m,f fields with the INCLUDE parameter. For example:

Chapter 3. Using DFSORT Program Control Statements

99

INCLUDE Control Statement

INCLUDE FORMAT=BI, COND=(5,4,LT,11,4,OR,21,4,EQ,31,4,OR, 61,20,SS,EQ,CFLY) OUTFIL INCLUDE=(5,4,BI,LT,11,4,BI,OR,21,4,BI,EQ,31,4,BI,OR, 61,20,SS,EQ,CFLY)

v D2 format can be specified with the INCLUDE statement but not with the INCLUDE parameter. See OUTFIL Control Statements on page 221 for more details on the OUTFIL INCLUDE parameter. COND

COND=

(logical expression) ALL NONE

logical expression

specifies one or more relational conditions logically combined, based on fields in the input record. If the logical expression is true for a given record, the record is included in the output data sets. specifies that all of the input records are to be included in the output data sets. specifies that none of the input records are to be included in the output data sets.

| |

ALL NONE

Default: ALL. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. FORMAT

FORMAT=f

FORMAT=f can be used to specify a particular format for one or more compare fields. f from FORMAT=f is used for p,m fields. f from FORMAT=f is ignored for p,m,f fields. For example, the following are all equivalent:
INCLUDE COND=(5,5,ZD,EQ,12,3,PD,OR,21,3,PD,NE,35,5,ZD) INCLUDE FORMAT=ZD,COND=(5,5,EQ,12,3,PD,OR,21,3,PD,NE,35,5) INCLUDE COND=(5,5,ZD,EQ,12,3,OR,21,3,NE,35,5,ZD),FORMAT=PD

The permissible field formats for comparisons are shown in Table 8 on page 102. SS (substring) is the only permissible field format for substring comparison tests. BI (unsigned binary) is the only permissible field format for bit logic tests. The Y2x formats are the only permissible field formats for date comparisons. The FS or CSF (floating sign), ZD (zoned decimal), and PD (packed decimal) formats are the only permissible field formats for numeric tests.

100

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

Default: None. FORMAT=f must be specified if any field is specified as p,m rather than p,m,f. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. Note: DFSORT issues an informational message and ignores FORMAT=f if all of the fields are specified as p,m,f.

Relational Condition
A relational condition specifies a comparison, substring comparison test, bit logic test, date comparison or numeric test to be performed. Relational conditions can be logically combined, with AND or OR, to form a logical expression. If they are combined, the following rules apply: v AND statements are evaluated before OR statements unless parentheses are used to change the order of evaluation; expressions inside parentheses are always evaluated first. (Nesting of parentheses is limited only by the amount of storage available.) v The symbols & (AND) and | (OR) can be used instead of the words.

Comparisons
Relational Condition Format
Two formats for the relational condition can be used:

(p1,m1,f1,

EQ NE GT GE LT LE

p2,m2,f2 constant

Or, if the FORMAT=f operand is used:

(p1,m1, f1,

EQ NE GT GE LT LE

p2,m2 ,f2 constant

Comparison operators are as follows: EQ Equal to NE Not equal to GT Greater than GE Greater than or equal to LT Less than
Chapter 3. Using DFSORT Program Control Statements

101

INCLUDE Control Statement

LE Fields: p1,m1,f1: These variables specify a field in the input record to be compared either to another field in the input record or to a constant. v p1 specifies the first byte of the compare field relative to the beginning of the input record.4 The first data byte of a fixed-length record (FLR) has relative position 1. The first data byte of a variable-length (VLR) record has relative position 5 (because the first 4 bytes contain the record descriptor word). All compare fields must start on a byte boundary, and no compare field can extend beyond byte 32752. v m1 specifies the length of the compare field. Acceptable lengths for different formats are in Table 8. v f1 specifies the format of the data in the compare field. Permissible formats are given in Table 8. You can use p1,m1 rather than p1,m1,f1 if you use FORMAT=f to supply the format for the field.
Table 8. Compare Field Formats and Lengths Format Code CH AQ ZD PD PD0 FI BI AC CSF or FS UFF SFF CSL or LS CST or TS CLO or OL CTO or OT ASL AST Length 1 to 256 bytes 1 to 256 bytes 1 to 256 bytes 1 to 255 bytes 2 to 8 bytes 1 to 256 bytes 1 to 256 bytes 1 to 256 bytes 1 to 32 bytes 1 to 44 bytes 1 to 44 bytes 2 to 256 bytes 2 to 256 bytes 1 to 256 bytes 1 to 256 bytes 2 to 256 bytes 2 to 256 bytes Description Character
5

Less than or equal to.

Character with alternate collating sequence Signed zoned decimal Signed packed decimal Packed decimal with sign and first digit ignored Signed fixed-point Unsigned binary ISCII/ASCII character Signed numeric with optional leading floating sign Unsigned free form numeric Signed free form numeric Signed numeric with leading separate sign Signed numeric with trailing separate sign Signed numeric with leading overpunch sign Signed numeric with trailing overpunch sign Signed ISCII/ASCII numeric with leading separate sign Signed ISCII/ASCII numeric with trailing separate sign

4. If your E15 user exit routine formats the record, p1 must refer to the record as reformatted by the exit.

102

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

Table 8. Compare Field Formats and Lengths (continued) Format Code D2 Length 1 to 256 bytes Description User-defined data type (requires an EFS program)

Note: See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions.

p2,m2,f2: These variables specify another field in the input record with which the p1,m1,f1 field will be compared. Permissible comparisons between compare fields with different formats are shown in Table 9 and Table 10. | AC, ASL, and AST formats sequence EBCDIC data using the ISCII/ASCII collating sequence. You can use p2,m2 rather than p2,m2,f2 if you use FORMAT=f to supply the format for the field.
Table 9. Permissable Field-to-Field Comparisons for INCLUDE/OMIT (Group 1) Field Format BI CH ZD PD FI CSF or FS UFF SFF CSL or LS CST or TS BI X X CH X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X ZD PD FI CSF or FS UFF SFF CSL or LS CST or TS

Table 10. Permissable Field-to-Field Comparisons for INCLUDE/OMIT (Group 2) Field Format PD0 AC ASL AST CLO or OL CTO or OT AQ D2 Note: D2 field formats are user-defined. PD0 X X X X X X X X X X X X AC ASL AST CLO or OL CTO or OT AQ D2

5. If CHALT is in effect, CH is treated as AQ. Chapter 3. Using DFSORT Program Control Statements

103

INCLUDE Control Statement

Constants: A constant can be a decimal number (n, +n, n), character string (Cxx...x), or hexadecimal string (X'yy...yy'). The current date can be used as a decimal number (DATE1P, &DATE1P, DATE2P, &DATE2P, DATE3P, &DATE3P) or character string (DATE1, &DATE1, DATE1(c), &DATE1(c), DATE2, &DATE2, DATE2(c), &DATE2(c), DATE3, &DATE3, DATE3(c), &DATE3(c), DATE4, &DATE4). A future date can be used as a decimal number (DATE1P+d, &DATE1P+d, DATE2P+m, &DATE2P+m, DATE3P+d, &DATE3P+d) or character string (DATE1+d, &DATE1+d, DATE1(c)+d, &DATE1(c)+d, DATE2+m, &DATE2+m, DATE2(c)+m, &DATE2(c)+m, DATE3+d, &DATE3+d, DATE3(c)+d, &DATE3(c)+d). A past date can be used as a decimal number (DATE1P-d, &DATE1P-d, DATE2P-m, &DATE2P-m, DATE3P-d, &DATE3P-d) or character string (DATE1-d, &DATE1-d, DATE1(c)-d, &DATE1(c)-d, DATE2-m, &DATE2-m, DATE2(c)-m, &DATE2(c)-m, DATE3-d, &DATE3-d, DATE3(c)-d, &DATE3(c)-d). The different constants are explained in detail below. Permissible comparisons between compare fields and constants are shown in Table 11.
Table 11. Permissible Field-to-Constant Comparisons for INCLUDE/OMIT Field Format Decimal Number BI CH ZD PD PD0 FI AC ASL AST CSF or FS UFF SFF CSL or LS CST or TS CLO or OL CTO or OT AQ D2 Note: D2 field formats are user-defined. X X X X X X X X X X X X X X X X X X X X X Self-Defining Term Character String X X Hexadecimal String X X

Decimal Number Format: The format for coding a decimal constant is:

104

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

[]n

When an FI field is compared with a decimal constant, n or +n cannot be larger than +9223372036854775807 and n cannot be smaller than -9223372036854775808. When a BI field is compared with a decimal constant, n or +n cannot be larger than +18446744073709551615 nor smaller than +0. A BI field cannot be compared to a negative number (n). A BI field cannot be compared to 0 even if NOSZERO is in effect. Examples of valid and invalid decimal constants are:
Valid 15 +15 15 18000000 Invalid ++15 15+ 1.5 1,500 Explanation Too many sign characters Sign in wrong place Contains invalid character Contains invalid character

Figure 8. Valid and Invalid Decimal Constants

Current Date as Decimal Number: DATE1P, &DATE1P, DATE2P, &DATE2P, DATE3P, or &DATE3P can be used to generate a decimal number for the current date of the run. Table 12 shows the form of the decimal number constant generated for each current date operand along with an example of the actual decimal number generated when the date of the run is June 21, 2005. yyyy represents the year, mm represents the month (01-12), dd represents the day (01-31) and ddd represents the day of the year (001-366).
Table 12. Decimal Numbers for Current Date Format of Operand DATE1P DATE2P DATE3P Format of Constant +yyyymmdd +yyyymm +yyyyddd Example of Constant +20050621 +200506 +2005172

Note: You can precede each of the operands in the table with an & with identical results. Future Date as Decimal Number: DATE1P+d, &DATE1P+d, DATE2P+m, &DATE2P+m, DATE3P+d, or &DATE3P+d can be used to generate a decimal number for a future date relative to the current date of the run. d is days in the future and m is months in the future. d and m can be 0 to 9999. Table 13 on page 106 shows the form of the decimal number constant generated for each future date operand along with an example of the actual decimal number generated when the date of the run is June 21, 2005. yyyy represents the year, mm represents the month (01-12) , dd represents the day (01-31) and ddd represents the day of the year (001-366).

Chapter 3. Using DFSORT Program Control Statements

105

INCLUDE Control Statement

Table 13. Decimal Numbers for Future Dates Format of Operand DATE1P+d DATE2P+m DATE3P+d Format of Constant +yyyymmdd +yyyymm +yyyyddd Example of Operand Example of Constant DATE1P+11 DATE2P+2 DATE3P+200 +20050702 +200508 +2006007

Note: You can precede each of the operands in the table with an & with identical results. Past Date as Decimal Number: DATE1P-d, &DATE1P-d, DATE2P-m, &DATE2P-m, DATE3P-d, or &DATE3P-d can be used to generate a decimal number for a past date relative to the current date of the run. d is days in the past and m is months in the past. d and m can be 0 to 9999. Table 14 shows the form of the decimal number constant generated for each past date operand along with an example of the actual decimal number generated when the date of the run is June 21, 2005. yyyy represents the year, mm represents the month (01-12), dd represents the day (01-31) and ddd represents the day of the year (001-366).
Table 14. Decimal Numbers for Past Dates Format of Operand DATE1P-d DATE2P-m DATE3P-d Format of Constant +yyyymmdd +yyyymm +yyyyddd Example of Operand Example of Constant DATE1P-30 DATE2P-12 DATE3P-172 +20050522 +200406 +2004366

Note: You can precede each of the operands in the table with an & with identical results. Character String Format: The format for coding a character string constant is:
Cxx...x

The value x may be any EBCDIC character (the EBCDIC character string is translated appropriately for comparison to an AC or AQ field). You can specify up to 256 characters. If you want to include a single apostrophe in the character string, you must specify it as two single apostrophes. Thus:
Required: ONEILL Specify: CONEILL

Examples of valid and invalid character string constants are shown below:

106

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

Valid CJDCO C$@# C+0.193 CFranks Invalid C ABCDEF CABCDEF CFranks Explanation Apostrophes not paired C identifier missing Apostrophe missing Two single apostrophes needed for one

Figure 9. Valid and Invalid Character String Constants

Double-byte data may be used in a character string for INCLUDE/OMIT comparisons. The start of double-byte data is delimited by the shift-out (SO) control character (X0E), and the end by the shift-in (SI) control character (X0F). SO and SI control characters are part of the character string and must be paired with zero or an even number of intervening bytes. Nested shift codes are not allowed. All characters between SO and SI must be valid double-byte characters. No single-byte meaning is drawn from the double-byte data. Examples of valid and invalid character string constants containing double-byte characters are shown below using: < to represent SO > to represent SI Dn to represent a double-byte character
Table 15. Valid and Invalid Strings with Double-Byte Data Valid CQ<D1D2>T C<D1D2D3> CQ<D1>R<D2> Invalid CQ<R>S CD1D2D3 CQ<D1<D2>> Explanation Single-byte data within SO/SI Missing SO/SI; treated as single-byte data Nested SO/SI

Tip: X'0E', X'0F', and X'7D' are treated as the special characters shift-out, shift-in, and single apostrophe in a character string. If you dont want to treat one or more of these characters as special in a particular value, use a hexadecimal string instead of a character string. For example, if you want to treat the binary value 000E0E7D as its decimal equivalent of 921213, use X'000E0E7D'; 0E will not be treated as shift-out and 7D will not be treated as a single apostrophe. Current Date as Character String: DATE1, &DATE1, DATE1(c), &DATE1(c), DATE2, &DATE2, DATE2(c), &DATE2(c), DATE3, &DATE3, DATE3(c), &DATE3(c), DATE4, or &DATE4 can be used to generate a character string for the current date of the run. Table 16 on page 108 shows the form of the character string constant generated for each current date operand along with an example of the actual character string generated when the date of the run is June 21, 2005 at 04:42:45 PM, using (/) for (c) where relevant. yyyy represents the year, mm (for date) represents the month (01-12), dd represents the day (01-31), ddd represents the day of the year (001-366), hh represents the hour (00-23), mm (for time) represents the minutes (00-59), ss represents the seconds (00-59), and c can be any character except a blank.

Chapter 3. Using DFSORT Program Control Statements

107

INCLUDE Control Statement

Table 16. Character Strings for Current Date Format of Operand DATE1 DATE1(c) DATE2 DATE2(c) DATE3 DATE3(c) DATE4 Format of Constant Cyyyymmdd Cyyyycmmcdd Cyyyymm Cyyyycmm Cyyyyddd Cyyyycddd Cyyyy-mm-dd-hh.mm.ss Example of Constant C20050621 C2005/06/21 C200506 C2005/06 C2005172 C2005/172 C2005-06-21-16.52.45

Note: You can precede each of the operands in the table with an & with identical results. Tip: When a field is shorter than the character string its compared to, DFSORT truncates the string on the right. You can take advantage of this to compare a field to only part of the DATE4 timestamp when appropriate. For example:
INCLUDE COND=(1,13,CH,GT,DATE4)

would compare the field in positions 1-13 to the truncated DATE4 constant Cyyyy-mm-dd-hh. Future Date as Character String: DATE1+d, &DATE1+d, DATE1(c)+d, &DATE1(c)+d, DATE2+m, &DATE2+m, DATE2(c)+m, &DATE2(c)+m, DATE3+d, &DATE3+d, DATE3(c)+d or &DATE3(c)+d can be used to generate a character string for a future date relative to the current date of the run. d is days in the future and m is months in the future. d and m can be 0 to 9999. Table 17 shows the form of the character string constant generated for each future date operand along with an example of the actual character string generated when the date of the run is June 21, 2005. yyyy represents the year, mm represents the month (01-12), dd represents the day (01-31), ddd represents the day of the year (001-366), and c can be any character except a blank.
Table 17. Character Strings for Future Dates Format of Operand DATE1+d DATE1(c)+d DATE2+m DATE2(c)+m DATE3+d DATE3(c)+d Format of Constant Cyyyymmdd Cyyyycmmcdd Cyyyymm Cyyyycmm Cyyyyddd Cyyyycddd Example of Operand Example of Constant DATE1+11 DATE1(/)+90 DATE2+2 DATE2(.)+25 DATE3+200 DATE3(-)+1 C20050702 C2005/09/19 C200508 C2007.07 C2006007 C2005-171

Note: You can precede each of the operands in the table with an & with identical results. Past Date as Character String: DATE1-d, &DATE1-d, DATE1(c)-d, &DATE1(c)-d, DATE2-m, &DATE2-m, DATE2(c)-m, &DATE2(c)-m, DATE3-d, &DATE3-d, DATE3(c)-d or &DATE3(c)-d can be used to generate a character string for a past date relative to the current date of the run. d is days in the past and m is months in the past. d and m can be 0 to 9999.

108

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

Table 18 shows the form of the character string constant generated for each past date operand along with an example of the actual character string generated when the date of the run is June 21, 2005. yyyy represents the year, mm represents the month (01-12), dd represents the day (01-31), ddd represents the day of the year (001-366), and c can be any character except a blank.
Table 18. Character Strings for Past Dates Format of Operand DATE1-d DATE1(c)-d DATE2-m DATE2(c)-m DATE3-d DATE3(c)-d Format of Constant Cyyyymmdd Cyyyycmmcdd Cyyyymm Cyyyycmm Cyyyyddd Cyyyycddd Example of Operand Example of Constant DATE1-1 DATE1(-)-60 DATE2-6 DATE2(/)-1 DATE3-300 DATE3(.)-21 C20050620 C2005-04-22 C200412 C2005/05 C2004238 C2005.151

Note: You can precede each of the operands in the table with an & with identical results. Hexadecimal String Format: The format for coding a hexadecimal string constant is:
Xyy...yy

The value yy represents any pair of hexadecimal digits. You can specify up to 256 pairs of hexadecimal digits. Because the first digit and sign are ignored in a PD0 field, you should not include the first digit or sign in a hexadecimal constant to be compared to a PD0 field. For example, 3-byte PD0 values like X'01234C' and X'01234D' would be equal to a hexadecimal constant of X'1234'. Examples of valid and invalid hexadecimal constants are shown in the following table.
Valid X'ABCD' X'BF3C' X'AF050505' X'BF3C' Invalid X'ABGD' X'BF3' AF050505 BF3CX Explanation Invalid hexadecimal digit Incomplete pair of digits Missing X identifier X identifier in wrong place

Figure 10. Valid and Invalid Hexadecimal Constants

Padding and Truncation

In a field-to-field comparison, the shorter compare field is padded appropriately. In a field-to-constant comparison, the constant is padded or truncated to the length of the compare field. Character and hexadecimal strings are truncated and padded on the right. The padding characters are:
Chapter 3. Using DFSORT Program Control Statements

109

INCLUDE Control Statement

v X'40' For a character string v X'00' For a hexadecimal string. Decimal constants are padded and truncated on the left. Padding is done with zeros in the proper format.

Cultural Environment Considerations

DFSORTs collating behavior can be modified according to your cultural environment. The cultural environment is established by selecting the active locale. The active locales collating rules affect INCLUDE and OMIT processing as follows: v DFSORT includes or omits records for output according to the collating rules defined in the active locale. This provides inclusion or omission for single- or multi-byte character data, based on defined collating rules which retain the cultural and local characteristics of a language. If locale processing is to be used, the active locale will only be used to process character (CH) compare fields and character and hexadecimal constants compared to character (CH) compare fields. For more information on locale processing, see Cultural Environment Considerations on page 7 or LOCALE in OPTION Control Statement on page 167.

Including Records in the Output Data SetComparison Examples

Example 1
INCLUDE COND=(5,8,GT,13,8,|,105,4,LE,1000),FORMAT=CSF

This example illustrates how to only include records in which: v The floating sign number in bytes 5 through 12 is greater than the floating sign number in bytes 13 through 20 OR v The floating sign number in bytes 105 through 108 is less than or equal to 1000. Note that all three compare fields have the same format.

Example 2
INCLUDE COND=(1,10,CH,EQ,CSTOCKHOLM, AND,21,8,ZD,GT,+50000, OR,31,4,CH,NE,CHERR)

This example illustrates how to only include records in which: v The first 10 bytes contain STOCKHOLM (this nine-character string was padded on the right with a blank) AND the zoned-decimal number in bytes 21 through 28 is greater than 50 000 OR v Bytes 31 through 34 do not contain HERR. Note that the AND is evaluated before the OR. ( Omitting Records from the Output Data SetExample on page 166 illustrates how parentheses can be used to change the order of evaluation.) Also note that ending a line with a comma or semicolon followed by a blank indicates that the parameters continue on the next line, starting in any position from columns 2 through 71.

110

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

Example 3
INCLUDE FORMAT=CH, COND=((5,1,EQ,8,1),&, ((20,1,EQ,CA,&,30,1,FI,GT,10),|, (20,1,EQ,CB,&,30,1,FI,LT,100),|, (20,1,NE,CA,&,20,1,NE,CB)))

This example illustrates how to only include records in which: v Byte 5 equals byte 8 AND v At least one of the following is true: Byte 20 equals A and byte 30 is greater than 10 Byte 20 equals B and byte 30 is less than 100 Byte 20 is not equal to A or B. Note that p,m,FI is used for the FI fields, and p,m with FORMAT=CH is used for all of the CH fields. With FORMAT=f, you can mix p,m and p,m,f fields when thats convenient such as when all or most of the fields have the same format (although you can always code p,m,f for all fields and not use FORMAT=f, if you prefer).

Example 4
INCLUDE COND=(7,2,CH,EQ,CT1,OR, (1,2,BI,GE,X001A,AND,20,2,CH,EQ,25,2,CH))

This example shows the effects of VLSCMP/NOVLSCMP and VLSHRT/NOVLSHRT on INCLUDE processing when short records are present. Consider the records shown in Figure 11 on page 112: v If VLSCMP is in effect, the first record is included because bytes 7-8 are equal to CT1, even though the comparison of bytes 20-21 to 25-26 involves short fields. The second record is included or omitted based on the comparison of bytes 20-21 to bytes 25-26. v If NOVLSCMP and VLSHRT are in effect, the first record is omitted because the comparison of bytes 20-21 to 25-26 involves short fields. The second record is included or omitted based on the comparison of bytes 20-21 to bytes 25-26. v If NOVLSCMP and NOVLSHRT are in effect, the first record causes message ICE015A or ICE218A to be issued because the comparison of bytes 20-21 to bytes 25-26 involves short fields.

Chapter 3. Using DFSORT Program Control Statements

111

INCLUDE Control Statement

RDW

compare field A

compare field B

T1 7 RDW T2 7
Figure 11. Sample Records

10 compare field C compare field D

20

25

Example 5
INCLUDE COND=(21,8,ZD,GT,DATE1P)

This example illustrates how to include records in which a zoned-decimal date of the form Zyyyymmdd in bytes 21-28 is greater than todays date. DATE1P generates a decimal number for the current date in the form +yyyymmdd.

Example 6
INCLUDE COND=(15,7,CH,GE,DATE3-7,AND,15,7,CH,LE,DATE3+7)

This example illustrates how to include records in which a character date of the form Cyyyyddd in bytes 15-21 is between 7 days in the past and 7 days in the future, relative to the current date. DATE3-7 generates a character constant in the form Cyyyyddd where yyyyddd is the current date minus 7 days. DATE3+7 generates a character constant in the form Cyyyyddd where yyyyddd is the current date plus 7 days.

Example 7
INCLUDE COND=(21,10,CH,GE,DATE1(-)-365)

This example illustrates how to include records in which a character date of the form Cyyyy-mm-dd in bytes 21-30 is within 365 days of the current date. DATE1(-)-365 generates a character constant in the form Cyyyy-mm-dd where yyyymmdd is the current date minus 365 days.

Substring Comparison Tests

Two types of substring comparison tests are offered, as follows: 1. Find a constant within a field value. For example, you can search the value in a 6-byte field for the character constant COK. If the field value is, for example, C**OK** or C****OK, the relational condition is true; if the field value is C**ERR*, the relational condition is false. 2. Find a field value within a constant. For example, you can search the character constant CJ69,L92,J82 for the value in a 3-byte field. If the field value is CJ69, CL92, or CJ82, the relational condition is true; if the field value is CX24, the relational condition is false. Note that the comma is used within the constant to separate the valid 3-character values; any character that will not appear in the field value can be used as a separator in the constant.

112

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

Relational Condition Format

Two formats for the relational condition can be used:

(p1,m1,SS,

EQ NE

, constant )

Or, if the FORMAT=SS operand is used:

(p1,m1, SS,

EQ NE

, constant )

Restriction: FORMAT=SS can precede COND but cannot follow it. Substring comparison operators are as follows: EQ Equal to NE Not equal to Fields: p1,m1: These variables specify the character field in the input record for the substring test. v p1 specifies the first byte of the character input field for the substring test, relative to the beginning of the input record.6 The first data byte of a fixed-length record (FLR) has relative position 1. The first data byte of a variable-length (VLR) record has relative position 5 (because the first 4 bytes contain the record descriptor word). All fields to be tested must start on a byte boundary and must not extend beyond byte 32752. v m1 specifies the length of the field to be tested. The length can be 1 to 32752 bytes. Constant: The constant can be a character string or a hexadecimal string. See Character String Format on page 106 and Hexadecimal String Format on page 109 for details. If m1 is greater than the length of the constant, the field value will be searched for the constant and the condition will be true if a match is found when the EQ comparison operator is specified or if a match is not found when the NE comparison operator is specified. If m1 is smaller than the length of the constant, the constant will be searched for the field value and the condition will be true if a match is found when the EQ comparison operator is specified or if a match is not found when the NE comparison operator is specified.

6. If your E15 user exit routine formats the record, p1 must refer to the record as reformatted by the exit. Chapter 3. Using DFSORT Program Control Statements

113

INCLUDE Control Statement

Including Records in the Output Data SetSubstring Comparison Example

Example
INCLUDE FORMAT=SS,COND=(11,6000,EQ,COK,OR,5,3,EQ,CJ69,L92,J82)

This example illustrates how to include only records in which: v OK is found somewhere within bytes 11 through 6010 OR v Bytes 5 through 7 contain J69, L92 or J82.

Bit Logic Tests

Two methods for bit logic testing are offered as follows: v Bit operator with hexadecimal or bit mask v Bit comparison tests While any bit logic test can be specified using either of the two methods, each of them offers unique advantages not found with the other. The ability to specify selected bits in a field, by either of the two methods, can greatly reduce the number of INCLUDE conditions that must be specified to achieve a given result, because the need to account for unspecified bits is eliminated.

Method 1: Bit Operator Tests

This method of bit logic testing allows you to test whether selected bits in a binary field are all on, all off, in a mixed on-off state, or in selected combinations of these states. While this method allows you to test many different possible bit combinations with a single operation, similar to the Test Under Mask (TM) machine instruction, it is less suited to determine if a field contains exactly one particular combination of on and off bits than Method 2 described below.

Relational Condition Format

Two formats for the relational condition can be used:

(p1,m1,BI,

ALL SOME NONE NOTALL NOTSOME NOTNONE BO BM BZ BNO BNM BNZ

, mask )

Or, if the FORMAT=BI operand is used:

114

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

(p1,m1, BI, ALL SOME NONE NOTALL NOTSOME NOTNONE BO BM BZ BNO BNM BNZ , mask )

Bit operators describe the input field to mask relationship to be tested as follows: ALL or BO All mask bits are on in the input field SOME or BM Some, but not all mask bits are on in the input field NONE or BZ No mask bits are on in the input field NOTALL or BNO Some or no mask bits are on in the input field NOTSOME or BNM All or no mask bits are on in the input field NOTNONE or BNZ All or some mask bits are on in the input field The first set of operators (ALL, SOME, and so on) are intended for those who like meaningful mnemonics. The second set of operators (BO, BM, and so on) are intended for those familiar with the conditions associated with the Test Under Mask (TM) instruction.

Fields
p1,m1: These variables specify the binary field in the input record to be tested against the mask. v p1 specifies the first byte of the binary input field to be tested against the mask, relative to the beginning of the input record.7 The first data byte of a fixed-length record (FLR) has relative position 1. The first data byte of a variable-length (VLR) record has relative position 5 (because the first 4 bytes contain the record descriptor word). All fields to be tested must start on a byte boundary and must not extend beyond byte 32752. v m1 specifies the length of the field to be tested. The length can be 1 to 256 bytes.

Mask
A hexadecimal string or bit string that indicates the bits in the field selected for testing. If a mask bit is on (1), the corresponding bit in the field is tested. If a mask bit is off (0), the corresponding bit in the field is ignored. Hexadecimal String Format: The format for coding a hexadecimal string mask is:
Xyy...yy

7. If your E15 user exit routine formats the record, p1 must refer to the record as reformatted by the exit. Chapter 3. Using DFSORT Program Control Statements

115

INCLUDE Control Statement

The value yy represents any pair of hexadecimal digits that constitute a byte (8 bits). Each bit must be 1 (test bit) or 0 (ignore bit). You can specify up to 256 pairs of hexadecimal digits. Bit String Format: The format for coding a bit string mask is:
Bbbbbbbbb...bbbbbbbb

The value bbbbbbbb represents 8 bits that constitute a byte. Each bit must be 1 (test bit) or 0 (ignore bit). You can specify up to 256 groups of 8 bits. The total number of bits in the mask must be a multiple of 8. A bit mask string can only be used with a bit operator.

Padding and Truncation

The hexadecimal or bit mask is truncated or padded on the right to the byte length of the binary field. The padding character is X00 (all bits off and thus not tested).

Including Records in the Output Data SetBit Operator Test Examples

Example 1
INCLUDE COND=(27,1,CH,EQ,CD,AND,18,1,BI,ALL,B10000000)

This example illustrates how to only include records in which: v Byte 27 contains D AND v Byte 18 has bit 0 on.

Example 2
INCLUDE COND=(11,1,BI,BM,X85)

This example illustrates how to only include records in which byte 11 has some, but not all of bits 0, 5 and 7 on. Results for selected field values are shown below:
Table 19. Bit Comparison Example 2: Results for Selected Field Values 11,1,BI Value X85 XC1 X84 X00 11,1,BI Result False True True False Action Omit Record Include Record Include Record Omit Record

Example 3
INCLUDE COND=(11,2,ALL,B0001001000110100, OR,21,1,NONE,B01001100),FORMAT=BI

This example illustrates how to only include records in which: v Bytes 11 through 12 have all of bits 3, 6, 10, 11 and 13 on OR v Byte 21 has none of bits 1, 4, or 5 on.

116

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

Results for selected field values are shown below:
Table 20. Bit Comparison Example 3: Results for Selected Field Values 11,2,BI Value X1234 X02C4 X0204 XF334 X1238 11,2,BI Result True False False True False 21,1,BI Value X4C X81 X40 X00 X4F 21,1,BI Result False True False True False Action Include Record Include Record Omit Record Include Record Omit Record

Method 2: Bit Comparison Tests

This method of bit logic testing allows you to test whether selected bits in a binary field are either in an exact pattern of on and off bits, or not in that exact pattern. Unlike Method 1 described above, only equal and unequal comparisons are allowed; however, this method has the advantage of being able to test for a precise combination of on and off bits.

Relational Condition Format

Two formats for the relational condition can be used:

(p1,m1,BI,

EQ NE

, constant )

Or, if the FORMAT=BI operand is used:

(p1,m1, BI,

EQ NE

, constant )

Bit comparison operators are as follows: EQ Equal to NE Not equal to

Fields
p1,m1: These variables specify the binary field in the input record to be compared to the bit constant. v p1 specifies the first byte of the binary input field to be compared to the bit constant, relative to the beginning of the input record.8 The first data byte of a fixed-length record (FLR) has relative position 1. The first data byte of a variable-length (VLR) record has relative position 5 (because the first 4 bytes contain the record descriptor word). All fields to be tested must start on a byte boundary and must not extend beyond byte 32752. v m1 specifies the length of the field to be tested. The length can be 1 to 256 bytes.

8. If your E15 user exit routine formats the record, p1 must refer to the record as reformatted by the exit. Chapter 3. Using DFSORT Program Control Statements

117

INCLUDE Control Statement

Bit Constant
A bit string constant that specifies the pattern to which the binary field is compared. If a bit in the constant is 1 or 0, the corresponding bit in the field is compared to 1 or 0, respectively. If a bit in the constant is . (period), the corresponding bit in the field is ignored. Bit String Format: The format for coding a bit string constant is:
Bbbbbbbbb...bbbbbbbb

The value bbbbbbbb represents 8 bits that constitute a byte. Each bit must be 1 (test bit for 1), 0 (test bit for 0) or . (ignore bit). You can specify up to 256 groups of 8 bits. The total number of bits in the mask must be a multiple of 8. A bit constant can only be used for bit comparison tests (BI format and EQ or NE operator).

Padding and Truncation

The bit constant is truncated or padded on the right to the byte length of the binary field. The padding character is B00000000 (all bits equal to 0). Note that the padded bytes are compared to the excess bytes in the binary field. Recommendation: To ensure that comparison of the padded bytes to the excess bytes in the binary field does not cause unwanted results, shorten the field length to eliminate the padding characters, or increase the length of the bit constant to specify the exact test pattern you want.

Including Records in the Output Data SetBit Comparison Test Examples

Example 1
INCLUDE COND=(27,1,CH,EQ,CD,AND,18,1,BI,EQ,B1.......)

This example illustrates how to only include records in which: v Byte 27 contains D AND v Byte 18 is equal to the specified pattern of bit 0 on.

Example 2
INCLUDE COND=(11,1,BI,NE,B10...1.1)

This example illustrates how to only include records in which byte 11 is not equal to the specified pattern of bit 0 on, bit 1 off, bit 5 on and bit 7 on. Results for selected field values are shown below:
Table 21. Bit Comparison Example 2: Results for Selected Field Values 11,1,BI Value X85 XC1 X84 X97 11,1,BI Result False True True False Action Omit Record Include Record Include Record Omit Record

118

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

Example 3
INCLUDE COND=(11,2,EQ,B..01....0......1, OR,21,1,EQ,B01......),FORMAT=BI

This example illustrates how to only include records in which: v Bytes 11 through 12 are equal to the specified pattern of bit 2 off, bit 3 on, bit 8 off and bit 15 on OR v Byte 21 is equal to the specified pattern of bit 0 off and bit 1 on. Results for selected field values are shown below:
Table 22. Bit Comparison Example 3: Results for Selected Field Values 11,2,BI Value X1221 X02C4 X1234 X5F7F XFFFF 11,2,BI Result True False False True False 21,1,BI Value XC0 X41 X00 X7F X2F 21,1,BI Result False True False True False Action Include Record Include Record Omit Record Include Record Omit Record

Date Comparisons
You can use DFSORTs Y2 formats in conjunction with the century window in effect, as follows: v Use the full date formats (Y2T, Y2U, Y2V, Y2W, Y2X and Y2Y) to compare a two-digit year date field to a two-digit year date constant, a current, future or past two-digit year date (Y constant), or to another two-digit year date field. v Use the year formats (Y2C, Y2Z, Y2S, Y2P, Y2D and Y2B) to compare a two-digit year field to a two-digit year constant (Y constant) or to another two-digit year field. For example, you can include only those records for which a Zyymm date field is between January 1996 and March 2005. Or you can include only those records for which a Pdddyy field is less than another Pdddyy field. Or you can include only those records for which a Cyyddd field is between todays date and 5 days earlier than todays date. The ordering of dates and special indicators used for comparisons with Y2 fields and Y constants is the same as the ascending orders for sorting and merging Y2 fields (see SORT Control Statement on page 398 for details).

Relational Condition Format

Two formats for the relational condition can be used:

Chapter 3. Using DFSORT Program Control Statements

119

INCLUDE Control Statement

(p1,m1,Y2x, EQ NE GT GE LT LE , p2,m2,Y2x constant )

Or, if the FORMAT=Y2x operand is used:

(p1,m1, Y2x,

EQ NE GT GE LT LE

p2,m2 ,Y2x constant

Comparison operators are as follows: EQ Equal to NE Not equal to GT Greater than GE Greater than or equal to LT Less than LE Less than or equal to. Fields: p1,m1,Y2x: These variables specify a two-digit year date field in the input record to be compared either to another two-digit year date field in the input record or to a two-digit year date constant. v p1 specifies the first byte of the date field relative to the beginning of the input record.9 The first data byte of a fixed-length record (FLR) has relative position 1. The first data byte of a variable-length (VLR) record has relative position 5 (because the first 4 bytes contain the record descriptor word). All date fields must start on a byte boundary, and no date field can extend beyond byte 32752. v m1 specifies the length of the date field. Appendix C, Data Format Descriptions, on page 769 describes the length and format for each type of date field. v Y2x specifies the Y2 format. Appendix C, Data Format Descriptions, on page 769 describes the length (m) and format (Y2x) for each type of date field. You can use p1,m1 rather than p1,m1,Y2x if you use FORMAT=Y2x to supply the format for the date field. p2,m2,Y2x: These variables specify another two-digit year date field in the input record with which the p1,m1,Y2x field will be compared.

9. If your E15 user exit routine formats the record, p1 must refer to the record as reformatted by the exit.

120

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

You can use p2,m2 rather than p2,m2,Y2x if you use FORMAT=Y2x to supply the format for the date field. Constant: A two-digit year date constant in the form Ystring, YDATE1, YDATE1+d, YDATE1-d, YDATE2, YDATE2+m, YDATE2-m, YDATE3, YDATE3+d, or YDATE3-d, with which the p1,m1,Y2x field will be compared. Comparisons: A date field can be compared to a date constant or another date field with the same number of non-year (x) digits. Table 23 shows the type of field-to-field and field-to-constant comparisons you can use. The fields shown for any type of date (for example, yyx and xyy) can be compared to any other fields shown for that type of date or to the Y constant shown for that type of date.
Table 23. Permissible Comparisons for Dates Type of Date yyx and xyy yyxx and xxyy Fields (m,f) 3,Y2T 3,Y2W 4,Y2T 4,Y2W 2,Y2U 2,Y2X 3,Y2V 3,Y2Y Y Constant Yyyx Yyyxx YDATE2 YDATE2+m YDATE2-m Yyyxxx YDATE3 YDATE3+d YDATE3-d Yyyxxxx YDATE1 YDATE1+d YDATE1-d Yyy

yyxxx and xxxyy

5,Y2T 5,Y2W

3,Y2U 3,Y2X

yyxxxx and xxxxyy

6,Y2T 6,Y2W

4,Y2V 4,Y2Y

yy

2,Y2C 2,Y2S 1,Y2D

2,Y2Z 2,Y2P 1,Y2B

Y constants for current, future, and past two-digit year dates are as follows. d can be 0 to 9999 days and m can be 0 to 9999 months. v YDATE1 generates a Y constant for the current date in the form Yyymmdd v YDATE1+d generates a Y constant for the current date plus d days in the form Yyymmdd v YDATE1-d generates a Y constant for the current date minus d days in the form Yyymmdd v YDATE2 generates a Y constant for the current date in the form Yyymm v YDATE2+m generates a Y constant for the current date plus m months in the form Yyymm v YDATE2-m generates a Y constant for the current date minus m months in the form Yyymm v YDATE3 generates a Y constant for the current date in the form Yyyddd v YDATE3+d generates a Y constant for the current date plus d days in the form Yyyddd v YDATE3-d generates a Y constant for the current date minus d days in the form Yyyddd. You must use the same number of digits in a Y constant as the type of date; leading zeros must be specified (for example, for Yyymm, use Y0001 for January 2000 and Y0501 for January 2005).
Chapter 3. Using DFSORT Program Control Statements

121

INCLUDE Control Statement

You can also use Y constants for special indicators as follows: v Y0...0 (CH/ZD/PD zeros) and Y9...9 (CH/ZD/PD nines) can be used with Y2T, Y2U, Y2V, Y2W, Y2X and Y2Y dates. You must use the same number of digits as the type of date (for example, Y000 for yyq or qyy, Y0000 for yymm or mmyy, and so forth). v YLOW (BI zeros), YBLANKS (blanks) and YHIGH (BI ones) can be used with Y2T, Y2W and Y2S dates.

Including Records in the Output Data SetDate Comparisons

Example 1
INCLUDE FORMAT=Y2T, COND=(3,4,GE,Y9901,AND, 3,4,LE,Y0312,OR, 3,4,LE,Y0000)

This example illustrates how to only include records in which: v A Cyymm date field in bytes 3 through 6 is between January 1999 and December 2003 OR v Bytes 3 through 6 contain CH zeros (C0000), ZD zeros (Z0000) or BI zeros (X'00000000'). Note that the century window in effect will be used to interpret the Y9901 and Y0312 date constants, as well as real dates in the Cyymm date field. However, the century window will not be used to interpret the Y0000 special indicator constant or special indicators in the Cyymm date field.

Example 2
INCLUDE COND=(2,3,Y2X,LT,36,5,Y2T)

This example illustrates how to only include records in which a Pdddyy date field in bytes 2 through 4 is less than a Zyyddd date field in bytes 36 through 40. Note that the century window in effect will be used to interpret real dates in the Pdddyy and Zyyddd date fields. However, the century window will not be used to interpret special indicators in the Pdddyy and Zyyddd date fields.

Numeric Tests
You can test a field for numerics or non-numerics in character, zoned decimal or packed decimal format. For example, you can include only those records in which a 5-byte field contains only 0-9 characters (that is, character numerics). Or you can include only those records in which a 9-byte field contains invalid zoned decimal data (that is, zoned decimal non-numerics). Or you can include only those records in which a 12-byte field contains valid packed decimal data (that is, packed decimal numerics). A field to be tested for numerics in character format looks like this in hexadecimal:
FdFd...Fd

The field is considered to be character numeric if every d is 0-9. (This is equivalent to 0-9 for each character.) Otherwise, the field is considered to be character

122

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

non-numeric. For example, 1234, 0001 and 9999 are all considered to be character numeric, whereas A234, 12.3, 1 and 123D are all considered to be character non-numeric. A field to be tested for numerics in zoned decimal format looks like this in hexadecimal:
zdzd...sd

The field is considered to be zoned decimal numeric if every z is F, every d is 0-9, and s is C, D or F. Otherwise, the field is considered to be zoned decimal non-numeric. For example, 1234 (XF1F2F3F4), 123D (XF1F2F3C4) and 123M (XF1F2F3D4) are all considered to be zoned decimal numeric, whereas A234 (XC1F2F3F4), 12.3 (XF1F24BF3) and 123X (XF1F2F3E7) are all considered to be zoned decimal non-numeric. A field to be tested for numerics in packed decimal format looks like this in hexadecimal:
dddd...ds

The field is considered to be packed decimal numeric if every d is 0-9, and s is C, D or F. Otherwise, the field is considered to be packed decimal non-numeric. For example, X12345C, X12345D and X12345F are all considered to be packed decimal numeric, whereas XA2345C, X1B345D and X12F45F are all considered to be packed decimal non-numeric.

Relational Condition Format

Two formats for the relational condition can be used:

(p1,m1,f1,

EQ NE

,NUM)

Or, if the FORMAT=f operand is used:

(p1,m1, f1,

EQ NE

,NUM)

Numeric test operators are as follows: EQ Equal to numerics NE Not equal to numerics (non-numerics) Fields: p1,m1,f1: These variables specify the field in the input record for the numeric test. v p1 specifies the first byte of the field relative to the beginning of the input record 10. The first data byte of a fixed-length record (FLR) has relative position 1. The first data byte of a variable-length (VLR) record has relative position 5
10. If your E15 user exit routine formats the record, p1 must refer to the record as reformatted by the exit. Chapter 3. Using DFSORT Program Control Statements

123

INCLUDE Control Statement

(because the first 4 bytes contain the record descriptor word). All fields must start on a byte boundary, and no field can extend beyond byte 32752. v m1 specifies the length of the field. The length can be 1 to 256 bytes. v f1 specifies the type of numerics the field is to be tested for as follows: FS test for numerics in character format (0-9 (XF0-XF9) in all bytes). Note: CSF can be used instead of FS. ZD PD test for numerics in zoned decimal format (0-9 (XF0-XF9) in all non-sign bytes; XF0-XF9, XD0-XD9 or XC0-XC9 in the sign byte) test for numerics in packed decimal format (0-9 for all digits; F, D or C for the sign).

You can use p1,m1 rather than p1,m1,f1, if you use FORMAT=f to supply the format for the field. NUM: Specifies a test for numerics or non-numerics. The condition will be true if the field is numeric when the EQ operator is specified or if the field is non-numeric when the NE operator is specified.

Including Records in the Output Data Set--Numeric Tests

Example 1
INCLUDE COND=(1,20,FS,EQ,NUM)

This example illustrates how to only include records in which the field in bytes 1 through 20 contains valid character numeric data (that is, 0-9 in all bytes).

Example 2
INCLUDE COND=(21,8,ZD,NE,NUM,OR,31,5,PD,NE,NUM)

This example illustrates how to only include records in which the field in bytes 21 through 28 contains invalid zoned decimal data, or the field in bytes 31 through 35 contains invalid packed decimal data (that is, one of the fields is non-numeric).

INCLUDE/OMIT Statement Notes

v Floating point compare fields cannot be referenced in INCLUDE or OMIT statements. v Any selection can be performed with either an INCLUDE or an OMIT statement. INCLUDE and OMIT are mutually exclusive. v If several relational conditions are joined with a combination of AND and OR logical operators, the AND statement is evaluated first. The order of evaluation can be changed by using parentheses inside the COND expression. v If any changes are made to record formats by user exits E15 or E32, the INCLUDE or OMIT statement must apply to the newest formats. v DFSORT issues a message and terminates if an INCLUDE or OMIT statement is specified for a tape work data set sort or conventional merge application. v If SZERO is in effect, 0 compares as less than +0 when numeric fields and constants are used. If NOSZERO is in effect, 0 compares as equal to +0 when numeric fields and constants are used.

124

z/OS V1R10.0 DFSORT Application Programming Guide

INCLUDE Control Statement

Table 24 on page 125 shows how DFSORT reacts to the result of a relational condition comparison, depending on whether the statement is INCLUDE or OMIT and whether the relational condition is followed by an AND or an OR logical operator. When writing complex statements, the table in Table 24 helps you get the result that you want.
Table 24. Logic Table for INCLUDE/OMIT. Relational Condition Program action if next logical operator is: Statement OMIT Compare True AND Check next compare, or if last compare OMIT record. INCLUDE record OR OMIT record

OMIT

False

Check next compare, or if last compare, INCLUDE record. INCLUDE record

INCLUDE

True

Check next compare, or if last compare, INCLUDE record. OMIT record

INCLUDE

False

Check compare, or if last compare, OMIT record.

INREC Control Statement

, INREC PARSE=( definition ) , ( , OVERLAY=( , item ) item )

FIELDS= BUILD=

IFTHEN=(clause) IFOUTLEN=n

The INREC control statement allows you to reformat the input records before they are sorted, merged, or copied. The INREC control statement supports a wide variety of parsing, editing, and 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. For variable fields, such as delimited fields, comma separated values (CSV), tab separated values, blank separated values, keyword separated fields,
Chapter 3. Using DFSORT Program Control Statements

125

INREC Control Statement

null-terminated strings (and many other types), you define rules that allow DFSORT to extract the relevant data into fixed parsed fields, and then use the parsed fields as you would use fixed fields. Insertion of blanks, zeros, strings, current date, future date, past date, current time, sequence numbers, decimal constants, and the results of arithmetic expressions before, between, and after the input fields in the reformatted records. Sophisticated conversion capabilities, such as hexadecimal display, conversion of EBCDIC letters from lowercase to uppercase or uppercase to lowercase, conversion of characters using the ALTSEQ translation 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 and shift right). Sophisticated editing capabilities, such as control of the way numeric fields are presented with respect to length, leading or suppressed zeros, thousands separators, decimal points, leading and trailing positive and negative signs, and so on. Twenty-seven pre-defined editing masks are available for commonly used numeric editing patterns, encompassing many of the numeric notations used throughout the world. In addition, a virtually unlimited number of numeric editing patterns are available via user-defined editing masks. Transformation of SMF, TOD, and ETOD date and time values to more usable forms. Transformation of various forms of two-digit year dates to various forms of four-digit year dates using a specified fixed or sliding century window. Selection of a character constant, hexadecimal constant, or input field from a lookup table, based on a character, hexadecimal, or bit string as input (that is, lookup and change).

v v v

You can create the reformatted INREC records in one of the following three ways using unedited, edited, or converted input fields (p,m for fixed fields, or %nn for parsed fields - see PARSE), and a variety of constants: v BUILD or FIELDS: Reformat each record by specifying all of its items one by one. Build gives you complete control over the items you want in your reformatted INREC records and the order in which they appear. You can delete, rearrange and insert fields and constants. Example:
INREC BUILD=(1,20,CABC,26:5C*, 15,3,PD,EDIT=(TTT.TT),21,30,80:X)

v OVERLAY: Reformat each record by specifying just the items that overlay specific columns. Overlay lets you change specific existing columns without affecting the entire record. Example:
INREC OVERLAY=(45:45,8,TRAN=LTOU)

v IFTHEN clauses: Reformat different records in different ways by specifying how build or overlay items are applied to records that meet given criteria. IFTHEN clauses let you use sophisticated conditional logic to choose how different record types are reformatted. Example: | | | | |
INREC IFTHEN=(WHEN=(1,5,CH,EQ,CTYPE1), BUILD=(1,40,C**,+1,TO=PD)), IFTHEN=(WHEN=(1,5,CH,EQ,CTYPE2), BUILD=(1,40,+2,TO=PD,XFFFF)), IFTHEN=(WHEN=NONE),OVERLAY=(45:CNONE))

You can choose to include any or all of the following items in your reformatted INREC records:

126

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

v Fixed position/length fields or variable position/length fields. For fixed 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, null-terminated strings (and many other types), you define rules that allow DFSORT to extract the relevant data into fixed parsed fields, and then use the parsed fields as you would use fixed fields. v Blanks, binary zeros, character strings, and hexadecimal strings v Current date, future date, past date, and current time in various forms v Unedited input fields aligned on byte, halfword, fullword, and doubleword boundaries v Hexadecimal representations of binary input fields v Left-justified, right-justified, left-squeezed, or right-squeezed input fields. v Numeric input fields of various formats converted to different numeric formats, or to character format edited to contain signs, thousands separators, decimal points, leading zeros or no leading zeros, and so on. v Decimal constants converted to different numeric formats, or to character format edited to contain signs, thousands separators, decimal points, leading zeros or no leading zeros, and so on. v The results of arithmetic expressions combining fields, decimal constants, operators (MIN, MAX, MUL, DIV, MOD, ADD and SUB) and parentheses converted to different numeric formats, or to character format edited to contain signs, thousands separators, decimal points, leading zeros or no leading zeros, and so on. v SMF, TOD and ETOD date and time fields converted to different numeric formats, or to character format edited to contain separators, leading zeros or no leading zeros, and so on. v Two-digit year input dates of various formats converted to four-digit year dates in different numeric formats, or to character format edited to contain separators, leading zeros or no leading zeros, and so on. v Sequence numbers in various formats. v A character constant, hexadecimal constant or input field selected from a lookup table, based on a character, hexadecimal or bit constant as input. For information concerning the interaction of INREC and OUTREC, see INREC Statement Notes on page 147. PARSE

Chapter 3. Using DFSORT Program Control Statements

127

INREC Control Statement

, , PARSE=( %nn= %= ( FIXLEN=m ABSPOS=p ADDPOS=x SUBPOS=y , STARTAFT=string STARTAFT=BLANKS STARTAT=string STARTAT=BLANKS STARTAT=NONBLANK , ENDBEFR=string ENDBEFR=BLANKS ENDAT=string ENDAT=BLANKS PAIR=APOST PAIR=QUOTE ) )

This operand allows you to extract variable position/length fields into fixed parsed fields. Parsed fields (%nn) can be used where fixed position/length fields (p,m) can be used in the BUILD (or FIELDS) or OVERLAY operands as described later in this sect ion. PARSE can be used for many different types of variable fields including delimited fields, comma separated values (CSV), tab separated values, blank separated values, keyword separated fields, null-terminated strings, and so on. You can assign up to 100 %nn parsed fields (%00-%99) to the variable fields you want to extract. Note that if all of the fields in your records have fixed positions and lengths, you dont need to use PARSE. But if any of the fields in your records have variable positions or lengths, you can use PARSE to treat them as fixed parsed fields in BUILD or OVERLAY. You can mix p,m fields (fixed fields) and %nn fields (parsed fields) in BUILD and OVERLAY. See PARSE under OUTFIL Control Statements for complete details. Sample Syntax
INREC PARSE=(%00=(ENDBEFR=C*,FIXLEN=3), %01=(ENDBEFR=BLANKS,FIXLEN=6), %02=(STARTAT=CMAX,FIXLEN=8), %03=(STARTAFT=C(,ENDBEFR=C),FIXLEN=6), %04=(STARTAFT=BLANKS,FIXLEN=5)), BUILD=(%03,X,%03,HEX,21:%02,31:%01,SFF,M26,LENGTH=7, 18,6,%00,UFF,M11,LENGTH=3,%04,JFY=(SHIFT=RIGHT))

Default for PARSE: None; must be specified. See Appendix B, Specification/Override of DFSORT Options, on page 741. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. FIELDS or BUILD

128

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

, FIELDS= BUILD= ( c: s p,m ,a %nn p p,m,HEX %nn,HEX p,HEX p,m,TRAN=LTOU %nn,TRAN=LTOU p,TRAN=LTOU p,m,TRAN=UTOL %nn,TRAN=UTOL p,TRAN=UTOL p,m,TRAN=ALTSEQ %nn,TRAN=ALTSEQ p,TRAN=ALTSEQ p,m,Y2x %nn,Y2x p,m,Y2x(c) %nn,Y2x(c) p,m,Y2xP %nn,Y2xP p,m,f ,edit %nn,f ,to (p,m,f) (%nn,f) deccon ,edit (deccon) ,to arexp ,edit (arexp) ,to p,m,Y2x ,edit ,to %nn,Y2x ,edit ,to p,m,lookup %nn,lookup p,m,justify %nn,justify p,m,squeeze %nn,squeeze seqnum )

Specifies all of the items in the reformatted INREC record in the order in which they are to be included. The reformatted INREC record consists of the separation fields, edited and unedited input fields (p,m for fixed fields, or %nn for parsed fields - see PARSE),, edited decimal constants, edited results of arithmetic expressions, and sequence numbers you select, in the order in which you select them, aligned on the boundaries or in the columns you indicate. For variable-length records, the first item in the BUILD or FIELDS parameter must specify or include the unedited 4-byte record descriptor word (RDW), that is, you must start with 1,m with m equal to or greater than 4. If you want to include the bytes from a specific position to the end of each input record at the end of each reformatted output record, you can specify that starting position (p) as the last item in the BUILD or FIELDS parameter. For example:
Chapter 3. Using DFSORT Program Control Statements

129

INREC Control Statement

INREC FIELDS=(1,4, 1,2,BI,TO=ZD,LENGTH=5, C|, 5) unedited RDW display RDW length in decimal | separator display input positions 5 to end

For fixed-length records, the first input and output data byte starts at position 1. For variable-length records, the first input and output data byte starts at position 5, after the RDW in positions 1-4. c: Specifies the position (column) for a separation field, input field, decimal constant, arithmetic expression, or sequence number, relative to the start of the reformatted input record. Unused space preceding the specified column is padded with EBCDIC blanks. The following rules apply: v c must be a number between 1 and 32752. v c: must be followed by a separation field, input field, decimal constant, or arithmetic expression. v c must not overlap the previous input field or separation field in the reformatted input record. v for variable-length records, c: must not be specified before the first input field (the record descriptor word) nor after the variable part of the input record. v The colon (:) is treated like the comma (,) or semicolon (;) for continuation to another line. Both valid and invalid examples are shown in Table 25.
Table 25. Examples of Valid and Invalid Column Alignment Validity Valid Valid Specified 33:CState 20:5,4,30:10,8 Result Columns 1-32 blank Columns 33-38 State Columns Columns Columns Columns 1-19 blank 20-23 input field (5,4) 24-29 blank 30-37 input field (10,8)

Invalid Invalid Invalid Invalid Invalid

0:5,4 :25Z 32753:21,8 5:10:2,5 20,10,6:CAB

Column value cannot be zero. Column value must be specified. Invalid column value must be less than 32753. Column values cannot be adjacent. Column value overlaps previous field.

Specifies that a separation field (blanks, zeros, character string, hexadecimal string, current date, future date, past date, or current time) is to appear in the reformatted input record. It can be specified before or after any input field. Consecutive separation fields can be specified. For variable-length records, separation fields must not be specified before the first input field (the record descriptor word), or after the variable part of the input record. Permissible values are nX, nZ, nCxx...x, nXyy...yy, and various date and time constants. nX Blank separation. n bytes of EBCDIC blanks (X'40') are to appear in the reformatted input records. n can range from 1 to 4095. If n is omitted, 1 is used. Examples of valid and invalid blank separation are shown in Table 26 on page 131.

130

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

Table 26. Examples of Valid and Invalid Blank Separation Validity Valid Valid Invalid Invalid Specified X or 1X 4095X 5000X 0X Result 1 blank 4095 blanks Too many repetitions. Use two adjacent separation fields instead (2500X,2500X, for example) 0 is not allowed.

nZ

Binary zero separation. n bytes of binary zeros (X'00') are to appear in the reformatted input records. n can range from 1 to 4095. If n is omitted, 1 is used. Examples of valid and invalid binary zero separation are shown in Table 27.

Table 27. Examples of Valid and Invalid Binary Zero Separation Validity Valid Valid Invalid Invalid Specified Z or 1Z 4095Z 4450Z 0Z Result 1 binary zero 4095 binary zeros Too many repetitions. Use two adjacent separation fields instead (4000Z,450Z for example). 0 is not allowed.

nCxx...x

Character string separation. n repetitions of the character string constant (Cxx...x) are to appear in the reformatted input records. n can range from 1 to 4095. If n is omitted, 1 is used. x can be any EBCDIC character. You can specify from 1 to 256 characters. If you want to include a single apostrophe in the character string, you must specify it as two single apostrophes:
Required: ONEILL Specify: CONEILL

Examples of valid and invalid character string separation are shown in Table 28.
Table 28. Examples of Valid and Invalid Character String Separation Validity Valid Valid Valid Valid Valid Valid Valid Invalid Invalid Invalid Specified CJohn Doe CJOHN DOE C$@# C+0.193 4000C 20C**FILLER** CFranks C ABCDEF CABCDE Result John Doe JOHN DOE $@# +0.193 8000 blanks **FILLER** repeated 20 times Franks Apostrophes not paired C identifier missing Apostrophe missing Length 8 8 3 6 8000 200 7 n/a n/a n/a

Chapter 3. Using DFSORT Program Control Statements

131

INREC Control Statement

Table 28. Examples of Valid and Invalid Character String Separation (continued) Validity Invalid Specified 4450C1 Result Too many repetitions. Use two adjacent separation fields instead (4000C1,450C1, for example). 0 is not allowed No characters specified Two single apostrophes needed for one Length n/a

Invalid Invalid Invalid

0CABC C CFranks

n/a n/a n/a

nX'yy...yy'

Hexadecimal string separation. n repetitions of the hexadecimal string constant (X'yy...yy') are to appear in the reformatted input records. n can range from 1 to 4095. If n is omitted, 1 is used. The value yy represents any pair of hexadecimal digits. You can specify from 1 to 256 pairs of hexadecimal digits. Examples of valid and invalid hexadecimal string separation are shown in Table 29.

Table 29. Examples of Valid and Invalid Hexadecimal String Separation Validity Valid Valid Valid Valid Invalid Invalid Invalid Invalid Invalid Specified X'FF' X'BF3C' 3X'00000F' 4000X'FFFF' X'ABGD' X'F1F' BF3C F2F1X 8000X'01' Result FF BF3C 00000F00000F00000F FF repeated 8000 times G is not a hexadecimal digit Incomplete pair of digits X identifier missing X in wrong place Too many repetitions. Use two adjacent separation fields instead (4000X'01',4000X'01', for example). 0 is not allowed No hexadecimal digits specified Length 1 2 9 8000 n/a n/a n/a n/a n/a

Invalid Invalid

0X'23AB' X''

n/a n/a

DATEn, DATEn(c), DATEnP Constant for current date. The current date of the run is to appear in the reformatted input records. See DATEn, DATEn(c), DATEnP under OUTFIL OUTREC for details. &DATEn, &DATEn(c), &DATEnP Can be used instead of DATEn, DATEn(c) and DATEnP, respectively. DATEn+r, DATEn(c)+r, DATEnP+r Constant for future date. A future date relative to the current date of the run is to appear in the reformatted input records. See DATEn+r, DATEn(c)+r, DATEnP+r under OUTFIL OUTREC for details. &DATEn+r, &DATEn(c)+r, &DATEnP+r Can be used instead of DATEn+r, DATEn(c)+r and DATEnP+r, respectively.

132

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

DATEn-r, DATEn(c)-r, DATEnP-r Constant for past date. A past date relative to the current date of the run is to appear in the reformatted input records. See DATEn-r, DATEn(c)-r, DATEnP-r under OUTFIL OUTREC for details. &DATEn-r, &DATEn(c)-r, &DATEnP-r Can be used instead of DATEn-r, DATEn(c)-r and DATEnP-r, respectively. TIMEn, TIMEn(c), TIMEnP Constant for current time. The time of the run is to appear in the reformatted input records. See TIMEn, TIMEn(c), TIMEnP under OUTFIL OUTREC for details. &TIMEn, &TIMEn(c), &TIMEnP Can be used instead of TIMEn, TIMEn(c) and TIMEnP, respectively. DATE Specifies that the current date is to appear in the reformatted input records in the form mm/dd/yy. See DATE under OUTFIL OUTREC for details. &DATE Can be used instead of DATE. DATE=(abcd) Specifies that the current date is to appear in the reformatted input records in the form adbdc. See DATE=(abcd) under OUTFIL OUTREC for details. &DATE=(abcd) Can be used instead of DATE=(abcd). DATENS=(abc) Specifies that the current date is to appear in the reformatted input records in the form abc. See DATENS=(ab) under OUTFIL OUTREC for details. &DATENS=(abc) Can be used instead of DATENS=(abc). YDDD=(abc) specifies that the current date is to appear in the reformatted input records in the form acb. See YDDD=(abc) under OUTFIL OUTREC for details. &YDDD=(abc) Can be used instead of YDDD=(abc). YDDDNS=(ab) specifies that the current date is to appear in the reformatted input records in the form ab. See YDDDNS=(ab) under OUTFIL OUTREC for details. &YDDDNS=(ab) can be used instead of YDDDNS=(ab). TIME specifies that the current time is to appear in the reformatted input records in the form hh:mm:ss. See TIME under OUTFIL OUTREC for details. &TIME Can be used instead of TIME. TIME=(abc) specifies that the current time is to appear in the reformatted input records in the form hhcmmcss (24-hour time) or hhcmmcss xx (12-hour time). See TIME=(abc) under OUTFIL OUTREC for details.

Chapter 3. Using DFSORT Program Control Statements

133

INREC Control Statement

&TIME=(abc) Can be used instead of TIME=(abc). TIMENS=(ab) specifies that the current time is to appear in the reformatted input record in the form hhmmss (24-hour time) or hhmmss xx (12-hour time). See TIMENS=(ab) under OUTFIL OUTREC for details. &TIMENS=(ab) Can be used instead of TIMENS=(ab). p,m,a Specifies that an unedited input field is to appear in the reformatted input record. p Specifies the first byte of the input field relative to the beginning of the input record.11 The first data byte of a fixed-length record has relative position 1. The first data byte of a variable-length record has relative position 5 (because the first 4 bytes contain the RDW). All fields must start on a byte boundary, and no field can extend beyond byte 32752. For special rules concerning variable-length records, see INREC Statement Notes on page 147. Specifies the length of the input field. It must include the sign if the data is signed, and must be an integer number of bytes. See INREC Statement Notes on page 147 for more information. Specifies the alignment (displacement) of the input field in the reformatted input record relative to the start of the reformatted input record. Permissible values of a are: H Halfword aligned. The displacement (p-1) of the field from the beginning of the reformatted input record, in bytes, is a multiple of two (that is, position 1, 3, 5, and so forth). Fullword aligned. The displacement is a multiple of four (that is, position 1, 5, 9, and so forth). Doubleword aligned. The displacement is a multiple of eight (that is, position 1, 9, 17, and so forth).

F D

Alignment can be necessary if, for example, the data is to be used in a COBOL application program where items are aligned through the SYNCHRONIZED clause. Unused space preceding aligned fields will always be padded with binary zeros. %nn specifies that an unedited parsed input field is to appear in the reformatted input record. See PARSE for details of parsed fields. See p,m,a for further details. Note that alignment (H, F, D) is not permitted for %nn fields (for example, %nn,F results in an error message and termination). | | | p specifies that the unedited variable part of the input record (that part beyond the minimum record length), is to appear in the reformatted input record, as the last field. p without m can only be used for variable-length records; not for fixed-length records.

11. If your E15 user exit reformats the record, p must refer to the record as reformatted by the exit.

134

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

Attention: If the reformatted input record includes only the RDW and the variable part of the input record, null records containing only an RDW may result. A value must be specified for p that is less than or equal to the minimum record length (RECORD statement L4 value) plus 1 byte. p,m,HEX specifies that the hexadecimal representation of an input field is to appear in the reformatted input record. See p,m,HEX under OUTFIL OUTREC for details. %nn,HEX specifies that the hexadecimal representation of a parsed input field is to appear in the reformatted input record. See PARSE for details of parsed fields. See p,m,HEX for further details. p,HEX specifies that the hexadecimal representation of the variable part of the input record (that part beyond the minimum record length), is to appear in the reformatted input record, as the last field. p,HEX can only be used for variable-length records; not for fixed-length records. See p,HEX under OUTFIL OUTREC for details. p,m,TRAN=LTOU specifies that lowercase EBCDIC letters (that is, a-z) in an input field are to appear as uppercase EBCDIC letters (that is, A-Z) in the reformatted input record. See p,m,TRAN=LTOU under OUTFIL OUTREC for details. %nn,TRAN=LTOU specifies that lowercase EBCDIC letters (that is, a-z) in a parsed input field are to appear as uppercase EBCDIC letters (that is, A-Z) in the reformatted input record. See PARSE for details of parsed fields. See p,m,TRAN=LTOU for further details. p,TRAN=LTOU specifies that lowercase EBCDIC letters (that is, a-z) in the variable part of the input record (that part beyond the minimum record length), are to appear as uppercase EBCDIC letters (that is, A-Z) in the reformatted input record, as the last field. p,TRAN=LTOU can only be used for variable-length records; not for fixed-length records. See p,TRAN=LTOU under OUTFIL OUTREC for details. p,m,TRAN=UTOL specifies that uppercase EBCDIC letters (that is, A-Z) in an input field are to appear as lowercase EBCDIC letters (that is, a-z) in the reformatted input record. See p,m,TRAN=UTOL under OUTFIL OUTREC for details. %nn,TRAN=UTOL specifies that uppercase EBCDIC letters (that is, A-Z) in a parsed input field are to appear as lowercase EBCDIC letters (that is, a-z) in the reformatted input record. See PARSE for details of parsed fields. See p,m,TRAN=UTOL for further details. p,TRAN=UTOL specifies that uppercase EBCDIC letters (that is, A-Z) in the variable part of
Chapter 3. Using DFSORT Program Control Statements

| |

| |

135

INREC Control Statement

the input record (that part beyond the minimum record length), are to appear as lowercase EBCDIC letters (that is, a-z) in the reformatted input record, as the last field. p,TRAN=UTOL can only be used for variable-length records; not for fixed-length records. See p,TRAN=UTOL under OUTFIL OUTREC for details. p,m,TRAN=ALTSEQ specifies that the characters in an input field are to be changed according to the ALTSEQ translation table in effect in the reformatted input record. See p,m,TRAN=ALTSEQ under OUTFIL OUTREC for details. %nn,TRAN=ALTSEQ specifies that the characters in a parsed input field are to be changed according to the ALTSEQ translation table in effect in the reformatted input record. See PARSE for details of parsed fields. See p,m,TRAN=ALTSEQ for further details. p,TRAN=ALTSEQ specifies that the characters in the variable part of the input record (that part beyond the minimum record length), are to be changed according to the ALTSEQ translation table in effect in the reformatted input record, as the last field. p,TRAN=ALTSEQ can only be used for variable-length records; not for fixed-length records. See p,TRAN=ALTSEQ under OUTFIL OUTREC for details.
Sample Syntax: Fixed input records INREC FIELDS=(1:5,10,15:8C0,25:20,15,TRAN=LTOU,80:X) Variable input records INREC FIELDS=(1,4,C RDW=,1,4,HEX,C FIXED=, 5,20,HEX,C VARIABLE=,21,HEX)

| |

| |

p,m,Y2x specifies that the four-digit year CH date representation of a two-digit year input date field is to appear in the reformatted input record. Real dates are transformed using the century window established by the Y2PAST option in effect. The century window is not used for special indicators; they are just expanded appropriately (for example, p,6,Y2T transforms C000000 to C00000000). See p,m,Y2x under OUTFIL OUTREC for details. Sample Syntax:
INREC FIELDS=(21,3,Y2V,X,12,5,Y2W)

%nn,Y2x specifies that the four-digit year CH date representation of a two-digit year parsed input date field is to appear in the reformatted input record. See PARSE for details of parsed fields. See p,m,Y2x for further details. p,m,Y2x(c) specifies that the four-digit year CH date representation with separators of a two-digit year input date field is to appear in the reformatted input record. Real dates are transformed using the century window established by the Y2PAST option in effect. The century window is not used for special indicators; they are just expanded appropriately (for example, p,6,Y2T(/) transforms C000000 to C0000/00/00). See p,m,Y2x(c) under OUTFIL OUTREC for details.

136

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

Sample Syntax:
INREC FIELDS=(25,6,Y2T(-),X,14,2,Y2U(/))

%nn,Y2x(c) specifies that the four-digit year CH date representation with separators of a two-digit year parsed input date field is to appear in the reformatted input record. See PARSE for details of parsed fields. See p,m,Y2x(c) for further details. p,m,Y2xP specifies that the four-digit year PD date representation of a two-digit year input date field is to appear in the reformatted input record. Real dates are transformed using the century window established by the Y2PAST option in effect. The century window is not used for special indicators; they are just expanded appropriately (for example, p,6,Y2TP transforms C000000 to P00000000). See p,m,Y2xP under OUTFIL OUTREC for details. Sample Syntax:
INREC FIELDS=(11,3,Y2XP,X,21,4,Y2WP)

%nn,Y2xP specifies that the four-digit year PD date representation of a two-digit year parsed input date field is to appear in the reformatted input record. See PARSE for details of parsed fields. See p,m,Y2xP for further details. p,m,f,edit or (p,m,f),edit specifies that an edited numeric input field is to appear in the reformatted input record. You can edit BI, FI, PD, PD0, ZD, FL, CSF, FS, UFF, SFF, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3 or TM4 fields using either pre-defined edit masks (M0-M26) or specific edit patterns you define. You can control the way the edited fields look with respect to length, leading or suppressed zeros, thousands separators, decimal points, leading and trailing positive and negative signs, and so on. See p,m,f,edit under OUTFIL OUTREC for details. Sample Syntax:
INREC FIELDS=(5:21,8,ZD,M19,X,46,5,ZD,M13, 31:(35,6,FS),SIGNS=(,,+,-),LENGTH=10, 51:8,4,PD,EDIT=(**II,IIT.TTXS),SIGNS=(,,+,-))

%nn,f,edit or (%nn,f),edit specifies that an edited numeric parsed input field is to appear in the reformatted input record. See PARSE for details of parsed fields. See p,m,f,edit or (p,m,f),edit for further details. p,m,f,to or (p,m,f),to specifies that a converted numeric input field is to appear in the reformatted input record. You can convert BI, FI, PD, PD0, ZD, FL, CSF, FS, UFF, SFF, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3, or TM4 fields to BI, FI, PD, PDC, PDF, ZD, ZDF, ZDC, or CSF/FS fields. See p,m,f,to under OUTFIL OUTREC for details. Sample Syntax:
INREC FIELDS=(21,5,ZD,TO=PD,X,(8,4,ZD),FI,LENGTH=2,X,55,4,FL,TO=FS)

Chapter 3. Using DFSORT Program Control Statements

137

INREC Control Statement

%nn,f,to or (%nn,f),to specifies that a converted numeric parsed input field is to appear in the reformatted input record. See PARSE for details of parsed fields. See p,m,f,to or (p,m,f),to for further details. deccon,edit or (deccon),edit specifies that an edited decimal constant is to appear in the reformatted input record. The decimal constant must be in the form +n or n where n is 1 to 31 decimal digits. The sign (+ or ) must be specified. A decimal constant produces a signed, 31-digit zoned decimal (ZD) result to be edited as specified. See deccon,edit under OUTFIL OUTREC for details. Sample Syntax:
INREC FIELDS=(5:+5000,EDIT=(T,TTT),X, (-25500),M18,LENGTH=8)

deccon,to or (deccon),to specifies that a converted decimal constant is to appear in the reformatted input record. The decimal constant must be in the form +n or n where n is 1 to 31 decimal digits. The sign (+ or ) must be specified. A decimal constant produces a signed, 31-digit zoned decimal (ZD) result to be converted as specified. See deccon,to under OUTFIL OUTREC for details. Sample Syntax:
INREC FIELDS=(+0,TO=PD,LENGTH=6,3Z,(-512000),FI)

arexp,edit or (arexp),edit specifies that the edited result of an arithmetic expression is to appear in the reformatted input record. The arithmetic expression can consist of input fields, decimal constants, operators and parentheses. An arithmetic expression produces a signed, 31-digit zoned decimal (ZD) result to be edited as specified. See arexp,edit under OUTFIL OUTREC for details. Sample Syntax:
INREC FIELDS=(C**,27,2,FI,MIN, 83,4,PD,EDIT=(STTTTTTT),SIGNS=(+,-), 15:(((15,5,ZD,ADD,+1),MUL,+100),DIV,62,2,PD),M25,LENGTH=10)

arexp,to or (arexp),to specifies that the converted result of an arithmetic expression is to appear in the reformatted input record. The arithmetic expression can consist of input fields, decimal constants, operators and parentheses. An arithmetic expression produces a signed, 31-digit zoned decimal (ZD) result to be converted as specified. See arexp,to under OUTFIL OUTREC for details. Sample Syntax:
INREC FIELDS=((15,6,FS,SUB,+5),ADD,(-1,MUL,36,6,FS),ZD,X, 3,2,FI,MIN,-6,LENGTH=4,TO=PD)

p,m,Y2x,edit specifies that an edited four-digit year CH date representation of a two-digit year input date field is to appear in the reformatted input record. See p,m,Y2x,edit under OUTFIL OUTREC for details.

138

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

%nn,Y2x,edit specifies that an edited four-digit year CH date representation of a two-digit year parsed input date field is to appear in the reformatted input record. See PARSE for details of parsed fields. See p,m,Y2x,edit for further details. p,m,Y2x,to specifies that a converted four-digit year date representation of a two-digit year input date field is to appear in the reformatted input record. See p,m,Y2x,to under OUTFIL OUTREC for details. %nn,Y2x,to specifies that a converted four-digit year CH date representation of a two-digit year parsed input date field is to appear in the reformatted input record. See PARSE for details of parsed fields. See p,m,Y2x,to for further details p,m,lookup or %nn,lookup specifies that a character constant, hexadecimal constant, input field (p,m), or parsed input field (%nn) from a lookup table is to appear in the reformatted input record. You can use p,m,lookup or %nn,lookup to select a specified character set constant (that is, a character or hexadecimal string) or set field (that is, an input field or parsed input field) based on matching an input value against find constants (that is, character, hexadecimal, or bit constants). See p,m,lookup or %nn,lookup under OUTFIL OUTREC for details. Sample Syntax:
INREC FIELDS=(11,1, CHANGE=(6, CR,CREAD, CU,CUPDATE, XFF,CEMPTY, CA,CALTER), NOMATCH=(11,6), 4X, 21,1, CHANGE=(10, B.1......,CVSAM, B.0......,CNON-VSAM))

p,m,justify specifies that a left-justified or right-justified input field is to appear in the reformatted input record. For a left-justified field, leading blanks are removed and the characters from the first nonblank to the last nonblank are shifted left, with blanks inserted on the right if needed. For a right-justified field, trailing blanks are removed and the characters from the last nonblank to the first nonblank are shifted right, with blanks inserted on the left if needed. Optionally: v specific leading and trailing characters can be changed to blanks before justification begins v a leading string can be inserted v a trailing string can be inserted v the output length can be changed (its equal to the input length by default) See p,m,justify under OUTFIL OUTREC for details. Sample Syntax:

Chapter 3. Using DFSORT Program Control Statements

139

INREC Control Statement

INREC FIELDS=(1,10, 21,20,JFY=(SHIFT=RIGHT),5X, 52,12,JFY=(SHIFT=LEFT,PREBLANK=C(),LEAD=CVOL=SER=, LENGTH=16))

%nn,justify specifies that a left-justified or right-justified parsed input field is to appear in the reformatted input record. See PARSE for details of parsed fields. See p,m,justify for further details. p,m,squeeze specifies that a left-squeezed or right-squeezed input field is to appear in the reformatted input record. For a left-squeezed field, all blanks are removed and the characters from the first nonblank to the last nonblank are shifted left, with blanks inserted on the right if needed. For a right-squeezed field, all blanks are removed and the characters from the last nonblank to the first nonblank are shifted right, with blanks inserted on the left if needed. Optionally: v specific characters can be changed to blanks before squeezing begins v a leading string can be inserted v a trailing string can be inserted v a string (for example, a comma delimiter) can be inserted wherever a group of blanks is removed between the first nonblank and the last nonblank v blanks can be kept as is between paired apostrophes (AB CD EF) or paired quotes (AB CD EF) v the output length can be changed (its equal to the input length by default) See p,m,squeeze under OUTFIL OUTREC for details. Sample Syntax:
INREC FIELDS=(21,20,SQZ=(SHIFT=LEFT),5X, 152,18,SQZ=(SHIFT=RIGHT,PREBLANK=X00, LEAD=C<,MID=C,,TRAIL=C>,PAIR=APOST))

%nn,squeeze specifies that a left-squeezed or right-squeezed parsed input field is to appear in the reformatted input record. See PARSE for details of parsed fields. See p,m,squeeze for further details. seqnum specifies that a sequence number is to appear in the reformatted input record. The sequence numbers are assigned in the order in which the records are received for INREC processing. You can create BI, PD, ZD, CSF, or FS sequence numbers and control their lengths, starting values and increment values. You can restart the sequence number at the start value each time a specified input field (p,m) or parsed input field (%nn) changes. See seqnum under OUTFIL OUTREC for details. Sample Syntax:
INREC FIELDS=(1,80,SEQNUM,8,ZD)

Default for BUILD or FIELDS: None; must be specified. See Appendix B, Specification/Override of DFSORT Options, on page 741. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. OVERLAY

140

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

, OVERLAY=( c: s p,m ,a %nn p,m,HEX %nn,HEX p,m,TRAN=LTOU %nn,TRAN=LTOU p,m,TRAN=UTOL %nn,TRAN=UTOL p,m,TRAN=ALTSEQ %nn,TRAN=ALTSEQ p,m,Y2x %nn,Y2x p,m,Y2x(c) %nn,Y2x(c) p,m,Y2xP %nn,Y2xP p,m,f ,edit %nn,f ,to (p,m,f) (%nn,f) deccon ,edit (deccon) ,to arexp ,edit (arexp) ,to p,m,Y2x ,edit ,to %nn,Y2x ,edit ,to p,m,lookup %nn,lookup p,m,justify %nn,justify p,m,squeeze %nn,squeeze seqnum )

Specifies each item that is to overlay specific columns in the reformatted record. Columns that are not overlaid remain unchanged. If you want to insert, rearrange, or delete fields, use BUILD or FIELDS rather than OVERLAY. Use OVERLAY only to overlay existing columns or to add fields at the end of every record. OVERLAY can be easier to use then BUILD or FIELDS when you just want to change a few fields without rebuilding the entire record. For fixed-length records, the first input and output data byte starts at position 1. For variable-length records, the first input and output data byte starts at position 5, after the RDW in positions 1-4. Use c: (column) to specify the output positions to be overlaid. If you do not specify c: for the first item, it defaults to 1:. If you do not specify c: for any other item, it starts after the previous item. For example, if you specify:
INREC OVERLAY=(25,2,11:CA,15,3,C**)

Chapter 3. Using DFSORT Program Control Statements

141

INREC Control Statement

Input positions 25-26 are placed at output positions 1-2; CA is placed at output position 11; input positions 15-17 are placed at output positions 12-14; and C** is placed at output positions 1516. The rest of the record remains unchanged. You can specify items in any order, you can change the same item multiple times and you can overlap output columns. Changes to earlier items affect changes to later items. For example, say you specify:
INREC OVERLAY=(21:8,4,ZD,MUL,+10,TO=ZD,LENGTH=6, 5:5,1,TRAN=UTOL, 5:5,1,CHANGE=(1,Ca,CX,Cb,CY),NOMATCH=(5,1))

and input position 5 has A. The second item (UTOL) would change A to a and the third item (CHANGE) would change a again to X. If you specify an OVERLAY item that extends the overlay record beyond the end of the input record, the reformatted record length is automatically increased to that length, and blanks are filled in on the left as needed. For variable-length records, the RDW length is also increased to correspond to the larger reformatted record length after all of the OVERLAY items are processed. For example, if your input record has a length of 40 and you specify:
INREC OVERLAY=(16:CABC,51:5C*,35:15,2)

the output record is given a length of 55. Blanks are filled in from columns 41-50. For variable-length records, the length in the RDW is changed from 40 to 55 after all of the OVERLAY items are processed. Missing bytes in specified input fields are replaced with blanks so the padded fields can be processed. See INREC FIELDS for details of the items listed in the OVERLAY syntax diagram above. You can specify all of the items for OVERLAY in the same way that you can specify them for BUILD or FIELDS with the following exceptions: v You cannot specify p or p,HEX or p,TRAN=value for OVERLAY. v For p,m,H or p,m,F or p,m,D fields specified for OVERLAY, fields are aligned as necessary without changing the preceding bytes. v For variable-length records, you must not overlay positions 1-4 (the RDW) for OVERLAY, so be sure to specify the first column (c:) as 5 or greater. If you do not specify the first column, it will default to 1: which is invalid for variable-length records with OVERLAY. Whereas FIELDS=(1,m,...) is required, OVERLAY=(1,m) is not allowed, since it would overlay the RDW. Sample Syntax: Fixed input records:
INREC OVERLAY=(21:21,4,ZD,TO=PD,LENGTH=4, 2:5,8,HEX,45:C*,32,4,C*,81:SEQNUM,5,ZD)

Variable input records:

INREC OVERLAY=(5:X0001,28:CDate is ,YDDDNS=(4D), 17:5C*)

Default for OVERLAY: None; must be specified. See Appendix B, Specification/Override of DFSORT Options, on page 741. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. IFTHEN

142

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

, IFTHEN=( WHEN=INIT ,PARSE=(definitions) ,BUILD=(items) ,OVERLAY=(items) WHEN=(logexp) ,PARSE=(definitions) ,BUILD=(items) ,HIT=NEXT ,OVERLAY=(items) WHEN=ANY ,PARSE=(definitions) ,BUILD=(items) ,HIT=NEXT ,OVERLAY=(items) WHEN=NONE ,PARSE=(definitions) ,BUILD=(items) ,OVERLAY=(items) )

IFTHEN clauses allow you to reformat different records in different ways by specifying how build or overlay items are to be applied to records that meet given criteria. IFTHEN clauses let you use simple or complex conditional logic to choose how different record types are reformatted. If you want to insert, rearrange, or delete fields in the same way for every record, use BUILD or FIELDS rather than IFTHEN. If you want to overlay existing columns in the same way for every record, use OVERLAY rather than IFTHEN. Use IFTHEN clauses if you want to insert, rearrange, delete or overlay fields in different ways for different records. You can use four types of IFTHEN clauses as follows: v WHEN=INIT: Use one or more WHEN=INIT clauses to apply build or overlay items to all of your input records. WHEN=INIT clauses are processed before any of the other IFTHEN clauses. v WHEN=(logexp): Use one or more WHEN=(logexp) clauses to apply build or overlay items to your input records that meet specified criteria. A WHEN=(logexp) clause is satisfied when the logical expression evaluates as true. v WHEN=ANY: Use a WHEN=ANY clause after multiple WHEN=(logexp) clauses to apply additional build or overlay items to your input records if they satisfied the criteria for any of the preceding WHEN=(logexp) clauses. v WHEN=NONE: Use one or more WHEN=NONE clauses to apply build or overlay items to your input records that did not meet the criteria for any of the WHEN=(logexp) clauses. WHEN=NONE clauses are processed after any of the other IFTHEN clauses. If you do not specify a WHEN=NONE clause, only the WHEN=INIT changes (if any) are applied to input records that do not meet the criteria for any of the WHEN=(logexp) clauses. IFTHEN clauses are processed in the following order: v WHEN=INIT clauses v WHEN=(logexp) clauses and WHEN=ANY clauses v WHEN=NONE clauses Processing of IFTHEN clauses continues unless one of the following occurs: v A WHEN=(logexp) or WHEN=ANY clause is satisfied, and HIT=NEXT is not specified. v There are no more IFTHEN clauses to process. When processing of IFTHEN clauses stops, the IFTHEN record created so far is used as the output record. Example:

Chapter 3. Using DFSORT Program Control Statements

143

INREC Control Statement

INREC IFTHEN=(WHEN=(12,1,BI,ALL,X3F),OVERLAY=(18:CYes)), IFTHEN=(WHEN=(35,2,PD,EQ,+14),BUILD=(1,40,45,3,HEX),HIT=NEXT), IFTHEN=(WHEN=(35,2,PD,GT,+17),BUILD=(1,40,41,5,HEX),HIT=NEXT), IFTHEN=(WHEN=ANY,BUILD=(1,55,CABC,70:X)), IFTHEN=(WHEN=(63,2,CH,EQ,CAB),OVERLAY=(18:CNo)), IFTHEN=(WHEN=NONE,BUILD=(1,40,51,8,TRAN=LTOU))

For this example, the IFTHEN clauses are processed as follows: v If IFTHEN clause 1 is satisfied, its overlay item is applied and IFTHEN processing stops. v If IFTHEN clause 1 is not satisfied, its overlay item is not applied and IFTHEN processing continues. v If IFTHEN clause 2 is satisfied, its build items are applied and IFTHEN processing continues. v If IFTHEN clause 2 is not satisfied, its build items are not applied and IFTHEN processing continues. v If IFTHEN clause 3 is satisfied, its build items are applied and IFTHEN processing continues. v If IFTHEN clause 3 is not satisfied, its build items are not applied and IFTHEN processing continues. v If IFTHEN clause 4 is satisfied, its build items are applied and IFTHEN processing stops. v If IFTHEN clause 4 is not satisfied, its build items are not applied and IFTHEN processing continues. v If IFTHEN clause 5 is satisfied, its overlay item is applied and IFTHEN processing stops. v If IFTHEN clause 5 is not satisfied, its overlay item is not applied and IFTHEN processing continues. v If IFTHEN clause 6 is satisfied, its build items are applied and IFTHEN processing stops. v If IFTHEN clause 6 is not satisfied, its build items are not applied and IFTHEN processing stops. All of the IFTHEN clauses operate sequentially on an IFTHEN record. The IFTHEN record is created initially from the input record. Each IFTHEN clause tests and changes the IFTHEN record, as appropriate. Thus, changes made by earlier IFTHEN clauses are seen by later IFTHEN clauses. For example, if you have a 40-byte input record and specify:
INREC IFTHEN=(WHEN=INIT,OVERLAY=(8:8,4,ZD,ADD,+1,TO=ZD,LENGTH=4)), IFTHEN=(WHEN=(8,4,ZD,EQ,+27),OVERLAY=(28:CYes)), IFTHEN=(WHEN=NONE,OVERLAY=(28:CNo))

The WHEN=INIT clause adds 1 to the ZD value and stores it in the IFTHEN record. The WHEN=(8,4,ZD,EQ,+27) clause tests the incremented ZD value in the IFTHEN record rather than the original ZD value in the input record. The IFTHEN record is adjusted as needed for the records created or changed by the IFTHEN clauses. For fixed-length records, blanks are filled in on the left as needed. For variable-length records, the RDW length is adjusted as needed each time the IFTHEN record is changed. Missing bytes in specified input fields are replaced with blanks so the padded fields can be processed. DFSORT sets an appropriate LRECL (or reformatted record length if the INREC record is further modified) for the output records based on the build and overlay items specified by the IFTHEN clauses. However, DFSORT does not analyze the possible results of WHEN=(logexp) conditions when

144

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

determining an appropriate LRECL. When you use INREC IFTHEN clauses, you can override the INREC LRECL determined by DFSORT with the INREC IFOUTLEN parameter. If SEQNUM is used in multiple IFTHEN clauses, the sequence number will be incremented for each record that satisfies the IFTHEN clause, that is, a separate SEQNUM counter will be kept for each IFTHEN clause. For example, if your input is:
RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD A B B C A C B D 1 1 2 1 2 2 3 1

and you specify:

INREC IFTHEN=(WHEN=(8,1,CH,EQ,CA),OVERLAY=(15:SEQNUM,4,ZD)), IFTHEN=(WHEN=(8,1,CH,EQ,CB),OVERLAY=(16:SEQNUM,4,ZD)), IFTHEN=(WHEN=NONE,OVERLAY=(17:SEQNUM,4,ZD))

your output will be:

RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD A B B C A C B D 1 1 2 1 2 2 3 1 0001 0001 0002 0001 0002 0002 0003 0003

Separate SEQNUM counters are kept for the A record, for the B record, and for the NONE records. WHEN=INIT clause See WHEN=INIT clause under OUTFIL IFTHEN for details. Note that / cannot be used to create blank records or new records. Sample Syntax:
INREC IFTHEN=(WHEN=INIT, BUILD=(1,20,21:CDepartment,31:3X,21,60)), IFTHEN=(WHEN=(5,2,CH,EQ,CD1),OVERLAY=(31:8,3)), IFTHEN=(WHEN=(5,2,CH,EQ,CD2),OVERLAY=(31:12,3))

WHEN=(logexp) clause See WHEN=(logexp) clause under OUTFIL IFTHEN for details. Note that although / can be used create blank records and new records with OUTFIL, it cannot be used with INREC. Sample Syntax:
INREC IFTHEN=(WHEN=(1,3,CH,EQ,CT01,AND, 18,4,ZD,LE,+2000),OVERLAY=(42:CType1 <= 2000),HIT=NEXT), IFTHEN=(WHEN=(1,3,CH,EQ,CT01,AND,6,1,BI,BO,X03), BUILD=(1,21,42,13)), IFTHEN=(WHEN=(1,3,CH,EQ,CT01,AND, 18,4,ZD,GT,+2000),OVERLAY=(42:CType1 > 2000 ),HIT=NEXT), IFTHEN=(WHEN=(1,3,CH,EQ,CT01,AND,6,1,BI,BO,X01), BUILD=(1,25,42,13))

WHEN=ANY clause
Chapter 3. Using DFSORT Program Control Statements

145

INREC Control Statement

See WHEN=ANY clause under OUTFIL IFTHEN for details. Note that although / can be used create blank records and new records with OUTFIL, it cannot be used with INREC. Sample Syntax:
INREC IFTHEN=(WHEN=(1,3,SS,EQ,CT01,T02,T03), BUILD=(CGroup A,X,1,80),HIT=NEXT), IFTHEN=(WHEN=(1,3,SS,EQ,CT04,T05,T06), BUILD=(CGroup B,X,1,80),HIT=NEXT), IFTHEN=(WHEN=(1,3,SS,EQ,CT07,T08,T09,T10), BUILD=(CGroup C,X,1,80),HIT=NEXT), IFTHEN=(WHEN=ANY,OVERLAY=(16:CGroup Found)

WHEN=NONE clause See WHEN=NONE clause under OUTFIL IFTHEN for details. Note that although / can be used create blank records and new records with OUTFIL, it cannot be used with INREC. Sample Syntax:
INREC IFTHEN=(WHEN=INIT,BUILD=(1,20,21:CDepartment,31:3X,21,60)), IFTHEN=(WHEN=(5,2,CH,EQ,CD1),OVERLAY=(31:8,3)), IFTHEN=(WHEN=(5,2,CH,EQ,CD2),OVERLAY=(31:12,3)), IFTHEN=(WHEN=NONE,OVERLAY=(31:C***))

Default for IFTHEN clauses: None; must be specified. See Appendix B, Specification/Override of DFSORT Options. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options. IFOUTLEN

IFOUTLEN=n

Overrides the INREC LRECL (or reformatted record length if the INREC record is further modified) determined by DFSORT from your INREC IFTHEN clauses. DFSORT sets an appropriate LRECL for the output records based on the build and overlay items specified by the IFTHEN clauses. However, DFSORT does not analyze the possible results of WHEN=(logexp) conditions when determining an appropriate INREC LRECL. When you use INREC IFTHEN clauses, you can override the INREC LRECL determined by DFSORT with the INREC IFOUTLEN parameter. Fixed-length records longer than the IFOUTLEN length are truncated to the IFOUTLEN length. Fixed-length records shorter than the IFOUTLEN are padded with blanks to the IFOUTLEN length. Variable-length records longer than the IFOUTLEN length are truncated to the IFOUTLEN length. n specifies the length to use for the INREC LRECL (or for the reformatted record length if the INREC record is further modified) . The value for n must be between 1 and 32767, but must not be larger than the maximum LRECL allowed for the RECFM, and must not conflict with the specified or retrieved LRECL for the fixed-length output data set.

Sample Syntax:

146

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

INREC IFOUTLEN=70, IFTHEN=(WHEN=(5,1,CH,EQ,C1,AND,8,3,ZD,EQ,+10), BUILD=(1,40,CT01-GROUP-A,65)), IFTHEN=(WHEN=(5,1,CH,EQ,C2,AND,8,3,ZD,EQ,+12), BUILD=(1,40,CT02-GROUP-B,65))

Default for IFOUTLEN: The LRECL determined from the IFTHEN clauses.

INREC Statement Notes

v When INREC is specified, DFSORT reformats the input records after user exit E15 or INCLUDE/OMIT statement processing is finished. Thus, references to fields by your E15 user exit and INCLUDE/OMIT statements are not affected, whereas your SORT, OUTREC, and SUM statements must refer to fields in the reformatted input records. Your E35 user exit must refer to fields in the reformatted output record. v In general, OUTREC should be used rather than INREC so your SORT and SUM statements can refer to fields in the original input records. v If you use locale processing for SORT, MERGE, INCLUDE, or OMIT fields, you must not use INREC. Use the OUTREC statement or the OUTFIL statement instead of INREC. v When you specify INREC, you must be aware of the change in record size and layout of the resulting reformatted input records. v Performance can be improved if you can significantly reduce the length of your records with INREC. INREC and OUTREC should not be used unless they are actually needed to reformat your records. v For variable-length records, the first entry in the FIELDS, BUILD, or IFTHEN BUILD parameter must specify or include the unedited 4-byte record descriptor word (RDW), that is, the first field must be 1,4 or 1,m with m greater than 4. DFSORT sets the length of the reformatted record in the RDW. If the first field in the data portion of the input record is to appear unedited in the reformatted record immediately following the RDW, the entry in the FIELDS, BUILD, or IFTHEN BUILD parameter can specify both RDW and data field in one (1,m,...). Otherwise, the RDW must be specifically included in the reformatted record (for example, 1,4,1,4,HEX). v For variable-length records, OVERLAY or IFTHEN OVERLAY items must not overlay the RDW in bytes 1-4. You must ensure that 1:, 2:, 3: or 4: is not specified or defaulted for any OVERLAY item. Note that the default for the first OVERLAY item is 1:, so you must override it. v If the SORTOUT LRECL is specified or available, DFSORT will use it even if it does not match the reformatted INREC record length; this can cause padding or truncation of the reformatted INREC records, or termination. If the SORTOUT LRECL is not specified or available, DFSORT can automatically use the reformatted INREC record length as the SORTOUT LRECL, when appropriate. See the discussion of the SOLRF and NOSOLRF options in OPTION Control Statement on page 167. For VSAM data sets, the maximum record size defined in the cluster is equivalent to the LRECL when processing fixed-length records, and is four bytes less than the LRECL when processing variable-length records. See VSAM Considerations on page 15 for more information. v With FIELDS, BUILD, or IFTHEN BUILD, the variable part of the input record (that part beyond the minimum record length) can be included in the reformatted record, and if included, must be the last part. In this case, a value

Chapter 3. Using DFSORT Program Control Statements

147

INREC Control Statement

must be specified for pn that is less than or equal to the minimum record length (see L4 of the RECORD control statement) plus 1 byte; mn and an must be omitted. For example:
INREC FIELDS=(1,8,20C*,9)

With OVERLAY, the variable part of the input record must not be included in the reformatted record. v If INREC with FIELDS or BUILD and OUTREC with FIELDS and BUILD are specified, either both must specify position-only for the last part, or neither must specify position-only for the last part. For example:
INREC BUILD=(1,8,20C*,9) OUTREC BUILD=(1,4,3Z,5)

or:
INREC FIELDS=(1,40,45,5) OUTREC FIELDS=(1,45,C****)

OVERLAY or IFTHEN, and FIELDS or BUILD, can differ with respect to position-only. For example:
INREC BUILD=(1,24,32:25) OUTREC IFTHEN=(WHEN=(8,1,ZD,GT,+5), BUILD=(1,24,25:CYes,28,10)), IFTHEN=(WHEN=NONE, BUILD=(1,24,25:CNo ,28,10))

or:
INREC FIELDS=(1,18,8C*,23) OUTREC OVERLAY=(24:CA)

v If the reformatted record includes only the RDW and the variable part of the input record, null records containing only an RDW could result. v The input records are reformatted before processing, as specified by INREC. The output records are in the format specified by INREC, unless OUTREC is also specified. v Fields referenced in INREC statements can overlap each other and control fields or both. v If input is variable records, the output is also variable. This means that each record is given the correct RDW by DFSORT before output. v If overflow might occur during summation, INREC can be used to create a larger SUM field in the reformatted input record (perhaps resulting in a larger record for sorting or merging) so that overflow does not occur. Example 5 on page 412 illustrates this technique. v DFSORT issues a message and terminates if an INREC statement is specified for a tape work data set sort or conventional merge application. v If SZERO is in effect, 0 is treated as negative and +0 is treated as positive for edited or converted input fields, decimal constants, and the results of arithmetic expressions. If NOSZERO is in effect, 0 and +0 are treated as positive for edited or converted input fields, decimal constants, and the results of arithmetic expressions. v If SZERO is in effect, -0 compares as less than +0 when numeric fields and constants are used. If NOSZERO is in effect, -0 compares as equal to +0 when numeric fields and constants are used. Note: OPTION SZERO or OPTION NOSZERO is ignored for INREC IFTHEN=(WHEN=(logexp),...) unless the OPTION statement is found in a higher source (for example, DFSPARM is a higher source than SYSIN) or

148

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

before the INREC statement in the same source. For example, NOSZERO will be used in both of the following cases: Case 1:
//DFSPARM DD * OPTION COPY,NOSZERO /* //SYSIN DD * INREC IFTHEN=(WHEN=(1,2,FS,EQ,+0),OVERLAY=(22:CYes)), IFTHEN=(WHEN=NONE,OVERLAY=(22:CNo )) /*

Case 2:
//SYSIN DD * OPTION COPY,NOSZERO INREC IFTHEN=(WHEN=(1,2,FS,EQ,+0),OVERLAY=(28:CA)), IFTHEN=(WHEN=NONE,OVERLAY=(28:CB)) /*

Reformatting Records Before Processing Examples

Both INREC and OUTREC can be used to reformat records, either separately or together. The two control statements perform similar functions, although INREC reformats records before sort, merge, or copy processing, whereas OUTREC reformats records after sort, merge, or copy processing. This section shows INREC examples. See Reformatting Records After Processing Examples on page 387 for OUTREC examples.

Example 1
INREC Method:
INCLUDE COND=(5,1,GE,CM),FORMAT=CH INREC FIELDS=(10,3,20,8,33,11,5,1) SORT FIELDS=(4,8,CH,A,1,3,FI,A) SUM FIELDS=(17,4,BI)

OUTREC Method:
INCLUDE COND=(5,1,GE,CM),FORMAT=CH OUTREC FIELDS=(10,3,20,8,33,11,5,1) SORT FIELDS=(20,8,CH,A,10,3,FI,A) SUM FIELDS=(38,4,BI)

The above examples illustrate how a fixed-length input data set is sorted and reformatted for output. Unnecessary fields are eliminated from the output records using INREC or OUTREC. The SORTIN LRECL is 80. Records are also included or excluded by means of the INCLUDE statement, and summed by means of the SUM statement. The reformatted input records are fixed length with a record size of 23 bytes. SOLRF (the IBM-supplied default) is in effect, so unless the SORTOUT LRECL is specified or available, it will automatically be set to the reformatted record length of 23. The reformatted records look as follows after INREC or OUTREC processing: Position 1-3 4-11 12-22 23 Contents Input positions 10 through 12 Input positions 20 through 27 Input positions 33 through 43 Input position 5

Chapter 3. Using DFSORT Program Control Statements

149

INREC Control Statement

Identical results are achieved with INREC or OUTREC. However, use of OUTREC makes it easier to code the SORT and SUM statements. In either case, the INCLUDE COND parameters must refer to the fields of the original input records. However, with INREC, the SUM and SORT FIELDS parameters must refer to the fields of the reformatted input records, while with OUTREC, the SUM and SORT FIELDS parameters must refer to the fields of the original input records.

Example 2
INREC FIELDS=(1,35,2Z,36,45) MERGE FIELDS=(20,4,CH,D,10,3,CH,D),FILES=3 SUM FIELDS=(36,4,BI,40,8,PD) RECORD TYPE=F,LENGTH=(80,,82)

This example illustrates how overflow of a summary field can be prevented when three fixed-length data sets are merged and reformatted for output. The input record size is 80 bytes. To illustrate the use of the RECORD statement, assume that SORTIN and SORTOUT are not present (that is, all input/output is handled by user exits). The reformatted input records are fixed-length with a record size of 82 bytes (an insignificant increase from the original size of 80 bytes). They look as follows: Position 1-35 36-37 38-82 Contents Input positions 1 through 35 Binary zeros (to prevent overflow) Input positions 36 through 80

The MERGE and SUM statements must refer to the fields of the reformatted input records. The reformatted output records are identical to the reformatted input records. Thus, the 2-byte summary field at positions 36 and 37 in the original input records expands to a 4-byte summary field in positions 36 through 39 of the reformatted input/output record before merging. This prevents overflow of this summary field. Restriction: If OUTREC were used instead of INREC, the records would be reformatted after merging, and the 2-byte summary field might overflow. Note: This method of preventing overflow cannot be used for negative FI summary fields because padding with zeros rather than ones would change the sign.

Example 3
INREC BUILD=(20,4,12,3) SORT FIELDS=(1,4,D,5,3,D),FORMAT=CH OUTREC BUILD=(5X,1,4,H,19:1,2,5,3,DATE1(),80XFF)

This example illustrates how a fixed-length input data set can be sorted and reformatted for output. A more efficient sort is achieved by using INREC before sorting to reduce the input records as much as possible, and using OUTREC after sorting to add padding, the current date and repeated fields. The SORTIN LRECL is 80 bytes. The reformatted input records are fixed-length, and have a record size of seven bytes (a significant reduction from the original size of 80 bytes). They look as follows: Position Contents

150

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

1-4 5-7 Input positions 20 through 23 Input positions 12 through 14

The SORT and OUTREC statements must refer to the fields of the reformatted input records. The reformatted output records are fixed length with a record size of 113 bytes. SOLRF (the IBM-supplied default) is in effect, so unless the SORTOUT LRECL is specified or available, it will automatically be set to the reformatted record length of 113. The reformatted output records look as follows: Position 1-5 6 7-10 11-18 19-20 21-23 24-33 34-113 Contents EBCDIC blanks Binary zero (for H alignment) Input positions 20 through 23 EBCDIC blanks Input positions 20 through 21 Input positions 12 through 14 The current date in the form Cyyyy-mm-dd Hexadecimal FFs

Thus, the use of INREC and OUTREC allows sorting of 7-byte records rather than 80-byte records, even though the output records are 113 bytes long.

Example 4
OPTION COPY,Y2PAST=1985 INREC FIELDS=(SEQNUM,4,BI, 8,5,ZD,TO=PD, 31,2,PD,TO=FI,LENGTH=2, 15,6,Y2TP, 25,3,CHANGE=(1,CL92,X01,CM72,X02,CJ42,X03), NOMATCH=(XFF))

This example illustrates how a sequence number can be generated, how values in one numeric or date format can be converted to another format, and how a lookup table can be used. The reformatted input records will look as follows: Position 1-4 57 89 1014 Contents A binary sequence number that starts at 1 and increments by 1. A PD field containing the converted ZD field from input positions 8 through 12. An FI field containing the converted PD field from input positions 31 through 32. A Pyyyymmdd date field containing the Cyymmdd date field from input positions 15-20 transformed according to the specified century window of 1985-2084. A BI field containing X01, X02, X03 or XFF as determined by using a lookup table for the input field in positions 25-27.

15

The SORT statement can now refer to the sort field in the reformatted input records. The OUTREC statement is used to restore the records to their original format.

Chapter 3. Using DFSORT Program Control Statements

151

INREC Control Statement

Example 5
INREC OVERLAY=(61:21,11,SFF,ADD,41,11,SFF,TO=PD,LENGTH=5) SORT FIELDS=(61,5,PD,A) OUTREC OVERLAY=(61:61,5,PD,EDIT=(SIII,IIT.TT),SIGNS=(+,-))

This example illustrates how you can use the OVERLAY parameter with INREC and OUTREC to change certain columns in your records without affecting other columns. Positions 61-65 of the reformatted input records are overlaid with a 5-byte PD value derived from adding the sddd,ddd.dd field at positions 21-31 to the sddd,ddd.dd field at positions 41-51. The records are then sorted by this 5-byte PD field. Positions 61-71 of the reformatted output records are overlaid with an sddd,ddd.dd field derived from the 5-byte PD value. The data before positions 61-71 and after positions 61-71 are not affected

Example 6
OPTION COPY INREC IFTHEN=(WHEN=(5,2,CH,EQ,CGP,AND,2,1,BI,EQ,+1), BUILD=(1,6,16,20,CT1,X0003,1,7,20C1)), IFTHEN=(WHEN=(5,2,CH,EQ,CGP,AND,2,1,BI,EQ,+2), BUILD=(1,6,45,20,CT2,X0008,16,7,20C2)), IFTHEN=(WHEN=(5,2,CH,EQ,CGP,AND,2,1,BI,EQ,+3), BUILD=(1,6,31,20,CT3,X0005,25,7,20C3)), IFTHEN=(WHEN=NONE,OVERLAY=(27:C00,XFFFF)), IFOUTLEN=57

This example illustrates how you can use IFTHEN clauses with INREC to reformat different records in different ways. IFOUTLEN=57 is used to set the reformatted record length to 57. Records with GP in positions 5-6 and X01 in position 2 are reformatted as follows: Position 1-6 7-26 27-28 29-30 31-37 38-57 Contents Input positions 1-6 Input positions 16-35 T1 X'0003' Input positions 1-7 20 1s

Records with GP in positions 5-6 and X'02' in position 2 are reformatted as follows: Position 1-6 7-26 27-28 29-30 31-37 38-57 Contents Input positions 1-6 Input positions 45-64 T2 X'0008' Input positions 16-22 20 2s

Records with GP in positions 5-6 and X'03' in position 2 are reformatted as follows: Position 1-6 7-26 Contents Input positions 1-6 Input positions 31-50

152

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

27-28 29-30 31-37 38-57 T3 X'0005' Input positions 25-31 20 3s

Records without GP in positions 5-6 or without X'01', X'02', or X'03' in position 2 are reformatted as follows: Position 1-26 27-28 29-30 31-57 Contents Input positions 1-26 00 X'FFFF' Input positions 31-57

Example 7
INREC OVERLAY=(16:1,15,JFY=(SHIFT=LEFT)) SORT FIELDS=(16,15,CH,A) OUTREC BUILD=(1,15)

This example illustrates how you can left-justify characters in an input field so they can be sorted without regard to the leading blanks. The 15-byte input records might look like this:
CARRIE VICKY FRANK SAM DAVID MARTIN

Note that if we sort these records using just this control statement:
SORT FIELDS=(1,15,CH,A)

The 15-byte output records are as follows:

FRANK VICKY SAM MARTIN CARRIE DAVID

Because of the different number of leading blanks in the input records, we dont get what we want. To fix that, while keeping the leading blanks in the original records, we use the JFY function of INREC to make a left-justified copy of the 15-byte input field at positions 16-30, SORT on it and use OUTREC to remove the left-justified field. With the INREC, SORT and OUTREC control statements shown above, the output records are:
CARRIE DAVID FRANK MARTIN SAM VICKY

If we wanted the output to contain the sorted left-justified fields, we could use these control statements:
INREC BUILD=(1,15,JFY=(SHIFT=LEFT)) SORT FIELDS=(1,15,CH,A)

Chapter 3. Using DFSORT Program Control Statements

153

INREC Control Statement

The output records would then be:
CARRIE DAVID FRANK MARTIN SAM VICKY

Example 8
INREC PARSE=(%00=(ENDBEFR=C,,FIXLEN=11), %01=(ENDBEFR=C,,FIXLEN=5), %02=(FIXLEN=6)), OVERLAY=(31:%00,42:%01,47:%02) SORT FIELDS=(31,11,CH,A,42,5,UFF,A,47,6,SFF,D) OUTREC BUILD=(1,30)

This example illustrates how you can sort FB input records with variable position/length fields, such as comma separated values. The 30-byte input records might look like this:
Marketing,96218,+27365 Development,3807,+1275 Research,7283,+5001 Development,1700,-5316 Research,978,+13562 Development,3807,-158 Research,7283,+5002 Marketing,52,-8736 Development,5781,+2736 Marketing,52,+1603 Research,16072,-2022

We want to sort the first field as character ascending, the second field as unsigned numeric ascending and the third field as signed numeric descending. Note that each record has three variable fields in comma separated value format. The fields do not start and end in the same position in every record and do not have the same length in every record. The first and second fields end with a comma and the third field ends with a blank. In order to sort variable fields like these, we use the PARSE and OVERLAY functions of INREC to create a fixed parsed copy of each variable field. We use %00 to create an 11-byte fixed parsed field into which we extract the value before the first comma. We use %01 to create a 5-byte fixed parsed field into which we extract the value after the first comma and before the second comma. We use %02 to create a 6-byte fixed parsed field into which we extract the value after the second comma. Then we SORT on the fixed parsed fields. Finally, we use OUTREC to remove the fixed parsed fields. After the INREC statement is processed, the records look like this:
Marketing,96218,+27365 Development,3807,+1275 Research,7283,+5001 Development,1700,-5316 Research,978,+13562 Development,3807,-158 Research,7283,+5002 Marketing,52,-8736 Development,5781,+2736 Marketing,52,+1603 Research,16072,-2022 Marketing 96218+27365 Development3807 +1275 Research 7283 +5001 Development1700 -5316 Research 978 +13562 Development3807 -158 Research 7283 +5002 Marketing 52 -8736 Development5781 +2736 Marketing 52 +1603 Research 16072-2022

154

z/OS V1R10.0 DFSORT Application Programming Guide

INREC Control Statement

Since the second fixed parsed field is unsigned and left-justified, we sort it with the UFF format. Since the third fixed parsed field is signed and left-justified, we sort it with the SFF format. After the SORT and OUTREC statements are processed, the output records look like this:
Development,1700,-5316 Development,3807,+1275 Development,3807,-158 Development,5781,+2736 Marketing,52,+1603 Marketing,52,-8736 Marketing,96218,+27365 Research,978,+13562 Research,7283,+5002 Research,7283,+5001 Research,16072,-2022

Example 9
INREC PARSE=(%00=(ENDBEFR=C,,FIXLEN=11), %01=(ENDBEFR=C,,FIXLEN=5), %02=(FIXLEN=6)), BUILD=(1,4,5:%00,16:%01,21:%02,27:5) SORT FIELDS=(5,11,CH,A,16,5,UFF,A,21,6,SFF,D) OUTREC BUILD=(1,4,27)

This example illustrates how you can sort VB input records with variable position/length fields, such as comma separated values. This example is very similar to the previous example for FB records, except that with VB records we need to copy the fixed parsed fields after the 4-byte RDW rather than at the end of the records. The VB input records might look like this:
Length|Data 26|Marketing,96218,+27365 26|Development,3807,+1275 23|Research,7283,+5001 26|Development,1700,-5316 23|Research,978,+13562 25|Development,3807,-158 23|Research,7283,+5002 22|Marketing,52,-8736 26|Development,5781,+2736 22|Marketing,52,+1603 24|Research,16072,-2022

After the INREC statement is processed, the records look like this:
Length|Data 48|Marketing 96218+27365Marketing,96218,+27365 48|Development3807 +1275 Development,3807,+1275 45|Research 7283 +5001 Research,7283,+5001 48|Development1700 -5316 Development,1700,-5316 45|Research 978 +13562Research,978,+13562 47|Development3807 -158 Development,3807,-158 45|Research 7283 +5002 Research,7283,+5002 44|Marketing 52 -8736 Marketing,52,-8736 48|Development5781 +2736 Development,5781,+2736 44|Marketing 52 +1603 Marketing,52,+1603 46|Research 16072-2022 Research,16072,-2022

After the SORT and OUTREC statements are processed, the output records look like this:
Chapter 3. Using DFSORT Program Control Statements

155

INREC Control Statement

Length|Data 26|Development,1700,-5316 26|Development,3807,+1275 25|Development,3807,-158 26|Development,5781,+2736 22|Marketing,52,+1603 22|Marketing,52,-8736 26|Marketing,96218,+27365 23|Research,978,+13562 23|Research,7283,+5002 23|Research,7283,+5001 24|Research,16072,-2022

MERGE Control Statement

|
MERGE FIELDS= (

, p,m,f,s , p,m, f, COPY )

, FORMAT=f

, , EQUALS NOEQUALS FILES=n FILSZ=x SIZE=y SKIPREC=z STOPAFT=n Y2PAST= s f

The MERGE control statement must be used when a merge operation is to be performed; this statement describes the control fields in the input records on which the input data sets have previously been sorted. A MERGE statement can also be used to specify a copy application. User labels will not be copied to the output data sets. You can merge up to 100 data sets with Blockset merge or up to 16 data sets with Conventional merge. If Blockset merge is not selected, you can use a SORTDIAG DD statement to force message ICE800I, which gives a code indicating why Blockset could not be used. The way in which DFSORT processes short MERGE control fields depends on the setting for VLSHRT/NOVLSHRT. A short field is one where the variable-length record is too short to contain the entire field, that is, the field extends beyond the

156

z/OS V1R10.0 DFSORT Application Programming Guide

MERGE Control Statement

record. For details about merging short records, see the discussion of the VLSHRT and NOVLSHRT options in OPTION Control Statement on page 167. The options available on the MERGE statement can be specified in other sources as well. A table showing all possible sources for these options and the order of override are given in Appendix B, Specification/Override of DFSORT Options, on page 741. When an option can be specified on either the MERGE or OPTION statement, it is preferable to specify it on the OPTION statement. DFSORT accepts but does not process the following MERGE operands: WORK=value and ORDER=value. DFSORTs collating behavior can be modified according to your cultural environment. The cultural environment is established by selecting the active locale. The active locales collating rules affect MERGE processing as follows: v DFSORT produces merged records for output according to the collating rules defined in the active locale. This provides merging for single- or multi-byte character data, based on defined collating rules that retain the cultural and local characteristics of a language. If locale processing is to be used, the active locale will only be used to process character (CH) control fields. For more information on locale processing, see Cultural Environment Considerations on page 7 or LOCALE in OPTION Control Statement on page 167. Note: For a merge application, records deleted during an E35 exit routine are not sequence checked. If you use an E35 exit routine without an output data set, sequence checking is not performed at the time the records are passed to the E35 user exit; therefore, you must ensure that input records are in correct sequence. FIELDS

, FIELDS= ( p,m,f,s )

Is written exactly the same way for a merge as it is for a sort. The meanings of p, m, f, and s are described in the discussion of the SORT statement. The defaults for this and the following parameters are also given there. See SORT Control Statement on page 398. | FIELDS=COPY

FIELDS=COPY

See the discussion of the COPY option on the OPTION statement, in OPTION Control Statement on page 167.
Chapter 3. Using DFSORT Program Control Statements

157

MERGE Control Statement

FORMAT=f

FORMAT=f

See the discussion of the FORMAT option in SORT Control Statement on page 398. Used the same way for a merge as for a sort. EQUALS or NOEQUALS

EQUALS NOEQUALS

See the discussion of these options on the OPTION statement, in OPTION Control Statement on page 167. FILES=n

FILES=n

Specifies the number of input files for a merge when input is supplied through the E32 exit. Default: None; must be specified when an E32 exit is used. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. FILSZ or SIZE

FILSZ=x SIZE=y

See the discussion of these options on the OPTION statement, in OPTION Control Statement on page 167. SKIPREC

SKIPREC=z

See the discussion of this option on the OPTION statement, in OPTION Control Statement on page 167.

158

z/OS V1R10.0 DFSORT Application Programming Guide

MERGE Control Statement

Note: SKIPREC is used for a copy or sort application, but is not used for a merge application. STOPAFT

STOPAFT=n

See the discussion of this option on the OPTION statement, in OPTION Control Statement on page 167. Note: STOPAFT is used for a copy or sort application, but is not used for a merge application. Y2PAST

Y2PAST=

s f

See the discussion of this option on the OPTION statement, in OPTION Control Statement on page 167. Note: CENTURY=value and CENTWIN=value can be used instead of Y2PAST=value.

Specifying a MERGE or COPYExamples

Example 1
MERGE FIELDS=(2,5,CH,A),FILSZ=29483

FIELDS The control field begins on byte 2 of each record in the input data sets. The field is 5 bytes long and contains character (EBCDIC) data that has been presorted in ascending order. FILSZ The input data sets contain exactly 29483 records.

Example 2
MERGE FIELDS=(3,8,ZD,E,40,6,CH,D)

FIELDS The major control field begins on byte 3 of each record, is 8 bytes long, and contains zoned decimal data that is modified by your routine before the merge examines it. The second control field begins on byte 40, is 6 bytes long, and contains character data in descending order.

Example 3
MERGE FIELDS=(25,4,A,48,8,A),FORMAT=ZD

Chapter 3. Using DFSORT Program Control Statements

159

MERGE Control Statement

FIELDS The major control field begins on byte 25 of each record, is 4 bytes long, and contains zoned decimal data that has been placed in ascending sequence. The second control field begins on byte 48, is 8 bytes long, is also in zoned decimal format, and is also in ascending sequence. The FORMAT parameter is used to indicate that both fields have ZD format.

Example 4
MERGE FIELDS=COPY

FIELDS The input data set is copied to output. No merge takes place.

MODS Control Statement

, MODS exit= ( n,m , s ,e ) HILEVEL=YES

The MODS statement is needed only when DFSORT passes control to your routines at user exits. The MODS statement associates user routines with specific DFSORT exits and provides DFSORT with descriptions of these routines. For details about DFSORT user exits and how user routines can be used, see Chapter 4, Using Your Own User Exit Routines, on page 413. To use one of the user exits, you substitute its three-character name (for example, E31) for the word exit in the MODS statement format above. You can specify any valid user exit, except E32. (E32 can be used only in a merge operation invoked from a program; its address must be passed in a parameter list.) exit

exit= ( n,m , s ,e

The values that follow the exit parameter describe the user routine. These values are: n specifies the name of your routine (member name if your routine is in a library). You can use any valid operating system name for your routine. This allows you to keep several alternative routines with different names in the same library.

m specifies the number of bytes of main storage your routine uses.Include storage obtained (via GETMAIN) by your routine (or, for example, by OPEN) and the storage required to load the COBOL library subroutines.

160

z/OS V1R10.0 DFSORT Application Programming Guide

MODS Control Statement

s specifies either the name of the DD statement in your DFSORT job step that defines the library in which your routine is located or SYSIN if your routine is in the input stream. SYSIN is not valid for copy processing. If a value is not specified for s, DFSORT uses the following search order to find the library in which your routine is located: 1. The libraries identified by the STEPLIB DD statement 2. The libraries identified by the JOBLIB DD statement (if there is no STEPLIB DD statement) 3. The link library. e specifies the linkage editor requirements of your routine or indicates that your routine is written in COBOL. The following values are allowed: N specifies that your routine has already been link-edited and can be used in the DFSORT run without further link-editing. This is the default for e. N (specified or defaulted) can be overridden by the EXEC PARM parameters E15=COB and E35=COB or by the HILEVEL=YES parameter. C specifies that your E15 or E35 routine is written in COBOL. If you code C for any other exit, it is ignored, and N is assumed. Your COBOL-written routine must already have been link-edited. The COBEXIT option of the OPTION statement specifies the library for the COBOL exits. specifies that your routine must be link-edited together with other routines to be used in the same phase (for example, E1n routines) of DFSORT. See Dynamically Link-Editing User Exit Routines on page 423 for additional information. This value is not valid for copy processing. specifies that your routine requires link-editing but that it must be link-edited separately from the other routines (for example, E3n routines) to be used in a particular phase of DFSORT. E11 and E31 exit routines are the only routines eligible for separate link-editing. See Dynamically Link-Editing User Exit Routines on page 423 for additional information. This value is not valid for copy processing.

If you do not specify a value for e, N is assumed. HILEVEL=YES

HILEVEL=YES

specifies that: v if an E15 routine is identified on the MODS statement, it is written in COBOL v if an E35 routine is identified on the MODS statement, it is written in COBOL. If you identify an E15 routine and an E35 routine on the MODS statement, specify HILEVEL=YES only if both routines are written in COBOL. If you do not identify an E15 or E35 routine on the MODS statement, HILEVEL=YES is ignored. Note: COBOL=YES can be used instead of HILEVEL=YES.

Chapter 3. Using DFSORT Program Control Statements

161

MODS Control Statement

Notes: 1. The s parameter must be the same or omitted for each routine with N or C for the e parameter (library concatenation is allowed). These routines cannot be placed in SYSIN. Each such routine must be a load module. 2. Each routine for which T or S is specified for the e parameter can be placed in any library or in SYSIN; they do not all have to be in the same library or SYSIN (but can be). Some routines can even be in different libraries (or the same library) and the rest can be in SYSIN. Each such routine, if in a library, can be either an object deck or a load module; if in SYSIN, it must be an object deck. 3. If the same routine is used in both input (that is, E1n routines) and output (that is, E3n routines) DFSORT program phases, a separate copy of the routine must be provided for each exit. 4. HILEVEL=YES can be used instead of C as the fourth parameter, to indicate that an E15 or E35 routine is written in COBOL. In this case, if T is specified as the fourth parameter for E15 or E35, DFSORT terminates. If you identify an E15 routine and an E35 routine on the MODS statement, specify HILEVEL=YES only if both routines are written in COBOL. 5. EXEC PARM parameter E15=COB can be used instead of C as the fourth parameter, to indicate that an E15 is written in COBOL. In this case, if T is specified as the fourth parameter for E15, DFSORT terminates. 6. EXEC PARM parameter E35=COB can be used instead of C as the fourth parameter, to indicate that an E35 is written in COBOL. In this case, if T is specified as the fourth parameter for E35, DFSORT terminates. 7. If HILEVEL=YES, E15=COB, or E35=COB is used instead of C as the fourth parameter, to indicate that an exit is written in COBOL, the fourth parameter for that exit must be specified as N or not specified. 8. If a COBOL E15 or E35 is specified for a conventional merge or tape work data set sort, DFSORT terminates. 9. exit=(n,m) can be used to omit both the s and e parameters. 10. exit=(n,m,,e) can be used to omit the s parameter, but not the parameter. 11. The s parameter must be specified for a conventional merge or tape work data set sort, or when S or T is specified for the e parameter. Default: None; must be specified if you use exit routines. N is the default for the fourth parameter. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. For information on user exit routines in SYSIN, see System DD Statements on page 64. For details on how to design your routines, refer to Summary of Rules for User Exit Routines on page 420. When you are preparing your MODS statement,remember that DFSORT must know the amount of main storage your routine needs so that it can allocate main storage properly for its own use. If you do not know the exact number of bytes your program requires (including requirements for system services), make a slightly high estimate. The value of m in the MODS statement is written the same way whether it is an exact figure or an estimate: you do not precede the value by E for an estimate.

162

z/OS V1R10.0 DFSORT Application Programming Guide

MODS Control Statement

Identifying User Exit RoutinesExamples

Example 1
MODS E15=(ADDREC,552,MODLIB),E35=(ALTREC,11032,MODLIB)

E15 At exit E15, DFSORT transfers control to your own routine. Your routine is in the library defined by a job control statement with the ddname MODLIB. Its member name is ADDREC and uses 552 bytes. E35 At exit E35, DFSORT transfers control to your routine. Your routine is in the library defined by the job control statement with the ddname MODLIB. Its member name is ALTREC and will use 11032 bytes.

Example 2
MODS E15=(COBOLE15,7000,,C), E35=(COBOLE35,7000,EXITC,C)

E15 At exit E15, DFSORT transfers control to your own routine. Your routine is written in COBOL and is in the STEPLIB/JOBLIB or link libraries. Its member name is COBOLE15 and it uses 7000 bytes. E35 At exit E35, DFSORT transfers control to your routine. Your routine is written in COBOL and is in the library defined by the job control statement with the ddname EXITC. Its member name is COBOLE35 and it uses 7000 bytes.

OMIT Control Statement

OMIT COND=

(logical expression) FORMAT=f ALL NONE

Use an OMIT statement if you do not want all of the input records to appear in the output data sets. The OMIT statement selects the records you do not want to include. You can specify either an INCLUDE statement or an OMIT statement in the same DFSORT run, but not both. The way in which DFSORT processes short INCLUDE/OMIT compare fields depends on the settings for VLSCMP/NOVLSCMP and VLSHRT/NOVLSHRT. A short field is one where the variable-length record is too short to contain the entire field, that is, the field extends beyond the record. For details about including or omitting short records, see the discussion of the VLSCMP and NOVLSCMP options in OPTION Control Statement on page 167. A logical expression is one or more relational conditions logically combined, based on fields in the input record, and can be represented at a high level as follows:

Chapter 3. Using DFSORT Program Control Statements

163

OMIT Control Statement

relational condition1 . , AND OR ,relational condition2

If the logical expression is true for a given record, the record is omitted from the output data set. Five types of relational conditions can be used as follows: 1. Comparisons: Compare two compare fields or a compare field and a decimal, hexadecimal, character or current, future, or past date constant. For example, you can compare the first 6 bytes of each record with its last 6 bytes, and omit those records in which those fields are identical. Or you can compare a date field with todays date, yesterdays date, or tomorrows date and omit those records accordingly. 2. Substring Comparison Tests: Search for a constant within a field value or a field value within a constant. For example, you can search the value in a 6-byte field for the character constant COK, and omit those records for which COK is found somewhere in the field. Or you can search the character constant CJ69,L92,J82 for the value in a 3-byte field, and omit those records for which CJ69, CL92, or CJ82 appears in the field. 3. Bit Logic Tests: Test the state (on or off) of selected bits in a binary field using a bit or hexadecimal mask or a bit constant. For example, you can omit those records which have bits 0 and 2 on in a 1-byte field. Or you can omit those records which have bits 3 and 12 on and bits 6 and 8 off in a 2-byte field. 4. Date Comparisons: Compare a two-digit year date field to a two-digit year date constant, the current two-digit year date or another two-digit year date field, using the century window in effect. For example, you can omit only those records for which a Zyymm date field is between January 1996 and March 2005. Or you can omit only those records for which a Pdddyy field is less than another Pdddyy field. 5. Numeric Tests: Test a field for numerics or non-numerics in character, zoned decimal, or packed decimal format. For example, you can omit only those records in which a 5-byte field contains only 0-9 characters (that is, numerics). Or you can omit only those records in which a 9-byte field contains invalid ZD numeric data (that is, non-numerics). Or you can omit only those records in which a 12-byte field contains valid PD numeric data (that is, numerics). For complete details on the parameters of the OMIT control statement, see INCLUDE Control Statement on page 98.

164

z/OS V1R10.0 DFSORT Application Programming Guide

OMIT Control Statement

The OMIT control statement differs from the OMIT parameter of the OUTFIL statement in the following ways: v The OMIT statement applies to all input records; the OMIT parameter applies only to the OUTFIL input records for its OUTFIL group. v FORMAT=f can be specified with the OMIT statement but not with the OMIT parameter. Thus, you can use FORMAT=f and p,m or p,m,f fields with the OMIT statement, but you must only use p,m,f fields with the OMIT parameter. For example:
OMIT FORMAT=BI, COND=(5,4,LT,11,4,OR,21,4,EQ,31,4,OR, 61,20,SS,EQ,CFLY) OUTFIL OMIT=(5,4,BI,LT,11,4,BI,OR,21,4,BI,EQ,31,4,BI,OR, 61,20,SS,EQ,CFLY)

v D2 format can be specified with the OMIT statement but not with the OMIT parameter. See OUTFIL Control Statements on page 221 for more details on the OUTFIL OMIT parameter. COND

COND=

(logical expression) ALL NONE

logical expression

specifies one or more relational conditions logically combined, based on fields in the input record. If the logical expression is true for a given record, the record is omitted from the output data sets. specifies that all of the input records are to be omitted from the output data sets. specifies that none of the input records are to be omitted from the output data sets.

| |

ALL NONE

Default: NONE. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. FORMAT

FORMAT=f

For details on this parameter, see INCLUDE Control Statement on page 98.

Chapter 3. Using DFSORT Program Control Statements

165

OMIT Control Statement

Omitting Records from the Output Data SetExample

Example
OMIT COND=(27,1,CH,EQ,CD,&, (22,2,BI,SOME,XC008,|, 28,1,BI,EQ,B.1....01))

This statement omits records in which: v Byte 27 contains D AND v Bytes 22 through 23 have some, but not all of bits 0, 1 and 12 on OR byte 28 is equal to the specified pattern of bit 1 on, bit 6 off and bit 7 on. Note that the AND and OR operators can be written with the AND and OR signs, and that parentheses are used to change the order in which AND and OR are evaluated. For additional examples of logical expressions, see INCLUDE Control Statement on page 98.

166

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

OPTION Control Statement

|
OPTION

, ARESALL= n nK nM n nK nM

ARESINV=

AVGRLEN=n CHALT NOCHALT CHECK NOCHECK CINV NOCINV CKPT COBEXIT= COPY DSA=n DSPSIZE= DYNALLOC

COB1 COB2

MAX n = d (,n) (d,n) OFF

DYNSPC=n EFS= name NONE EQUALS NOEQUALS EXITCK= STRONG WEAK FILSZ= x Ex Ux SIZE= y Ey Uy HIPRMAX= OPTIMAL n p% LIST NOLIST LISTX NOLISTX LOCALE= name CURRENT NONE

Figure 12. Syntax Diagram for the Option Control Statement (Part 1 of 3)

Chapter 3. Using DFSORT Program Control Statements

167

OPTION Control Statement

MAINSIZE=

n nK nM MAX MOSIZE= MAX n p% MSGDDN=ddname MSGPRT= ALL NONE CRITICAL NOBLKSET NOOUTREL NOOUTSEC NULLOUT= RC0 RC4 RC16 ODMAXBF= n nK nM OVFLO= RC0 RC4 RC16 PAD= RC0 RC4 RC16 RESALL= n nK nM RESET NORESET RESINV= n nK nM SDB= LARGE YES INPUT NO SKIPREC=z SMF= SHORT FULL NO SOLRF NOSOLRF SORTDD=cccc SORTIN=ddname SORTOUT=ddname SPANINC= RC0 RC4 RC16

Figure 12. Syntax Diagram for the Option Control Statement (Part 2 of 3)

168

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

STOPAFT=n SZERO NOSZERO TRUNC= RC0 RC4 RC16 USEWKDD VERIFY NOVERIFY VLLONG NOVLLONG VLSCMP NOVLSCMP VLSHRT NOVLSHRT VSAMEMT NVSAMEMT VSAMIO NOVSAMIO WRKREL NOWRKREL WRKSEC NOWRKSEC Y2PAST= s f ZDPRINT NZDPRINT

Figure 12. Syntax Diagram for the Option Control Statement (Part 3 of 3)

Note for Syntax Diagram: The keywords EFS, LIST, NOLIST, LISTX, NOLISTX, MSGDDN, MSGPRT, SMF, SORTDD, SORTIN, SORTOUT, and USEWKDD are used only when they are specified on the OPTION control statement passed by an extended parameter list or when specified in the DFSPARM data set. If they are specified on an OPTION statement read from the SYSIN or SORTCNTL data set, the keyword is recognized, but the parameters are ignored. The OPTION control statement allows you to override some of the options available at installation time (such as EQUALS and CHECK) and to supply other optional information (such as DYNALLOC, COPY, and SKIPREC). Some of the options available on the OPTION statement are also available on the SORT or MERGE statement (such as FILSZ and SIZE). It is preferable to specify these options on the OPTION statement. For override rules, see Appendix B, Specification/Override of DFSORT Options, on page 741. Details of aliases for OPTION statement options are given under the description of individual options. Table 34 on page 217 summarizes the available aliases. DFSORT accepts but does not process the following OPTION operands: ALGQ, APP, APPEND, BIAS=value, BLKSET, CASCADE, DIAG, ERASE, EXCPVR=value,

Chapter 3. Using DFSORT Program Control Statements

169

OPTION Control Statement

| | MAXPFIX=value, NEW, NEWFILE, NODIAG, NOERASE, NOINC, NOSTIMER, NOSWAP, OPT=value, REP, REPLACE, ROUTE=value, WRKADR=value, WRKDEV=value, and WRKSIZ=value. ARESALL

ARESALL=

n nK nM

Temporarily overrides the ARESALL installation option, which specifies the number of bytes to be reserved above virtual for system use. ARESALL applies only to the amount of main storage above virtual. This option is normally not needed because of the large amount of storage available above 16MB virtual (the default for ARESALL is 0 bytes). The RESALL option applies to the amount of main storage below 16MB virtual. n specifies that n bytes of storage are to be reserved. Limit: 8 digits. nK specifies that n times 1024 bytes of storage are to be reserved. Limit: 5 digits. nM specifies that n times 1048576 bytes of storage are to be reserved. Limit: 2 digits. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: SeeAppendix B, Specification/Override of DFSORT Options, on page 741. ARESINV

ARESINV=

n nK nM

Temporarily overrides the ARESINV installation option, which specifies the number of bytes to be reserved for an invoking programs user exits that reside in or use space above 16MB virtual. The reserved space is not meant to be used for the invoking programs executable code. ARESINV is used only when DFSORT is dynamically invoked. ARESINV applies only to the amount of main storage above 16MB virtual. The RESINV option applies to the amount of main storage below 16MB virtual. n specifies that n bytes of storage are to be reserved. Limit: 8 digits. nK specifies that n times 1024 bytes of storage are to be reserved.

170

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

Limit: 5 digits. nM specifies that n times 1048576 bytes of storage are to be reserved. Limit: 2 digits. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. AVGRLEN

AVGRLEN=n

Specifies the average input record length in bytes for variable-length record sort applications. This value is used when necessary to determine the input file size. The resulting value is important for sort applications, because it is used for several internal optimizations as well as for dynamic work data set allocation (see OPTION DYNALLOC). See Specify Input/Output Data Set Characteristics Accurately on page 683 and Allocation of Work Data Sets on page 733 for more information on file size considerations. n specifies the average input record length. n must be between 4 and 32767 and must include the 4-byte record descriptor word (RDW).

Notes: 1. AVGRLEN=n on the OPTION statement overrides the L5 value on the RECORD statement (LENGTH operand) if both are specified. The L5 value on the RECORD statement is ignored for Blockset. 2. L5=n can be used instead of AVGRLEN=n. Default: If AVGRLEN=n is not specified, DFSORT uses one-half of the maximum record length as the average record length. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. CHALT or NOCHALT

CHALT NOCHALT

Temporarily overrides the CHALT installation option, which specifies whether format CH fields are translated by the alternate collating sequence as well as format AQ or just the latter. CHALT specifies that DFSORT translates character control fields and compare fields with formats CH and AQ using the alternate collating sequence.
Chapter 3. Using DFSORT Program Control Statements

171

OPTION Control Statement

NOCHALT specifies that format CH fields are not translated. Note: If you use locale processing for SORT, MERGE, INCLUDE, or OMIT fields, you must not use CHALT. If you need alternate sequence processing for a particular field, use format AQ. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. CHECK or NOCHECK

CHECK NOCHECK

Temporarily overrides the CHECK installation option, which specifies whether the record count should be checked for applications that use the E35 user exit routine without an output data set. CHECK specifies that the record count should be checked. NOCHECK specifies that the record count should not be checked. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: SeeAppendix B, Specification/Override of DFSORT Options, on page 741. CINV or NOCINV

CINV NOCINV

Temporarily overrides the CINV installation option, which specifies whether DFSORT can use control interval access for VSAM data sets. The Blockset technique uses control interval access for VSAM input data sets, when possible, to improve performance. CINV specifies that DFSORT should use control interval access when possible for VSAM data sets. NOCINV specifies that DFSORT should not use control interval access. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details.

172

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. CKPT

CKPT

Activates the Checkpoint/Restart facility for sorts that use the Peerage or Vale techniques. Because CKPT is only supported in the Peerage and Vale techniques, the Blockset technique must be bypassed for the Checkpoint/Restart facility to be used. Installation option IGNCKPT=NO causes Blockset to be bypassed when CKPT is specified at run-time. The NOBLKSET option can also be used to bypass Blockset at run-time. A SORTCKPT DD statement must be coded when you use the Checkpoint/Restart facility (see SORTCKPT DD Statement on page 76). Notes: 1. CHKPT can be used instead of CKPT. 2. Functions such as OUTFIL processing, which are supported only by the Blockset technique, cannot be used if the Checkpoint/Restart facility is used. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. COBEXIT

COBEXIT

COB1 COB2

Temporarily overrides the COBEXIT installation option, which specifies the library for COBOL E15 and E35 routines. COB1 specifies that COBOL E15 and E35 routines are run with the OS/VS COBOL run-time library or, in some cases, with no COBOL run-time library. COBEXIT=COB1 is obsolete, but is still available for compatibility reasons. Note that Language Environment is the only run-time library for COBOL supported by IBM service. COB2 specifies that COBOL E15 and E35 routines are run with either the VS COBOL II run-time library or the Language Environment run-time library. Note that Language Environment is the only run-time library for COBOL supported by IBM service.
Chapter 3. Using DFSORT Program Control Statements

173

OPTION Control Statement

Note: The DFSORT documents only discuss the Language Environment run-time library, and assume that COBEXIT=COB2 is in effect. Although it is possible to run with older run-time libraries, and with COBEXIT=COB1, these are not recommended or discussed, and are not supported by IBM service. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. COPY

COPY

Causes DFSORT to copy a SORTIN data set or inserted records to the output data sets unless all records are disposed of by an E35 exit routine. Records can be edited by E15 and E35 exit routines; INCLUDE/OMIT, INREC, OUTREC, and OUTFIL statements; and SKIPREC and STOPAFT parameters. E35 is entered after each SORTIN or E15 record is copied. The following must not be used in copy applications: v BDAM data sets v Dynamic link-editing. See message ICE160A in z/OS DFSORT Messages, Codes and Diagnosis Guide for additional restrictions that apply to copy applications. Note: User labels will not be copied to the output data sets. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. DSA

DSA=n

Temporarily overrides the DSA installation option, which specifies the maximum amount of storage available to DFSORT for dynamic storage adjustment of a Blockset sort application when SIZE/MAINSIZE=MAX is in effect. If you specify a DSA value greater than the TMAXLIM value in effect, you allow DFSORT to use more storage than the TMAXLIM value if doing so should improve performance. The amount of storage DFSORT uses is subject to the DSA value as well as system limits such as region size. However, whereas DFSORT always tries to obtain as much storage as it can up to the TMAXLIM value, DFSORT only tries to obtain as much storage as needed to improve performance up to the DSA value. The performance improvement from dynamic storage adjustment usually provides a good tradeoff against the increased storage used by DFSORT. On

174

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

storage constrained systems, however, the DSA value should be set low enough to prevent unacceptable paging. n specifies that DFSORT can dynamically adjust storage to improve performance, subject to a limit of n MB. n must be a value between 0 and 2000. If n is less than or equal to the TMAXLIM value in effect, n is set to 0 to indicate that storage will not be dynamically adjusted.

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. DSPSIZE

DSPSIZE=

MAX n

Temporarily overrides the DSPSIZE installation option, which specifies the maximum amount of data space to be used with dataspace sorting. A data space is an area of contiguous virtual storage that is backed by real and auxiliary storage, whichever is necessary as determined by the system. Because DFSORT is able to sort large pieces of data using data space, CPU time and elapsed time are reduced. | | | | | | | | | | | | | | | | | | | | | | | | | | | Several factors can limit the amount of data space an application uses: v The IEFUSI exit can limit the total amount of Hiperspace, memory objects and data space available to an application. v DSPSIZE can limit the amount of data space available to an application, as detailed below. v Sufficient available storage must be present to back DFSORTs data spaces. Available storage is the storage used to back new data space data and consists of the following two types: 1. Free storage. This is storage not being used by any application. 2. Old storage. This is storage used by another application whose data has been unreferenced for a sufficiently long time so that the system considers it eligible to be paged out to auxiliary storage to make room for new data space data. The amount of available storage constantly changes, depending on current system activity. Consequently, DFSORT checks the amount of available central storage throughout a data space sorting run and switches from using a data space to using disk work data sets if the available central storage is too low. v Other concurrent Hipersorting, memory sorting and dataspace sorting applications further limit the amount of available storage. A dataspace sorting application knows the storage needs of every other Hipersorting, memory object sorting and dataspace sorting application on the system. A dataspace sorting application does not try to back its data space data with storage needed by another Hipersorting, memory object sorting or dataspace sorting application. This prevents overcommitment of storage resources if multiple large concurrent DFSORT applications start at similar times on the same system.
Chapter 3. Using DFSORT Program Control Statements

175

OPTION Control Statement

| | | | | | | | | | | v The installation options EXPMAX, EXPOLD, and EXPRES can also be used to further limit the amount of storage available to dataspace sorting applications. EXPMAX limits the total amount of available storage that can be used at any one time to back DFSORT Hiperspaces, memory objects and data spaces. EXPOLD limits the total amount of old storage that can be used at any one time to back DFSORT Hiperspaces, memory objects and data spaces. EXPRES sets aside a specified amount of available storage for use by non-Hipersorting, non-memory object sorting and non-dataspace sorting applications. Some of these limits depend on system and other DFSORT activity throughout the time a dataspace sorting application runs. Consequently, the amount of data space a dataspace sorting application uses can vary from run to run. If the amount of data space DFSORT decides to use is sufficient, DFSORT sorts your data in main storage and does not require additional temporary work space. If the amount of data space is not sufficient, DFSORT uses disk as temporary work space. Installation option DYNAUTO=NO is changed to DYNAUTO=YES whenever dataspace sorting is possible. Hiperspace is not used when dataspace sorting is used. MAX specifies that DFSORT dynamically determines the maximum amount of data space to be used for dataspace sorting. In this case, DFSORT bases its data space usage on the size of the file being sorted and the paging activity of the system. n specifies the maximum amount, in MB, of data space to be used for dataspace sorting. n must be a value between 0 and 9999. The actual amount of data space used does not exceed n, but may be less than n depending on the size of the file being sorted and the paging activity of the system. If n is zero, dataspace sorting is not used. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. DYNALLOC

DYNALLOC

d (,n) (d,n)

Assigns DFSORT the task of dynamically allocating needed work space. You do not need to calculate and use JCL to specify the amount of work space needed by the program. DFSORT uses the dynamic allocation facility of the operating system to allocate work space for you. Refer to Appendix A, Using Work Space, on page 731 for guidelines on the use of DYNALLOC. d specifies the device name. You can specify any IBM disk or tape device

176

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

supported by your operating system in the same way you would specify it in the JCL UNIT parameter. You can also specify a group name, such as DISK or SYSDA. For best performance, specify an emulated 3390-9 device (such as RAMAC) or another high-speed IBM disk device, and avoid specifying a tape, virtual (VIO), or real 3390-9 device. n specifies the maximum number of requested work data sets. If you specify more than 255, a maximum of 255 data sets is used. If you specify 1 and the Blockset technique is selected, a maximum of 2 data sets is used. If you specify more than 32 and the Blockset technique is not selected, a maximum of 32 data sets is used.

Tip: For optimum allocation of resources such as virtual storage, avoid specifying a large number of work data sets unnecessarily. For tape work data sets, the number of volumes specified (explicitly or by default) is allocated to the program. The program requests standard label tapes. | DYNALLOC is not used if SORTWKdd DD statements are provided unless installation option DYNAUTO=IGNWKDD is specified and OPTION USEWKDD is not in effect. If VIO=NO is in effect: v Work space can be allocated on nontemporary data sets (DSNAME parameter specified). v If the device (d) you specify is a virtual device and reallocation to a real device fails, DFSORT will ignore VIO=NO and use the virtual device. Note: Message ICE165I gives information about work data set allocation/use. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. v DYNALLOC can automatically be activated by using the DYNAUTO installation option. v If DYNALLOC is specified without d, the default for d is that specified (or defaulted) by the DYNALOC installation option v If DYNALLOC is specified without n, the default for n is that specified (or defaulted) by the DYNALOC installation option. You can specify DYNALLOC without n, without d, or without both. If DYNALLOC is specified without n, and the IBMsupplied default for the n value of the DYNALOC installation option is chosen, then: v If one of the Blockset techniques is chosen, four work data sets will be requested. v If a technique other than Blockset is chosen, three work data sets will be requested. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. DYNALLOC=OFF

| | | | | |

Chapter 3. Using DFSORT Program Control Statements

177

OPTION Control Statement

|
DYNALLOC=OFF

Directs DFSORT not to allocate work space dynamically, overriding that function of installation option DYNAUTO=YES, or DYNAUTO=IGNWKDD, or the run-time option DYNALLOC (without OFF). Use this option when you know that an in-core sort can be performed, and you want to suppress dynamic allocation of work space. OFF directs DFSORT not to allocate work space dynamically. Note: When Hipersorting or dataspace sorting is in effect, DFSORT uses dynamic allocation when necessary, even if DYNALLOC=OFF has been specified. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. DYNSPC

DYNSPC=n

DYNSPC=ntemporarily overrides the DYNSPC installation option, which specifies the total default primary space allocation for all of the dynamically allocated work data sets when the input file size is unknown. That is, when DFSORT cannot determine the input file size for a sort application and the number of records is not supplied by a FILSZ or SIZE value. Generally, DFSORT can automatically determine the input file size. However, in a few cases, such as when an E15 supplies all of the input records, when information about a tape data set is not available from a tape management system, or when Blockset is not selected, DFSORT cannot determine an accurate file size. In these cases, if the number of records is not supplied by the FILSZ or SIZE run-time option, and dynamic allocation of work data sets is used, DFSORT uses the DYNSPC value in effect as the approximate amount of primary space. DFSORT uses 20% of the primary space as secondary space. Although the primary space is always allocated, secondary space (up to 15 extents) is only allocated as needed. You may want to use DYNSPC to override the installation default with a larger or smaller value depending on the amount of disk space available for DFSORT work data sets, and the amount of data to be sorted for this application. As a guideline, Table 30 shows the approximate primary space in cylinders that is allocated on a 3390 when Blockset sorts an unknown number of 6000-byte records.
Table 30. Example of DYNSPC Primary Space DYNSPC value (megabytes) 32 Primary space (cylinders) 48

178

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

Table 30. Example of DYNSPC Primary Space (continued) DYNSPC value (megabytes) 64 128 256 512 Primary space (cylinders) 93 183 366 732

The larger your DYNSPC value, the more data DFSORT can sort when the file size is unknown. For example, in a test using just dynamically allocated work space (no Hiperspace or data space) with the primary space shown in Table 30 on page 178, and all of the corresponding secondary space, Blockset is able to sort approximately 150 megabytes with DYNSPC=32 and approximately 1200 megabytes with DYNSPC=256. If Hiperspace or data space can be used along with dynamically allocated work space, the amount of data DFSORT can sort will increase according to the amount of Hiperspace or data space available. n specifies the total default primary space, in megabytes, to be allocated for all dynamically allocated work data sets (n is not the primary space for each data set). n must be a value between 1 and 65535. Do not specify a value which exceeds the available disk space, because this causes dynamic allocation to fail for sort applications that use this value. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. EFS

EFS=

name NONE

Temporarily overrides the EFS installation option, which specifies whether DFSORT is to pass control to an Extended Function Support (EFS) program. See Chapter 8, Using Extended Function Support, on page 647 for more information. name specifies the name of the EFS program that will be called to interface with DFSORT. NONE specifies no call will be made to the EFS program. Notes: 1. EFS is processed only if it is passed on the OPTION control statement in an extended parameter list or in DFSPARM. 2. If you use locale processing for SORT, MERGE, INCLUDE, or OMIT fields, you must not use an EFS program. DFSORTs locale processing may eliminate the need for an EFS program. See the LOCALE option later in this section for information related to locale processing.

Chapter 3. Using DFSORT Program Control Statements

179

OPTION Control Statement

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. EQUALS or NOEQUALS

EQUALS NOEQUALS

Temporarily overrides the EQUALS installation option, which specifies whether the original sequence of records that collate identically for a sort or a merge should be preserved from input to output. EQUALS specifies that the original sequence must be preserved. NOEQUALS specifies that the original sequence need not be preserved. For sort applications, the sequence of the output records depends upon the order of: v The records from the SORTIN file v The records inserted by an E15 user exit routine v The E15 records inserted within input from SORTIN. For merge applications, the sequence of the output records depends upon the order of: v The records from a SORTINnn file. Records that collate identically are output in the order of their file increments. For example, records from SORTIN01 are output before any records that collate identically from SORTIN02. v The records from an E32 user exit routine for the same file increment number. Records that collate identically from E32 are output in the order of their file increments. For example, records from the file with increment 0 are output before any records that collate identically from the file with increment 4. Notes: 1. When EQUALS is in effect, the total number of bytes occupied by all control fields must not exceed 4088. 2. Using EQUALS can degrade performance. 3. When EQUALS is in effect with SUM, the first record of summed records is kept. When NOEQUALS is in effect with SUM, the record to be kept is unpredictable. If a technique other than Blockset is selected, NOEQUALS is forced if SUM is specified. 4. Do not specify EQUALS if variable-length records are sorted using tape work files and the RDW is part of the control field. 5. The number of records to be sorted cannot exceed 4294967295 (4 gigarecords minus 1); if the number of records exceeds this number, message ICE121A is issued and DFSORT terminates.

180

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options. EXITCK

EXITCK

STRONG WEAK

Temporarily overrides the EXITCK installation option, which specifies whether DFSORT terminates or continues when it receives certain invalid return codes from E15 or E35 user exit routines. For full details of the return codes affected by this parameter, see E15/E35 Return Codes and EXITCK on page 458. STRONG specifies that DFSORT issues an error message and terminates when it receives an invalid return code from an E15 or E35 user exit routine. WEAK specifies that DFSORT interprets certain invalid return codes from E15 and E35 user exit routines as valid and continues processing. Use of EXITCK=WEAK can make it difficult to detect errors in the logic of E15 and E35 user exit routines. Note: EXITCK=WEAK is treated like EXITCK=STRONG when: v Tape work data sets are specified for a sort application. v The Blockset technique is not selected for a merge application. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options. FILSZ or SIZE

FILSZ=

x Ex Ux y Ey Uy

SIZE=

The FILSZ parameter specifies either the exact number of records to be sorted or merged, or an estimate of the number of records to be sorted. The SIZE parameter specifies either the exact number of records in the input data sets, or an estimate of the number of records in the input data sets. The supplied record count is used by DFSORT for two purposes: 1. To check that the actual number of records sorted or merged or the number of records in the input data sets is equal to the exact number of records
Chapter 3. Using DFSORT Program Control Statements

181

OPTION Control Statement

expected. FILSZ=x or SIZE=y causes this check to be performed and results in termination with message ICE047A if the check fails. 2. To determine the input file size for a sort application. DFSORT performs calculations based on the user supplied record count and other parameters (such as AVGRLEN) to estimate the total number of bytes to be sorted. This value is important for sort runs, because it is used for several internal optimizations as well as for dynamic work data set allocation (see OPTION DYNALLOC). If no input record count (or only an estimate) is supplied for the sort run, DFSORT attempts to automatically compute the file size to be used for the optimizations and allocations. The type of FILSZ or SIZE value specified (x/y, Ux/Uy, Ex/Ey, or none) controls the way DFSORT performs the above two functions, and can have a significant effect on performance and work data set allocation. See Chapter 9, Improving Efficiency, on page 681 and File Size and Dynamic Allocation on page 734 for more information on file size considerations. x or y specifies the exact number of records to be sorted or merged (x) or the exact number of records in the input data sets (y). This value is always used for both the record check and the file size calculations. FILSZ=x or SIZE=y can be used to force DFSORT to perform file size calculations based on x or y, and to cause DFSORT to terminate the sort or merge application if x or y is not exact. | If installation option FSZEST=NO is in effect and either FILSZ=x or SIZE=y is specified, DFSORT terminates if the actual number of records is different from the specified exact value (x or y). In this case, the actual number of records is placed in the IN field of message ICE047A (or message ICE054I in some cases) before termination. However, if installation option FSZEST=YES is in effect, DFSORT treats FILSZ=x or SIZE=y like FILSZ=Ex or SIZE=Ey, respectively; it does not terminate when the actual number of records does not equal x or y. FILSZ=0 causes Hipersorting, dataspace sorting, and dynamic allocation of work space not to be used, and results in termination with message ICE047A unless the number of records sorted or merged is 0. If no E15 user exit is present, SIZE=0 has the same effect in terms of Hipersorting and dynamic allocation of work space, and results in termination with message ICE047A unless the number of records in the input data sets is 0. x specifies the exact number of records to be sorted or merged; it must take into account the number of records in the input data sets, records to be inserted or deleted by E15 or E32, and records to be deleted by the INCLUDE/OMIT statement, SKIPREC, and STOPAFT. x must be changed whenever the number of records to be sorted or merged changes in any way. specifies the exact number of records in the input data sets; it must take into account the number of records to be deleted by STOPAFT. y must be changed whenever the number of records in the input data sets changes in any way. Limit: 28 digits (15 significant digits) Ex or Ey specifies an estimate of the number of records to be sorted (x) or an estimate of the number of records in the input data sets (y). This value is not used for the record check. It is used for the file size calculations, but only if DFSORT could not reasonably estimate the input file size itself. In

182

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

all other cases, this value is ignored by DFSORT. See Dynamic Allocation of Work Data Sets on page 734 for details on exactly when an estimated record count is used and when it is ignored by DFSORT. FILSZ=E0 or SIZE=E0 is always ignored. x specifies an estimate of the number of records to be sorted; it should take into account the number of records in the input data sets, records to be inserted or deleted by E15, and records to be deleted by the INCLUDE/OMIT statement, SKIPREC, and STOPAFT. x should be changed whenever the number of records to be sorted changes significantly. specifies an estimate of the number of records in the input data sets; it should take into account the number of records to be deleted by STOPAFT. y should be changed whenever the number of records in the input data sets changes significantly. Limit: 28 digits (15 significant digits) Ux or Uy specifies the number of records to be sorted (x) or the number of records in the input data sets (y). This value is not used for the record check, but is always used for the file size calculations. FILSZ=Ux or SIZE=Uy can be used to force DFSORT to perform file size calculations based on x or y, while avoiding termination if x or y is not exact. The FSZEST installation option has no effect on FILSZ=Ux or SIZE=Uy processing. FILSZ=U0 causes Hipersorting, dataspace sorting, and dynamic allocation of work space not to be used, and may cause degraded performance or termination with message ICE046A, if the actual number of records to be sorted is significantly larger than 0. If no E15 user exit is present, SIZE=U0 has the same effect in terms of Hipersorting, dataspace sorting,and dynamic allocation of work space, and may cause degraded performance or termination with message ICE046A, if the actual number of records in the input data sets is significantly larger than 0. x specifies the number of records to be sorted; it should take into account the number of records in the input data sets, records to be inserted or deleted by E15, and records to be deleted by the INCLUDE/OMIT statement, SKIPREC, and STOPAFT. x should be changed whenever the number of records to be sorted changes significantly. specifies the number of records in the input data sets; it should take into account the number of records to be deleted by STOPAFT. y should be changed whenever the number of records in the input data sets changes significantly. Limit: 28 digits (15 significant digits) Table 31 summarizes the differences for the three FILSZ variations:
Table 31. FILSZ Variations Summary. FILSZ=n is equivalent to FILSZ=En if installation option FSZEST=YES is specified. Conditions Number of records Applications FILSZ=n Exact Sort, merge FILSZ=Un Estimate Sort FILSZ=En Estimate Sort

Chapter 3. Using DFSORT Program Control Statements

183

OPTION Control Statement

Table 31. FILSZ Variations Summary (continued). FILSZ=n is equivalent to FILSZ=En if installation option FSZEST=YES is specified. Conditions Terminate if n wrong? FILSZ=n Yes FILSZ=Un No Yes FILSZ=En No When DFSORT cannot compute file size

Use for file size calculation? Yes n includes records: In input data sets Inserted/deleted by E15 Inserted by E32 Deleted by INCLUDE/OMIT Deleted by SKIPREC Deleted by STOPAFT Update n when number of records changes: Effects of n=0 Yes Yes Yes Yes Yes Yes In any way Hipersorting and DYNALLOC not used

Yes Yes No Yes Yes Yes Significantly Hipersorting and DYNALLOC not used

Yes Yes No Yes Yes Yes Significantly None

Table 32 summarizes the differences for the three SIZE variations:

Table 32. SIZE Variations Summary. SIZE=n is equivalent to SIZE=En if installation option FSZEST=YES is specified. Conditions Number of records Applications Terminate if n wrong? SIZE=n Exact Sort, merge Yes SIZE=Un Estimate Sort No Yes SIZE=En Estimate Sort No When DFSORT cannot compute file size

Use for file size calculation? Yes n includes records: In input data sets Inserted/deleted by E15 Inserted by E32 Deleted by INCLUDE/OMIT Deleted by SKIPREC Deleted by STOPAFT Update n when number of records changes: Effects of n=0 Yes No No No No Yes In any way Hipersorting and DYNALLOC not used

Yes No No No No Yes Significantly Hipersorting and DYNALLOC not used

Yes No No No No Yes Significantly None

Attention: Using the SIZE or FILSZ parameter to supply inaccurate information to DFSORT can negatively affect DFSORT performance, and, when work space is dynamically allocated, can result in wasted disk space or termination with message ICE083A or ICE046A. Therefore, it is important to update the record count value whenever the number of records to be sorted changes significantly.

184

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. HIPRMAX

HIPRMAX=

OPTIMAL n p%

Temporarily overrides the HIPRMAX installation option, which specifies the maximum amount of Hiperspace to be used for Hipersorting. Hiperspace is a high-performance data space that resides in central storage and is backed by auxiliary storage (if necessary). Because I/O processing is reduced for Hipersorting, elapsed time, EXCP counts, and channel usage are also reduced. | | Several factors can limit the amount of Hiperspace an application uses: v The IEFUSI exit can limit the total amount of Hiperspace, memory objects and data space available to an application. v HIPRMAX can limit the amount of Hiperspace available to an application, as detailed below. v Sufficient available storage must be present to back DFSORTs Hiperspaces. Available storage is the storage used to back new Hiperspace data and consists of the following two types: 1. Free storage. This is storage not being used by any application. 2. Old storage. This is storage used by another application whose data has been unreferenced for a sufficiently long time so that the system considers it eligible to be paged out to auxiliary storage to make room for new Hiperspace data. The amount of available storage constantly changes, depending upon current system activity. Consequently, DFSORT checks the available storage level throughout a Hipersorting application and switches from Hiperspace to work data sets if the available storage level gets too low. v Other concurrent Hipersorting, memory sorting and dataspace sorting applications further limit the amount of available storage. A Hipersorting application knows the storage needs of every other Hipersorting, memory object sorting and dataspace sorting application on the system. A Hipersorting application does not try to back its Hiperspace data with storage needed by another Hipersorting, memory object sorting, or dataspace sorting application. This prevents overcommitment of storage resources if multiple large concurrent DFSORT applications start at similar times on the same system. v The installation options EXPMAX, EXPOLD, and EXPRES can also be used to further limit the amount of storage available to Hipersorting applications. EXPMAX limits the total amount of available storage that can be used at any one time to back DFSORT Hiperspaces, memory objects and data spaces. EXPOLD limits the total amount of old storage that can be used at any one time to back DFSORT Hiperspaces, memory objects and data spaces.

| | | |

| | | | | | | | | | | | | | |

Chapter 3. Using DFSORT Program Control Statements

185

OPTION Control Statement

| | | | EXPRES sets aside a specified amount of available storage for use by non-Hipersorting, non-memory object sorting, and non-dataspace sorting applications. Some of these limits depend on system and other DFSORT activity throughout the time a Hipersorting application runs. Consequently, the amount of Hiperspace a Hipersorting application uses can vary from run to run. HIPRMAX=n specifies a fixed value for HIPRMAX. HIPRMAX=p% specifies a value for HIPRMAX that varies as a percentage of an appropriate portion of central storage. If the storage on a system changes, HIPRMAX=p% will cause a corresponding change in the HIPRMAX value selected by DFSORT, whereas HIPRMAX=n will not. When sharing DFSORT installation options between systems, such as in a sysplex, HIPRMAX=p% can be used to tailor the HIPRMAX value to the system selected for the application, providing a more dynamic HIPRMAX value than HIPRMAX=n. If the amount of Hiperspace available for Hipersorting is insufficient for temporary storage of the records, intermediate disk storage is used along with Hiperspace. If the amount of Hiperspace is too small to improve performance, Hipersorting is not used. DYNAUTO=NO is changed to DYNAUTO=YES for Hipersorting. | | Hipersorting can cause a small CPU time increase. When CPU optimization is a concern, you can use HIPRMAX=0 to suppress Hipersorting. Note: HIPRLIM=OPTIMAL can be used instead of HIPRMAX=OPTIMAL. HIPRLIM=m can be used instead of HIPRMAX=n. HIPRLIM=m specifies a Hiperspace limit of m times 4096 bytes rounded up to the nearest megabyte. m must be a value between 0 and 2559744. If m is 0, Hipersorting is not used. OPTIMAL specifies that DFSORT determines dynamically the maximum amount of Hiperspace to be used for Hipersorting. n specifies that DFSORT determines dynamically the maximum amount of Hiperspace to be used for Hipersorting, subject to a limit of nMB. n must be a value between 0 and 32767. If n is 0, Hipersorting is not used. specifies that DFSORT determines dynamically the maximum amount of hiperspace to be used for Hipersorting, subject to a limit of p percent of an appropriate portion of central storage. p must be a value between 0 and 100. If p is 0, Hipersorting is not used. The value calculated for p% is limited to 32767MB, and is rounded down to the nearest MB.

p%

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. LIST or NOLIST

186

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

LIST NOLIST

Temporarily overrides the LIST installation option, which specifies whether DFSORT program control statements should be written to the message data set. See z/OS DFSORT Messages, Codes and Diagnosis Guide for details on use of the message data set. LIST specifies that DFSORT control statements are printed to the message data set. NOLIST specifies that DFSORT control statements are not printed to the message data set. Note: LIST or NOLIST are processed only if they are passed on the OPTION control statement in an extended parameter list or in DFSPARM. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. LISTX or NOLISTX

LISTX NOLISTX

Temporarily overrides the LISTX installation option, which specifies whether DFSORT writes to the message data set program control statements that are returned by an EFS program. See z/OS DFSORT Messages, Codes and Diagnosis Guide for details on use of the message data set. LISTX specifies that control statements returned by an EFS program are printed to the message data set. NOLISTX specifies that control statements returned by an EFS program are not printed to the message data set. Notes: 1. LISTX or NOLISTX are processed only if they are passed on the OPTION control statement in an extended parameter list or in DFSPARM. 2. If EFS=NONE is in effect after final override rules have been applied, NOLISTX is in effect. 3. LISTX and NOLISTX can be used independently of LIST and NOLIST. 4. For more information on printing EFS control statements, see z/OS DFSORT Messages, Codes and Diagnosis Guide

Chapter 3. Using DFSORT Program Control Statements

187

OPTION Control Statement

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. LOCALE

LOCALE=

name CURRENT NONE

Temporarily overrides the LOCALE installation option, which specifies whether locale processing is to be used and, if so, designates the active locale. DFSORTs collating behavior can be modified according to your cultural environment. Your cultural environment is defined to DFSORT using the X/Open locale model. A locale is a collection of data grouped into categories that describes the information about your cultural environment. The collate category of a locale is a collection of sequence declarations that defines the relative order between collating elements (single character and multi-character collating elements). The sequence declarations define the collating rules. If locale processing is to be used, the active locale will affect the behavior of DFSORTs SORT, MERGE, INCLUDE, and OMIT functions. For SORT and MERGE, the active locale will only be used to process character (CH) control fields. For INCLUDE and OMIT, the active locale will only be used to process character (CH) compare fields, and character and hexadecimal constants compared to character (CH) compare fields. Note: Locale processing is not used for IFTHEN WHEN constants or compare fields. name specifies that locale processing is to be used and designates the name of the locale to be made active during DFSORT processing. The locales are designated using a descriptive name. For example, to set the active locale to represent the French language and the cultural conventions of Canada, specify LOCALE=FR_CA. You can specify up to 32 characters for the descriptive locale name. The locale names themselves are not case-sensitive. See Using Locales for complete locale naming conventions. You can use IBM-supplied and user-defined locales. The state of the active locale prior to DFSORT being entered will be restored on DFSORTs completion. CURRENT specifies that locale processing is to be used, and the current locale active when DFSORT is entered will remain the active locale during DFSORT processing.

188

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

NONE specifies that locale processing is not to be used. DFSORT will use the binary encoding of the code page defined for your data for collating and comparing.

Notes: 1. LOCALE is processed only if it is passed on the OPTION control statement in an extended parameter list or in DFSPARM. 2. To use an IBM-supplied locale, DFSORT must have access to the Language Environment run-time library. For example, this library might be called SYS1.SCEERUN. If you are unsure of the name of this library at your location, contact your system administrator. To use a user-defined locale, DFSORT must have access to the load library containing it. 3. If you use locale processing for SORT, MERGE, INCLUDE, or OMIT fields: v VLSHRT is not used for SORT or MERGE v INREC or an E61 user exit must not be usedfor SORT or MERGE. v CHALT or an EFS program must not be used. 4. Locale processing is not used for IFTHEN WHEN constants or compare fields. 5. Locale processing for DFSORTs SORT, MERGE, INCLUDE, and OMIT functions can improve performance relative to applications that must perform pre-processing or post-processing of data to produce the desired collating results. However, locale processing should be used only when required, because it can show degraded performance relative to collating, using character encoding values. 6. DFSORT locale processing may require an additional amount of storage that depends on the environment supporting the locale as well as the locale itself. It may be necessary to specify a REGION of several MB or more for DFSORT applications that use locale processing. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions:; See Appendix B, Specification/Override of DFSORT Options, on page 741. MAINSIZE

MAINSIZE=

n nK nM MAX

| |

Temporarily overrides the SIZE installation option, which specifies the amount of main storage available to DFSORT. MAINSIZE applies to the total amount of main storage above and below 16MB virtual. DFSORT determines how much storage to allocate above and below 16MB virtual, but the total amount of storage cannot exceed MAINSIZE. Storage used for OUTFIL processing will be adjusted automatically, depending upon several factors, including: v Total available storage v Non-OUTFIL processing storage requirements
Chapter 3. Using DFSORT Program Control Statements

189

OPTION Control Statement

v Number of OUTFIL data sets and their attributes (for example, block size). OUTFIL processing is subject to the ODMAXBF limit and your system storage limits (for example, IEFUSI) but not to DFSORT storage limits, that is, SIZE/MAINSIZE, MAXLIM, and TMAXLIM. DFSORT attempts to use storage above 16MB virtual for OUTFIL processing whenever possible. For details on main storage allocation, see Tuning Main Storage on page 689. n specifies that n bytes of storage are to be allocated. If you specify more that 2097152000, 2097152000 is used. Limit: 10 digits nK specifies that n times 1024 bytes of storage are to be allocated. If you specify more than 2048000K, 2048000K is used. Limit: 7 digits nM specifies that n times 1048576 bytes of storage are to be allocated. If you specify more than 2000M, 2000M is used. Limit: 4 digits. MAX instructs DFSORT to calculate the amount of virtual storage available and allocate an amount of storage up to the TMAXLIM or DSA value when Blockset is selected, or up to the MAXLIM value when Blockset is not selected. Note: CORE=value can be used instead of MAINSIZE=value. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. MOSIZE

MOSIZE=

MAX n p%

| |

Temporarily overrides the MOSIZE installation option, which specifies the maximum size of a memory object to be used for memory object sorting in 64-bit virtual storage. A memory object is a data area in virtual storage that is allocated above the bar and backed by central storage. Because I/O processing is reduced for memory object sorting, elapsed time, EXCP counts, and channel usage are also reduced. Note: The bar refers to the 2-gigabyte address within the 64-bit address space. The bar separates storage below the 2-gigabyte address called below the bar, from storage above the 2-gigabyte address called above the bar. Several factors can limit the size of a memory object an application uses:

190

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

1. The MEMLIMIT parameter on the JOB or EXEC JCL statement can limit the total number of usable virtual pages above the bar in a single address space. 2. In addition to limiting the total amount of Hiperspace and data space available to an application, the IEFUSI exit can also limit the total number of usable virtual pages above the bar in a single address space. 3. MOSIZE can limit the size of a memory object available to an application, as detailed below. 4. Sufficient available central storage must be present to back DFSORTs memory object. The amount of available central storage constantly changes, depending on current system activity. Consequently, DFSORT checks the amount of available central storage throughout a memory object sorting run and switches from using a memory object to using disk work data sets if the available central storage is too low. 5. Other concurrent Hipersorting, memory object sorting, and dataspace sorting applications further limit the amount of available storage. A memory object sorting application is aware of the storage needs of every other Hipersorting, memory object sorting, and dataspace sorting application on the system, and does not attempt to back its memory object with storage needed by another Hipersorting, memory object sorting, or dataspace sorting application. This prevents overcommitment of storage resources in the event of multiple large concurrent DFSORT applications starting at similar times on the same system. 6. The installation options EXPMAX, EXPOLD, and EXPRES can also be used to further limit the amount of storage available to memory object sorting applications. EXPMAX limits the total amount of available storage that can be used at any one time to back DFSORT Hiperspaces, memory objects, and data spaces. EXPOLD limits the total amount of old storage that can be used at any one time to back DFSORT Hiperspaces, memory objects, and data spaces. EXPRES sets aside a specified amount of available storage for use by non-Hipersorting, non-memory object sorting, and non-dataspace sorting applications. Some of these limits depend on system, and other Hipersorting, memory object sorting, and dataspace sorting activity throughout the time a memory object sorting application runs. Consequently, the size of a memory object a memory object sorting application uses can vary from run to run. MOSIZE=n specifies a fixed value for MOSIZE. MOSIZE=p% specifies a value for MOSIZE that varies as a percentage of the available central storage on the system at run-time. If the available central storage on a system changes, MOSIZE=p% will cause a corresponding change in the MOSIZE value selected by DFSORT, whereas MOSIZE=n will not. When sharing DFSORT installation options between systems, such as in a sysplex, MOSIZE=p% can be used to tailor the MOSIZE value to the system selected for the application, providing a more dynamic MOSIZE value than MOSIZE=n. If the size of a memory object is insufficient for temporary storage of the records, intermediate disk storage is used along with a memory object. If the size of a memory object is too small to improve performance, memory object sorting is not used. DYNAUTO=NO is changed to DYNAUTO=YES for memory object sorting. Hiperspace and data space are not used when memory object sorting is used.

| | |

| | | | | | | | | | | | | | | | | | |

Chapter 3. Using DFSORT Program Control Statements

191

OPTION Control Statement

MAX n specifies that DFSORT determines dynamically the maximum size of a memory object to be used for memory object sorting. specifies that DFSORT determines dynamically the maximum size of a memory object to be used for memory object sorting, subject to a limit of nMB. n must be a value between 0 and 2147483646. If n is 0, memory object sorting is not used. specifies that DFSORT determines dynamically the maximum size of a memory object to be used for memory object sorting, subject to a limit of p percent of the available central storage. p must be a value between 0 and 100. If p is 0, memory object sorting is not used. The value calculated for p% is limited to 2147483646MB, and is rounded down to the nearest MB.

p%

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. MSGDDN

MSGDDN=ddname

Temporarily overrides the MSGDDN installation option, which specifies an alternate ddname for the message data set. MSGDDN must be in effect if: v A program that invokes DFSORT uses SYSOUT (for instance, COBOL uses SYSOUT) and you do not want DFSORT messages intermixed with the program messages. v Your E15 and E35 routines are written in COBOL and you do not want DFSORT messages intermixed with the program messages. v A program invokes DFSORT more than once and you want separate messages for each invocation of DFSORT. The ddname can be any 1- through 8- character name but must be unique within the job step; do not use a name that is used by DFSORT (for example, SORTIN). If the ddname specified is not available at run-time, SYSOUT is used instead. For details on use of the message data set, see z/OS DFSORT Messages, Codes and Diagnosis Guide Note: MSGDDN is processed only if it is passed on the OPTION control statement in an extended parameter list or in DFSPARM. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. MSGPRT

192

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

MSGPRT= ALL CRITICAL NONE

Temporarily overrides the MSGPRT installation option, which specifies the class of messages to be written to the message data set. For details on use of the message data set, see z/OS DFSORT Messages, Codes and Diagnosis Guide. ALL specifies that all messages except diagnostic messages (ICE800I to ICE999I) are to be printed. Control statements print only if LIST is in effect. CRITICAL specifies that only critical messages will be printed. Control statements print only if LIST is in effect. NONE specifies that no messages and control statements will be printed. Notes: 1. MSGPRT is processed only if it is passed on the OPTION control statement in an extended parameter list or in DFSPARM. 2. PRINT=value can be used instead of MSGPRT=value. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. NOBLKSET

NOBLKSET

Causes DFSORT to bypass the Blockset technique normally used for a sort or merge application. Using this option generally results in degraded performance. Note: Functions such as OUTFIL processing, which are supported only by the Blockset technique, cause the NOBLKSET option to be ignored. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. NOOUTREL

NOOUTREL

Chapter 3. Using DFSORT Program Control Statements

193

OPTION Control Statement

Temporarily overrides the OUTREL installation option, which specifies whether unused temporary output data set space is released. NOOUTREL means that unused temporary output data set space is not released. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. NOOUTSEC

NOOUTSEC

Temporarily overrides the OUTSEC installation option, which specifies whether automatic secondary allocation is used for temporary or new output data sets. NOOUTSEC means that automatic secondary allocation for output data sets is not used. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. | NULLOUT

NULLOUT=

RC0 RC4 RC16

Temporarily overrides the NULLOUT installation option, which specifies the action to be taken by DFSORT when there are no records for the SORTOUT data set, as indicated by an OUT count of 0 in message ICE054I RC0 specifies that DFSORT should issue message ICE173I, set a return code of 0, and continue processing when there are no records for the SORTOUT data set. RC4 specifies that DFSORT should issue message ICE173I, set a return code of 4, and continue processing when there are no records for the SORTOUT data set. RC16 specifies that DFSORT should issue message ICE206A, terminate, and give a return code of 16 when there are no records for the SORTOUT data set. Notes: 1. The return code of 0 or 4 set when there are no records for the SORTOUT data set can be overridden by a higher return code set for some other reason.

194

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

2. NULLOUT does not apply when SORTOUT is not present, when tape work data sets are specified for a sort application, or when the Blockset technique is not selected for a merge application. DFSORT does not check if there are no records for the SORTOUT data set in these cases. 3. NULLOUT applies to the SORTOUT data set. NULLOFL on the OUTFIL statement applies to OUTFIL data sets. 4. For an ICEGENER application, NULLOUT applies to the SYSUT2 data set if DFSORT copy is used. Note that ICEGENER passes back return code 12 instead of return code 16. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. ODMAXBF

ODMAXBF=

n nK nM

Temporarily overrides the ODMAXBF installation option, which specifies the maximum buffer space DFSORT can use for each OUTFIL data set. The actual amount of buffer space used for a particular OUTFIL data set will not exceed the ODMAXBF limit, but can be less than the limit. OUTFIL processing is supported by the Blockset technique for sort, copy, and merge applications. The storage used for OUTFIL processing is adjusted automatically according to the total storage available, the storage needed for non-OUTFIL processing, and the number of OUTFIL data sets and their attributes (for example, block size). OUTFIL processing is subject to the ODMAXBF limit in effect and the system storage limits (for example, IEFUSI), but not to the DFSORT storage limits (that is, SIZE, MAXLIM, and TMAXLIM). DFSORT attempts to use storage above 16MB virtual for OUTFIL processing whenever possible. Lowering ODMAXBF below 2M can cause performance degradation for the application, but may be necessary if you consider the amount of storage used for OUTFIL processing to be a problem. Raising ODMAXBF can improve EXCPs for the application but can also increase the amount of storage needed. n specifies that a maximum of n bytes of buffer space is to be used for each OUTFIL data set. If you specify less than 262144, 262144 is used. If you specify more than 16777216, 16777216 is used. Limit: 8 digits nK specifies that a maximum of n times 1024 bytes of buffer space is to be used for each OUTFIL data set. If you specify less than 256K, 256K is used. If you specify more than 16384K, 16384K is used. Limit: 5 digits

Chapter 3. Using DFSORT Program Control Statements

195

OPTION Control Statement

nM specifies that a maximum of n times 1048576 bytes of buffer space is to be used for each OUTFIL data set. If you specify 0M, 256K is used. If you specify more than 16M, 16M is used. Limit: 2 digits Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. OVFLO

OVFLO=

RC0 RC4 RC16

Temporarily overrides the OVFLO installation option, which specifies the action to be taken by DFSORT when BI, FI, PD or ZD summary fields overflow. RC0 specifies that DFSORT should issue message ICE152I (once), set a return code of 0 and continue processing when summary fields overflow. The pair of records involved in a summary overflow is left unsummed and neither record is deleted. Summary overflow does not prevent further summation. RC4 specifies that DFSORT should issue message ICE152I (once), set a return code of 4 and continue processing when summary fields overflow. The pair of records involved in a summary overflow is left unsummed and neither record is deleted. Summary overflow does not prevent further summation. RC16 specifies that DFSORT should issue message ICE195A, terminate and give a return code of 16 when summary fields overflow. Note: The return code of 0 or 4 set for summary overflow can be overridden by a higher return code set for some other reason. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. PAD

PAD=

RC0 RC4 RC16

196

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

Temporarily overrides the PAD installation option, which specifies the action to be taken by DFSORT when the SORTOUT LRECL is larger than the SORTIN/SORTINnn LRECL, for the cases where DFSORT allows LRECL padding. RC0 specifies that DFSORT should issue message ICE171I, set a return code of 0 and continue processing when the SORTOUT LRECL is larger than the SORTIN/SORTINnn LRECL. RC4 specifies that DFSORT should issue message ICE171I, set a return code of 4 and continue processing when the SORTOUT LRECL is larger than the SORTIN/SORTINnn LRECL. RC16 specifies that DFSORT should issue message ICE196A, terminate and give a return code of 16 when the SORTOUT LRECL is larger than the SORTIN/SORTINnn LRECL. Notes: 1. The return code of 0 or 4 set for LRECL padding can be overridden by a higher return code set for some other reason. 2. For an ICEGENER application, the GNPAD value is used and the PAD value is ignored. 3. For some LRECL padding situations (for example, a tape work data set sort), DFSORT issues ICE043A and terminates with a return code of 16. The PAD value has no effect in these cases. 4. DFSORT does not check for LRECL padding if: a. A SORTIN DD (sort/copy), SORTINnn DD (merge) or SORTOUT DD is not present b. A SORTIN DD (sort/copy), SORTINnn DD (merge) or SORTOUT DD specifies a VSAM data set. 5. DFSORT does not check OUTFIL data sets for LRECL padding. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. RESALL

RESALL=

n nK nM

Temporarily overrides the RESALL installation option, which specifies the number of bytes to be reserved in a REGION for system use. Usually, only 4K bytes (the standard default) of main storage must be available in a region for system use. However, in some cases, this may not be enough; for example, if your installation does not have BSAM/QSAM modules resident, you have user exits that open data sets, or you have COBOL exits. RESALL is used only when MAINSIZE/SIZE=MAX is in effect.
Chapter 3. Using DFSORT Program Control Statements

197

OPTION Control Statement

RESALL applies only to the amount of main storage below 16MB virtual. The ARESALL option applies to the amount of main storage above 16MB virtual. n specifies that n bytes of storage are to be reserved. If you specify less than 4096, 4096 is used. Limit: 8 digits. nK specifies that n times 1024 bytes of storage are to be reserved. If you specify less than 4K, 4K is used. Limit: 5 digits. nM specifies that n times 1048576 bytes of storage are to be reserved. If you specify 0M, 4K is used. Limit: 2 digits. Tip: A better way to reserve the required storage for user exits activated by the MODS statement is to use the m parameter of the MODS statement. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. RESET or NORESET

RESET NORESET

Temporarily overrides the RESET installation option, which specifies whether DFSORT should process a VSAM output data set defined with REUSE as a NEW or MOD data set. RESET specifies that DFSORT processes a VSAM output data set defined with REUSE as a NEW data set. The high-used RBA is reset to zero and the output data set is effectively treated as an initially empty cluster. NORESET specifies that DFSORT processes a VSAM output data set defined with REUSE as a MOD data set. The high-used RBA is not reset and the output data set is effectively treated as an initially non-empty cluster. Note: A VSAM output data set defined without REUSE is processed as a MOD data set. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. RESINV

198

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

RESINV= n nK nM

Temporarily overrides the RESINV installation option, which specifies the number of bytes to be reserved in a REGION for the invoking program. RESINV is used only when DFSORT is dynamically invoked and MAINSIZE/SIZE=MAX is in effect. RESINV applies only to the amount of main storage below 16MB virtual. The ARESINV option applies to the amount of main storage above 16MB virtual. This extra space is usually required for data handling by the invoking program or user exits while DFSORT is running (as is the case with some PL/I- and COBOL- invoked sort applications). Therefore, if your invoking programs user exits do not perform data set handling, you do not need to specify this parameter. The reserved space is not meant to be used for the invoking programs executable code. The amount of space required depends upon what routines you have, how the data is stored, and which access method you use. n specifies that n bytes of storage are to be reserved. Limit: 8 digits nK specifies that n times 1024 bytes of storage are to be reserved. Limit: 5 digits nM specifies n times 1048576 bytes of main storage are to be reserved. Limit: 2 digits. Tip: A better way to reserve the required storage for user exits activated by the MODS statement is to use the m parameter of the MODS statement. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SDB

SDB=

LARGE YES INPUT NO

Temporarily overrides the SDB installation option, which specifies whether DFSORT should use the system-determined optimum block size for output data sets when the block size is specified as zero or defaulted to zero. System-determined block size applies to both SMS-managed and
Chapter 3. Using DFSORT Program Control Statements

199

OPTION Control Statement

non-SMS-managed data sets and results in the most efficient use of space for the device on which the output data set resides. DFSORT can select system-determined optimum block sizes greater than 32760 bytes for tape output data sets. If you want DFSORT to use system-determined block sizes for disk and tape output data sets, specify one of the following values: v SDB=LARGE if you want to allow DFSORT to select tape output block sizes greater than 32760 bytes. v SDB=YES (or its alias SDB=SMALL) if you want DFSORT to select tape output block sizes less than or equal to 32760 bytes. v SDB=INPUT if you want to allow DFSORT to select tape output block sizes greater than 32760 bytes only when tape input data sets with block sizes greater than 32760 bytes are used. DFSORT will not select a tape output block size greater than the BLKSZLIM in effect. In particular, if a default BLKSZLIM of 32760 is in effect, DFSORT will not select a tape output block size greater than 32760 bytes. Therefore, in order to allow DFSORT to select tape output block sizes greater than 32760 bytes for particular jobs, you may need to ensure that your JCL or data class supplies appropriately large BLKSZLIM values (for example, 1GB) for those jobs. If you dont want DFSORT to use system-determined block sizes, specify SDB=NO (not recommended as an installation option). LARGE specifies that DFSORT is to use the system-determined optimum block size for an output data set when its block size is zero. SDB=LARGE allows DFSORT to select a block size greater than 32760 bytes for a tape output data set, when appropriate. A larger tape block size can improve elapsed time and tape utilization, but you must ensure that applications which subsequently use the resulting tape data set can handle larger block sizes. DFSORT selects the system-determined optimum block size as follows: v For a disk output data set, the optimum block size for the device used is selected based on the obtained or derived RECFM and LRECL for the output data set. The maximum block size for disk output data sets is 32760 bytes. v For a tape output data set, the optimum block size is selected based on the obtained or derived RECFM and LRECL for the output data set, as shown in Table 33.
Table 33. SDB=LARGE Block Sizes for Tape Output Data Sets RECFM F or FS FB or FBS BLKSIZE is set to: LRECL Highest possible multiple of LRECL that is less than or equal to the optimum block size for the device, subject to the BLKSZLIM in effect. LRECL + 4 Optimum block size for the device, subject to the BLKSZLIM in effect.

V, D, VS, or DS VB, DB, VBS, or DBS

200

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

DFSORT uses the system-determined optimum block size for the output data set in most cases when the block size is zero. However, the following conditions prevent DFSORT from using the system-determined block size: v Output data set block size is available (that is, non-zero) in the JFCB (disk or tape) or format 1 DSCB (disk) or tape label (only for DISP=MOD with AL, SL, or NSL label, when appropriate) v Output is a spool, dummy, VSAM, or unmovable data set, or an HFS file. v The output data set is on tape with a label type of AL v DFSORTs Blockset technique is not selected. In the above cases, DFSORT uses the specified block size, or determines an appropriate (though not necessarily optimum) block size for the output data set. The selected block size is limited to 32760 bytes. YES specifies that DFSORT is to use the system-determined optimum block size for an output data set when its block size is zero, but is to limit the selected block size to a maximum of 32760 bytes. See the discussion of SDB=LARGE for more information; the only difference between SDB=LARGE and SDB=YES is that SDB=LARGE allows block sizes greater than 32760 bytes for tape output data sets, whereas SDB=YES does not. INPUT specifies that DFSORT is to use the system-determined optimum block size for an output data set when its block size is zero, but is to limit the selected block size to a maximum of 32760 bytes if the input block size is less than or equal to 32760 bytes. Thus, SDB=INPUT works like SDB=LARGE if the input block size is greater than 32760 bytes (only possible for tape input data sets) and works like SDB=YES if the input block size is less than or equal to 32760 bytes. See the discussions of SDB=LARGE and SDB=YES for more information. NO specifies that DFSORT is not to use the system-determined optimum block size. When the output data set block size is zero, DFSORT selects an appropriate (though not necessarily optimum) block size for the output data set based on the obtained or derived output or input attributes. SDB=NO limits the selected block sizes to a maximum of 32760 bytes. SDB=NO works like SDB=YES if the input block size is greater than 32760 bytes (only possible for tape input data sets). See the discussion of SDB=YES for more information. Notes: 1. SDB=NO does not prevent the use of system-determined block size for the output data set at allocation or in other cases where the output data set block size is set before DFSORT gets control. 2. When DFSORT uses system-determined block size, the selected output data set block size may be different from the block size selected previously. Applications that require a specific output data set block size should be changed to specify that block size explicitly. 3. SDB and SDB=SMALL can be used instead of SDB=YES. NOSDB can be used instead of SDB=NO. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details.
Chapter 3. Using DFSORT Program Control Statements

201

OPTION Control Statement

Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SIZE See FILSZ. SKIPREC

SKIPREC=z

Specifies the number of records z you want to skip (delete) before starting to sort or copy the input data set. SKIPREC is usually used if, on a preceding DFSORT run, you have processed only part of the input data set. An application with an input data set that exceeds intermediate storage capacity usually terminates unsuccessfully. However, for a tape work data set sort, you can use a routine at E16 (as described in Chapter 4, Using Your Own User Exit Routines, on page 413) to instruct the program to sort only those records already read in. It then prints a message giving the number of records sorted. You can use SKIPREC in a subsequent sort run to bypass the previously-sorted records, sort only the remaining records, and then merge the output from different runs to complete the application. z specifies the number of records to be skipped.

Limit: 28 digits (15 significant digits) Notes: 1. SKIPREC applies only to records read from SORTIN (not from E15 routines). (See Figure 2 on page 9.) 2. If SKIPREC=0 is in effect, SKIPREC is not used. 3. You may want to consider using the STARTREC parameter of the OUTFIL statement as an alternative to using SKIPREC. Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SMF

SMF=

SHORT FULL NO

Temporarily overrides the SMF installation option, which specifies whether a DFSORT SMF record is to be produced as described in z/OS DFSORT Installation and Customization. SHORT specifies that DFSORT is to produce a short SMF type-16 record for a successful run. The short SMF record does not contain record-length distribution statistics or data set sections.

202

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

FULL specifies that DFSORT is to produce a full SMF type-16 record for a successful run. The full SMF record contains the same information as the short record, as well as record-length distribution and data set sections, as appropriate. specifies that DFSORT is not to produce an SMF type-16 record for this run.

NO

| | |

Notes: 1. SMF is processed only if it is passed on the OPTION control statement in an extended parameter list or in DFSPARM. 2. SMF=FULL can degrade performance for a variable-length record application. 3. The DFSORT SVC is called to write SMF type-16 records. If SMF=SHORT or SMF=FULL is in effect, the correct DFSORT SVC for this release must be loaded in LPA or MLPA. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SOLRF or NOSOLRF

SOLRF NOSOLRF

Temporarily overrides the SOLRF installation option, which specifies whether DFSORT should set the SORTOUT LRECL to the reformatted record length when the SORTOUT LRECL is unknown. SOLRF specifies that DFSORT should use the reformatted record length for the SORTOUT LRECL when the SORTOUT LRECL is not specified or available. DFSORT will use one of the following for the SORTOUT LRECL, in the order listed: 1. The SORTOUT LRECL if available from the JFCB, format 1 DSCB, DFSMSrmm, ICETPEX, or tape label 2. The L3 length if specified in the RECORD statement 3. The OUTREC length if the OUTREC statement is specified 4. The INREC length if the INREC statement is specified 5. The L2 length if specified in the RECORD statement providing an E15 user exit is present 6. The SORTIN or SORTINnn LRECL if available from the JFCB, format 1 DSCB, DFSMSrmm, ICETPEX, or tape label 7. The L1 length in the RECORD statement NOSOLRF specifies that DFSORT should not use the reformatted record length for the SORTOUT LRECL. DFSORT will use one of the following for the SORTOUT LRECL, in the order listed:

Chapter 3. Using DFSORT Program Control Statements

203

OPTION Control Statement

1. The SORTOUT LRECL if available from the JFCB, format 1 DSCB, DFSMSrmm, ICETPEX, or tape label 2. The L3 length if specified in the RECORD statement providing an E35 exit, OUTREC statement or INREC statement is present 3. The L2 length if specified in the RECORD statement providing an E15 user exit is present 4. The SORTIN or SORTINnn LRECL if available from the JFCB, format 1 DSCB, DFSMSrmm, ICETPEX, or tape label 5. The L1 length in the RECORD statement Notes: 1. With SOLRF in effect (the IBM-supplied default), DFSORT sets the SORTOUT LRECL to the INREC or OUTREC record length when appropriate, which is usually what you want when you use INREC or OUTREC. If you want DFSORT to use the input length for the SORTOUT LRECL even when INREC or OUTREC is present, you can use NOSOLRF, but be aware that this can cause padding or truncation of the reformatted records, or termination. 2. CAOUTREC can be used instead of SOLRF. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SORTDD

SORTDD=cccc

Specifies a four-character prefix for the ddnames to be used when you dynamically invoke DFSORT more than once in a program step. The four characters replace SORT in the following ddnames: SORTIN, SORTOUT, SORTINn, SORTINnn, SORTOFd, SORTOFdd, SORTWKd, SORTWKdd, and SORTCNTL. This allows you to use a different set of ddnames for each call to DFSORT. cccc Specifies a four-character prefix. The four characters must all be alphanumeric or national ($, #, or @). The first character must be alphabetic. The first three characters must not be SYS. For example, if you use ABC# as replacement characters, DFSORT uses DD statements ABC#IN, ABC#CNTL, ABC#WKdd, and ABC#OUT instead of SORTIN, SORTCNTL, SORTWKdd, and SORTOUT. Notes: 1. SORTDD is processed only if it is passed on the OPTION control statement in an extended parameter list, or in DFSPARM. 2. If both SORTIN=ddname and SORTDD=cccc are specified, ddname is used for DFSORT input. 3. If both SORTOUT=ddname and SORTDD=cccc are specified, ddname is used for DFSORT output.

204

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

Default: SORT. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SORTIN

SORTIN=ddname

Specifies a ddname to be associated with the SORTIN data set. This allows you to dynamically invoke DFSORT more than once in a program step, passing a different ddname for each input data set. The ddname can be 1 through 8 characters, but must be unique within the job step. Do not use ddnames reserved for use by DFSORT, such as ccccWKd, ccccWKdd, ccccDKd, or ccccDKdd , where cccc is the specified or defaulted value for the SORTDD operand and d is any character. Notes: 1. SORTIN is processed only if it is passed on the OPTION control statement in an extended parameter list, or in DFSPARM. 2. If both SORTIN=ddname and SORTDD=cccc are specified, ddname is used for the input file. The same ddname cannot be specified for SORTIN and SORTOUT. 3. If SORTIN is used for a tape work data set sort, DFSORT terminates. Default: SORTIN, unless SORTDD=cccc is specified in which case ccccIN is the default. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SORTOUT

SORTOUT=ddname

Specifies a ddname to be associated with the SORTOUT data set. This allows you to dynamically invoke DFSORT more than once in a program step, passing a different ddname for each output data set. The ddname can be 1 through 8 characters, but must be unique within the job step. Do not use ddnames reserved for use by DFSORT, such as ccccWKd, ccccWKdd, ccccDKd, or ccccDKdd , where cccc is the specified or defaulted value for the SORTDD operand and d is any character. Notes: 1. SORTOUT is processed only if it is passed on the OPTION control statement in an extended parameter list or in DFSPARM.

Chapter 3. Using DFSORT Program Control Statements

205

OPTION Control Statement

2. If both SORTOUT=ddname and SORTDD=cccc are specified, ddname is used for the output file. The same ddname cannot be specified for SORTIN and SORTOUT. 3. If SORTOUT is specified for a conventional merge or for a tape work data set sort, DFSORT terminates. Default: SORTOUT, unless SORTDD=cccc is specified, in which case ccccOUT is the default. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SPANINC

SPANINC=

RC0 RC4 RC16

Temporarily overrides the SPANINC installation option, which specifies the action to be taken by DFSORT when one or more incomplete spanned records are detected in a variable spanned input data set. RC0 specifies that DFSORT should issue message ICE197I (once), set a return code of 0 and eliminate all incomplete spanned records it detects. Valid records will be recovered. RC4 specifies that DFSORT should issue message ICE197I (once), set a return code of 4 and eliminate all incomplete spanned records it detects. Valid records will be recovered. RC16 specifies that DFSORT should issue message ICE204A, terminate and give a return code of 16 when an incomplete spanned record is detected. Notes: 1. The return code of 0 or 4 set for incomplete spanned records can be overridden by a higher return code set for some other reason. 2. In cases where a spanned record cannot be properly assembled (for example, it has a segment length less than 4 bytes), DFSORT issues ICE141A and terminates with a return code of 16. The SPANINC value has no effect in these cases. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. STOPAFT

206

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

STOPAFT=n

Specifies the maximum number of records (n) you want accepted for sorting or copying (that is, read from SORTIN or inserted by E15 and not deleted by SKIPREC, E15, or the INCLUDE/OMIT statement). When n records have been accepted, no more records are read from SORTIN; E15 continues to be entered as if EOF were encountered until a return code of 8 is sent, but no more records are inserted. If end-of-file is encountered before n records are accepted, only those records accepted up to that point are sorted or copied. n specifies the maximum number of records to be accepted. Limit: 28 digits (15 significant digits) Default: None; optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. SZERO or NOSZERO

SZERO NOSZERO

Temporarily overrides the SZERO installation option, which specifies whether DFSORT should treat numeric 0 and +0 values as signed (that is, different) or unsigned (that is, the same) for collation, comparisons, editing and conversions, minimums and maximums. The following DFSORT control statements are affected by this option: INCLUDE, INREC, MERGE, OMIT, OUTFIL, OUTREC and SORT. SZERO specifies that DFSORT should treat numeric zero values as signed. 0 and +0 are treated as different values, that is, 0 is treated as a negative value and +0 is treated as a positive value. SZERO affects DFSORT processing of numeric values as follows: v For collation of SORT and MERGE fields, 0 collates before +0 in ascending order and after +0 in descending order. v For comparisons of INCLUDE, OMIT, and OUTFIL compare fields and constants, 0 compares as less than +0. v For editing and conversions of INREC, OUTREC, and OUTFIL reformatting fields, decimal constants, and the results of arithmetic expressions, 0 is treated as negative and +0 is treated as positive. v For minimums and maximums of OUTFIL TRAILERx fields, 0 is treated as negative and +0 is treated as positive. NOSZERO specifies that DFSORT should treat numeric zero values as unsigned. 0 and +0 are treated as the same value, that is, 0 and +0 are both treated as positive values. NOSZERO affects DFSORT processing of numeric values as follows:
Chapter 3. Using DFSORT Program Control Statements

207

OPTION Control Statement

v For collation of SORT and MERGE fields, 0 collates equally with +0. v For comparisons of INCLUDE, OMIT and OUTFIL compare fields and constants, 0 compares as equal to +0. v For editing and conversions of INREC, OUTREC, and OUTFIL reformatting fields, decimal constants, and the results of arithmetic expressions, 0 and +0 are treated as positive. v For minimums and maximums of OUTFIL TRAILERx fields, 0 and +0 are treated as positive. Note: OPTION SZERO or OPTION NOSZERO is ignored for OUTFIL INCLUDE=(logexp) and OMIT=(logexp), and INREC, OUTREC, and OUTFIL IFTHEN=(WHEN=(logexp)...), if the OPTION statement is found after the INREC, OUTREC, or OUTFIL statement. To avoid this, specify SZERO or NOSZERO as an EXEC/DFSPARM PARM option, or in an OPTION statement before the INREC, OUTREC, or OUTFIL statement in the same source, for example:
//SYSIN DD * OPTION NOSZERO,COPY OUTFIL INCLUDE=(...) /*

Default: Usually, the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. TRUNC

TRUNC=

RC0 RC4 RC16

Temporarily overrides the TRUNC installation option, which specifies the action to be taken by DFSORT when the SORTOUT LRECL is smaller than the SORTIN/SORTINnn LRECL, for the cases where DFSORT allows LRECL truncation. RC0 specifies that DFSORT should issue message ICE171I, set a return code of 0 and continue processing when the SORTOUT LRECL is smaller than the SORTIN/SORTINnn LRECL. RC4 specifies that DFSORT should issue message ICE171I, set a return code of 4 and continue processing when the SORTOUT LRECL is smaller than the SORTIN/SORTINnn LRECL. RC16 specifies that DFSORT should issue message ICE196A, terminate and give a return code of 16 when the SORTOUT LRECL is smaller than the SORTIN/SORTINnn LRECL.

208

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

Notes: 1. The return code of 0 or 4 set for LRECL truncation can be overridden by a higher return code set for some other reason. 2. For an ICEGENER application, the GNTRUNC value is used and the TRUNC value is ignored. 3. For some LRECL truncation situations (for example, a tape work data set sort), DFSORT issues ICE043A and terminates with a return code of 16. The TRUNC value has no effect in these cases. 4. DFSORT does not check for LRECL truncation if: a. A SORTIN DD (sort/copy), SORTINnn DD (merge) or SORTOUT DD is not present b. A SORTIN DD (sort/copy), SORTINnn DD (merge) or SORTOUT DD specifies a VSAM data set. 5. DFSORT does not check OUTFIL data sets for LRECL truncation. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. USEWKDD

USEWKDD

Temporarily overrides the DYNAUTO=IGNWKDD option, which specifies that dynamic work data sets are used even if SORTWKdd DD statements are present. This option allows JCL SORTWKdd data sets to be used rather than deallocated. Note: USEWKDD is processed only if it is passed on the OPTION control statement in an extended parameter list or in DFSPARM. Default: None, optional. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Function: See Appendix B, Specification/Override of DFSORT Options, on page 741. VERIFY or NOVERIFY

VERIFY NOVERIFY

Temporarily overrides the VERIFY installation option, which specifies whether sequence checking of the final output records must be performed. VERIFY specifies that sequence checking is performed.

Chapter 3. Using DFSORT Program Control Statements

209

OPTION Control Statement

NOVERIFY specifies that sequence checking is not performed. Notes: 1. Using VERIFY can degrade performance. 2. SEQ=YES can be used instead of VERIFY, SEQ=NO can be used instead of NOVERIFY. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. VLLONG or NOVLLONG

VLLONG NOVLLONG

Temporarily overrides the VLLONG installation option, which specifies whether DFSORT is to truncate long variable-length output records. A long output record is one whose length is greater than the LRECL of the SORTOUT or OUTFIL data set it is to be written to. VLLONG is not meaningful for fixed-length output record processing. VLLONG NOVLLONG specifies that DFSORT truncates long variable-length output records to the LRECL of the SORTOUT or OUTFIL data set. specifies that DFSORT terminates if a long variable-length output record is found.

Notes: 1. VLLONG should not be used unless you want the data at the end of long variable-length output records to be truncated for your DFSORT application; inappropriate use of VLLONG can result in unwanted loss of data. 2. VLLONG can be used to truncate long OUTFIL data records, but has no effect on long OUTFIL header or trailer records. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. VLSCMP or NOVLSCMP

VLSCMP NOVLSCMP

Temporarily overrides the VLSCMP installation option, which specifies whether DFSORT is to pad short variable-length INCLUDE/OMIT compare

210

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

fields with binary zeros. A short field is one where the variable-length record is too short to contain the entire field, that is, the field extends beyond the record. VLSCMP and NOVLSCMP apply to the INCLUDE and OMIT statements and to the INCLUDE and OMIT parameters of the OUTFIL statement. The compare fields are only padded temporarily for testing; they are not actually changed for output. VLSCMP is not meaningful for fixed-length record processing. The settings for VLSCMP/NOVLSCMP and VLSHRT/NOVLSHRT provide three levels of processing for short INCLUDE/OMIT fields in the following hierarchy: 1. VLSCMP allows all of the INCLUDE/OMIT comparisons to be performed even if some fields are short. Because short fields are padded with binary zeros, comparisons involving short fields are false (unless a test against binary zero is relevant, as discussed below). Comparisons involving non-short fields can be true or false. 2. NOVLSCMP and VLSHRT treat the entire INCLUDE/OMIT logical expression as false if any field is short. Thus comparisons involving non-short fields are ignored if any comparison involves a short field. 3. NOVLSCMP and NOVLSHRT result in termination if any field is short. To illustrate how this works, suppose the following INCLUDE statement is used:
INCLUDE COND=(6,1,CH,EQ,C1,OR,70,2,CH,EQ,CT1)

If a variable-length input record has a length less than 71 bytes, the field at bytes 70-71 is short and the following occurs: v With VLSCMP, the record is included if byte 6 of the input record is C1 or omitted if byte 6 is not C1. The comparison of bytes 70-71 equal to CT1 is false because bytes 70-71 contain either Xhh00 (for a record length of 70 bytes) or X0000 (for a record length of less than 70 bytes). The comparison involving the non-short field is performed even though a short field is present. v With NOVLSCMP and VLSHRT, the record is omitted because any short field makes the entire logical expression false. The comparison involving the non-short field is not performed because a short field is present. v With NOVLSCMP and NOVLSHRT, DFSORT terminates because any short field results in termination. In general, comparisons involving short fields are false with VLSCMP. However, if a binary zero value is relevant to the comparison, the use of binary zeros for padding might make the comparison true. For example, suppose the following INCLUDE statement is used:
INCLUDE COND=(21,2,CH,EQ,CJX,OR, (55,2,CH,EQ,58,2,CH,AND, 70,1,BI,LT,X08))

If a variable-length input record has a length less than 70 bytes, the field at byte 70 is short and is padded to X00. This makes the comparison of byte 70 less than X08 true even though byte 70 is a short field and so probably irrelevant. Likewise, if a variable-length record has a length less than 55 bytes, the fields at bytes 55-56 and 58-59 are short and are each padded to X0000, and the field at byte 70 is short and is padded to X00. This makes the comparison of
Chapter 3. Using DFSORT Program Control Statements

211

OPTION Control Statement

bytes 55-56 equal to 58-59 true and the comparison of byte 70 less than X08 true even though all three fields are short and probably irrelevant. In such cases where padding of short fields with binary zeros may result in unwanted true comparisons, you can get the result you want by adding an appropriate check of the record length to the INCLUDE/OMIT logical expression, such as:
INCLUDE COND=(21,2,CH,EQ,CJX,OR, (1,2,BI,GE,X0046,AND, 55,2,CH,EQ,58,2,CH,AND, 70,1,BI,LT,X08))

Now the comparisons involving bytes 55-56, 58-59 and 70 can only be true for records that are 70 bytes (X0046) or longer. Thus, the irrelevant comparisons involving short fields are eliminated. Keep in mind that short compare fields are padded with zeros when VLSCMP is in effect and code your INCLUDE/OMIT logical expressions to allow for that or even take advantage of it. VLSCMP NOVLSCMP specifies that short variable-length compare fields are padded with binary zeros. specifies that short variable-length compare fields are not padded.

Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. VLSHRT or NOVLSHRT

VLSHRT NOVLSHRT

Temporarily overrides the VLSHRT installation option, which specifies whether DFSORT is to continue processing if a short variable-length SORT/MERGE control field, INCLUDE/OMIT compare field, or SUM summary field is found. A short field is one where the variable-length record is too short to contain the entire field, meaning that the field extends beyond the record. VLSHRT applies to the SORT, MERGE, INCLUDE, OMIT and SUM statements, and to the INCLUDE and OMIT parameters of the OUTFIL statement. VLSHRT processing is not meaningful for fixed-length record processing. The way in which DFSORT processes short INCLUDE/OMIT compare fields depends on the settings for VLSCMP/NOVLSCMP and VLSHRT/NOVLSHRT. For details, see the discussion of the VLSCMP and NOVLSCMP options. VLSHRT specifies that DFSORT continues processing if a short control field, compare field or summary field is found. NOVLSHRT specifies that DFSORT terminates if a short control field, compare field or summary field is found.

212

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

Notes: 1. VLSHRT is not used if an INREC or OUTREC statement is specified, if you have an EFS01 or EFS02 routine, or if locale processing is used for SORT or MERGE fields. Note that none of these situations prevents the use of VLSCMP. 2. Unlike the OUTREC statement, the OUTREC , BUILD, OVERLAY, or IFTHEN parameter of the OUTFIL statement does not force NOVLSHRT. Thus, you can use VLSHRT with OUTFIL to eliminate records with the INCLUDE or OMIT parameter and reformat the remaining records with the OUTREC, , BUILD, OVERLAY, or IFTHEN parameter. If a short OUTFIL OUTREC or BUILD field is found, DFSORT terminates (even if VLSHRT is in effect) unless the VLFILL=byte parameter of OUTFIL is specified. If a short OUTFIL OVERLAY or IFTHEN field is found, DFSORT pads the missing bytes with blanks so it can be processed. 3. If VLSHRT is in effect and Blockset is selected: v DFSORT pads short SORT or MERGE control fields with binary zeros, thus making the order predictable for records with equal control fields of different lengths. The control fields are only padded temporarily for collation; they are not actually changed for output. Padding may increase the amount of work space required. v Records with short SUM summary fields are excluded from summation; that is, if either one of a pair of records being summed has a short SUM field, the records are left unsummed and neither record is deleted. 4. If VLSHRT is in effect and Blockset is not selected: v DFSORT terminates if the first byte of the first (major) SORT or MERGE control field is not included in the record. v DFSORT does not pad short SORT or MERGE control fields, thus making the order unpredictable for records with equal control fields of different lengths. v In certain cases, VLSHRT is not used because of the number and position of the SORT or MERGE control fields. v EQUALS is not used. Tip: You can use a SORTDIAG DD statement to force message ICE800I, which gives a code indicating why Blockset could not be used. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. VSAMEMT or NVSAMEMT

VSAMEMT NVSAMEMT

Temporarily overrides the VSAMEMT installation option, which specifies whether DFSORT should accept an empty VSAM input data set.

Chapter 3. Using DFSORT Program Control Statements

213

OPTION Control Statement

VSAMEMT specifies that DFSORT accepts an empty VSAM input data set and processes it as having zero records. NVSAMEMT specifies that DFSORT terminates if an empty VSAM input data set is found. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. VSAMIO or NOVSAMIO

VSAMIO NOVSAMIO

Temporarily overrides the VSAMIO installation option, which specifies whether DFSORT should allow a VSAM data set defined with REUSE to be sorted in-place. VSAMIO specifies that DFSORT can use the same VSAM data set for input and output when all of the following conditions are met: v The application is a sort. v RESET is in effect. v The VSAM data set was defined with REUSE. These conditions ensure that the VSAM data set is processed as NEW for output and will contain the sorted input records, that is, it will be sorted in-place. DFSORT terminates if the same VSAM data set is specified for input and output and any of the above conditions are not met. NOVSAMIO specifies that DFSORT terminates if the same VSAM data set is used for input and output. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. WRKREL or NOWRKREL

WRKREL NOWRKREL

Temporarily overrides the WRKREL installation option, which specifies whether unused temporary SORTWKdd data set space will be released.

214

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

WRKREL specifies that unused space is released. NOWRKREL specifies that unused space is not released. Notes: 1. If you have dedicated certain volumes for SORTWKdd data sets, and you do not want unused temporary space to be released, you should specify NOWRKREL. 2. If WRKREL is in effect, DFSORT releases space for the SORTWKdd data sets just prior to termination. Space is released only for those SORTWKdd data sets that were used for the sort application. 3. RLS=0 can be used instead of NOWRKREL. RLS=n (n greater than 0) can be used instead of WRKREL. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. WRKSEC or NOWRKSEC

WRKSEC NOWRKSEC

Temporarily overrides the WRKSEC installation option, which specifies whether DFSORT uses automatic secondary allocation for temporary JCL SORTWKdd data sets. WRKSEC specifies that automatic secondary allocation for temporary JCL SORTWKdd data sets is used and that 25 percent of the primary allocation will be used as the secondary allocation. NOWRKSEC specifies that automatic secondary allocation for temporary JCL SORTWKdd data sets is not used. Note: SEC=0 can be used instead of NOWRKSEC. SEC=n (n greater than 0) can be used instead of WRKSEC. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. Y2PAST

Y2PAST=

s f

Chapter 3. Using DFSORT Program Control Statements

215

OPTION Control Statement

Temporarily overrides the Y2PAST installation option, which specifies the sliding (s) or fixed (f) century window. The century window is used with DFSORTs Y2 formats to correctly interpret two-digit year data values as four-digit year data values. s specifies the number of years DFSORT is to subtract from the current year to set the beginning of the sliding century window. Because the Y2PAST value is subtracted from the current year, the century window slides as the current year changes. For example, Y2PAST=81 would set a century window of 1925-2024 in 2006 and 1926-2025 in 2007. s must be a value between 0 and 100. specifies the beginning of the fixed century window. For example, Y2PAST=1962 would set a century window of 1962-2061. f must be a value between 1000 and 3000.

Note: CENTURY=value and CENTWIN=value can be used instead of Y2PAST=value. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. ZDPRINT or NZDPRINT

ZDPRINT NZDPRINT

Temporarily overrides the ZDPRINT installation option, which specifies whether positive zoned-decimal (ZD) fields resulting from summing must be converted to printable numbers (that is, whether the zone of the last digit should be changed from a hexadecimal C to a hexadecimal F). See SUM Control Statement on page 408 for further details on the use of ZDPRINT and NZDPRINT. ZDPRINT means convert positive ZD summation results to printable numbers. For example, change hexadecimal F3F2C5 (prints as 32E) to F3F2F5 (prints as 325). means do not convert positive ZD summation results to printable numbers.

NZDPRINT

Note: ZDPRINT=YES can be used instead of ZDPRINT. ZDPRINT=NO can be used instead of NZDPRINT. Default: Usually the installation default. See Appendix B, Specification/ Override of DFSORT Options, on page 741 for full override details. Applicable Function: See Appendix B, Specification/Override of DFSORT Options, on page 741.

Aliases for OPTION Statement Options

For compatibility reasons, the following OPTION statement options can be specified by using the aliases listed below. See the indicated OPTION statement options for complete details.

216

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

Table 34. Aliases for OPTION Statement Options Alias CAOUTREC CENTURY=value CENTWIN=value CHKPT CORE=value HIPRLIM=value L5=value NOSDB PRINT=value RLS=n RLS=0 SDB SDB=SMALL SEC=n SEC=0 SEQ=YES SEQ=NO ZDPRINT=YES ZDPRINT=NO OPTION Statement Option SOLRF Y2PAST=value Y2PAST=value CKPT MAINSIZE=value HIPRMAX=value AVGRLEN=value SDB=NO MSGPRT=value WRKREL NOWRKREL SDB=YES SDB=YES WRKSEC NOWRKSEC VERIFY NOVERIFY ZDPRINT NZDPRINT

Specifying DFSORT Options or COPYExamples

Example 1
SORT FIELDS=(1,20,CH,A) OPTION SIZE=50000,SKIPREC=5,EQUALS,DYNALLOC

FIELDS The control field begins on the first byte of each record in the input data set, is 20 bytes long, contains character data, and is to be sorted in ascending order. SIZE The data set to be sorted contains 50000 records.

SKIPREC Five records are skipped (deleted) before starting to process the input data set. EQUALS The sequence of records that collate identically is preserved from input to output. DYNALLOC Two data sets (by default) are allocated on SYSDA (by default). The space on the data set is calculated using the SIZE value in effect.

Example 2
SORT FIELDS=(1,2,CH,A),CKPT OPTION EQUALS,NOCHALT,NOVERIFY,CHECK

Chapter 3. Using DFSORT Program Control Statements

217

OPTION Control Statement

FIELDS The control field begins on the first byte of each record in the input data set, is 2 bytes long, contains character data, and is to be sorted in ascending order. CKPT DFSORT takes checkpoints during this run. Note: CKPT is ignored if the Blockset technique is used. If checkpoints are required, you must bypass the Blockset technique by specifying the NOBLKSET option, or by specifying installation option IGNCKPT=NO. However, functions such as OUTFIL, which are supported only by the Blockset technique, cannot be used if the Checkpoint/Restart facility is used. EQUALS The sequence of records that collate identically is preserved from input to output. NOCHALT Only AQ fields are translated through the ALTSEQ translate table. If installation option CHALT=YES was specified, then NOCHALT temporarily overrides it. NOVERIFY No sequence check is performed on the final output records. CHECK The record count is checked at the end of program processing.

Example 3
OPTION FILSZ=50,SKIPREC=5,DYNALLOC=3390 SORT FIELDS=(1,2,CH,A),SKIPREC=1,SIZE=200,DYNALLOC=(3380,5)

This example shows how parameters specified on the OPTION control statement override those specified on the SORT control statement, regardless of the order of the two statements. FILSZ DFSORT expects 50 records on the input data set. (Note that there is a difference in meaning between FILSZ and SIZE and that the OPTION specification of FILSZ is used in place of SIZE.) SKIPREC DFSORT causes five records from the beginning of the input file to be skipped. (SKIPREC=1 on the SORT statement is ignored.) DYNALLOC DFSORT allocates two work data sets (by default) on an IBM 3390. FIELDS The control field begins on the first byte of each record in the input data set, is 2 bytes long, contains character data, and is to be sorted in ascending order.

Example 4
OPTION NOBLKSET

NOBLKSET DFSORT does not use the Blockset technique for a sort or merge.

Example 5
OPTION STOPAFT=100

218

z/OS V1R10.0 DFSORT Application Programming Guide

OPTION Control Statement

STOPAFT DFSORT accepts 100 records before sorting or copying.

Example 6
OPTION RESINV=32000,MSGPRT=NONE, MSGDDN=SORTMSGS,SORTDD=ABCD,SORTIN=MYINPUT, SORTOUT=MYOUTPUT,NOLIST

This example illustrates the parameters RESINV, MSGPRT, MSGDDN, SORTDD, SORTIN, SORTOUT, and NOLIST, and the actions taken when these parameters are supplied on an OPTION statement read from the SYSIN data set or the SORTCNTL data set. The parameters are recognized, but not used. RESINV | | 32000 bytes of storage are reserved for the user.

MSGPRT=NONE The keyword is ignored, and messages are printed according to the installation default. MSGDDN=SORTMSGS The keyword is ignored, and all messages are written to the SYSOUT data set. SORTDD=ABCD The keyword is ignored, and the standard prefix SORT is used. SORTIN=MYINPUT The keyword is ignored, and the ddname SORTIN is used to reference the input data set. SORTOUT=MYOUTPUT The keyword is ignored, and the ddname SORTOUT is used to reference the output data set.

| |

NOLIST

The keyword is ignored, and control statements are printed according to the installation defaults.

Example 7
OPTION RESINV=32000,MSGPRT=CRITICAL MSGDDN=SORTMSGS,SORTDD=ABCD,SORTIN=MYINPUT, SORTOUT=MYOUTPUT,NOLIST

This example illustrates keywords RESINV, MSGPRT, MSGDDN, SORTDD, SORTIN, SORTOUT, and NOLIST and the actions taken when these keywords are supplied on the OPTION control statement passed by DFSPARM. These options can also be passed in an extended parameter list, but must be coded as one contiguous statement without continuation lines. RESINV 32000 bytes of storage are reserved for the user.

MSGPRT=CRITICAL Only critical messages are printed on the message data set. MSGDDN=SORTMSGS Messages are written to the SORTMSGS data set. SORTDD=ABCD SORT uses ABCD as a prefix for all sort names. SORTIN=MYINPUT The ddname MYINPUT is used to reference the input data set.

Chapter 3. Using DFSORT Program Control Statements

219

OPTION Control Statement

SORTOUT=MYOUTPUT The ddname MYOUTPUT is used to reference the output data set. NOLIST Control statements are not printed.

Example 8
SORT FIELDS=(3,4,CH,A) OPTION COPY,SKIPREC=10,CKPT MODS E15=(E15,1024,MODLIB),E35=(E35,1024,MODLIB)

SORT The sort statement is ignored because the COPY option has been specified. COPY The copy processing is always done on a record-by-record basis. Each record is therefore read from SORTIN, passed to the E15 exit, passed to the E35 exit, and written to SORTOUT. (Contrast this with a sort, where all the records are read from SORTIN and passed to the E15 exit before any records are passed to the E35 exit and written to SORTOUT.) SKIPREC Ten records are skipped before copying starts. CKPT The checkpoint option is not used for copy applications.

Example 9
SORT FIELDS=(5,4,CH,A) SUM FIELDS=(12,5,ZD,25,6,ZD) OPTION ZDPRINT

ZDPRINT The positive summed ZD values are printable because DFSORT uses an F sign for the last digit.

220

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

OUTFIL Control Statements

, OUTFIL FNAMES= ddname , ( ddname suffix , )

FILES=

( suffix ) STARTREC=n ENDREC=n SAMPLE= n (n,m) INCLUDE= ( logical expression ) ALL NONE OMIT= ( logical expression ) ALL NONE SAVE , PARSE=( definition , ( item )

OUTREC= BUILD=

) ,VTOF ,CONVERT ,VLFILL=byte

, OVERLAY= ( , item )

IFTHEN=(clause) IFOUTLEN=n FTOV VLTRIM=byte REPEAT=n SPLIT SPLITBY=n SPLIT1R=n NULLOFL= RC0 RC4 RC16 LINES=n , HEADER1= ( item , item , HEADER2= ( item , ) )

TRAILER1= (

TRAILER2= ( item ) Additional Parameters for OUTFIL

Chapter 3. Using DFSORT Program Control Statements

221

OUTFIL Control Statements

Additional Parameters for OUTFIL

, SECTIONS= ( NODETAIL BLKCCH1 BLKCCH2 BLKCCT1 REMOVECC item )

OUTFIL control statements allow you to create one or more output data sets for a sort, copy, or merge application from a single pass over one or more input data sets. You can use multiple OUTFIL statements, with each statement specifying the OUTFIL processing to be performed for one or more output data sets. OUTFIL processing begins after all other processing ends (that is, after processing for exits, options, and other control statements). OUTFILE can be used as an alias for OUTFIL. OUTFIL statements support 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, records that 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. For fixed 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, null-terminated strings (and many other types), you define rules that allow DFSORT to extract the relevant data into fixed parsed fields, and then use the parsed fields as you would use fixed fields. Insertion of blanks, zeros, strings, current date, future date, past date, current time, sequence numbers, decimal constants, and the results of arithmetic expressions before, between, and after the input fields in the reformatted records. Sophisticated conversion capabilities, such as hexadecimal display, conversion of EBCDIC letters from lowercase to uppercase or uppercase to lowercase, conversion of characters using the ALTSEQ translation 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 and shift right). Sophisticated editing capabilities, such as control of the way numeric fields are presented with respect to length, leading or suppressed zeros, thousands separators, decimal points, leading and trailing positive and negative signs, and so on.

222

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Twenty-seven pre-defined editing masks are available for commonly used numeric editing patterns, encompassing many of the numeric notations used throughout the world. In addition, a virtually unlimited number of numeric editing patterns are available via user-defined editing masks. Transformation of SMF, TOD, and ETOD date and time values to more usable forms. Transformation of two-digit year dates to various forms of four-digit year dates using a specified fixed or sliding century window. 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). v Creation of the reformatted records in one of the following three ways: By building the entire record one item at a time. By only overlaying specific columns. By using sophisticated conditional logic to choose how different records are built or overlaid. v Highly detailed three-level (report, page, and section) reports containing a variety of report elements you can specify (for example, current date, current time, edited or converted page numbers, character strings, and blank lines) or derive from the input records (for example, character fields; unedited, edited or converted numeric input fields; edited or converted record counts; and edited or converted totals, maximums, minimums, and averages for numeric input fields). v Creation of multiple output records from each input record, with or without intervening blank output records. v Repetition and sampling of data records. v Splitting of data records in rotation among a set of output data sets. The parameters of OUTFIL are grouped by primary purpose as follows: v FNAMES and FILES specify the ddnames of the OUTFIL data sets to be created. Each OUTFIL data set to be created must be specifically identified using FNAMES or FILES in an OUTFIL statement. By contrast, the SORTOUT data set is created by default if a DD statement for it is present. The term SORTOUT data set denotes the single non-OUTFIL output data set, but in fact, the SORTOUT ddname can be used for an OUTFIL data set either explicitly or by default. If SORTOUT is identified as an OUTFIL ddname, either explicitly (for example, via FILES=OUT) or by default (OUTFIL without FILES or FNAMES), the data set associated with the SORTOUT ddname will be processed as an OUTFIL data set rather than as the SORTOUT data set. OUTFIL data sets have characteristics and requirements similar to those for the SORTOUT data set, but there are differences in the way each is processed. The major differences are that an E39 exit routine is not entered for OUTFIL data sets, and that OUTFIL processing does not permit the use of the LRECL value to pad fixed-format OUTFIL records. (DFSORT will automatically determine and set an appropriate RECFM, LRECL, and BLKSIZE for each OUTFIL data set for which these attributes are not specified or available.) For a single DFSORT application, OUTFIL data sets can be intermixed with respect to VSAM and non-VSAM, tape and disk, and so on. All of the data sets specified for a particular OUTFIL statement are processed in a similar way and thus are referred to as an OUTFIL group. (That is, you group OUTFIL data sets that use the same operands by specifying them on a single OUTFIL statement.) For example, the first OUTFIL statement might have an INCLUDE operand that applies to an OUTFIL group of one non-VSAM data set on disk and another on
Chapter 3. Using DFSORT Program Control Statements

223

OUTFIL Control Statements

tape; a second OUTFIL statement might have OMIT and OUTREC operands that apply to an OUTFIL group of one non-VSAM data set on disk and two VSAM data sets. Records are processed for OUTFIL as they are for SORTOUT, after all other DFSORT processing is complete. Conceptually, you can think of an OUTFIL input record as being intercepted at the point between being passed from an E35 exit and written to SORTOUT, although neither an E35 exit nor SORTOUT need actually be specified with OUTFIL processing. With that in mind, see Figure 2 on page 9 for details on the processing that occurs prior to processing the OUTFIL input record. In particular: Records deleted by an E15 or E35 exit, an INCLUDE, OMIT or SUM statement, or the SKIPREC or STOPAFT parameter are not available for OUTFIL processing If records are reformatted by an E15 exit, an INREC or OUTREC statement, or an E35 exit, the resulting reformatted record is the OUTFIL input record to which OUTFIL fields must refer. v STARTREC starts processing for an OUTFIL group at a specific OUTFIL input record. ENDREC ends processing for an OUTFIL group at a specific OUTFIL input record. SAMPLE selects a sample of OUTFIL input records for an OUTFIL group using a specific interval and number of records in that interval. Separately or together, STARTREC, ENDREC, and SAMPLE select a range of records to which subsequent OUTFIL processing will apply. v INCLUDE, OMIT, and SAVE select the records to be included in the data sets of an OUTFIL group. INCLUDE and OMIT operate against the specified fields of each OUTFIL input record to select the output records for their OUTFIL group (all records are selected by default). SAVE selects the records that are not selected for any other OUTFIL group. Whereas the INCLUDE and OMIT statements apply to all input records, the INCLUDE and OMIT parameters apply only to the OUTFIL input records for their OUTFIL group. The INCLUDE and OMIT parameters have all of the logical expression capabilities of the INCLUDE and OMIT statements. v PARSE, OUTREC, BUILD, OVERLAY, or IFTHEN reformat the output records for an OUTFIL group. These parameters allow you to rearrange, edit, and change fixed position/length fields or variable position/length fields from the OUTFIL input records and to insert blanks, zeros, strings, current date, future date, past date, current time, sequence numbers, decimal constants, and the results of arithmetic expressions. OVERLAY allows you to change specific existing columns without affecting the entire record. IFTHEN clauses allow you to reformat different records in different ways according to the criteria you specify. IFOUTLEN can be used with IFTHEN clauses to set the output LRECL. OUTREC or BUILD gives you complete control over the items in your reformatted records and the order in which they appear, and also allows you to produce multiple reformatted output records from each input record, with or without intervening blank output records. VTOF or CONVERT can be used with OUTREC or BUILD to convert variable-length input records to fixed-length output records. VLFILL can be used to allow processing of variable-length input records which are too short to contain all specified OUTREC or BUILD fields. Whereas the FIELDS, BUILD, OVERLAY, and IFTHEN parameters of the OUTREC statement apply to all input records, the OUTREC, BUILD, OVERLAY, and IFTHEN parameters of the OUTFIL statement apply only to the OUTFIL

224

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

input records for its OUTFIL group. In addition, the OUTREC and BUILD parameters of the OUTFIL statement support the forward slash (/) separator for creating blank records and new records, whereas the FIELDS and BUILD parameters of the OUTREC statement do not. v FTOV can be used to convert fixed-length input records to variable-length output records. FTOV can be used with or without OUTREC, BUILD, OVERLAY, or IFTHEN. v VLTRIM can be used to remove the trailing bytes with a specified value, such as blanks, binary zeros or asterisks, from variable-length records. VLTRIM can be used with or without FTOV. v REPEAT can be used to repeat each output record a specified number of times. v SPLIT, SPLITBY, or SPLIT1R splits the output records in rotation among the data sets of an OUTFIL group. With SPLIT, the first output record is written to the first OUTFIL data set in the group, the second output record is written to the second data set, and so on. When each OUTFIL data set has one record, the rotation starts again with the first OUTFIL data set. SPLITBY can be used to rotate by a specified number of records rather than by one record, for example, records 1-10 to the first OUTFIL data set, records 11-20 to the second OUTFIL data set, and so on. When each OUTFIL data set has n records, the rotation starts again with the first OUTFIL data set. SPLIT1R can be used to rotate once by a specified number of records. SPLIT1R continues with the last OUTFIL data set instead of rotating back to the first OUTFIL data set. When each OUTFIL data set has n records, the last OUTFIL data set will have the remainder of the records even if that is more than n. v LINES, HEADER1, TRAILER1, HEADER2, TRAILER2, SECTIONS, and NODETAIL indicate that a report is to be produced for an OUTFIL group, and specify the details of the report records to be produced for the report. Reports can contain report records for a report header (first page), report trailer (last page), page header and page trailer (at the top and bottom of each page, respectively), and section headers and trailers (before and after each section, respectively). Data records for the report result from the inclusion of OUTFIL input records. All of the capabilities of the OUTREC, BUILD, OVERLAY, or IFTHEN parameters are available to create reformatted data records from the OUTFIL input records. Each set of sequential OUTFIL input records, with the same binary value for a specified field, results in a corresponding set of data records that is treated as a section in the report. The length for the data records must be equal to or greater than the maximum report record length. OUTFIL data sets used for reports must have or will be given ANSI control character format (A as in, for example, RECFM=FBA or RECFM=VBA), and must allow an extra byte in the LRECL for the carriage control character that DFSORT will add to each report and data record. DFSORT uses these carriage control characters to control page ejects and the placement of the lines in your report according to your specifications. DFSORT uses appropriate carriage controls (for example, C- for triple space) in header and trailer records when possible, to reduce the number of report records written. DFSORT always uses the single space carriage control (C ) in data records. Although these carriage control characters may not be shown when you view an OUTFIL data set (depending upon how you view it), they will be used if you print the report.

Chapter 3. Using DFSORT Program Control Statements

225

OUTFIL Control Statements

v BLKCCH1, BLKCCT1 or BLKCCH2 can be used avoid forcing a page eject for the report header, report trailer or first page header, respectively, by using a blank instead of a 1 for the ANSI control carriage character of its first line. v REMOVECC can be used to remove the ANSI control characters from a report. In this case, an A is not added to or required for the RECFM and an extra byte is not added to or required for the LRECL. v Figure 13 illustrates the order in which OUTFIL records and parameters are processed.

OUTFIL input records

OUTFIL STARTREC OUTFIL SAMPLE OUTFIL ENDREC

OUTFIL INCLUDE OUTFIL OMIT OUTFIL SAVE

OUTFIL PARSE OUTFIL OUTREC, BUILD, OVERLAY, or IFTHEN OUTFIL FTOV OUTFIL VTOF or CONVERT OUTFIL VLFILL OUTFIL VLTRIM OUTFIL REPEAT OUTFIL Reports

OUTFIL SPLIT OUTFIL SPLITBY OUTFIL SPLIT1R

OUTFIL Data Sets

Figure 13. OUTFIL Processing Order

Notes: 1. DFSORT accepts but does not process the following OUTFIL operands: BLKSIZE=value, BUFLIM=value, BUFOFF=value, CARDS=value, CLOSE=value, DISK, ESDS, EXIT, FREEOUT, KSDS, LRECL=value, NOTPMK, OPEN=value, OUTPUT, PAGES=value, PRINT, PUNCH, REUSE, RRDS, SPAN, SYSLST, TAPE, and TOL. 2. Sample syntax is shown throughout this section. Complete OUTFIL statement examples are shown and explained under OUTFIL FeaturesExamples on page 344. FNAMES

226

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

FNAMES= ddname , ( ddname )

Specifies ddnames associated with the OUTFIL data sets for this OUTFIL statement. The ddnames specified using the FNAMES and FILES parameters constitute the output data sets for this OUTFIL group to which all of the other parameters for this OUTFIL statement apply. If FNAMES specifies the ddname in effect for the SORTOUT data set (that is, whichever is in effect among SORTOUT, name from SORTOUT=name, or ccccOUT from SORTDD=cccc), DFSORT will treat the data set associated with that ddname as an OUTFIL data set rather than as the SORTOUT data set. ddname specifies a 1- through 8-character ddname. A DD statement must be present for this ddname. Sample Syntax:
OUTFIL FNAMES=(OUT1,OUT2,PRINTER,TAPE) OUTFIL FNAMES=BACKUP

Default for FNAMES: If neither FNAMES nor FILES is specified for an OUTFIL statement, the default ddname is SORTOUT or ccccOUT if SORTDD=cccc is in effect. FILES

FILES=

d dd OUT , ( d dd OUT )

Specifies suffixes for ddnames to be associated with the OUTFIL data sets for this OUTFIL statement. The ddnames specified using the FNAMES and FILES parameters constitute the output data sets for this OUTFIL group to which all of the other parameters for this OUTFIL statement apply. If FILES specifies the ddname in effect for the SORTOUT data set (that is, whichever is in effect among SORTOUT, name from SORTOUT=name, or ccccOUT from SORTDD=cccc), DFSORT will treat the data set associated with that ddname as an OUTFIL data set rather than as the SORTOUT data set. d specifies the 1-character suffix to be used to form the ddname SORTOFd or ccccOFd if SORTDD=cccc is in effect. A DD statement must be present for this ddname.

dd specifies the 2-character suffix to be used to form the ddname SORTOFdd or ccccOFdd if SORTDD=cccc is in effect. A DD statement must be present for this ddname.
Chapter 3. Using DFSORT Program Control Statements

227

OUTFIL Control Statements

OUT specifies the suffix OUT is to be used to form the ddname SORTOUT or ccccOUT if SORTDD=cccc is in effect. A DD statement must be present for this ddname. Sample Syntax:
OUTFIL FILES=(1,2,PR,TP) OUTFIL FILES=OUT

Default for FILES: If neither FNAMES nor FILES is specified for an OUTFIL statement, the default ddname is SORTOUT or ccccOUT if SORTDD=cccc is in effect. STARTREC

STARTREC=n

Specifies the OUTFIL input record at which OUTFIL processing is to start for this OUTFIL group. OUTFIL input records before this starting record are not included in the data sets for this OUTFIL group. n specifies the relative record number. The value for n starts at 1 (the first record) and is limited to 28 digits (15 significant digits).

Sample Syntax:
OUTFIL FNAMES=SKIP20,STARTREC=21

Default for STARTREC: 1. ENDREC

ENDREC=n

Specifies the OUTFIL input record at which OUTFIL processing is to end for this OUTFIL group. OUTFIL input records after this ending record are not included in the data sets for this OUTFIL group. The ENDREC value must be equal to or greater than the STARTREC value if both are specified on the same OUTFIL statement. n specifies the relative record number. The value for n starts at 1 (the first record) and is limited to 28 digits (15 significant digits).
OUTFIL OUTFIL OUTFIL OUTFIL FNAMES=TOP10,ENDREC=10 FNAMES=FRONT,ENDREC=500 FNAMES=MIDDLE,STARTREC=501,ENDREC=2205 FNAMES=BACK,STARTREC=2206

Sample Syntax:

Default for ENDREC: The last OUTFIL input record. SAMPLE

228

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

SAMPLE= n (n,m)

Specifies a sample of OUTFIL input records to be processed for this OUTFIL group. The sample consists of the first m records in every nth interval. n m specifies the interval size. The value for n starts at 2 (sample every other record) and is limited to 28 digits (15 significant digits). specifies the number of records to be processed in each interval. The value for m starts at 1 (process the first record in each interval) and is limited to 28 digits (15 significant digits). If m is not specified, 1 is used for m. If m is specified, it must be less than n.

Sample Syntax:
* PROCESS RECORDS 1, 6, 11, ... OUTFIL FNAMES=OUT1,SAMPLE=5 * PROCESS RECORDS 1, 2, 1001, 1002, 2001, 2002 OUTFIL FNAMES=OUT2,SAMPLE=(1000,2),ENDREC=2500 * PROCESS RECORDS 23, 48, 73 OUTFIL FNAMES=OUT3,STARTREC=23,ENDREC=75,SAMPLE=25 * PROCESS RECORDS 1001, 1002, 1003, 1101, 1102, 1103, ... OUTFIL FNAMES=OUT4,STARTREC=1001,SAMPLE=(100,3)

Default for SAMPLE: None; must be specified. INCLUDE

INCLUDE=

(logical expression) ALL NONE

Selects the records to be included in the data sets for this OUTFIL group. The INCLUDE parameter operates in the same way as the INCLUDE statement, except that: v The INCLUDE statement applies to all input records; the INCLUDE parameter applies only to the OUTFIL input records for its OUTFIL group. v FORMAT=f can be specified with the INCLUDE statement, but not with the INCLUDE parameter. Thus, you can use FORMAT=f and p,m or p,m,f fields with the INCLUDE statement, but you must only use p,m,f fields with the INCLUDE parameter. For example:
INCLUDE FORMAT=BI, COND=(5,4,LT,11,4,OR,21,4,EQ,31,4,OR, 61,20,SS,EQ,CFLY) OUTFIL INCLUDE=(5,4,BI,LT,11,4,BI,OR,21,4,BI,EQ,31,4,BI,OR, 61,20,SS,EQ,CFLY)

v D2 format can be specified with the INCLUDE statement, but not with the INCLUDE parameter. See INCLUDE Control Statement on page 98 for complete details.
Chapter 3. Using DFSORT Program Control Statements

229

OUTFIL Control Statements

logical expression specifies one or more relational conditions logically combined based on fields in the OUTFIL input record. If the logical expression is true for a given record, the record is included in the data sets for this OUTFIL group. | | ALL NONE specifies that all of the OUTFIL input records are to be included in the data sets for this OUTFIL group. specifies that none of the OUTFIL input records are to be included in the data sets for this OUTFIL group.

Sample Syntax:
OUTFIL FNAMES=J69,INCLUDE=(5,3,CH,EQ,CJ69) OUTFIL FNAMES=J82,INCLUDE=(5,3,CH,EQ,CJ82)

Default for INCLUDE: ALL. OMIT

OMIT=

(logical expression) ALL NONE

Selects the records to be omitted from the data sets for this OUTFIL group. The OMIT parameter operates in the same way as the OMIT statement, except that: v The OMIT statement applies to all input records; the OMIT parameter applies only to the OUTFIL input records for its OUTFIL group. v FORMAT=f can be specified with the OMIT statement, but not with the OMIT parameter. Thus, you can use FORMAT=f and p,m or p,m,f fields with the OMIT statement, but you must only use p,m,f fields with the OMIT parameter. For example:
OMIT FORMAT=BI, COND=(5,4,LT,11,4,OR,21,4,EQ,31,4,OR, 61,20,SS,EQ,CFLY) OUTFIL OMIT=(5,4,BI,LT,11,4,BI,OR,21,4,BI,EQ,31,4,BI,OR, 61,20,SS,EQ,CFLY)

v The D2 format can be specified with the OMIT statement, but not with the OMIT parameter. See OMIT Control Statement on page 163 and INCLUDE Control Statement on page 98 for complete details. logical expression specifies one or more relational conditions logically combined based on fields in the OUTFIL input record. If the logical expression is true for a given record, the record is omitted from the data sets for this OUTFIL group. | ALL specifies that all of the OUTFIL input records are to be omitted from the data sets for this OUTFIL group.

230

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

| NONE specifies that none of the OUTFIL input records are to be omitted from the data sets for this OUTFIL group. Sample Syntax:
OUTFIL FILES=01,OMIT=NONE OUTFIL OMIT=(5,1,BI,EQ,B110.....) OUTFIL FNAMES=(OUT1,OUT2), OMIT=(7,2,CH,EQ,C32,OR,18,3,CH,EQ,CXYZ)

Default for OMIT: NONE. SAVE

SAVE

Specifies that OUTFIL input records not included by STARTREC, ENDREC, SAMPLE, INCLUDE or OMIT for any other OUTFIL group are to be included in the data sets for this OUTFIL group. SAVE operates in a global fashion over all of the other OUTFIL statements for which SAVE is not specified, enabling you to keep any OUTFIL input records that would not be kept otherwise. SAVE will include the same records for each group for which it is specified. Sample Syntax:
OUTFIL INCLUDE=(8,6,CH,EQ,CACCTNG),FNAMES=GP1 OUTFIL INCLUDE=(8,6,CH,EQ,CDVPMNT),FNAMES=GP2 OUTFIL SAVE,FNAMES=NOT1OR2

Default for SAVE: None; must be specified. PARSE

, , PARSE=( %nn= %= ( FIXLEN=m ABSPOS=p ADDPOS=x SUBPOS=y , STARTAFT=string STARTAFT=BLANKS STARTAT=string STARTAT=BLANKS STARTAT=NONBLANK , ENDBEFR=string ENDBEFR=BLANKS ENDAT=string ENDAT=BLANKS PAIR=APOST PAIR=QUOTE ) )

Chapter 3. Using DFSORT Program Control Statements

231

OUTFIL Control Statements

This operand allows you to extract variable position/length fields into fixed parsed fields. Parsed fields (%nn) can be used where fixed position/length fields (p,m) can be used in the BUILD (or OUTREC) or OVERLAY operands as described later in this section. PARSE can be used for many different types of variable fields including delimited fields, comma separated values (CSV), tab separated values, blank separated values, keyword separated fields, null-terminated strings, and so on. You can assign up to 100 %nn parsed fields (%00-%99) to the variable fields you want to extract. Note that if all of the fields in your records have fixed positions and lengths, you dont need to use PARSE. But if any of the fields in your records have variable positions or lengths, you can use PARSE to treat them as fixed parsed fields in BUILD or OVERLAY. You can mix p,m fields (fixed fields) and %nn fields (parsed fields) in BUILD and OVERLAY. For each %nn parsed field, you define where the data to be extracted starts and ends, and the length (m) of the fixed field to contain the extracted data. For example, if your input records contained CSV data as follows:
AA,BBBB,C,DDDDD EEEEE,,F,GG HHH,IIIII,JJ,K

and you wanted to reformat the data into fixed positions like this:
AA EEEEE HHH BBBB IIIII C F JJ DDDDD GG K

you could use this OUTFIL statement:

OUTFIL PARSE=(%01=(ENDBEFR=C,,FIXLEN=5), %02=(ENDBEFR=C,,FIXLEN=5), %03=(ENDBEFR=C,,FIXLEN=5), %04=(FIXLEN=5)), BUILD=(1:%01,11:%02,21:%03,31:%04)

The PARSE operand: v assigns %01 to the first parsed field, and defines it as starting at position 1 and ending before the next (first) comma with a fixed length of 5 bytes v assigns %02 to the second parsed field, and defines it as starting after the (first) comma and ending before the next (second) comma with a fixed length of 5 bytes v assigns %03 to the third parsed field, and defines it as starting after the (second) comma and ending before the next (third) comma with a fixed length of 5 bytes v assigns %04 to the fourth parsed field, and defines it as starting after the (third) comma and ending after 5 bytes with a fixed length of 5 bytes You can start extracting data at a specific position (ABSPOS=p), a relative position (ADDPOS=x or SUBPOS=y), after the start of one or more specific strings (STARTAFT=string) or blanks (STARTAFT=BLANKS), or at the start of one or more specific strings (STARTAT=string) or blanks (STARTAT=BLANKS) or a nonblank (STARTAT=NONBLANK). You can end extracting data before the start of one or more specific strings (ENDBEFR=string) or blanks (ENDBEFR=BLANKS), at the end of one or more specific strings (ENDAT=string) or blanks (ENDAT=BLANKS), or after a specified number of bytes (FIXLEN=m without ENDBEFR or ENDAT).

232

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

For each record, each %nn and % parsed field you define is processed according to the suboperands you define, in the following order: v ABSPOS or ADDPOS or SUBPOS v STARTAFT, STARTAT and PAIR v ENDBEFR, ENDAT and PAIR v FIXLEN As each %nn parsed field is processed, data is extracted according to the suboperands you specify. In addition, as each %nn or % parsed field is processed, the Start Pointer for the next parsed field advances through the record according to the suboperands you specify. By default, for the first parsed field, the Start Pointer is set to position 1 for fixed-length records or to position 5 for variable-length records, and the Start Pointer for each subsequent %nn parsed field uses the Start Pointer as set by the previous %nn parsed field. For any parsed field, the Start Pointer advances as follows depending on the suboperands specified, and may advance more than once (for example, if STARTAFT and ENDBEFR are both specified, or if STARTAT and FIXLEN are both specified): v if ABSPOS=p is specified, the Start Pointer is set to position p. v if ADDPOS=x is specified, the Start Pointer is incremented by x. v if SUBPOS=y is specified, the Start Pointer is decremented by y. v if STARTAFT=string or STARTAT=string is specified, the search for string starts at the Start Pointer. If string is found, the Start Pointer is set to the byte after the end of the string. If string is not found, the current parsed field and any subsequent parsed fields contain all blanks. v if STARTAFT=BLANKS or STARTAT=BLANKS is specified, the search for blanks starts at the Start Pointer. If a blank is found, the Start Pointer is set to the next nonblank. If a blank is not found, the current parsed field and any subsequent parsed fields contain all blanks. v if STARTAT=NONBLANK is specified, the search for a nonblank starts at the Start Pointer. If a nonblank is found, the Start Pointer is set to the nonblank. If a nonblank is not found, the current parsed field and any subsequent parsed fields contain all blanks. v if ENDBEFR=string or ENDAT=string is specified, the search for string starts at the Start Pointer. If string is found, the Start Pointer is set to the byte after the end of the string. If string is not found, data for this parsed field is extracted up to the end of the record. Subsequent parsed fields contain all blanks. v if ENDBEFR=BLANKS or ENDAT=BLANKS is specified, the search for blanks starts at the Start Pointer. If a blank is found, the Start Pointer is set to the next nonblank. If a blank is not found, data for this parsed field is extracted up to the end of the record. Subsequent parsed fields contain all blanks. v if ENDBEFR and ENDAT are not specified and FIXLEN=m is specified, the Start Pointer is set m bytes past the start of the extracted data. v if the Start Pointer advances past the end of the record, PARSE processing stops. For example, if you had these records as input:
11*+23 NEW MAXCC=00 (Monica) 18 1*-6 OLD MAXCC=04 (Joey) -2735 232*+86342 SHR MAXCC=04 (Rachel) 0

Chapter 3. Using DFSORT Program Control Statements

233

OUTFIL Control Statements

and you wanted this output:
Monica Joey Rachel MAXCC=00 +000023 011 18 MAXCC=04 -000006 001 -2735 MAXCC=04 +086342 232 0

you could use this OUTFIL statement:

OUTFIL FNAMES=OUT1, PARSE=(%00=(ENDBEFR=C*,FIXLEN=3), %01=(ENDBEFR=BLANKS,FIXLEN=6), %02=(STARTAT=CMAX,FIXLEN=8), %03=(STARTAFT=C(,ENDBEFR=C),FIXLEN=6), %04=(STARTAFT=BLANKS,FIXLEN=5)), BUILD=(%03,11:%02,21:%01,SFF,M26,LENGTH=7, 30:%00,UFF,M11,LENGTH=3,35:%04,JFY=(SHIFT=RIGHT))

For this example, the Start Pointer advances as follows for the first record: v For %00: Set Start Pointer to position 1. Start searching for * end string at position 1. Extract 11 (per ENDBEFR=C*). Set Start Pointer after * (at +). v For %01: Start searching for end blank at the Start Pointer (at +). Extract +23 (per ENDBEFR=BLANKS). Set Start Pointer after the blanks (at N). v For %02: Start searching for MAX start string at the Start Pointer (at N). Extract MAXCC=00 (per FIXLEN=8). Increment Start Pointer by m (8) bytes from the start of the extracted string (at blank after 00). v For %03: Start searching for ( start string at Start Pointer (at blank after 00). Set Start Pointer after ( (at M). Start searching for ) end string at Start Pointer (at M). Extract Monica (per ENDBEFR=C)). Set Start Pointer after ) (at blank after )). v For %04: Start searching for start blank at the Start Pointer (at blank after )). Extract 18 (per FIXLEN=5). If the Start Pointer advances past the end of the record, PARSE processing stops. For example, if you had these input records:
First=George Last=Washington First=John Middle=Quincy Last=Adams

and you used this OUTFIL statement:

OUTFIL FNAMES=OUT1, PARSE=(%00=(STARTAFT=CFirst=,ENDBEFR=C ,FIXLEN=12), %01=(STARTAFT=CMiddle=,ENDBEFR=C ,FIXLEN=12), %02=(STARTAFT=CLast=,ENDBEFR=C ,FIXLEN=12)), BUILD=(%00,%01,%02)

the %01 parsed field (middle name) is not found in the first record, so PARSE processing stops and the %02 parsed field is set to blanks. You can handle this kind of possible missing field situation by using IFTHEN PARSE instead of PARSE. For example:
OUTFIL FNAMES=OUT1, IFTHEN=(WHEN=INIT, PARSE=(%00=(STARTAFT=CFirst=,ENDBEFR=C ,FIXLEN=12))), IFTHEN=(WHEN=INIT, PARSE=(%01=(STARTAFT=CMiddle=,ENDBEFR=C ,FIXLEN=12))), IFTHEN=(WHEN=INIT, PARSE=(%02=(STARTAFT=CLast=,ENDBEFR=C ,FIXLEN=12)), BUILD=(%00,%01,%02))

By default, the Start Pointer is set to 1 (F) or 5 (V) for each IFTHEN PARSE, so the missing middle name in the first record does not prevent the last name from being extracted.

234

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

See the discussion of IFTHEN for more information on IFTHEN PARSE. You must define each %nn field with PARSE before you use it in BUILD or OVERLAY, so generally you would want to specify PARSE before BUILD or OVERLAY. If you define a %nn field with PARSE, but do not use it in BUILD or OVERLAY, data will not be extracted for that parsed field. Each %nn parsed field (%00-%99) can only be defined once per run with PARSE, but can be used as many times as needed in BUILD or OVERLAY. The %nn parsed fields defined for a particular source (INREC, OUTREC or OUTFIL) can only be used in the BUILD or OVERLAY operands for that source. Generally, you will only use PARSE for one source (for example, INREC) per run. But you could define a separate set of %nn parsed fields for each source, if needed. For example, you could define %21 and %22 for the INREC statement, %01, %02 and %03 for the OUTREC statement, %40 and %45 for OUTFIL statement 1, and %30, %31 and %32 for OUTFIL statement 2. You could then use %21 and %22 for INREC BUILD or OVERLAY, %02 and %03 for OUTREC BUILD or OVERLAY, %40 and %45 for OUTFIL statement 1 BUILD or OVERLAY, and %30, %31 and %32 for OUTFIL statement 2 BUILD or OVERLAY. Note that you could not, for example, use %21 and %22 for OUTREC BUILD or OVERLAY. If you specify PARSE=(...),IFTHEN=(...) or IFTHEN=(...),PARSE=(...), DFSORT will terminate. If you need to specify PARSE with IFTHEN, specify it within one or more individual IFTHEN clauses, as appropriate. For details, see the description of IFTHEN. %nn Assigns %nn to a parsed field. The variable-length data defined for the parsed field is extracted to a fixed length area (padded with blanks or truncated as appropriate) and can be used where a p,m field can be used in BUILD or OVERLAY. nn can be 00 to 99, but each %nn value can only be defined once per run. This gives you a maximum of 100 parsed fields per run. %0 to %9 can be used, but will be treated as equivalent to %00 to %09. You can use %n and %0n interchangeably, but you cannot define both %n and %0n in the same run. Sample Syntax
OUTFIL PARSE=(%99=(ABSPOS=6,STARTAT=CKW=(,ENDAT=C),FIXLEN=20), %03=(STARTAFT=BLANKS,FIXLEN=10)), OVERLAY=(1:1,5,%03,C=,%99,1:1,36,SQZ=(SHIFT=LEFT))

% Specifies a parsed field to be ignored. No data is extracted, but the starting point for the next parsed field advances according to the suboperands specified. Use % when you dont need the data from a particular field, but you do need to get to the next field. For example, if we had the four CSV fields shown earlier as input, but we only wanted to extract the first and fourth fields, we could use this OUTFIL statement:
OUTFIL PARSE=(%01=(ENDBEFR=C,,FIXLEN=5), %=(ENDBEFR=C,), %=(ENDBEFR=C,), %04=(FIXLEN=5)), BUILD=(1:%01,11:%04,21:%01,HEX)

Data is extracted for %01 (first field) and %04 (fourth field), but not for % (second and third fields).

Chapter 3. Using DFSORT Program Control Statements

235

OUTFIL Control Statements

FIXLEN=m Specifies the length (m) of the fixed area to contain the extracted variable-length data for this %nn fixed parsed field. m can be 1 to 32752. You must specify FIXLEN=m for each %nn parsed field. FIXLEN=m is optional for a % ignored field. When %nn is specified in BUILD or OVERLAY, the variable-length data is extracted to the fixed area and then used for BUILD or OVERLAY processing. The fixed area always contains m bytes. If the extracted data is longer than m, the fixed area contains the first m bytes of the extracted data (the data is truncated on the right to m bytes). If the extracted data is shorter than m, the fixed area contains the extracted data padded with blanks on the right to m bytes. If no data is extracted, the fixed area contains all blanks. The length m from FIXLEN=m for fixed parsed fields (%nn) corresponds to the length (m) for fixed fields (p,m). Keep in mind that %nn fields are left-aligned and may be padded on the right with blanks. You must ensure that the data in each %nn field and its length (m) are valid for the way you want to use that %nn field in BUILD or OVERLAY. For example, if you had these records as input:
123,8621 1,302 18345,17

and you wanted this output:

1.23 0.01 183.45 86.21 3.02 0.17

you could use this OUTFIL statement:

OUTFIL PARSE=(%00=(ENDBEFR=C,,FIXLEN=5), %01=(FIXLEN=5)), BUILD=(%00,UFF,EDIT=(IIT.TT),2X,%01,UFF,EDIT=(IIT.TT))

Note that the 5-byte extracted parsed fields for %00 are left-aligned and padded with blanks (b) like this:
123bb 1bbbb 18345

and the 5-byte extracted parsed fields for %01 are left-aligned and padded with blanks (b) like this:
8621b 302bb 17bbb

Thus, you cannot use numeric formats like ZD or FS for these parsed fields, but you can use UFF. Note also that you must ensure that m from FIXLEN=m for each %nn parsed field is valid for the specific BUILD or OVERLAY item in which you use %nn. For example, you could use 1-44 as m for UFF, but you couldnt use 45 as m. If ENDBEFR and ENDAT are not specified, the Start Pointer is set m bytes past the start of the extracted data. For example, if you had this record as input:
MAX=(ABCDEF)

and you specified:

236

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

OUTFIL PARSE=(%00=(STARTAT=CMAX,FIXLEN=8), %01=(FIXLEN=3),%02=(FIXLEN=1)), BUILD=(%00,12:%01,20:%02)

The output record would be:

MAX=(ABC DEF )

Sample Syntax
OUTFIL PARSE=(%00=(STARTAFT=CKW=,FIXLEN=12)), BUILD=(%00)

ABSPOS=p Sets the Start Pointer for this parsed field to p. p can be 1 to 32752. By default, the Start Pointer for the first %nn parsed field is position 1 for fixed-length records or position 5 for variable-length records, and the Start Pointer for each subsequent %nn parsed field is the Start Pointer set by the previous %nn field. You can use ABSPOS=p to set the Start Pointer to position p to override the default Start Pointer. If the resulting Start Pointer is less than position 5 for variable length records, it will be set to position 5. Example If your input is:
****|BB|CCCC| ****|EEEE|FF|

and you wanted to reformat the data into fixed positions like this:
**** BB CCCC **** EEEE FF

you could use this OUTFIL statement:

OUTFIL PARSE=(%01=(ABSPOS=6,ENDBEFR=C|,FIXLEN=4), %02=(ENDBEFR=C|,FIXLEN=4)), BUILD=(1,4,X,%01,X,%02)

The initial Start Pointer for the %01 parsed field is set to position 6 instead of to position 1. ADDPOS=x Increments the Start Pointer for this parsed field by x. x can be 1 to 32752. By default, the Start Pointer for the first %nn parsed field is position 1 for fixed-length records or position 5 for variable-length records, and the Start Pointer for each subsequent %nn parsed field is the Start Pointer set by the previous %nn field. You can use ADDPOS=x to increment the Start Pointer by x to override the default Start Pointer. Sample Syntax
OUTFIL PARSE=(%00=(ENDAT=C||,FIXLEN=10), %01=(ADDPOS=5,STARTAFT=C;,FIXLEN=6)), BUILD=(%00,TRAN=ALTSEQ,%01)

SUBPOS=y Decrements the Start Pointer for this parsed field by y. y can be 1 to 32752. By default, the Start Pointer for the first %nn parsed field is position 1 for fixed-length records or position 5 for variable-length records, and the Start Pointer for each subsequent %nn parsed field is the Start Pointer set by the previous %nn field. You can use SUBPOS=y to decrement the Start Pointer by x to override the default Start Pointer. If the resulting Start Pointer is

Chapter 3. Using DFSORT Program Control Statements

237

OUTFIL Control Statements

less than position 1 for fixed-length records, it will be set to position 1. If the resulting Start Pointer is less than position 5 for variable-length records, it will be set to position 5. Sample Syntax
OUTFIL PARSE=(%00=(ENDBEFR=C|;|,FIXLEN=10), %01=(SUBPOS=1,STARTAT=C|,ENDAT=C|,FIXLEN=12)), BUILD=(%00,TRAN=ALTSEQ,%01)

STARTAFT=string Data is to be extracted for this parsed field starting after the last byte of the specified string. The search for the string begins at the Start Pointer. If the specified string is not found, data is not extracted for this parsed field or any subsequent parsed fields. If the specified string is found, data is extracted to the fixed area for this parsed field starting at the byte after the end of the string, and the Start Pointer is set to the byte after the end of the string. string can be 1 to 256 characters specified using a character string constant (Cxx...x) or a hexadecimal string constant (Xyy...yy). See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. Example If your input is:
MAX=25,832 MAX=1,275 MIN=17 %3 MIN=2,831 $4

and you wanted your output to contain MAX-MIN, you could use this OUTFIL statement:
OUTFIL PARSE=(%00=(STARTAFT=CMAX=,ENDBEFR=X40,FIXLEN=6), %01=(STARTAFT=CMIN=,ENDBEFR=X40,FIXLEN=6)), OVERLAY=(50:CDELTA: ,%00,UFF,SUB,%01,UFF,TO=ZD,LENGTH=8)

STARTAFT=BLANKS Data is to be extracted for this parsed field starting at the first nonblank after one or more blanks. The search for a blank begins at the Start Pointer. If a blank is not found, data is not extracted for this parsed field or any subsequent parsed fields. If a blank is found, data is extracted to the fixed area for this parsed field starting at the first nonblank, and the Start Pointer is set to the first nonblank. Example If your input is:
Frank Vicky D28 D52

and you wanted your output to be:

Frank Vicky D28 D52

you could use this OUTFIL statement:

OUTFIL PARSE=(%00=(STARTAFT=BLANKS,FIXLEN=8), %01=(STARTAFT=BLANKS,FIXLEN=3)), BUILD=(%00,14:%01)

STARTAT=string Data is to be extracted for this parsed field starting at the first byte of the specified string. The search for the string begins at the Start Pointer. If the

238

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

specified string is not found, data is not extracted for this parsed field or any subsequent parsed fields. If the specified string is found, data is extracted to the fixed area for this parsed field starting at the first byte of the string, and the Start Pointer is set to the byte after the end of the string. string can be 1 to 256 characters specified using a character string constant (Cxx...x) or a hexadecimal string constant (Xyy...yy). See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. Example If your input is:
MAX=58321 MIN=00273 MAX=01275 MIN=00017

and you wanted your output to be:

MAX=58321 MIN=00273 MAX=01275 MIN=00017

you could use this OUTFIL statement:

OUTFIL PARSE=(%00=(STARTAT=CMAX=,FIXLEN=9), %01=(STARTAT=CMIN=,FIXLEN=9)), BUILD=(%00,X,%01)

STARTAT=BLANKS Data is to be extracted for this parsed field starting at the first blank. The search for a blank begins at the Start Pointer. If a blank is not found, data is not extracted for this parsed field or any subsequent parsed fields. If a blank is found, data is extracted to the fixed area for this parsed field starting at the first blank, and the Start Pointer is set to the first nonblank. STARTAT=NONBLANK Data is to be extracted for this parsed field starting at the first nonblank. The search for a nonblank begins at the Start Pointer. If a nonblank is not found, data is not extracted for this parsed field or any subsequent parsed fields. If a nonblank is found, data is extracted to the fixed area for this parsed field starting at the nonblank, and the Start Pointer is set to the nonblank. Example If your input is:
Frank D28 Victoria Holly D15 Roberta D52 D52

and you wanted your output to be:

Frank Victoria Holly Roberta D28 D52 D15 D52

you could use this OUTFIL statement:

OUTFIL PARSE=(%00=(STARTAT=NONBLANK,ENDBEFR=BLANKS,FIXLEN=8), %01=(FIXLEN=3)), BUILD=(%00,14:%01)

Chapter 3. Using DFSORT Program Control Statements

239

OUTFIL Control Statements

Note: Multiple STARTAFT/STARTAT strings, BLANKS or NONBLANK can be used for a %nn parsed field to search for more than one string, blanks or a nonblank. The first search satisfied is used. Example If your input is:
12 MAXCC=08 58 MINCC=00 MAXCC=04

and you wanted your output to be:

MAXCC=08 MINCC=00 MAXCC=04

you could use this OUTFIL statement:

OUTFIL PARSE=(%00=(STARTAT=CMAXCC=,STARTAT=CMINCC=, FIXLEN=8)),BUILD=(%00)

ENDBEFR=string Data is to be extracted for this parsed field ending before the first byte of the specified string. The search for the string begins at the Start Pointer. If the specified string is not found, data is extracted to the fixed area for this parsed field up to the end of the record, but data is not extracted for any subsequent parsed fields. If the specified string is found, data is extracted to the fixed area for this parsed field up to the byte before the start of the string, and the Start Pointer is set to the byte after the end of the string. string can be 1 to 256 characters specified using a character string constant (Cxx...x) or a hexadecimal string constant (Xyy...yy). See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. Example If your input is:
Morgan Hill;California;5000: San Jose;California;2000: Austin;Texas;8000:

and you wanted your output to be:

Morgan Hill San Jose Austin California 5000 California 2000 Texas 8000

you could use this OUTFIL statement:

OUTFIL PARSE=(%00=(ENDBEFR=C;,FIXLEN=14), %01=(ENDBEFR=C;,FIXLEN=12), %02=(ENDBEFR=C:,FIXLEN=4)), BUILD=(%00,%01,%02)

ENDBEFR=X00 can be used to extract null-terminated strings to fixed parsed fields. Example If your input contains null-terminated strings that look like this in hex:

240

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

F0F5F800 F1F2F3F4F500 F9F7F2F000 F500 F0F0F3F700

and you wanted to convert the null-terminated strings to right-aligned numeric values like this:
58 12345 9720 5 37

you could use this OUTFIL statement:

OUTFIL PARSE=(%01=(ENDBEFR=X00,FIXLEN=5)), BUILD=(%01,UFF,EDIT=(IIIIT))

ENDBEFR=BLANKS Data is to be extracted for this parsed field ending before the first blank. The search for a blank begins at the Start Pointer. If a blank is not found, data is extracted to the fixed area for this parsed field up to the end of the record, but data is not extracted for any subsequent parsed fields. If a blank is found, data is extracted to the fixed area for this parsed field up to the byte before the blank, and the Start Pointer is set to the first nonblank. Example If your input is:
1 Frank 2 Loretta D28 123 D52 No 58 Yes

and you wanted your output to be:

0123 Frank D28 0058 Loretta D52

you could use this OUTFIL statement:

OUTFIL PARSE=(%00=(STARTAFT=BLANKS,ENDBEFR=BLANKS,FIXLEN=8), %01=(ENDBEFR=BLANKS,FIXLEN=3), %02=(ENDBEFR=C ,FIXLEN=4)), BUILD=(%02,UFF,EDIT=(TTTT),X,%00,%01)

ENDAT=string Data is to be extracted for this parsed field ending at the last byte of the specified string. The search for the string begins at the Start Pointer. If the specified string is not found, data is extracted to the fixed area for this parsed field up to the end of the record, but data is not extracted for any subsequent parsed fields. If the specified string is found, data is extracted to the fixed area for this parsed field up to the last byte of the string, and the Start Pointer is set to the byte after the end of the string string can be 1 to 256 characters specified using a character string constant (Cxx...x) or a hexadecimal string constant (Xyy...yy). See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. Example If your input is:
12,(June) 5852,(Gracie)
Chapter 3. Using DFSORT Program Control Statements

241

OUTFIL Control Statements

and you wanted your output to be:
(June) (Gracie)

you could use this OUTFIL statement:

OUTFIL PARSE=(%00=(STARTAT=C(,ENDAT=C),FIXLEN=12)), BUILD=(%00)

ENDAT=BLANKS Data is to be extracted for this parsed field ending at the last blank before a nonblank. The search for a blank begins at the Start Pointer. If a blank is not found, data is extracted to the fixed area for this parsed field up to the end of the record, but data is not extracted for any subsequent parsed fields. If a blank is found, data is extracted to the fixed area for this parsed field up to the byte before the first nonblank, and the Start Pointer is set to the first nonblank. Note: Multiple ENDBEFR/ENDAT strings or BLANKS can be used for a %nn parsed field to search for more than one string or blanks. The first search satisfied is used. Example If your input is:
12; 58: 04/

and you wanted your output to be:

12 58 04

you could use this OUTFIL statement:

OUTFIL PARSE=(%01=(ENDBEFR=C;,ENDBEFR=C:,ENDBEFR=C/, FIXLEN=10)), BUILD=(%01,UFF,TO=ZD,LENGTH=2,80:X)

PAIR=APOST Do not search for strings or blanks between apostrophe () pairs. Use POST=APOST when you might have strings you are searching for within literals that should not satisfy the search. Once an apostrophe is found, searching is discontinued until another apostrophe is found. Searching then continues after the second apostrophe of the pair. If an unpaired apostrophe is found, strings or BLANKS will not be recognized from that point on, so be careful not to set the Start Pointer in the middle of an apostrophe pair. Do not specify PAIR=APOST if you want to search for a string containing an apostrophe, because the string will not be searched for within the paired apostrophes. Example If your input is:
23,12,567,823,5,032 9,903,18,321,8

and you wanted your output to be:

242

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

23 12,567,823 9,903 18,321 5,032 8

you could use this OUTFIL statement:

OUTFIL PARSE=(%00=(ENDBEFR=C,,FIXLEN=12,PAIR=APOST), %01=(ENDBEFR=C,,FIXLEN=12,PAIR=APOST), %02=(FIXLEN=12)), BUILD=(%00,UFF,EDIT=(II,III,IIT),X, %01,UFF,EDIT=(II,III,IIT),X, %02,UFF,EDIT=(II,III,IIT))

With PAIR=APOST, the commas outside the apostrophe pairs satisfy the search, but the commas within the apostrophe pairs do not satisfy the search. PAIR=QUOTE Do not search for strings or blanks between quote () pairs. Use POST=QUOTE when you might have strings you are searching for within literals that should not satisfy the search. Once a quote is found, searching is discontinued until another quote is found. Searching then continues after the second quote of the pair. If an unpaired quote is found, strings or BLANKS will not be recognized from that point on, so be careful not to set the Start Pointer in the middle of a quote pair. Do not specify PAIR=QUOTE if you want to search for a string containing a quote, because the string will not be searched for within the paired quotes. Example If your input is:
"23","12,567,823","5,032" "9,903","18,321","8"

and you wanted your output to be:

23 12,567,823 9,903 18,321 5,032 8

you could use this OUTFIL statement:

OUTFIL PARSE=(%00=(ENDBEFR=C,,FIXLEN=12,PAIR=QUOTE), %01=(ENDBEFR=C,,FIXLEN=12,PAIR=QUOTE), %02=(FIXLEN=12)), BUILD=(%00,UFF,EDIT=(II,III,IIT),X, %01,UFF,EDIT=(II,III,IIT),X, %02,UFF,EDIT=(II,III,IIT))

With PAIR=QUOTE, the commas outside the quote pairs satisfy the search, but the commas within the quote pairs do not satisfy the search. Default for PARSE: None; must be specified. OUTREC, BUILD, OVERLAY, or IFTHEN

Chapter 3. Using DFSORT Program Control Statements

243

OUTFIL Control Statements

, OUTREC= BUILD= ( , OVERLAY=( , item ) item )

IFTHEN=(clause)

These operands allow you to reformat the OUTFIL input records in this OUTFIL group. You can create the reformatted OUTFIL records in one of the following three ways using unedited, edited, or converted input fields (p,m for fixed fields, or %nn for parsed fields - see PARSE) and a variety of constants: v BUILD or OUTREC: Reformat each record by specifying all of its items one by one. Build gives you complete control over the items you want in your reformatted OUTFIL records and the order in which they appear. You can delete, rearrange and insert fields and constants. Examples:
OUTFIL FNAMES=OUT1,BUILD=(1,20,CABC,26:5C*, 15,3,PD,EDIT=(TTT.TT),21,30,80:X) OUTFIL FNAMES=OUT2, PARSE=(%00=(ENDBEFR=C,,FIXLEN=6), %01=(ENDBEFR=C,,FIXLEN=5), %=(ENDBEFR=C,), %02=(FIXLEN=6)), BUILD=(C|,%01,SFF,ADD,%02,SFF,M4,LENGTH=12, C|,%00,C|)

v OVERLAY: Reformat each record by specifying just the items that overlay specific columns. Overlay lets you change specific existing columns without affecting the entire record. Example:
OUTFIL OVERLAY=(45:45,8,TRAN=LTOU)

v IFTHEN clauses: Reformat different records in different ways by specifying how build or overlay items are applied to records that meet given criteria. IFTHEN clauses let you use sophisticated conditional logic to choose how different record types are reformatted. Example:
OUTFIL IFTHEN=(WHEN=(1,5,CH,EQ,CTYPE1), BUILD=(1,40,C**,+1,TO=PD)), IFTHEN=(WHEN=(1,5,CH,EQ,CTYPE2), BUILD=(1,40,+2,TO=PD,XFFFF)), IFTHEN=(WHEN=NONE),OVERLAY=(45:CNONE))

You can choose to include any or all of the following items in your reformatted OUTFIL records: v Fixed position/length fields or variable position/length fields. For fixed 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, null-terminated strings (and many other types), you define rules that allow DFSORT to extract the relevant data into fixed parsed fields, and then use the parsed fields as you would use fixed fields. v Blanks, binary zeros, character strings, and hexadecimal strings. v Current date, future date, past date, and current time in various forms.

244

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

v Unedited input fields aligned on byte, halfword, fullword, and doubleword boundaries. v Hexadecimal representations of binary input fields. v Left-justified, right-justified, left-squeezed or right-squeezed input fields. v Numeric input fields of various formats converted to different numeric formats, or to character format edited to contain signs, thousands separators, decimal points, leading zeros or no leading zeros, and so on. v Decimal constants converted to different numeric formats, or to character format edited to contain signs, thousands separators, decimal points, leading zeros or no leading zeros, and so on. v The results of arithmetic expressions combining fields, decimal constants, operators (MIN, MAX, MUL, DIV, MOD, ADD and SUB) and parentheses converted to different numeric formats, or to character format edited to contain signs, thousands separators, decimal points, leading zeros or no leading zeros, and so on. v SMF, TOD, and ETOD date and time fields converted to different numeric formats, or to character format edited to contain separators, leading zeros or no leading zeros, and so on. v Two-digit year input dates of various formats converted to four-digit year dates in different numeric formats, or to character format edited to contain separators, leading zeros or no leading zeros, and so on. v Sequence numbers in various formats. v A character constant, hexadecimal constant or input field selected from a lookup table, based on a character, hexadecimal or bit constant as input. OUTREC or BUILD

Chapter 3. Using DFSORT Program Control Statements

245

OUTFIL Control Statements

, OUTREC= BUILD= ( c: s p,m ,a %nn p p,m,HEX %nn,HEX p,HEX p,m,TRAN=LTOU %nn,TRAN=LTOU p,TRAN=LTOU p,m,TRAN=UTOL %nn,TRAN=UTOL p,TRAN=UTOL p,m,TRAN=ALTSEQ %nn,TRAN=ALTSEQ p,TRAN=ALTSEQ p,m,Y2x %nn,Y2x p,m,Y2x(c) %nn,Y2x(c) p,m,Y2xP %nn,Y2xP p,m,f ,edit %nn,f ,to (p,m,f) (%nn,f) deccon ,edit (deccon) ,to arexp ,edit (arexp) ,to p,m,Y2x ,edit ,to %nn,Y2x ,edit ,to p,m,lookup %nn,lookup p,m,justify %nn,justify p,m,squeeze %nn,squeeze seqnum )

Specifies all of the items in the reformatted OUTFIL record in the order in which they are to be included. The reformatted OUTFIL record consists of the separation fields, edited and unedited input fields (p,m for fixed fields, or %nn for parsed fields - see PARSE), edited decimal constants, edited results of arithmetic expressions, and sequence numbers you select, in the order in which you select them, aligned on the boundaries or in the columns you indicate. For variable-length records, the first item in the BUILD or OUTREC parameter must specify or include the unedited 4-byte record descriptor word (RDW), that is, you must start with 1,m with m equal to or greater than 4. If you want to include the bytes from a specific position to the end of each input record at the end of each reformatted output record, you can specify that starting position (p) as the last item in the BUILD or OUTREC parameter. For example:

246

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

OUTFIL OUTREC=(1,4, 1,2,BI,TO=ZD,LENGTH=5, C|, 5) unedited RDW display RDW length in decimal | separator display input positions 5 to end

For fixed-length records, the first input and output data byte starts at position 1. For variable-length records, the first input and output data byte starts at position 5, after the RDW in positions 1-4. You can use the BUILD or OUTREC parameter to produce multiple reformatted output records for each OUTFIL input record, with or without intervening blank output records. You can use the BUILD or OUTREC parameter in conjunction with the VTOF or CONVERT parameter to convert variable-length record data sets to fixed-length record data sets. You can use the BUILD or OUTREC parameter with the FTOV parameter to convert fixed-length record data sets to variable-length record data sets. You can use the VLFILL parameter to allow processing of variable-length input records which are too short to contain all specified BUILD or OUTREC fields. You can use the VLTRIM parameter in conjunction with the BUILD or OUTREC parameter to remove specified trailing bytes from the end of variable-length records. The BUILD or OUTREC parameter can be used with any or all of the report parameters (LINES, HEADER1, TRAILER1, HEADER2, TRAILER2, SECTIONS, BLKCCH1, BLKCCH2, BLKCCT1, and NODETAIL) to produce reports. The report parameters specify the report records to be produced, while the BUILD or OUTREC parameter specifies the reformatted data records to be produced. DFSORT uses ANSI carriage control characters to control page ejects and the placement of the lines in your report, according to your specifications. You can use the REMOVECC parameter to remove the ANSI carriage control characters. When you create an OUTFIL report, the length for the longest or only data record must be equal to or greater than the maximum report record length. You can use the BUILD or OUTREC parameter to force a length for the data records that is longer than any report record; you can then either let DFSORT compute and set the LRECL, or ensure that the computed LRECL is equal to the existing or specified LRECL. Remember to allow an extra byte in the LRECL for the ANSI carriage control character. For example, if your data records are 40 bytes, but your longest report record is 60 bytes, you can use a BUILD or OUTREC parameter such as:
OUTREC=(1,40,80:X)

DFSORT will then set the LRECL to 81 (1 byte for the ANSI carriage control character plus 80 bytes for the length of the data records), and pad the data records with blanks on the right. If you dont want the ANSI carriage control characters to appear in the output data set, use the REMOVECC parameter to remove them. For example, if you specify:
OUTREC=(1,40,80:X),REMOVECC

DFSORT will set the LRECL to 80 instead of 81 and remove the ANSI carriage control character from each record before it is written. The BUILD or FIELDS parameter of the OUTREC statement differs from the BUILD or OUTREC parameter of the OUTFIL statement in the following ways:
Chapter 3. Using DFSORT Program Control Statements

247

OUTFIL Control Statements

v The BUILD or FIELDS parameter of the OUTREC statement applies to all input records; the BUILD or OUTREC parameter of the OUTFIL statement only applies to the OUTFIL input records for its OUTFIL group. v The BUILD or OUTREC parameter of the OUTFIL statement supports the slash (/) separator for creating blank records and new records; the BUILD or FIELDS parameter of the OUTREC statement does not. The reformatted OUTFIL output record consists of the separation fields, edited and unedited input fields, (p,m for fixed fields, or %nn for parsed fields - see PARSE), edited decimal constants, edited results of arithmetic expressions, and sequence numbers you select, in the order in which you select them, aligned on the boundaries or in the columns you indicate. c: specifies the position (column) for a separation field, input field, decimal constant, arithmetic expression, or sequence number, relative to the start of the reformatted OUTFIL output record. Count the RDW (variable-length output records only) but not the carriage control character (for reports) when specifying c:. That is, 1: indicates the first byte of the data in fixed-length output records and 5: indicates the first byte of the data in variable-length output records. Unused space preceding the specified column is padded with EBCDIC blanks. The following rules apply: v c must be a number between 1 and 32752. v c: must be followed by a separation field, input field, decimal constant, or arithmetic expression. v c must not overlap the previous input field or separation field in the reformatted OUTFIL output record. v For variable-length records, c: must not be specified before the first input field (the record descriptor word) nor after the variable part of the OUTFIL input record. v The colon (:) is treated like the comma (,) or semicolon (;) for continuation to another line. See Table 25 on page 130 for examples of valid and invalid column alignment. s specifies that a separation field (blanks, zeros, character string, hexadecimal string, current date, future date, past date, or current time) is to appear in the reformatted OUTFIL output record, or that a new output record is to be started, with or without intervening blank output records. These separation elements (separation fields, new record indicators, and blank record indicators) can be specified before or after any input field. Consecutive separation elements may be specified. For variable-length records, separation elements must not be specified before the first input field (the record descriptor word) or after the variable part of the OUTFIL input record. Permissible values are nX, nZ, nCxx...x, nX'yy...yy', various date and time constants, /.../ and n/. nX Blank separation. n bytes of EBCDIC blanks (X'40') are to appear in the reformatted OUTFIL output records. n can range from 1 to 4095. If n is omitted, 1 is used. See Table 26 on page 131 for examples of valid and invalid blank separation. nZ Binary zero separation. n bytes of binary zeros (X'00') are to appear in the reformatted OUTFIL output records. n can range from 1 to 4095. If n is omitted, 1 is used.

248

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

See Table 27 on page 131 for examples of valid and invalid binary zero separation. nCxx...x Character string separation. n repetitions of the character string constant (Cxx...x) are to appear in the reformatted OUTFIL output records. n can range from 1 to 4095. If n is omitted, 1 is used. x can be any EBCDIC character. You can specify from 1 to 256 characters. If you want to include a single apostrophe in the character string, you must specify it as two single apostrophes:
Required: ONEILL Specify: CONEILL

See Table 28 on page 131 for examples of valid and invalid character string separation. nX'yy...yy' Hexadecimal string separation. n repetitions of the hexadecimal string constant (X'yy...yy') are to appear in the reformatted OUTFIL output records. n can range from 1 to 4095. If n is omitted, 1 is used. The value yy represents any pair of hexadecimal digits. You can specify from 1 to 256 pairs of hexadecimal digits. See Table 29 on page 132 for examples of valid and invalid hexadecimal string separation. DATEn, DATEN(c), DATEnP Constant for current date. The current date of the run is to appear in the reformatted OUTFIL output records. DATE1, &DATE1, DATE1(c), &DATE1(c), DATE2, &DATE2, DATE2(c), &DATE2(c), DATE3, &DATE3, DATE3(c) or &DATE3(c) can be used to generate a character constant for the current date of the run. DATE1P, &DATE1P, DATE2P, &DATE2P, DATE3P or &DATE3P can be used to generate a packed decimal constant for the current date of the run. Table 35 shows the form of the constant generated for each current date operand and an example of the actual constant generated when the date of the run is June 21, 2005 at 4:42:45 PM, using (/) for (c) where relevant. yyyy represents the year, mm (for date) represents the month (01-12), dd represents the day (01-31), ddd represents the day of the year (001-366), hh represents the hour (00-23), mm (for time) represents the minutes (00-59), ss represents the seconds (00-59), and c can be any character except a blank.
Table 35. Current date constants Format of Operand DATE1 DATE1(c) DATE1P DATE2 DATE2(c) DATE2P DATE3 Format of Constant Cyyyymmdd Cyyyycmmcdd Pyyyymmdd Cyyyymm Cyyyycmm Pyyyymm Cyyyyddd Length (bytes) Example of Constant 8 10 5 6 7 4 7 C20050621 C2005/06/21 P20050621 C200506 C2005/06 P200506 C2005172

Chapter 3. Using DFSORT Program Control Statements

249

OUTFIL Control Statements

Table 35. Current date constants (continued) Format of Operand DATE3(c) DATE3P DATE4 Format of Constant Cyyyycddd Pyyyyddd Cyyyy-mm-dd-hh.mm.ss Length (bytes) Example of Constant 8 4 19 C2005/172 P2005172 C2005-06-21-16.52.45

Note: You can precede each of the operands in the table with an & with identical results. &DATEn, &DATEN(c), &DATEnP Can be used instead of DATEn, DATEn(c) and DATEnP, respectively DATEn+r, DATEn(c)+r, DATEnP+r Constant for future date. A future date relative to the current date of the run is to appear in the reformatted OUTFIL output records. DATE1+d, &DATE1+d, DATE1(c)+d, &DATE1(c)+d, DATE2+m, &DATE2+m, DATE2(c)+m, &DATE2(c)+m, DATE3+d, &DATE3+d, DATE3(c)+d or &DATE3(c)+d can be used to generate a character constant for a future date relative to the current date of the run. DATE1P+d, &DATE1P+d, DATE2P+m, &DATE2P+m, DATE3P+d or &DATE3P+d can be used to generate a packed decimal constant for a future date relative to the current date of the run. d is days in the future and m is months in the future. d and m can be 0 to 9999. Table 36 shows the form of the constant generated for each future date operand and an example of the actual constant generated when the date of the run is June 21, 2005, using (/) for (c) where relevant. yyyy represents the year, mm (for date) represents the month (01-12), dd represents the day (01-31), ddd represents the day of the year (001-366), and c can be any character except a blank.
Table 36. Future Date Constants Format of Operand DATE1+d DATE1(c)+d DATE1P+d DATE2+m DATE2(c)+m DATE2P+m DATE3+d DATE3(c)+d DATE3P+d Format of Constant Cyyyymmdd Cyyyycmmcdd Pyyyymmdd Cyyyymm Cyyyycmm Pyyyymm Cyyyyddd Cyyyycddd Pyyyyddd Length (bytes) 8 10 5 6 7 4 7 8 4 Example of Operand DATE1+11 DATE1(/)+90 DATE1P+11 DATE2+2 DATE2(.)+25 DATE2P+2 DATE3+200 DATE3(-)+1 DATE3P+200 Example of Constant C20050702 C2005/09/19 P20050702 C200508 C2007.07 P200508 C2006007 C2005-171 P2006007

Note: You can precede each of the operands in the table with an & with identical results.

250

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

&DATEn+r, &DATEn(c)+r, &DATEnP+r Can be used instead of DATEn+r, DATEn(c)+r and DATEnP+r, respectively. DATEn-r, DATEn(c)-r, DATEnP-r Constant for past date. A past date relative to the current date of the run is to appear in the reformatted OUTFIL output records. DATE1-d, &DATE1-d, DATE1(c)-d, &DATE1(c)-d, DATE2-m, &DATE2-m, DATE2(c)-m, &DATE2(c)-m, DATE3-d, &DATE3-d, DATE3(c)-d or &DATE3(c)-d can be used to generate a character constant for a past date relative to the current date of the run. DATE1P-d, &DATE1P-d, DATE2P-m, &DATE2P-m, DATE3P-d or &DATE3P-d can be used to generate a packed decimal constant for a past date relative to the current date of the run. d is days in the past and m is months in the past. d and m can be 0 to 9999. Table 37 shows the form of the constant generated for each past date operand and an example of the actual constant generated when the date of the run is June 21, 2005, using (/) for (c) where relevant. yyyy represents the year, mm (for date) represents the month (01-12), dd represents the day (01-31), ddd represents the day of the year (001-366), and c can be any character except a blank.
Table 37. Past Date Constants Format of Operand DATE1-d DATE1(c)-d DATE1P-d DATE2-m DATE2(c)-m DATE2P-m DATE3-d DATE3(c)-d DATE3P-d Format of Constant Cyyyymmdd Cyyyycmmcdd Pyyyymmdd Cyyyymm Cyyyycmm Pyyyymm Cyyyyddd Cyyyycddd Pyyyyddd Length (bytes) 8 10 5 6 7 4 7 8 4 Example of Operand DATE1-1 DATE1(-)-60 DATE1P-30 DATE2-6 DATE2(/)-1 DATE2P-12 DATE3-300 DATE3(.)-21 DATE3P-172 Example of Constant C20050620 C2005-04-22 P20050522 C200412 C2005/05 P200406 C2004238 C2005.151 P2004366

Note: You can precede each of the operands in the table with an & with identical results. &DATEn-r, &DATEn(c)-r, &DATEnP-r Can be used instead of DATEn-r, DATEn(c)-r and DATEnP-r, respectively. TIMEn, TIMEn(c), TIMEnP Constant for current time. The time of the run is to appear in the reformatted OUTFIL output records. Table 38 on page 252 shows the constant generated for each separation field you can specify along with its length and an example using (:) for (c) where relevant. hh represents the hour (00-23), mm represents the minutes (00-59), ss represents the seconds (00-59), and c can be any character except a blank.
Chapter 3. Using DFSORT Program Control Statements

251

OUTFIL Control Statements

Table 38. Current time constants Separation Field TIME1 TIME1(c) TIME1P TIME2 TIME2(c) TIME2P TIME3 TIME3P Constant Chhmmss Chhcmmcss Phhmmss Chhmm Chhcmm Phhmm Chh Phh Length (bytes) 01:55:43 PM 6 8 4 4 5 3 2 2 C135543 C13:55:43 P135543 C1355 C13:55 P1355 C13 P13

&TIMEn, &TIMEn(c), &TIMEnP Can be used instead of TIMEn, TIMEn(c), and TIMEnP, respectively. DATE specifies that the current date is to appear in the reformatted OUTFIL output records in the form mm/dd/yy, where mm represents the month (01-12), dd represents the day (01-31), and yy represents the last two digits of the year (for example, 04). can be used instead of DATE.

&DATE

DATE=(abcd) specifies that the current date is to appear in the reformatted OUTFIL output records in the form adbdc, where a, b, and c indicate the order in which the month, day, and year are to appear and whether the year is to appear as two or four digits, and d is the character to be used to separate the month, day and year. For a, b, and c, use M to represent the month (01-12), D to represent the day (01-31), Y to represent the last two digits of the year (for example, 04), or 4 to represent the four digits of the year (for example, 2004). M, D, and Y or 4 can each be specified only once. Examples: DATE=(DMY.) would produce a date of the form dd.mm.yy, which on March 29, 2004, would appear as 29.03.04. DATE=(4MD-) would produce a date of the form yyyy-mm-dd, which on March 29, 2004, would appear as 2004-03-29. a, b, c, and d must be specified. &DATE=(abcd) can be used instead of DATE=(abcd). DATENS=(abc) specifies that the current date is to appear in the reformatted OUTFIL output record in the form abc, where a, b and c indicate the order in which the month, day, and year are to appear and whether the year is to appear as two or four digits. For a, b and c, use M to represent the month (01-12), D to represent the day (01-31), Y to represent the last two digits of the year (for example, 04), or 4 to represent the four digits of the year (for example, 2004). M, D, and Y or 4 can each be specified only once. Examples: DATENS=(DMY) would

252

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

produce a date of the form ddmmyy, which on March 29, 2004, would appear as 290304. DATENS=(4MD) would produce a date of the form yyyymmdd, which on March 29, 2004, would appear as 20040329. a, b and c must be specified. &DATENS=(abc) can be used instead of DATENS=(abc). YDDD=(abc) specifies that the current date is to appear in the reformatted OUTFIL output records in the form acb, where a and b indicate the order in which the year and day of the year are to appear and whether the year is to appear as two or four digits, and c is the character to be used to separate the year and day of the year. For a and b, use D to represent the day of the year (001-366), Y to represent the last two digits of the year (for example, 04), or 4 to represent the four digits of the year (for example, 2004). D, and Y or 4 can each be specified only once. Examples: YDDD=(DY-) would produce a date of the form ddd-yy, which on April 7, 2004, would appear as 098-04. YDDD=(4D/) would produce a date of the form yyyy/ddd, which on April 7, 2004, would appear as 2004/098. a, b and c must be specified. &YDDD=(abc) can be used instead of YDDD=(abc). YDDDNS=(ab) specifies that the current date is to appear in the reformatted OUTFIL output records in the form ab, where a and b indicate the order in which the year and day of the year are to appear and whether the year is to appear as two or four digits. For a and b, use D to represent the day of the year (001-366), Y to represent the last two digits of the year (for example, 04), or 4 to represent the four digits of the year (for example, 2004). D, and Y or 4 can each be specified only once. Examples: YDDDNS=(DY) would produce a date of the form dddyy, which on April 7, 2004, would appear as 09804. YDDDNS=(4D) would produce a date of the form yyyyddd, which on April 7, 2004, would appear as 2004098. a and b must be specified. &YDDDNS=(ab) can be used instead of YDDDNS=(ab). TIME specifies that the current time is to appear in the reformatted OUTFIL output records in the form hh:mm:ss, where hh represents the hour (00-23), mm represents the minutes (00-59), and ss represents the seconds (00-59). can be used instead of TIME. specifies that the current time is to appear in the reformatted OUTFIL output records in the form hhcmmcss (24-hour time) or hhcmmcss xx (12-hour time).

&TIME TIME=(abc)

Chapter 3. Using DFSORT Program Control Statements

253

OUTFIL Control Statements

If ab is 24, the time is to appear in the form hhcmmcss (24-hour time) where hh represents the hour (00-23), mm represents the minutes (00-59), ss represents the seconds (00-59), and c is the character used to separate the hours, minutes, and seconds. Example: TIME=(24.) would produce a time of the form hh.mm.ss, which at 08:25:13 pm would appear as 20.25.13. If ab is 12, the time is to appear in the form hhcmmcss xx (12-hour time) where hh represents the hour (01-12), mm represents the minutes (00-59), ss represents the seconds (00-59), xx is am or pm, and c is the character used to separate the hours, minutes, and seconds. Example: TIME=(12.) would produce a time of the form hh.mm.ss xx, which at 08:25:13 pm would appear as 08.25.13 pm. ab and c must be specified. &TIME=(abc) can be used instead of TIME=(abc). TIMENS=(ab) specifies that the current time is to appear in the reformatted OUTFIL output record in the form hhmmss (24-hour time) or hhmmss xx (12-hour time). If ab is 24, the time is to appear in the form hhmmss (24-hour time) where hh represents the hour (00-23), mm represents the minutes (00-59), and ss represents the seconds (00-59). Example: TIMENS=(24) would produce a time of the form hhmmss, which at 08:25:13 pm would appear as 202513. If ab is 12, the time is to appear in the form hhmmss xx (12-hour time) where hh represents the hour (01-12), mm represents the minutes (00-59), and ss represents the seconds (00-59). Example: TIMENS=(12) would produce a time of the form hhmmss xx, which at 08:25:13 pm would appear as 082513 pm. ab must be specified. &TIMENS=(ab) can be used instead of TIMENS=(ab). /.../ or n/ Blank records or a new record. A new output record is to be started with or without intervening blank output records. If /.../ or n/ is specified at the beginning or end of OUTREC, n blank output records are to be produced. If /.../ or n/ is specified in the middle of OUTREC, n1 blank output records are to be produced (thus, / or 1/ indicates a new output record with no intervening blank output records). At least one input field or separation field must be specified if you use /.../ or n/. For example, OUTREC=(//) is not allowed, whereas OUTREC=(//X) is allowed. Either n/ (for example, 5/) or multiple /s (for example, /////) can be used. n can range from 1 to 255. If n is omitted, 1 is used. As an example, if you specify:
OUTFIL OUTREC=(2/,CField 2 contains ,4,3,/, CField 1 contains ,1,3)

254

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

an input record containing:
111222

would produce the following four output records:

Blanks Blanks Field 2 contains 222 Field 1 contains 111

Note that four OUTFIL output records are produced for each OUTFIL input record. p,m,a specifies that an unedited input field is to appear in the reformatted OUTFIL output record. p specifies the first byte of the input field relative to the beginning of the OUTFIL input record. The first data byte of a fixed-length record has relative position 1. The first data byte of a variable-length record has relative position 5, because the first four bytes are occupied by the RDW. All fields must start on a byte boundary, and no field can extend beyond byte 32752. See OUTFIL Statements Notes on page 340 for special rules concerning variable-length records. specifies the length in bytes of the input field. specifies the alignment (displacement) of the input field in the reformatted OUTFIL output record relative to the start of the reformatted OUTFIL output record. The permissible values of a are: H Halfword aligned. The displacement (p1) of the field from the beginning of the reformatted OUTFIL input record, in bytes, is a multiple of 2 (that is, position 1, 3, 5, and so forth). Fullword aligned. The displacement is a multiple of 4 (that is, position 1, 5, 9, and so forth). Doubleword aligned. The displacement is a multiple of 8 (that is, position 1, 9, 17, and so forth).

m a

F D

Alignment can be necessary if, for example, the data is used in a COBOL application program where items are aligned through the SYNCHRONIZED clause. Unused space preceding aligned fields are always padded with binary zeros. %nn specifies that an unedited parsed input field is to appear in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,a for further details. Note that alignment (H, F, D) is not permitted for %nn fields (for example, %nn,F results in an error message and termination). p | | specifies the unedited variable part of the OUTFIL input record (that part beyond the minimum record length) is to appear in the reformatted OUTFIL output record as the last field. p without m can only be used for variable-length records; not for fixed-length records. Attention: If the reformatted input record includes only the RDW and the variable part of the input record, null records containing only an RDW may result.

Chapter 3. Using DFSORT Program Control Statements

255

OUTFIL Control Statements

A value must be specified for p that is less than or equal to the minimum OUTFIL input record length plus 1 byte. p,m,HEX specifies that the hexadecimal representation of an input field is to appear in the reformatted OUTFIL output record. p m HEX See p under p,m,a. specifies the length in bytes of the input field. The value for m must be 1 to 16376. requests hexadecimal representation of the input field. Each byte of the input field is replaced by its two-byte equivalent. For example, the characters AB would be replaced by C1C2.

%nn,HEX specifies that the hexadecimal representation of a parsed input field is to appear in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,HEX for further details. p,HEX specifies that the hexadecimal representation of the variable part of the OUTFIL input record (that part beyond the minimum record length) is to appear in the reformatted OUTFIL output record as the last field. p,HEX can only be used for variable-length records; not for fixed-length records. Attention: If the reformatted input record includes only the RDW and the variable part of the input record, null records containing only an RDW may result. p HEX A value must be specified for p that is less than or equal to the minimum record length plus 1 byte. requests hexadecimal representation of the variable part of the OUTFIL input record. Each byte of the input field is replaced by its two-byte equivalent. For example, the characters AB would be replaced by C1C2.

| |

p,m,TRAN=LTOU specifies that lowercase EBCDIC letters (that is, a-z) in an input field are to appear as uppercase EBCDIC letters (that is, A-Z) in the reformatted OUTFIL output record. p m See p under p,m,a See m under p,m,a

TRAN=LTOU requests conversion of lowercase letters to uppercase letters. Each a-z character of the input field is replaced by the corresponding A-Z character. Other characters are not changed. For example, the characters Vicky-123,x would be replaced by VICKY-123,X. %nn,TRAN=LTOU specifies that lowercase EBCDIC letters (that is, a-z) in a parsed input field are to appear as uppercase EBCDIC letters (that is, A-Z) in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,TRAN=LTOU for further details. p,TRAN=LTOU specifies that lowercase EBCDIC letters (that is, a-z) in the variable part of the OUTFIL input record (that part beyond the minimum record length), are to

256

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

appear as uppercase EBCDIC letters (that is, A-Z) in the reformatted OUTFIL output record, as the last field. p,TRAN=LTOU can only be used for variable-length records; not for fixed-length records. Attention: If the reformatted input record includes only the RDW and the variable part of the input record, null records containing only an RDW may result. p A value must be specified for p that is less than or equal to the minimum record length plus 1 byte.

| |

TRAN=LTOU requests conversion of lowercase EBCDIC letters to uppercase EBCDIC letters. Each a-z character of the variable part of the OUTFIL input record is replaced by the corresponding A-Z character. Other characters are not changed. For example, the characters Vicky-123,x would be replaced by VICKY-123,X. p,m,TRAN=UTOL specifies that uppercase EBCDIC letters (that is, A-Z) in an input field are to appear as lowercase EBCDIC letters (that is, a-z) in the reformatted OUTFIL output record. p m See p under p,m,a See m under p,m,a

TRAN=UTOL requests conversion of uppercase EBCDIC letters to lowercase EBCDIC leters. Each A-Z character of the variable part of the OUTFIL input record is replaced by the corresponding a-z character. Other characters are not changed. For example, the characters CARRIE-005, CA would be replaced by carrie-005, ca. Attention: If TRAN=UTOL is used for numeric data, it may have unintended consequences. For example, a ZD field with 32J (XF3F2D1 = Z-321) would appear as 32j (XF3F28A=invalid ZD number). %nn,TRAN=UTOL specifies that uppercase EBCDIC letters (that is, A-Z) in a parsed input field are to appear as lowercase EBCDIC letters (that is, a-z) in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,TRAN=UTOL for further details. p,TRAN=UTOL specifies that uppercase EBCDIC letters (that is, A-Z) in the variable part of the OUTFIL input record (that part beyond the minimum record length), are to appear as lowercase EBCDIC letters (that is, a-z) in the reformatted OUTFIL output record, as the last field. p,TRAN=UTOL can only be used for variable-length records; not for fixed-length records. Attention: If the reformatted input record includes only the RDW and the variable part of the input record, null records containing only an RDW may result. p A value must be specified for p that is less than or equal to the minimum record length plus 1 byte.

| |

TRAN=UTOL requests conversion of uppercase letters to lowercase letters. Each A-Z character of the variable part of the OUTFIL input record is replaced
Chapter 3. Using DFSORT Program Control Statements

257

OUTFIL Control Statements

by the corresponding a-z character. Other characters are not changed. For example, the characters CARRIE-005, CA would be replaced by carrie-005, ca. Attention: If TRAN=UTOL is used for numeric data, it may have unintended consequences. For example, a ZD field with 32J (XF3F2D1 = Z-321) would appear as 32j (XF3F28A=invalid ZD number). p,m,TRAN=ALTSEQ specifies that the characters in an input field are to be changed according to the ALTSEQ translation table in effect in the reformatted OUTFIL output record. p m See p under p,m,a See m under p,m,a

TRAN=ALTSEQ specifies that the characters in the variable part of the OUTFIL input record (that part beyond the minimum record length), are to be changed according to the ALTSEQ translation table in effect in the reformatted OUTFIL output record, as the last field. p,TRAN=ALTSEQ can only be used for variable-length records; not for fixed-length records. Attention: If the reformatted input record includes only the RDW and the variable part of the input record, null records containing only an RDW may result. Attention: If TRAN=ALTSEQ is used for numeric data, it may have unintended consequences. For example, with TRAN=ALTSEQ and ALTSEQ CODE=(0040), a PD field with X00003C (P3) would appear as X40403C (P40403). %nn,TRAN=ALTSEQ specifies that the characters in a parsed input field are to be changed according to the ALTSEQ translation table in effect in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,TRAN=ALTSEQ for further details. p,TRAN=ALTSEQ specifies that the characters in the variable part of the OUTFIL input record (that part beyond the minimum record length), are to be changed according to the ALTSEQ translation table in effect in the reformatted OUTFIL output record, as the last field. p,TRAN=ALTSEQ can only be used for variable-length records; not for fixed-length records. Attention: If the reformatted input record includes only the RDW and the variable part of the input record, null records containing only an RDW may result. p A value must be specified for p that is less than or equal to the minimum record length plus 1 byte.

| |

TRAN=ALTSEQ requests conversion of characters according to the ALTSEQ translation table in effect. Each character of the variable part of the OUTFIL input record which has been assigned a different character in the ALTSEQ table is replaced by that character. Other characters are not changed. For example, if this ALTSEQ statement is specified:
ALTSEQ CODE=(5C61,C1F1)

258

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

the characters /*XA*/ would be replaced by //X1//. See ALTSEQ Control Statement on page 89 for more information on how to assign replacement characters in the ALTSEQ table. Attention: If TRAN=ALTSEQ is used for numeric data, it may have unintended consequences. For example, with TRAN=ALTSEQ and ALTSEQ CODE=(0040), a PD field with X00003C (P3) would appear as X40403C (P40403).

Sample Syntax: Fixed input records: OUTFIL FNAMES=(OUT1,OUT2), OUTREC=(1:5,10,15:8C0, 25:20,15,TRAN=UTOL,80:X) Variable input records: OUTFIL OUTREC=(1,4,C RDW=,1,3,HEX,C FIXED=, 5,20,HEX,C VARIABLE=,21,HEX)

p,m,Y2x specifies that the four-digit year CH date representation of a two-digit year input date field is to appear in the reformatted OUTFIL output record. Real dates are transformed using the century window established by the Y2PAST option in effect. The century window is not used for special indicators; they are just expanded appropriately (for example, p,6,Y2T transforms C000000 to C00000000). p m Y2x See p under p,m,a. specifies the length in bytes of the two-digit year date field. specifies the Y2 format. See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions.

Sample Syntax:
OUTFIL OUTREC=(21,3,Y2V,X,12,5,Y2W)

Table 39 shows the output produced for each type of date.

Table 39. p,m,Y2x Output Type of Date yyx yyxx yyxxx yyxxxx xyy xxyy xxxyy xxxxyy yy yy yy Fields (m,f) 3,Y2T 4,Y2T 5,Y2T 6,Y2T 3,Y2W 4,Y2W 5,Y2W 6,Y2W 2,Y2C 2,Y2S 1,Y2D 2,Y2U 3,Y2V 3,Y2U 4,Y2V 2,Y2X 3,Y2Y 3,Y2X 4,Y2Y 2,Y2Z 2,Y2P 1,Y2B Output for p,m,Y2x Cyyyyx Cyyyyxx Cyyyyxxx Cyyyyxxxx Cxyyyy Cxxyyyy Cxxxyyyy Cxxxxyyyy Cyyyy Cyyyy Cyyyy

Chapter 3. Using DFSORT Program Control Statements

259

OUTFIL Control Statements

%nn,Y2x specifies that the four-digit year CH date representation of a two-digit year parsed input date field is to appear in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,Y2x for further details. p,m,Y2x(c) specifies that the four-digit year CH date representation with separators of a two-digit year input date field is to appear in the reformatted OUTFIL output record. Real dates are transformed using the century window established by the Y2PAST option in effect. The century window is not used for special indicators; they are just expanded appropriately (for example, p,6,Y2T(/) transforms C000000 to C0000/00/00). p m Y2x c See p under p,m,a. specifies the length in bytes of the two-digit year date field. specifies the Y2 format. See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions. specifies the separator character. c can be any character except a blank.

Sample Syntax:
OUTFIL OUTREC=(25,6,Y2T(-),X,14,2,Y2U(/))

Table 40 shows the output produced for each type of Y2x(c) date field when / is used for c.
Table 40. p,m,Y2x(c) Output Type of Date yyx yyxx yyxxx yyxxxx xyy xxyy xxxyy xxxxyy Fields (m,f) 3,Y2T 4,Y2T 5,Y2T 6,Y2T 3,Y2W 4,Y2W 5,Y2W 6,Y2W 2,Y2U 3,Y2V 3,Y2U 4,Y2V 2,Y2X 3,Y2Y 3,Y2X 4,Y2Y Output for p,m,Y2x(/) Cyyyy/x Cyyyy/xx Cyyyy/xxx Cyyyy/xx/xx Cx/yyyy Cxx/yyyy Cxxx/yyyy Cxx/xx/yyyy

%nn,Y2x(c) specifies that the four-digit year CH date representation with separators of a two-digit year parsed input date field is to appear in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,Y2x(c) for further details. p,m,Y2xP specifies that the four-digit year PD date representation of a two-digit year input date field is to appear in the reformatted OUTFIL output record. Real dates are transformed using the century window established by the Y2PAST option in effect. The century window is not used for special indicators; they are just expanded appropriately (for example, p,6,Y2TP transforms C000000 to P00000000): p m See p under p,m,a. specifies the length in bytes of the two-digit year date field.

260

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Y2xP specifies the Y2 format. See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions.

Sample Syntax:
OUTFIL OUTREC=(11,3,Y2XP,X,21,4,Y2WP)

Table 41 shows the output produced for each type of date.

Table 41. p,m,Y2xP Output Type of Date yyx yyxx yyxxx yyxxxx xyy xxyy xxxyy xxxxyy yy yy Fields (m,f) 3,Y2TP 4,Y2TP 5,Y2TP 6,Y2TP 3,Y2WP 4,Y2WP 5,Y2WP 6,Y2WP 2,Y2PP 1,Y2DP 2,Y2UP 3,Y2VP 3,Y2UP 4,Y2VP 2,Y2XP 3,Y2YP 3,Y2XP 4,Y2YP Output for p,m,Y2xP Pyyyyx Pyyyyxx Pyyyyxxx Pyyyyxxxx Pxyyyy Pxxyyyy Pxxxyyyy Pxxxxyyyy Pyyyy X'yyyy'

%nn,Y2xP specifies that the four-digit year PD date representation of a two-digit year parsed input date field is to appear in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,Y2xP for further details. p,m,f,edit or (p,m,f),edit specifies that an edited numeric input field is to appear in the reformatted OUTFIL output record. You can edit BI, FI, PD, PD0, ZD, FL,CSF, FS, UFF, SFF, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3 or TM4 fields using either pre-defined edit masks (M0-M26) or specific edit patterns you define. You can control the way the edited fields look with respect to length, leading or suppressed zeros, thousands separators, decimal points, leading and trailing positive and negative signs, and so on. p m See p under p,m,a. specifies the length in bytes of the numeric field. The length must include the sign, if the data is signed. See Table 42 for permissible length values. specifies the format of the numeric field:
Length 1 to 8 bytes 1 to 8 bytes 1 to 16 bytes 2 to 8 bytes 1 to 31 bytes Description Unsigned binary Signed fixed-point Signed packed decimal Packed decimal with sign and first digit ignored Signed zoned decimal

Table 42. Edit Field Formats and Lengths Format Code BI FI PD PD0 ZD

Chapter 3. Using DFSORT Program Control Statements

261

OUTFIL Control Statements

Table 42. Edit Field Formats and Lengths (continued) Format Code FL CSF or FS UFF SFF DT1 DT2 DT3 DC1 DC2 DC3 DE1 DE2 DE3 TM1 TM2 TM3 TM4 TC1 TC2 TC3 TC4 TE1 TE2 TE3 TE4 Length 4 or 8 bytes 1 to 32 bytes (31 digit limit) 1 to 44 bytes (31 digit limit) 1 to 44 bytes (31 digit limit) 4 bytes 4 bytes 4 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes 4 bytes 4 bytes 4 bytes 4 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes Description Signed hexadecimal floating-point converted to signed integer Signed numeric with optional leading floating sign Unsigned free form numeric Signed free form numeric SMF date interpreted as Zyyyymmdd SMF date interpreted as Zyyyymm SMF date interpreted as Zyyyyddd TOD date interpreted as Zyyyymmdd TOD date interpreted as Zyyyymm TOD date interpreted as Zyyyyddd ETOD date interpreted as Zyyyymmdd ETOD date interpreted as Zyyyymm ETOD date interpreted as Zyyyyddd SMF time interpreted as Zhhmmss SMF time interpreted as Zhhmm SMF time interpreted as Zhh SMF time interpreted as Zhhmmssxx TOD time interpreted as Zhhmmss TOD time interpreted as Zhhmm TOD time interpreted as Zhh TOD time interpreted as Zhhmmssxx ETOD time interpreted as Zhhmmss ETOD time interpreted as Zhhmm ETOD time interpreted as Zhh ETOD time interpreted as Zhhmmssxx

Note: See Appendix C, Data Format Descriptions for detailed format descriptions.

For a CSF or FS format field: v A maximum of 31 digits is allowed. If a CSF or FS value with 32 digits is found, the leftmost digit will be treated as a positive sign indicator. For a UFF or SFF format field: v A maximum of 31 digits is allowed. If a UFF or SFF value with more than 31 digits is found, the leftmost digits will be ignored.

262

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

For a ZD or PD format field: v An invalid digit results in a data exception (0C7 ABEND) or incorrect numeric output; A-F are invalid digits. ICETOOLs VERIFY or DISPLAY operator can be used to identify decimal values with invalid digits. v A value is treated as positive if its sign is F, E, C, A, 8, 6, 4, 2, or 0. v A value is treated as negative if its sign is D, B, 9, 7, 5, 3, or 1. For a PD0 format field: v The first digit is ignored. v An invalid digit other than the first results in a data exception (0C7 ABEND) or incorrect numeric output; A-F are invalid digits. v The sign is ignored and the value is treated as positive. For an FL format field: v The normalized or unnormalized FL (hexadecimal floating-point) value is converted to a signed integer in the range -9223372036854775808 to 9223372036854775807. The fractional part of the FL value is lost, and in some cases the signed integer may be one of a number of possible signed integers for the FL value depending on its precision. Converted values less than -9223372036854775808 are set to -9223372036854775808. Converted values greater than 9223372036854775807 are set to 9223372036854775807. v If you are not running in z/Architecture mode, specifying an FL format field results in an error message and termination. For a DT1, DT2, or DT3 format field: v An invalid SMF date can result in a data exception (0C7 ABEND) or an incorrect ZD date. v SMF date values are always treated as positive. For a DC1, DC2, DC3, DE1, DE2, or DE3 format field: v TOD and ETOD date values are always treated as positive. For a TM1, TM2, TM3, or TM4 format field: v An invalid SMF time can result in an incorrect ZD time. v SMF time values are always treated as positive. For a TC1, TC2, TC3, TC4, TE1, TE2, TE3, or TE4 format field: v TOD and ETOD time values are always treated as positive. edit

Mn EDIT= EDxy=

(pattern) (pattern)

Chapter 3. Using DFSORT Program Control Statements

263

OUTFIL Control Statements

|
, SIGNS= SIGNz= (lp,ln,tp,tn) ,LENGTH=n

Specifies how the numeric field is to be edited for output. If an Mn, EDIT, or EDxy parameter is not specified: v a DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3, or TM4 field is edited using the M11 edit mask. v a BI, FI, PD, PD0, ZD, FL, CSF, FS, UFF, or SFF field is edited using the M0 edit mask. Mn specifies one of twenty-seven pre-defined edit masks (M0-M26) for presenting numeric data. If these pre-defined edit masks are not suitable for presenting your numeric data, the EDIT parameter gives you the flexibility to define your own edit patterns. The twenty-seven pre-defined edit masks can be represented as follows:
Table 43. Edit Mask Patterns Mask Pattern Examples Value M0 IIIIIIIIIIIIIIIIIIIIIIIIIIIIIITS +01234 00001 M1 TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTS 00123 +00123 M2 II,III,III,III,III,III,III,III,III,IIT.TTS +123450 000020 M3 II,III,III,III,III,III,III,III,III,IIT.TTCR 001234 +123456 M4 SII,III,III,III,III,III,III,III,III,IIT.TT +0123456 1234567 M5 SII,III,III,III,III,III,III,III,III,IIT.TTS 001234 +123450 M6 III-TTT-TTTT 00123456 12345678 M7 TTT-TT-TTTT 00123456 12345678 M8 IT:TT:TT 030553 121736 M9 IT/TT/TT 123004 083104 M10 IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIT 01234 00000 Result 1234 1 00123 00123 1,234.50 0.20 12.34CR 1,234.56 +1,234.56 12,345.67 (12.34) 1,234.50 012-3456 1-234-56788 000-12-3456 012-34-5678 3:05:53 12:17:36 12/30/04 8/31/04 1234 0

264

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Table 43. Edit Mask Patterns (continued) Mask Pattern Examples Value M11 TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT 00010 01234 M12 SI,III,III,III,III,III,III,III,III,III,IIT +1234567 0012345 Result 00010 01234 1,234,567 12,345 1.234.567 12.345 1 234 567 (12 345) 1 234 567 12 345 1 234 567 12 345 1234567 12345 1,234.56 12,345.67 1.234,56 12.345,67 1 234,56 (12 345,67) 1 234,567 12 345,67 1 234,56 12 345,67 1234.56 12345.67 1234,56 12345,67 1234 1 +01234 00001

| M13
M14

SI.III.III.III.III.III.III.III.III.III.IIT

+1234567 0012345

SI III III III III III III III III III IITS

+1234567 0012345

M15

I III III III III III III III III III IITS

+1234567 0012345

M16

SI III III III III III III III III III IIT

+1234567 0012345

M17

SIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIT

+1234567 0012345

M18

SII,III,III,III,III,III,III,III,III,IIT.TT

+0123456 1234567

M19

SII.III.III.III.III.III.III.III.III.IIT,TT

+0123456 1234567

M20

SI III III III III III III III III IIT,TTS

+0123456 1234567

M21

II III III III III III III III III IIT,TTS

+0123456 1234567

M22

SI III III III III IIII III III III IIT,TT

+0123456 1234567

M23

SIIIIIIIIIIIIIIIIIIIIIIIIIIIIT.TT

+0123456 1234567

M24

SIIIIIIIIIIIIIIIIIIIIIIIIIIIIT,TT

+0123456 1234567

M25

SIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIT

+01234 00001

M26

STTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT

1234 1

The elements used in the representation of the edit masks in Table 43 on page 264 are as follows: v I indicates a leading insignificant digit. If zero, this digit will not be shown. v T indicates a significant digit. If zero, this digit will be shown. v CR (in M3) is printed to the right of the digits if the value is negative; otherwise, two blanks are printed to the right of the digits.

Chapter 3. Using DFSORT Program Control Statements

265

OUTFIL Control Statements

v S indicates a sign. If it appears as the first character in the pattern, it is a leading sign. If it appears as the last character in the pattern, it is a trailing sign. If S appears as both the first and last characters in a pattern (example: M5), the first character is a leading sign and the last character is a trailing sign. Four different sign values are used: leading positive sign (lp), leading negative sign (ln), trailing positive sign (tp) and trailing negative sign (tn). Their applicable values for the Mn edit masks are:
Table 44. Edit Mask Signs Mask M0 M1 M2 M3 M4 M5 M6 M7 M8 M9 M10 M11 M12 M13 M14 M15 M16 M17 M18 M19 M20 M21 M22 M23 M24 M25 M26 lp none none none none + blank none none none none none none blank blank blank none blank blank blank blank blank none blank blank blank blank + ln none none none none ( none none none none none none ( none ( none tp blank blank blank none none blank none none none none none none none none blank blank none none none none blank blank none none none none none tn none none ) none none none none none none none none ) none none none none ) none none none none none

v any other character (for example, /) will be printed as shown, subject to certain rules to be subsequently discussed. The implied length of the edited output field depends on the number of digits and characters needed for the pattern of the particular edit mask used. The LENGTH parameter can be used to change the implied length of the edited output field. The number of digits needed depends on the format and length of the numeric field as follows:

266

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Table 45. Digits Needed for Numeric Fields Format ZD PD PD0 BI, FI BI, FI BI, FI BI, FI BI, FI BI, FI BI, FI BI, FI FL CSF or FS CSF or FS UFF, SFF UFF, SFF Input Length m m m 1 2 3 4 5 6 7 8 4 or 8 32 m (less than 32) 32 to 44 m (less than 32) Digits Needed m 2m1 2m2 3 5 8 10 13 15 17 20 20 31 m 31 m

The length of the output field can be represented as follows for each pattern, where d is the number of digits needed, as shown in Table 45, and the result is rounded down to the nearest integer:
Table 46. Edit Mask Output Field Lengths Mask Output Field Length Input (f,m) M0 M1 M2 M3 M4 M5 M6 M7 M8 M9 M10 M11 M12 M13 M14 M15 M16 d+1 d+1 d + 1 + d/3 d + 2 + d/3 d + 1 + d/3 d + 2 + d/3 12 11 8 8 d d d + 1 + (d 1)/3 d + 1 + (d 1)/3 d + 2 + (d 1)/3 d + 1 + (d 1)/3 d + 1 + (d 1)/3 ZD,3 PD,10 BI,4 UFF,20 PD,8 FI,3 ZD,10 PD,5 ZD,6 PD,4 BI,6 PD,5 PD,3 FS,5 ZD,5 FI,3 SFF,41 Example Output Length 4 20 14 28 21 12 12 11 8 8 15 9 7 7 8 11 42

Chapter 3. Using DFSORT Program Control Statements

267

OUTFIL Control Statements

Table 46. Edit Mask Output Field Lengths (continued) Mask Output Field Length Input (f,m) M17 M18 M19 M20 M21 M22 M23 M24 M25 M26 d + 1 + (d 1)/3 d + 1 + d/3 d + 1 + d/3 d + 2 + d/3 d + 1 + d/3 d + 1 + d/3 d + 1 + d/3 d + 1 + d/3 d+1 d+1 FI,4 BI,4 PD,8 FI,3 ZD,3 BI,2 PD,6 ZD,21 CSF,16 FL,4 Example Output Length 14 14 21 12 5 7 15 29 17 21

To illustrate conceptually how DFSORT produces the edited output from the numeric value, consider the following example:
OUTFIL OUTREC=(5,7,ZD,M5) with ZD values of C0123456(+0123456) and C000302J (-0003021)

As shown in the preceding tables, it is determined that: v The general pattern for M5 is: SI,III,...,IIT.TTS v The signs to be used are blank for leading positive sign, C( for leading negative sign, blank for trailing positive sign and C) for trailing negative sign v The number of digits needed is 7 v The length of the output field is 11 (7 + 2 + 7/3) v The specific pattern for the output field is thus: CSII,IIT.TTS The digits of C0123456 are mapped to the pattern, resulting in CS01,234.56S. Because the value is positive, the leading sign is replaced with blank and the trailing sign is replaced with blank, resulting in C 01,234.56 . Finally, all digits before the first non-zero digit (1 in this case), are replaced with blanks, resulting in the final output of C 1,234.56 . The digits of C000302J are mapped to the pattern, resulting in CS00,030.21S. Because the value is negative, the leading sign is replaced with C( and the trailing sign is replaced with C) resulting in C(00,030.21). All digits before the first non-zero digit (3 in this case), are replaced with blanks, resulting in C( 30.21). Finally, the leading sign is floated to the right, next to the first non-zero digit, resulting in the final output of C (30.21). To state the rules in more general terms, the steps DFSORT takes conceptually to produce the edited output from the numeric value are as follows: v Determine the specific pattern and its length, using the preceding tables. v Map the digits of the numeric value to the pattern.

268

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

v If the value is positive, replace the leading and trailing signs (if any) with the characters for positive values shown in Table 44 on page 266. Otherwise, replace the leading and trailing signs (if any) with the characters for negative values shown in that same table. v Replace all digits before the first non-zero (I) or significant digit (T) with blanks. v Float the leading sign (if any) to the right, next to the first non-zero (I) or significant digit (T). The following additional rule applies to edit masks: v The specific pattern is determined from the general pattern by including signs, the rightmost digits needed as determined from the input format and length, and any characters in between those rightmost digits. This may unintentionally truncate significant digits (T). As an example, if you specify 5,1,ZD,M4, the length of the output field will be 2 (1 + 1 + 1/3). The general pattern for M4 is SI,III,...,IIT.TT, but the specific pattern will be ST (the leading sign and the rightmost digit). EDIT specifies an edit pattern for presenting numeric data. If the pre-defined edit masks (M0-M26) are not suitable for presenting your numeric data, EDIT gives you the flexibility to define your own edit patterns. The elements you use to specify the pattern are the same as those used for the edit masks: I, T, S, and printable characters. However, S will not be recognized as a sign indicator unless the SIGNS parameter is also specified. pattern specifies the edit pattern to be used. Not enclosing the pattern in single apostrophes restricts you from specifying the following characters in the pattern: blank, apostrophe, unbalanced left or right parentheses, and hexadecimal digits 20, 21, and 22. For example, EDIT=((IIT.TT)) is valid, whereas EDIT=(C)ITT.TT), EDIT=(I / T) and EDIT=(SII.T) are not. The maximum number of digits (Is and Ts) you specify in the pattern must not exceed 31. The maximum length of the pattern must not exceed 44 characters. pattern specifies the edit pattern to be used. Enclosing the pattern in single apostrophes allows you to specify any character in the pattern except hexadecimal digits 20, 21, or 22. If you want to include a single apostrophe in the pattern, you must specify it as two single apostrophes, which will be counted as a single character in the pattern. As examples, EDIT=(C)ITT.TT), EDIT=(I / T), and EDIT=(SII.T) are all valid. The maximum number of digits (Is and Ts) you specify in the pattern must not exceed 31. The maximum length of the pattern must not exceed 44 characters. The implied length of the edited output field is the same as the length of the pattern. The LENGTH parameter can be used to change the implied length of the edited output field. To illustrate conceptually how DFSORT produces the edited output from the numeric value, consider the following example:

Chapter 3. Using DFSORT Program Control Statements

269

OUTFIL Control Statements

OUTFIL OUTREC=(1,5,ZD,EDIT=(**I/ITTTCR)) with ZD values of C01230(+1230) and C0004J (-41)

The digits of C01230 are mapped to the pattern, resulting in C**0/1230CR. Because the value is positive, the characters (CCR) to the right of the last digit are replaced with blanks, resulting in C**0/1230 . All digits before the first non-zero digit (1 in this case) are replaced with blanks, resulting in C** /1230 . Finally, all characters before the first digit in the pattern are floated to the right, next to the first non-zero digit, resulting in C **1230 . The digits of C0004J are mapped to the pattern, resulting in C**0/0041CR. Because the value is negative, the characters (CCR) to the right of the last digit are kept. All digits before the first T digit are replaced with blanks, resulting in C** / 041CR. Finally, all characters before the first digit in the pattern are floated to the right, next to the first non-zero digit, resulting in C **041CR. In general terms, the steps DFSORT takes conceptually to produce the edited output from the numeric value are as follows: v Map the digits of the numeric value to the pattern, padding on the left with zeros, if necessary. v If the value is positive, replace the leading and trailing signs (if any) with the characters for positive values specified by the SIGNS parameter and replace any characters between the last digit and the trailing sign (if any) with blanks. Otherwise, replace the leading and trailing signs (if any) with the characters for negative values specified by the SIGNS parameter and keep any characters between the last digit and the trailing sign (if any). v Replace all digits before the first non-zero (I) or significant digit (T) with blanks. v Float all characters (if any) before the first digit in the pattern to the right, next to the first non-zero (I) or significant digit (T). The following additional rules apply to edit patterns: v An insignificant digit (I) after a significant digit (T) is treated as a significant digit. v If SIGNS is specified, an S in the first or last character of the pattern is treated as a sign; an S anywhere else in the pattern is treated as the letter S. If SIGNS is not specified, an S anywhere in the pattern is treated as the letter S. v If the pattern contains fewer digits than the value, the leftmost digits of the value will be lost, intentionally or unintentionally. As an example, if you specify 5,5,ZD,EDIT=(IIT) for a value of C12345, the result will be C345. As another example, if you specify 1,6,ZD,EDIT=($IIT.T) for a value of C100345, the result will be C $34.5. EDxy specifies an edit pattern for presenting numeric data. EDxy is a special variation of EDIT that allows other characters to be substituted for I and T in the pattern. For example, if you use EDAB instead of EDIT, you must use A in the pattern instead of I and use B instead of T to represent digits. x and y must not be the same character. If SIGNS is specified, x and y must not be S. If SIGNz is specified, x and y must not be the same character as z. You can select x and y from: A-Z, #, $, @, and 0-9. SIGNS specifies the sign values to be used when editing numeric values according to

270

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

the edit mask (Mn) or pattern (EDIT or EDxy). You can specify any or all of the four sign values. Any value not specified must be represented by a comma. Blank will be used for any sign value you do not specify. As examples, SIGNS=(+,) specifies + for lp, for ln, blank for tp, and blank for tn; SIGNS=(,,+,) specifies blank for lp, blank for ln, + for tp, and for tn. lp specifies the value for the leading positive sign. If an S is specified as the first character of the edit mask or pattern and the value is positive, the lp value will be used as the leading sign. ln specifies the value for the leading negative sign. If an S is specified as the first character of the edit mask or pattern and the value is negative, the ln value will be used as the leading sign. tp specifies the value for the trailing positive sign. If an S is specified as the last character of the edit mask or pattern and the value is positive, the tp value will be used as the trailing sign. tn specifies the value for the trailing negative sign. If an S is specified as the last character of the edit mask or pattern and the value is negative, the tn value will be used as the trailing sign. If you want to use any of the following characters as sign values, you must enclose them in single apostrophes: comma, blank, or unbalanced left or right parentheses. A single apostrophe must be specified as four single apostrophes (that is, two single apostrophes enclosed in single apostrophes). A semicolon cannot be substituted for a comma as the delimiter between sign characters. SIGNz specifies the sign values to be used when editing numeric values according to the edit pattern (EDIT or EDxy). SIGNz is a special variation of SIGNS which allows another character to be substituted for S in the pattern. For example, if you use SIGNX instead of SIGNS, you must use X in the pattern instead of S to identify a sign. If EDIT is specified, z must not be I or T. If EDxy is specified, z must not be the same character as either x or y. You can select z from: A-Z, #, $, @, and 0-9. LENGTH specifies the length of the edited output field. If the implied length of the edited output field produced using an edit mask or edit pattern is not suitable for presenting your numeric data, LENGTH can be used to make the edited output field shorter or longer. n specifies the length of the edited output field. The value for n must be between 1 and 44. LENGTH does not change the pattern used, only the length of the resulting edited output field. For example, as discussed previously for Mn, if you specify:
OUTFIL OUTREC=(5,1,ZD,M4)

the pattern will be CST rather than CST.TT because the digit length is 1. Specifying:
OUTFIL OUTREC=(5,1,ZD,M4,LENGTH=5)

will change the pattern to C

ST, not to CST.TT.

If you specify a value for n that is shorter than the implied length, truncation will occur on the left after editing. For example, if you specify:
Chapter 3. Using DFSORT Program Control Statements

271

OUTFIL Control Statements

OUTFIL OUTREC=(1,5,ZD,EDIT=($IIT.TT),LENGTH=5)

with a value of C12345, editing according to the specified $IIT.TT pattern will produce C$123.45, but the specified length of 5 will truncate this to C23.45. If you specify a value for n that is longer than the implied length, padding on the left with blanks will occur after editing. For example, if you specify:
OUTFIL OUTREC=(1,5,ZD,EDIT=($IIT.TT),LENGTH=10)

with a value of C12345, editing according to the specified $IIT.TT pattern will produce C$123.45, but the specified length of 10 will pad this to C $123.45. Sample Syntax:
OUTFIL FNAMES=OUT1,OUTREC=(5:21,19,ZD,M19,35:46,5,ZD,M13) OUTFIL FILES=1,OUTREC=(4,8,BI,C * ,13,8,BI,80:X), ENDREC=10,OMIT=(4,8,BI,EQ,13,8,BI) OUTFIL FILES=(2,3), OUTREC=(11:55,6,FS,SIGNS=(,,+,-),LENGTH=10, 31:(41,4,PD),EDIT=(**II,IIT.TTXS),SIGNS=(,,+,-))

%nn,f,edit or (%nn,f),edit specifies that an edited numeric parsed input field is to appear in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,f,edit or (p,m,f),edit for further details. p,m,f,to or (p,m,f),to specifies that a converted numeric input field is to appear in the reformatted OUTFIL output record. You can convert BI, FI, PD, PD0, ZD, FL, CSF, FS, UFF, SFF, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3, or TM4 fields to BI, FI, PD, PDC, PDF, ZD, ZDF, ZDC, or CSF/FS fields. p m f to See p under p,m,f,edit. See m under p,m,f,edit. See f under p,m,f,edit.

fo TO=

fo (fo)

,LENGTH=

n (n)

specifies how the numeric field is to be converted for output. fo specifies the format for the output field, which can be BI, FI, PD, PDC, PDF, ZD, ZDF, ZDC, CSF or FS. Any one of these output field formats (fo) can be used with any one of the input field formats (f). If you do not specify the LENGTH parameter, DFSORT will determine the implied length of the output field from the length (m) and format (f) of the input field and the format (fo) of the output field. The implied length of the output field can be represented as follows for each output format, where d is the number of digits needed for the input field as shown in Table 45 on page 267

272

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

267, and the result is rounded down to the nearest integer:
Table 47. To Output Field Lengths Output Format BI with d <= 9 BI with d > 9 FI with d <= 9 FI with d > 9 PD, PDC, or PDF ZD, ZDF, or ZDC CSF or FS Output Length 4 8 4 8 d/2 + 1 d d+1 Example Input (f,m) FS,9 FS,10 ZD,7 ZD,12 BI,4 PD,9 FI,4 Example Output Length 4 8 4 8 6 17 21

For ZD or ZDF output, F is used as the positive sign and D is used as the negative sign. For ZDC output, C is used as the positive sign. For PD or PDC output, C is used as the positive sign and D is used as the negative sign. For PDF output, F is used as the positive sign. For CSF or FS output, blank is used as the positive sign, is used as the negative sign and leading zeros are suppressed. For ZD, ZDF, ZDC, PD, PDC, PDF, CSF, or FS output, the maximum output value is 9999999999999999999999999999999 (31 digits) and the minimum output value is -9999999999999999999999999999999 (31 digits), which correspond to the maximum and minimum input values, respectively. For BI output: v An input value greater than 18446744073709551615 (XFFFFFFFFFFFFFFFF) produces an output value of 18446744073709551615 (XFFFFFFFFFFFFFFFF). v An input value less than zero produces an absolute output value. For example, an input value of P5000 produces a BI output value of 5000 (X1388). For FI output, an input value greater than 9223372036854775807 (X7FFFFFFFFFFFFFFF) produces an output value of 9223372036854775807 (X7FFFFFFFFFFFFFFF), and an input value less than -9223372036854775808 (X8000000000000000) produces an output value of -9223372036854775808 (X8000000000000000). fo, TO=fo and TO=(fo) are interchangeable except that: v fo must be specified before the LENGTH parameter whereas TO can be specified before or after the LENGTH parameter. v TO=fo or TO=(fo) should be used after a symbol rather than fo to prevent the misinterpretation of fo as f. See the discussion of OUTFIL OUTREC in Chapter 7 for details. LENGTH specifies the length of the converted output field. If the implied length of the output field is not suitable, LENGTH can be used to make the output field shorter or longer. n specifies the length of the converted output field. The value for n must be between 1 and 44.

Chapter 3. Using DFSORT Program Control Statements

273

OUTFIL Control Statements

If you specify a value for n that is shorter than the implied length, truncation on the left will occur after conversion. For example, if you specify:
OUTFIL OUTREC=(1,8,ZD,TO=PD,LENGTH=3)

with values of ZL812345678 (XF1F2F3F4F5F6F7D8) and ZL858 (XF0F0F0F0F0F0F5F8), conversion with the implied length (5) will produce PL512345678 (X012345678D) and PL558 (X0000000058C). The specified length of 3 will then result in truncation to PL345678 (X45678D) and PL358 (X00058C). If you specify a value for n that is longer than the implied length, padding on the left will occur after conversion using: v Blanks for CSF and FS output values v Character zeros for ZD output values v Binary zeros for PD and BI output values v Binary zeros for positive FI output values v Binary ones for negative FI output values For example, if you specify:
OUTFIL OUTREC=(1,4,ZD,TO=FI,LENGTH=6)

with values of ZL41234 (XF1F2F3D4) and ZL458 (XF0F0F5F8), conversion with the implied length (4) will produce FL41234 (XFFFFFB2E) and FL458 (X000004D2). The specified length of 6 will then result in padding to FL61234 (XFFFFFFFFFB2E) and FL658 (X00000000003A). Sample Syntax:
OUTFIL OUTREC=((21,5,ZD),PD,X,8,4,ZD,TO=FI,LENGTH=2)

%nn,f,to or (%nn,f),to specifies that a converted numeric parsed input field is to appear in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,f,to or (p,m,f),to for further details. deccon,edit or (deccon),edit specifies that an edited decimal constant is to appear in the reformatted OUTFIL output record. The decimal constant must be in the form +n or n where n is 1 to 31 decimal digits. The sign (+ or ) must be specified. A decimal constant produces a signed, 31-digit zoned decimal (ZD) result to be edited as specified. If an Mn, EDIT, or EDxy parameter is not specified, the decimal constant is edited using the M0 edit mask. The default number of digits (d) used for editing is 15 for a decimal constant with 1 to 15 significant digits, or 31 for a decimal constant with 16 to 31 significant digits. If EDIT or EDxy is specified, the number of digits in the pattern (Is and Ts) is used. See edit under p,m,f,edit for further details on the edit fields you can use. Sample Syntax:
OUTFIL OUTREC=(5,8,+4096,2X,-17,M18,LENGTH=7,2X, (+2000000),EDIT=(STTTTT.TT),SIGNS=(+))

deccon,to or (deccon),to specifies that a converted decimal constant is to appear in the reformatted OUTFIL output record. The decimal constant must be in the form +n or n

274

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

where n is 1 to 31 decimal digits. The sign (+ or ) must be specified. A decimal constant produces a signed, 31-digit zoned decimal (ZD) result to be converted as specified. The default number of digits (d) used for conversion is 15 for a decimal constant with 1 to 15 significant digits, or 31 for a decimal constant with 16 to 31 significant digits. See to under p,m,f,to for further details on the to fields you can use. Sample Syntax:
OUTFIL FNAMES=OUT1, OUTREC=(6:+0,TO=PD,LENGTH=6,+0,TO=PD,LENGTH=6,/, 6:(-4096),ZD,LENGTH=12)

arexp,edit or (arexp),edit Specifies that the edited result of an arithmetic expression is to appear in the reformatted OUTFIL output record. An arithmetic expression takes the form:
term,operator,term<,operator,...>

where: v term is a field (p,m,f), a parsed field (%nn,f), or a decimal constant (+n or n). See p,m,f under p,m,f,edit for details on the fields you can use. See deccon under deccon,edit for details on the decimal constants you can use. v operator is MIN (minimum), MAX (maximum), MUL (multiplication), DIV (division), MOD (modulus), ADD (addition) or SUB (subtraction). The order of evaluation precedence for the operators is as follows unless it is changed by parentheses: 1. MIN and MAX 2. MUL, DIV and MOD 3. ADD and SUB The intermediate or final result of a DIV operation is rounded down to the nearest integer. The intermediate or final result of a MOD operation is an integer remainder with the same sign as the dividend. If an intermediate or final result of an arithmetic expression overflows 31 digits, the overflowing intermediate or final result will be truncated to 31 digits, intentionally or unintentionally. If an intermediate or final result of an arithmetic expression requires division or modulus by 0, the intermediate or final result will be set to 0, intentionally or unintentionally. An arithmetic expression produces a signed, 31-digit zoned decimal (ZD) result to be edited as specified. If an Mn, EDIT, or EDxy parameter is not specified, the result is edited using the M0 edit mask. The default number of digits (d) used for editing is 15 if every term in the expression is one of the following: v a 1-4 byte BI or FI field v a 1-8 byte PD field v a 1-15 byte ZD, FS, CSF, UFF or SFF field v a decimal constant with 1-15 significant digits. The default number of digits (d) used for editing is 31 if any term in the expression is one of the following: v a 5-8 byte BI or FI field v a 9-16 byte PD field v a 16-31 byte ZD field v a 4-byte or 8-byte FL field
Chapter 3. Using DFSORT Program Control Statements

275

OUTFIL Control Statements

v a 16-32 byte FS or CSF field v a 16-44 byte UFF or SFF field v a decimal constant with 16-31 significant digits. If EDIT or EDxy is specified, the number of digits in the pattern (Is and Ts) is used. See edit under p,m,f,edit for further details on the edit fields you can use. Sample Syntax:
OUTFIL OUTREC=(5:C% REDUCTION FOR ,21,8,C IS , ((11,6,ZD,SUB,31,6,ZD),MUL,+1000),DIV,11,6,ZD, EDIT=(SIIT.T),SIGNS=(+,-))

arexp,to or (arexp),to specifies that the converted result of an arithmetic expression is to appear in the reformatted OUTFIL output record. See arexp under arexp,edit for further details on arithmetic expressions. An arithmetic expression produces a signed, 31-digit zoned decimal (ZD) result to be converted as specified. The default number of digits (d) used for conversion is 15 if every term in the expression is one of the following: v a 1-4 byte BI or FI field v a 1-8 byte PD field v a 1-15 byte ZD, FS, CSF, UFF or SFF field v a decimal constant with 1-15 significant digits. The default number of digits (d) used for conversion is 31 if any term in the expression is one of the following: v a 5-8 byte BI or FI field v a 9-16 byte PD field v a 16-31 byte ZD field v a 4-byte or 8-byte FL field v a 16-32 byte FS or CSF field v a 16-44 byte UFF or SFF field v a decimal constant with 16-31 significant digits. See to under p,m,f,to for further details on the to fields you can use. Sample Syntax:
OUTFIL FNAMES=OUT, OUTREC=(61,3,X, 35,6,FS,ADD,45,6,FS,ADD,55,6,FS,TO=FS,LENGTH=7,X, (5,11,PD,MIN,112,11,PD),PD,LENGTH=11,X, 64,5,SEQNUM,5,ZD)

p,m,Y2x,edit specifies that an edited four-digit year CH date representation of a two-digit year input date field is to appear in the reformatted OUTFIL output record. The two-digit year date field you specify is transformed to a four-digit year ZD date field as shown in Table 39 on page 259, and then edited according to the edit parameters you specify. For example, if you specify:
OUTFIL OUTREC=(28,3,Y2V,EDIT=(TTTT-T-T))

the PL3yyxx (X0yyxxC) date value will be transformed to a Zyyyyxx date value and then edited to Cyyyy-x-x. See p,m,Y2x and p,m,f,edit for related details.

276

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

%nn,Y2x,edit specifies that an edited four-digit year CH date representation of a two-digit year parsed input date field is to appear in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,Y2x,edit for further details. p,m,Y2x,to specifies that a converted four-digit year date representation of a two-digit year input date field is to appear in the reformatted OUTFIL output record. The two-digit year date field you specify is transformed to a four-digit year ZD date field as shown in Table 39 on page 259, and then converted according to the parameters you specify. For example, if you specify:
OUTFIL OUTREC=(5,4,Y2W,TO=PD,LENGTH=6)

the Cxxyy date value will be transformed to a Zxxyyyy date value and then converted to PL6xxyyyy (X00000xxyyyyC). See p,m,Y2x and p,m,f,to for related details. %nn,Y2x,to specifies that a converted four-digit year CH date representation of a two-digit year parsed input date field is to appear in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,Y2x,to for further details p,m,lookup or %nn,lookup specifies that a character constant, hexadecimal constant, input field (p,m), or parsed input field (%nn) from a lookup table is to appear in the reformatted OUTFIL output record. You can use p,m,lookup or %nn,lookup to select a specified set constant (that is, a character or hexadecimal string) or set field (that is, an input field or parsed input field) based on matching an input value against find constants (that is, character, hexadecimal, or bit constants). p m See p under p,m,a. specifies the length in bytes of the input field to be compared to the find constants. The value for m must be 1 to 64 if character or hexadecimal find constants are used, or 1 if bit find constants are used. specifies a parsed input field to be compared to the find constants. See PARSE for details of parsed fields. Specifies how the input field or parsed input field is to be changed to the output field, using a lookup table. CHANGE

%nn lookup

. CHANGE=(-v ,find,set ) ,NOMATCH=(set)

specifies a list of change pairs, each consisting of a find constant to be compared to the input field value or parsed input field value and a set constant or set field to use as the output field when a match occurs.
Chapter 3. Using DFSORT Program Control Statements

277

OUTFIL Control Statements

v specifies the length in bytes of the output field to be inserted in the reformatted OUTFIL output record. The value for v must be between 1 and 64.

find specifies a find constant to be compared to the input field value or parsed input field value. If the input field value or parsed input field value matches the find constant, the corresponding set constant or set field is used for the output field. The find constants can be either character string constants, hexadecimal string constants, or bit constants: v Character string constants (Cxx...x) and hexadecimal string constants (Xyy...yy) can be 1 to m bytes and can be intermixed with each other, but not with bit constants. See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. If the string is less than m bytes, it will be padded on the right to a length of m bytes, using blanks (X40) for a character string constant or zeros (X00) for a hexadecimal string constant. v Bit constants (Bbbbbbbbb) must be 1 byte and cannot be intermixed with character or string constants. See INCLUDE Control Statement on page 98 for details of coding bit constants. For bit constants, because of the specification of bits to be ignored, more than one find constant can match an input field value; the set constant for the first match found will be used as the output field. For example, if you specify:
OUTFIL OUTREC=(5,1, CHANGE=(1,B11......,CA,B1.......,CB))

input field value XC0 (B11000000) matches both bit constants, but CA will be used for the set constant, because its find constant is the first match. set specifies a set constant or set field to be used as the output field if the corresponding find constant matches the input field value or parsed input field value. Set constants and set fields can be intermixed. Set constants can be either character string constants (Cxx...x) or hexadecimal string constants (X'yy...yy') of 1 to v bytes. See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. If the string is less than v bytes, it will be padded on the right to a length of v bytes, using blanks (X'40') for a character string constant or zeros (X'00') for a hexadecimal string constant. Set fields are specified as q,n or %nn. q specifies the input position. See p under p,m,a for details of coding q. n specifies the input length of 1 to v bytes. %nn specifies a parsed input field. See PARSE for details of parsed fields. If the set field length is less than v, the input field or parsed input field will be padded on the right to a length of v bytes, using blanks (X40). NOMATCH specifies the action to be taken if an input field value or parsed input

278

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

field value does not match any of the find constants. If you do not specify NOMATCH, and a match is not found for any input value, DFSORT terminates processing. If you specify NOMATCH, it must follow CHANGE. set specifies a set constant or set field to be used as the output field if a match is not found. Set constants can be either character string constants (Cxx...x) or hexadecimal string constants (Xyy...yy) of 1 to v bytes and can be intermixed. See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. If the string is less than v bytes, it will be padded on the right to a length of v bytes, using blanks (X40) for a character string constant or zeros (X00) for a hexadecimal string constant. Set fields are specified as q,n or %nn. q specifies the input position. See p under p,m,a for details of coding q. n specifies the input length of 1 to v bytes. %nn specifies a parsed input field. See PARSE for details of parsed fields. If the set field length is less than v, the input field or parsed input field will be padded on the right to a length of v bytes, using blanks (X40). Sample Syntax:
OUTFIL FILES=1, OUTREC=(11,1, CHANGE=(6, CR,CREAD, CU,CUPDATE, XFF,CEMPTY, CX,35,6, CA,CALTER), NOMATCH=(11,6), 4X, 21,1, CHANGE=(10, B.1......,CVSAM, B.0......,CNON-VSAM))

p,m,justify specifies that a left-justified or right-justified input field is to appear in the reformatted OUTFIL output record. For a left-justified field, leading blanks are removed and the characters from the first nonblank to the last nonblank are shifted left, with blanks inserted on the right if needed. For a right-justified field, trailing blanks are removed and the characters from the last nonblank to the first nonblank are shifted right, with blanks inserted on the left if needed. Optionally: v specific leading and trailing characters can be changed to blanks before justification begins v a leading string can be inserted v a trailing string can be inserted v the output length can be changed (its equal to the input length by default) p See p under p,m,a.

m See m under p,m,a.

Chapter 3. Using DFSORT Program Control Statements

279

OUTFIL Control Statements

justify specifies how the input field is to be justified for output. JFY

, JFY= ( SHIFT=LEFT SHIFT=RIGHT LENGTH=n PREBLANK=list LEAD=string TRAIL=string )

Note: For clarity, in the examples below, b is used to represent a blank in the input fields. SHIFT=LEFT specifies that a left-justified input field is to appear in the reformatted OUTFIL output record. Leading blanks are removed and the characters from the first nonblank to the last nonblank are shifted left, with blanks inserted on the right if needed. For example, with:
1,15,JFY=(SHIFT=LEFT)

an input field of:

bbbbABbCDbbEFbb

results in an output field of:

ABbCDbbEFbbbbbb

m is used for the output field length unless LENGTH=n is specified. If the left-justified input field is shorter than the output field length, blanks are inserted on the right. If the left-justified input field is longer than the output field length, characters are truncated on the right. You can use LENGTH=n to prevent padding or truncation. SHIFT=RIGHT specifies that a right-justified input field is to appear in the reformatted OUTFIL output record. Trailing blanks are removed and the characters from the last nonblank to the first nonblank are shifted right, with blanks inserted on the left if needed. For example, with:
1,15,JFY=(SHIFT=RIGHT)

an input field of:

bbbbABbCDbbEFbb

results in an output field of:

bbbbbbABbCDbbEF

280

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

m is used for the output field length unless LENGTH=n is specified. If the right-justified input field is shorter than the output field length, blanks are inserted on the left. If the right-justified input field is longer than the output field length, characters are truncated on the left. You can use LENGTH=n to prevent padding or truncation. LENGTH=n specifies the length of the justified output field. The value for n must be between 1 and 32752. If LENGTH=n is not specified, m (the input field length) is used for the length of the justified output field. You can use LENGTH=n to prevent padding or truncation. PREBLANK=list specifies a list of one or more characters to be changed to blanks before justify processing begins. Only leading and trailing characters are changed to blanks. Scanning from left to right, each nonblank character at the start of the input field that matches a character in the list is replaced by a blank character, until a nonblank character not in the list is found. Scanning from right to left, each nonblank character at the end of the input field that matches a character in the list will be replaced by a blank character, until a nonblank character not in the list is found. list can be 1 to 10 characters specified using a character string constant (Cxx...x) or a hexadecimal string constant (Xyy...yy). See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. Each character in the list is treated as one character to be preblanked. Thus PREBLANK=C* specifies an asterisk is to be preblanked, and PREBLANK=C,;$ specifies a comma, a semicolon and a dollar sign are each to be preblanked. For example, lets say we have an input field of:
**b<*ABbCD*bEF>*b**

If we specify:
1,19,JFY=(SHIFT=LEFT,PREBLANK=C*)

each leading or trailing asterisk is changed to a blank before leftjustify processing begins. So the output field is:
<*ABbCD*bEF>bbbbbbb

If we specify:
1,19,JFY=(SHIFT=RIGHT,PREBLANK=C*<>)

each leading or trailing asterisk, less than sign and greater than sign is changed to a blank before right-justify processing begins. So the output field is:
bbbbbbbbbbABbCD*bEF

LEAD=string specifies a string to be inserted in the output field before the first nonblank character in the input field. string can be 1 to 50 characters specified using a character string constant (Cxx...x) or a hexadecimal string constant (Xyy...yy). See
Chapter 3. Using DFSORT Program Control Statements

281

OUTFIL Control Statements

INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. For example, lets say we have an input field of:
bABCbEbbbbb

If we specify:
1,11,JFY=(SHIFT=RIGHT,LEAD=CXYZ)

the output field is:

bbbXYZABCbE

When we add characters with LEAD=string, its often necessary to specify LENGTH=n to avoid truncation. For example, lets say we have an input field of:
AbBbC

If we specify:
1,5,JFY=(SHIFT=LEFT,LEAD=CXYZ)

the output field is:

XYZAb

Since the output field length is defaulted to the input field length of 5, the resulting 8 characters (XYZAbBbC) are truncated on the right to 5 characters (XYZAb) for output. If we instead specify:
1,5,JFY=(SHIFT=LEFT,LEAD=CXYZ,LENGTH=8)

the output field is:

XYZAbBbC

LENGTH=8 increases the output field by the 3 LEAD characters and truncation is prevented. TRAIL=string specifies a string to be inserted in the output field after the last nonblank character in the input field. string can be 1 to 50 characters specified using a character string constant (Cxx...x) or a hexadecimal string constant (Xyy...yy). See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. For example, lets say we have an input field of:
bABCbEbbbbb

If we specify:
1,11,JFY=(SHIFT=LEFT,TRAIL=CXYZ)

the output field is:

ABCbEXYZbbb

When we add characters with TRAIL=string, its often necessary to specify LENGTH=n to avoid truncation. For example, lets say we have an input field of:
AbBbC

282

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

If we specify:
1,5,JFY=(SHIFT=RIGHT,TRAIL=CXYZ)

the output field is:

bCXYZ

Since the output field length is defaulted to the input field length of 5, the resulting 8 characters (AbBbCXYZ) are truncated on the left to 5 characters (bCXYZ) for output. If we instead specify:
1,5,JFY=(SHIFT=RIGHT,TRAIL=CXYZ,LENGTH=8)

the output field is:

AbBbCXYZ

LENGTH=8 increases the output field by the 3 TRAIL characters and truncation is prevented. Sample Syntax:
OUTFIL BUILD=(5:16,20,JFY=(SHIFT=LEFT,PREBLANK=C*, LEAD=C<A>,TRAIL=C</A>,LENGTH=22))

%nn,justify specifies that a left-justified or right-justified parsed input field is to appear in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,justify for further details. p,m,squeeze specifies that a left-squeezed or right-squeezed input field is to appear in the reformatted OUTFIL output record. For a left-squeezed field, all blanks are removed and the characters from the first nonblank to the last nonblank are shifted left, with blanks inserted on the right if needed. For a right-squeezed field, all blanks are removed and the characters from the last nonblank to the first nonblank are shifted right, with blanks inserted on the left if needed. Optionally: v specific characters can be changed to blanks before squeezing begins v a leading string can be inserted v a trailing string can be inserted v a string (for example, a comma delimiter) can be inserted wherever a group of blanks is removed between the first nonblank and the last nonblank v blanks can be kept as is between paired apostrophes (AB CD EF) or paired quotes (AB CD EF) v the output length can be changed (its equal to the input length by default) p See p under p,m,a.

m See m under p,m,a. squeeze Specifies how the input field is to be squeezed for output. SQZ

Chapter 3. Using DFSORT Program Control Statements

283

OUTFIL Control Statements

, SQZ= ( SHIFT=LEFT SHIFT=RIGHT LENGTH=n PREBLANK=list LEAD=string MID=string TRAIL=string PAIR=APOST PAIR=QUOTE )

Note: For clarity, in the examples below, b is used to represent a blank in the input fields. SHIFT=LEFT specifies that a left-squeezed input field is to appear in the reformatted OUTFIL output record. All blanks are removed and the characters from the first nonblank to the last nonblank are shifted left, with blanks inserted on the right if needed. For example, with:
1,15,SQZ=(SHIFT=LEFT)

an input field of:

bbbbABbCDbbEFbb

results in an output field of:

ABCDEFbbbbbbbbb

m is used for the output field length unless LENGTH=n is specified. If the left-squeezed input field is shorter than the output field length, blanks are inserted on the right. If the left-squeezed input field is longer than the output field length, characters are truncated on the right. SHIFT=RIGHT specifies that a right-squeezed input field is to appear in the reformatted OUTFIL output record. All blanks are removed and the characters from the last nonblank to the first nonblank are shifted right, with blanks inserted on the left if needed. For example, with:
1,15,SQZ=(SHIFT=RIGHT)

an input field of:

bbbbABbCDbbEFbb

results in an output field of:

bbbbbbbbbABCDEF

m is used for the output field length unless LENGTH=n is specified. If the right-squeezed input field is shorter than the output field length, blanks are inserted on the left. If the right-squeezed input field is longer than the output field length, characters are truncated on the left.

284

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

LENGTH=n specifies the length of the squeezed output field. The value for n must be between 1 and 32752. If LENGTH=n is not specified, m (the input field length) is used for the length of the squeezed output field. PREBLANK=list specifies a list of one or more characters to be changed to blanks before squeeze processing begins. Each nonblank character in the input field that matches a character in the list is replaced by a blank character. list can be 1 to 10 characters specified using a character string constant (Cxx...x) or a hexadecimal string constant (Xyy...yy). See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. Each character in the list is treated as one character to be preblanked. Thus PREBLANK=C* specifies an asterisk is to be preblanked, and PREBLANK=C,;$ specifies a comma, a semicolon and a dollar sign are each to be preblanked. For example, lets say we have an input field of:
**b<*ABbC<>D*bEF>*b**

If we specify:
1,21,SQZ=(SHIFT=LEFT,PREBLANK=C*,LENGTH=12)

each asterisk is changed to a blank before left-squeeze processing begins. The output field is:
<ABC<>DEF>bb

If we specify:
1,21,SQZ=(SHIFT=RIGHT,PREBLANK=C*<>)

each asterisk, less than sign and greater than sign is changed to a blank before right-squeeze processing begins. The output field is:
bbbbbbbbbbbbbbbABCDEF

LEAD=string specifies a string to be inserted in the output field before the first nonblank character in the input field. string can be 1 to 50 characters specified using a character string constant (Cxx...x) or a hexadecimal string constant (Xyy...yy). See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. For example, lets say we have an input field of:
bABCbEbbbbb

If we specify:
1,11,SQZ=(SHIFT=RIGHT,LEAD=CXYZ)

the output field is:

bbbbXYZABCE

Chapter 3. Using DFSORT Program Control Statements

285

OUTFIL Control Statements

When we add characters with LEAD=string, its often necessary to specify LENGTH=n to avoid truncation. For additional information on this, see LEAD=string for JFY above. MID=string specifies a string to be inserted in the output field wherever one or more blanks is removed between the first nonblank and the last nonblank. string can be 1 to 10 characters specified using a character string constant (Cxx...x) or a hexadecimal string constant (Xyy...yy). See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. For example, lets say we have an input field of:
bABbbCbbbDbE

If we specify:
1,12,SQZ=(SHIFT=LEFT,MID=C,)

the output field is:

AB,C,D,Ebbbb

When we add characters with MID=string, its often necessary to specify LENGTH=n to avoid truncation. For example, lets say we have an input field of:
AbBbC

If we specify:
1,5,SQZ=(SHIFT=LEFT,MID=CXY)

the output field is:

AXYBX

Since the output field length is defaulted to the input field length of 5, the resulting 7 characters (AXYBXYC) are truncated on the right to 5 characters (AXYBX) for output. If we instead specify:
1,5,SQZ=(SHIFT=LEFT,MID=CXY,LENGTH=7)

the output field is:

AXYBXYC

LENGTH=7 increases the output field to accommodate the MID strings and truncation is prevented. TRAIL=string specifies a string to be inserted in the output field after the last nonblank character in the input field. string can be 1 to 50 characters specified using a character string constant (Cxx...x) or a hexadecimal string constant (Xyy...yy). See INCLUDE Control Statement on page 98 for details of coding character and hexadecimal string constants. For example, lets say we have an input field of:
bABCbEbbbbb

286

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

If we specify:
1,11,SQZ=(SHIFT=LEFT,LEAD=X7D,TRAIL=X7D)

the output field is:

ABCEbbbbb

When we add characters with TRAIL=string, its often necessary to specify LENGTH=n to avoid truncation. For additional information on this, see TRAIL=string for JFY above. PAIR=APOST specifies that blanks and PREBLANK characters between apostrophe () pairs are to be kept as is. Use PAIR=APOST when you have literals that should not be squeezed. For example, lets say we have an input field of:
b*bABbb**CbbbD*Ebb*

If we specify:
1,25,SQZ=(SHIFT=LEFT,PREBLANK=C*,MID=C,)

all of the blanks and asterisks, including those inside the apostrophe pairs, are squeezed out. The output field is:
AB,,C,D,E,bbbbbbbbb

However, if we specify:
1,25,SQZ=(SHIFT=LEFT,PREBLANK=C*,MID=C,, PAIR=APOST)

only the blanks and asterisks outside of the apostrophe pairs are squeezed out. The output field is:
ABbb**C,D*Ebbbbbbbb

If an apostrophe is specified in the PREBLANK list (for example, PREBLANK=C or PREBLANK=X7D), it is ignored, that is, an apostrophe in the input field is not replaced by a blank. So if you want each apostrophe to be replaced by a blank, do not specify PAIR=APOST. For SHIFT=LEFT, scanning is left to right. If an apostrophe is found with no subsequent apostrophe, all of the characters from the apostrophe to the end of the input field are ignored. For example, lets say we have an input field of:
bbXbYABCbbbDbb

If we specify:
1,15,SQZ=(SHIFT=LEFT,PAIR=APOST)

theres an unpaired apostrophe, so all of the characters from the apostrophe to the end of the input field are ignored. The output field is:
XYABCbbbDbbbbb

For SHIFT=RIGHT, scanning is right to left. If an apostrophe is found with no previous apostrophe, all of the characters from the

Chapter 3. Using DFSORT Program Control Statements

287

OUTFIL Control Statements

apostrophe to the beginning of the input field are ignored. For example, lets say we have an input field of:
bbXbYABCbbbDbb

If we specify:
1,15,SQZ=(SHIFT=RIGHT,PAIR=APOST)

theres an unpaired apostrophe, so all of the characters from the apostrophe to the beginning of the input field are ignored. The output field is:
bbbbbbbXbYABCD

PAIR=QUOTE specifies that blanks and PREBLANK characters between quote () pairs are to be kept as is. Use PAIR=QUOTE when you have literals that should not be squeezed. For example, lets say we have an input field of:
b*b"ABbb*""*C"bbb"D*Ebb"*

If we specify:
1,25,SQZ=(SHIFT=LEFT,PREBLANK=C*,MID=C,)

all of the blanks and asterisks, including those inside the quote pairs, are squeezed out. The output field is:
"AB,"",C","D,E,"bbbbbbbbb

However, if we specify:
1,25,SQZ=(SHIFT=LEFT,PREBLANK=C*,MID=C,, PAIR=QUOTE)

only the blanks and asterisks outside of the quote pairs are squeezed out. The output field is:
"ABbb*""*C","D*Ebbbbbbbb

If a quote is specified in the PREBLANK list (for example, PREBLANK=C or PREBLANK=X7F), it is ignored, that is, a quote in the input field is not replaced by a blank. So if you want each quote to be replaced by a blank, do not specify PAIR=QUOTE. For SHIFT=LEFT, scanning is left to right. If a quote is found with no subsequent quote, all of the characters from the quote to the end of the input field are ignored. For example, lets say we have an input field of:
bbXbY"ABCbbbDbb

If we specify:
1,15,SQZ=(SHIFT=LEFT,PAIR=QUOTE)

theres an unpaired quote, so all of the characters from the quote to the end of the input field are ignored. The output field is:
XY"ABCbbbDbbbbb

288

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

For SHIFT=RIGHT, scanning is right to left. If a quote is found with no previous quote, all of the characters from the quote to the beginning of the input field are ignored. For example, lets say we have an input field of:
bbXbY"ABCbbbDbb

If we specify:
1,15,SQZ=(SHIFT=RIGHT,PAIR=QUOTE)

theres an unpaired quote, so all of the characters from the quote to the beginning of the input field are ignored. The output field is:
bbbbbbbXbY"ABCD

Sample Syntax:
OUTFIL BUILD=(5:16,20,SQZ=(SHIFT=LEFT,PAIR=QUOTE,PREBLANK=C<>))

%nn,squeeze specifies that a left-squeezed or right-squeezed parsed input field is to appear in the reformatted OUTFIL output record. See PARSE for details of parsed fields. See p,m,squeeze for further details. seqnum

SEQNUM,n,fs ,START=j ,INCR=i ,RESTART=(p,m) ,RESTART=(%nn)

specifies that a sequence number is to appear in the reformatted OUTFIL output record. The sequence numbers are assigned in the order in which the records are received for OUTFIL OUTREC processing. You can create BI, PD, ZD, CSF, or FS sequence numbers and control their lengths, starting values and increment values. You can restart the sequence number at the start value each time a specified OUTFIL input field (p,m) or parsed input field (%nn) changes. n specifies the length of the sequence number. The value for n must be between 1 and 16.

fs specifies the format for the sequence number, which can be BI, PD, ZD, CSF, or FS. For a ZD format sequence number, F is used as the sign. For a PD format sequence number, C is used as the sign. For a CSF or FS format sequence number, blank is used as the sign and leading zeros are suppressed. For a PD, ZD, CSF, or FS format sequence number, the maximum value DFSORT can create is limited to the lesser of 15 decimal digits or the output field length (n). If a sequence number overflows this limit, it will be truncated to the lesser of 15 decimal digits or the output field length, and then subsequently incremented as usual. For a BI format sequence number, the maximum value DFSORT can create is limited to the lesser of 8 bytes of ones (XFFFFFFFFFFFFFFFF) or the number of ones that will fit in the specified output field length
Chapter 3. Using DFSORT Program Control Statements

289

OUTFIL Control Statements

(n). If a sequence number overflows this limit, it will be truncated to the lesser of 8 bytes or the output field length, and then subsequently incremented as usual. START specifies the starting value for the sequence number. j specifies the starting value. The value for j must be between 0 and 100000000000. The default for j is 1.

INCR specifies the increment value for the sequence number. i specifies the increment value. The value for i must be between 1 and 10000000. The default for i is 1.

RESTART specifies that DFSORT is to restart the sequence number at the starting value (START=j) when the binary value for the specified OUTFIL input field or parsed input field changes. This allows you to sequence each set of records with the same value (that is, duplicate records) separately. For example: Without RESTART, if you had six OUTFIL input records with A, A, A, B, B and C, respectively, in position 1, the output records would be given the sequence numbers 1, 2, 3, 4, 5 and 6. But with RESTART=(1,1), the output records are given the sequence numbers 1, 2, 3, 1, 2 and 1; DFSORT restarts at the starting value (1, by default) when the input value at position 1 changes from A to B and again when it changes from B to C. p,m or %nn specifies the OUTFIL input field or parsed input field to be used to determine when the sequence number is to be restarted at the starting value. If a variable-length OUTFIL input record is too short to contain a specified restart field, binary zeros (or blanks for a parsed field) will be used for the missing bytes, intentionally or unintentionally. p See p under p,m,a m specifies the length in bytes of the input field. The value for m must be between 1 and 256. %nn specifies the parsed input field. See PARSE for details of parsed fields. Sample Syntax:
OUTFIL FNAMES=O1,OUTREC=(SEQNUM,6,ZD,START=1000,INCR=50, X,22,8,X,13,5) OUTFIL FNAMES=O2,OUTREC=(1,12,SEQNUM,4,BI) OUTFIL FNAMES=O3,OUTREC=(1,80,81:SEQNUM,8,ZD,START=21,INCR=20, RESTART=(35,8))

Default for BUILD or OUTREC: None; must be specified. OVERLAY

290

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

, OVERLAY= ( c: s p,m ,a %nn p p,m,HEX %nn,HEX p,HEX p,m,TRAN=LTOU %nn,TRAN=LTOU p,TRAN=LTOU p,m,TRAN=UTOL %nn,TRAN=UTOL p,TRAN=UTOL p,m,TRAN=ALTSEQ %nn,TRAN=ALTSEQ p,TRAN=ALTSEQ p,m,Y2x %nn,Y2x p,m,Y2x(c) %nn,Y2x(c) p,m,Y2xP %nn,Y2xP p,m,f ,edit %nn,f ,to (p,m,f) (%nn,f) deccon ,edit (deccon) ,to arexp ,edit (arexp) ,to p,m,Y2x ,edit ,to %nn,Y2x ,edit ,to p,m,lookup %nn,lookup p,m,justify %nn,justify p,m,squeeze %nn,squeeze seqnum )

Specifies each item that is to overlay specific columns in the reformatted record. Columns that are not overlaid remain unchanged. If you want to insert, rearrange, or delete fields, use BUILD or OUTREC rather than OVERLAY. Use OVERLAY only to overlay existing columns or to add fields at the end of every record. OVERLAY can be easier to use then BUILD or OUTREC when you just want to change a few fields without rebuilding the entire record. For fixed-length records, the first input and output data byte starts at position 1. For variable-length records, the first input and output data byte starts at position 5, after the RDW in positions 1-4.

Chapter 3. Using DFSORT Program Control Statements

291

OUTFIL Control Statements

Use c: (column) to specify the output positions to be overlaid. If you do not specify c: for the first item, it defaults to 1:. If you do not specify c: for any other item, it starts after the previous item. For example, if you specify:
OUTFIL OVERLAY=(25,2,11:CA,15,3,C**)

Input positions 25-26 are placed at output positions 1-2; CA is placed at output position 11; input positions 15-17 are placed at output positions 12-14; and C** is placed at output positions 15-16. The rest of the record remains unchanged. You can specify items in any order, you can change the same item multiple times and you can overlap output columns. Changes to earlier items affect changes to later items. For example, say you specify:
OUTFIL OVERLAY=(21:8,4,ZD,MUL,+10,TO=ZD,LENGTH=6, 5:5,1,TRAN=UTOL, 5:5,1,CHANGE=(1,Ca,CX,Cb,CY),NOMATCH=(5,1))

and input position 5 has A. The second item (UTOL) would change A to a and the third item (CHANGE) would change a again to X. If you specify an OVERLAY item that extends the overlay record beyond the end of the input record, the reformatted record length is automatically increased to that length, and blanks are filled in on the left as needed. For variable-length records, the RDW length is increased to correspond to the larger reformatted record length after all of the OVERLAY items are processed. For example, if your OUTFIL input record has a length of 40 and you specify:
OUTFIL OVERLAY=(16:CABC,51:5C*,35:15,2)

the OUTFIL output record is given a length of 55. Blanks are filled in from columns 41-50. For variable-length records, the length in the RDW is changed from 40 to 55 after all of the OVERLAY items are processed. Missing bytes in specified input fields are replaced with blanks so the padded fields can be processed. You can use the OVERLAY parameter with the FTOV parameter to convert fixed-length record data sets to variable-length record data sets. You can use the VLTRIM parameter with the OVERLAY parameter to remove specified trailing bytes from the end of variable-length records. You can use the OVERLAY parameter with any or all of the report parameters in the same way as for the BUILD or OUTREC parameter. The OVERLAY parameter of the OUTREC statement applies to all input records whereas the OVERLAY parameter of the OUTFIL statement only applies to the OUTFIL input records for its OUTFIL group. See OUTFIL OUTREC for details of the items listed in the OVERLAY syntax diagram above. You can specify all of the items for OVERLAY in the same way that you can specify them for BUILD or OUTREC with the following exceptions: v You cannot specify p or p,HEX or p,TRAN=value for OVERLAY. v You cannot specify / for OVERLAY. v For p,m,H or p,m,F or or p,m,D fields specified for OVERLAY, fields are aligned as necessary without changing the preceding bytes. v For variable-length records, you must not overlay positions 1-4 (the RDW) for OVERLAY, so be sure to specify the first column (c:) as 5 or greater. Do not specify 1:, 2:, 3: or 4: anywhere in your OVERLAY parameter. If you do not specify the first column, it will default to 1: which is invalid for

292

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

variable-length records with OVERLAY. Whereas OUTREC=(1,m,...) is required, OVERLAY=(1,m) is not allowed since it would overlay the RDW. Sample Syntax: Fixed input records:
OUTFIL FNAMES=FLR, OVERLAY=(21:21,4,ZD,TO=PD,LENGTH=4, 2:5,8,HEX,45:C*,32,4,C*,81:SEQNUM,5,ZD)

Variable input records:

OUTFIL FNAMES=VLR, OVERLAY=(5:X0001,28:CDate is ,YDDDNS=(4D), 17:5C*)

Default for OVERLAY: None; must be specified. IFTHEN

, IFTHEN=( WHEN=INIT ,PARSE=(definitions) ,BUILD=(items) ,OVERLAY=(items) WHEN=(logexp) ,PARSE=(definitions) ,BUILD=(items) ,HIT=NEXT ,OVERLAY=(items) WHEN=ANY ,PARSE=(definitions) ,BUILD=(items) ,HIT=NEXT ,OVERLAY=(items) WHEN=NONE ,PARSE=(definitions) ,BUILD=(items) ,OVERLAY=(items) )

IFTHEN clauses allow you to reformat different records in different ways by specifying how build or overlay items are to be applied to records that meet given criteria. IFTHEN clauses let you use simple or complex conditional logic to choose how different record types are reformatted. If you want to insert, rearrange, or delete fields in the same way for every record, use BUILD or OUTREC rather than IFTHEN. If you want to overlay existing columns in the same way for every record, use OVERLAY rather than IFTHEN. Use IFTHEN clauses if you want to insert, rearrange, delete or overlay fields in different ways for different records. You can use four types of IFTHEN clauses as follows: v WHEN=INIT: Use one or more WHEN=INIT clauses to apply build or overlay items to all of your input records. WHEN=INIT clauses are processed before any of the other IFTHEN clauses. v WHEN=(logexp): Use one or more WHEN=(logexp) clauses to apply build or overlay items to your input records that meet specified criteria. A WHEN=(logexp) clause is satisfied when the logical expression evaluates as true. v WHEN=ANY: Use a WHEN=ANY clause after multiple WHEN=(logexp) clauses to apply additional build or overlay items to your input records if they satisfied the criteria for any of the preceding WHEN=(logexp) clauses. v WHEN=NONE: Use one or more WHEN=NONE clauses to apply build or overlay items to your input records that did not meet the criteria for any of the WHEN=(logexp) clauses. WHEN=NONE clauses are processed after any
Chapter 3. Using DFSORT Program Control Statements

293

OUTFIL Control Statements

of the other IFTHEN clauses. If you do not specify a WHEN=NONE clause, only the WHEN=INIT changes (if any) are applied to input records that do not meet the criteria for any of the WHEN=(logexp) clauses. IFTHEN clauses are processed in the following order: v WHEN=INIT clauses v WHEN=(logexp) clauses and WHEN=ANY clauses v WHEN=NONE clauses Processing of IFTHEN clauses continues unless one of the following occurs: v A WHEN=(logexp) or WHEN=ANY clause is satisfied, and HIT=NEXT is not specified. v A WHEN=(logexp), WHEN=ANY or WHEN=NONE clause is satisfied, and BUILD with / is specified (multiple output records). v There are no more IFTHEN clauses to process. When processing of IFTHEN clauses stops, the IFTHEN record created so far is used as the output record. Example:
OUTFIL IFTHEN=(WHEN=(12,1,BI,ALL,X3F),OVERLAY=(18:CYes)), IFTHEN=(WHEN=(35,2,PD,EQ,+14),BUILD=(1,40,45,3,HEX),HIT=NEXT), IFTHEN=(WHEN=(35,2,PD,GT,+17),BUILD=(1,40,41,5,HEX),HIT=NEXT), IFTHEN=(WHEN=ANY,BUILD=(1,55,CABC,70:X)), IFTHEN=(WHEN=(35,2,PD,EQ,+8),BUILD=(1,40,2/,45,10)), IFTHEN=(WHEN=(63,2,CH,EQ,CAB),OVERLAY=(18:CNo)), IFTHEN=(WHEN=NONE,BUILD=(1,40,51,8,TRAN=LTOU))

For this example, the IFTHEN clauses are processed as follows: If IFTHEN clause 1 is satisfied, its overlay item is applied and IFTHEN processing stops. If IFTHEN clause 1 is not satisfied, its overlay item is not applied and IFTHEN processing continues. If IFTHEN clause 2 is satisfied, its build items are applied and IFTHEN processing continues. If IFTHEN clause 2 is not satisfied, its build items are not applied and IFTHEN processing continues. If IFTHEN clause 3 is satisfied, its build items are applied and IFTHEN processing continues. If IFTHEN clause 3 is not satisfied, its build items are not applied and IFTHEN processing continues. If IFTHEN clause 4 is satisfied, its build items are applied and IFTHEN processing stops. If IFTHEN clause 4 is not satisfied, its build items are not applied and IFTHEN processing continues. If IFTHEN clause 5 is satisfied, its build items are applied and IFTHEN processing stops. If IFTHEN clause 5 is not satisfied, its build items are not applied and IFTHEN processing continues. If IFTHEN clause 6 is satisfied, its overlay item is applied and IFTHEN processing stops. If IFTHEN clause 6 is not satisfied, its overlay item is not applied and IFTHEN processing continues. If IFTHEN clause 7 is satisfied, its build items are applied and IFTHEN processing stops. If IFTHEN clause 7 is not satisfied, its build items are not applied and IFTHEN processing stops.

294

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

All of the IFTHEN clauses operate sequentially on an IFTHEN record. The IFTHEN record is created initially from the input record. Each IFTHEN clause tests and changes the IFTHEN record, as appropriate. Thus, changes made by earlier IFTHEN clauses are seen by later IFTHEN clauses. For example, if you have a 40-byte input record and specify:
OUTFIL IFTHEN=(WHEN=INIT,OVERLAY=(8:8,4,ZD,ADD,+1,TO=ZD,LENGTH=4)), IFTHEN=(WHEN=(8,4,ZD,EQ,+27),OVERLAY=(28:CYes)), IFTHEN=(WHEN=NONE,OVERLAY=(28:CNo))

The WHEN=INIT clause adds 1 to the ZD value and stores it in the IFTHEN record. The WHEN=(8,4,ZD,EQ,+27) clause tests the incremented ZD value in the IFTHEN record rather than the original ZD value in the input record. The IFTHEN record is adjusted as needed for the records created or changed by the IFTHEN clauses. For fixed-length records, blanks are filled in on the left as needed. For variable-length records, the RDW length is adjusted as needed each time the IFTHEN record is changed. Missing bytes in specified input fields are replaced with blanks so the padded fields can be processed. DFSORT sets an appropriate LRECL for the OUTFIL output records based on the build and overlay items specified by the IFTHEN clauses. However, DFSORT does not analyze the possible results of WHEN=(logexp) conditions when determining an appropriate LRECL. When you use OUTFIL IFTHEN clauses, you can override the OUTFIL LRECL determined by DFSORT with the OUTFIL IFOUTLEN parameter. If SEQNUM is used in multiple IFTHEN clauses, the sequence number will be incremented for each record that satisfies the IFTHEN clause, that is, a separate SEQNUM counter will be kept for each IFTHEN clause. For example, if your input is:
RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD A B B C A C B D 1 1 2 1 2 2 3 1

and you specify:

OUTFIL IFTHEN=(WHEN=(8,1,CH,EQ,CA),OVERLAY=(15:SEQNUM,4,ZD)), IFTHEN=(WHEN=(8,1,CH,EQ,CB),OVERLAY=(16:SEQNUM,4,ZD)), IFTHEN=(WHEN=NONE,OVERLAY=(17:SEQNUM,4,ZD))

your output will be:

RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD A B B C A C B D 1 1 2 1 2 2 3 1 0001 0001 0002 0001 0002 0002 0003 0003

Separate SEQNUM counters are kept for the A record, for the B record, and for the NONE records. You can use IFTHEN clauses with the FTOV parameter to convert fixed-length record data sets to variable-length record data sets.
Chapter 3. Using DFSORT Program Control Statements

295

OUTFIL Control Statements

You can use the VLTRIM parameter with IFTHEN clauses to remove specified trailing bytes from the end of variable-length records. You can use IFTHEN clauses with any or all of the report parameters in the same way as for the BUILD or OUTREC parameter. The IFTHEN clauses of the OUTREC statement apply to all input records whereas the IFTHEN clauses of the OUTFIL statement only apply to the OUTFIL input records for its OUTFIL group. WHEN=INIT clause Specifies build or overlay items to be applied to all records. If multiple WHEN=INIT clauses are specified, they are processed in the order in which they are specified. WHEN=INIT clauses are processed before any other type of IFTHEN clauses. WHEN=INIT Identifies a WHEN=INIT clause. PARSE=(definitions) Defines %nn fixed parsed fields into which variable position/length fields are extracted for all records. See OUTFIL PARSE for details. You can use the %nn parsed fields defined in a WHEN=INIT clause in the BUILD or OVERLAY operand of that clause and all subsequent IFTHEN clauses. Sample Syntax:
OUTFIL IFOUTLEN=50, IFTHEN=(WHEN=INIT, PARSE=(%01=(ABSPOS=11,STARTAT=NONBLANK, ENDBEFR=C,,FIXLEN=12), %02=(ENDBEFR=C,,FIXLEN=10), %03=(FIXLEN=12))), IFTHEN=(WHEN=(5,2,CH,EQ,CUS),BUILD=(%02,%03)), IFTHEN=(WHEN=(5,2,CH,EQ,CUK),BUILD=(%01,%02)), IFTHEN=(WHEN=NONE,BUILD=(%03,%01))

BUILD=(items) Specifies the build items to be applied to each record. See OUTFIL BUILD for details. You can specify all of the items in the same way that you can specify them for OUTFIL BUILD, except that you cannot specify / to create blank records or new records. OVERLAY=(items) Specifies the overlay items to be applied to each record. See OUTFIL OVERLAY for details. You can specify all of the items in the same way that you can specify them for OUTFIL OVERLAY. Sample Syntax:
OUTFIL FNAMES=OUT1, IFTHEN=(WHEN=INIT,BUILD=(1,20,21:CDepartment,31:3X,21,60) IFTHEN=(WHEN=(5,2,CH,EQ,CD1),OVERLAY=(31:8,3)), IFTHEN=(WHEN=(5,2,CH,EQ,CD2),OVERLAY=(31:12,3))

WHEN=(logexp) clause Specifies build or overlay items to be applied to records for which the specified logical expression is true. If multiple WHEN=(logexp) clauses are specified, they are processed in the order in which they are specified. WHEN=(logexp) Identifies a WHEN=(logexp) clause and specifies the criteria to be tested to determine if the build or overlay items are to be applied to

296

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

the record. See the INCLUDE statement for details of the logical expressions you can use. You can specify all of the logical expressions in the same way that you can specify them for the INCLUDE statement except that: v You cannot specify FORMAT=f with WHEN=(logexp). v You cannot specify D2 format in WHEN=(logexp). v Locale processing is not used for WHEN=(logexp). v VLSCMP and VLSHRT are not used with WHEN=(logexp). Instead, missing bytes in specified input fields are replaced with blanks so the padded fields can be processed. PARSE=(definitions) Defines %nn fixed parsed fields into which variable position/length fields are extracted for each record for which the logical expression is true. See OUTFIL PARSE for details. You can only use the %nn parsed fields defined in a WHEN=(logexp) clause in the BUILD or OVERLAY operand of that WHEN=(logexp) clause. Sample Syntax:
OUTFIL IFTHEN=(WHEN=(45,2,CH,EQ,CAL), PARSE=(%01=(ENDBEFR=C,,FIXLEN=12), %02=(FIXLEN=10)), OVERLAY=(21:%02,51:%01))

BUILD=(items) Specifies the build items to be applied to each record for which the logical expression is true. See OUTFIL BUILD for details. You can specify all of the items in the same way that you can specify them for OUTFIL BUILD. OVERLAY=(items) Specifies the overlay items to be applied to each record for which the logical expression is true. See OUTFIL OVERLAY for details. You can specify all of the items in the same way that you can specify them for OUTFIL OVERLAY. HIT=NEXT Specifies that IFTHEN processing should continue even if the logical expression is true. By default (if HIT=NEXT is not specified), IFTHEN processing stops if the logical expression is true. Sample Syntax:
OUTFIL FNAMES=OUT2, IFTHEN=(WHEN=(1,3,CH,EQ,CT01,AND, 18,4,ZD,LE,+2000),OVERLAY=(42:CType1 <= 2000),HIT=NEXT), IFTHEN=(WHEN=(1,3,CH,EQ,CT01,AND,6,1,BI,BO,X03), BUILD=(1,21,42,13)), IFTHEN=(WHEN=(1,3,CH,EQ,CT01,AND, 18,4,ZD,GT,+2000),OVERLAY=(42:CType1 > 2000 ),HIT=NEXT), IFTHEN=(WHEN=(1,3,CH,EQ,CT01,AND,6,1,BI,BO,X01), BUILD=(1,25,42,13))

WHEN=ANY clause Specifies build or overlay items to be applied to records for which the logical expression in any preceding WHEN=(logexp) clause is true. For the first WHEN=ANY clause, the preceding WHEN=(logexp) clauses are those before this WHEN=ANY clause. For the second or subsequent WHEN=ANY clause, the preceding WHEN=(logexp) clauses are those between the previous WHEN=ANY clause and this WHEN=ANY clause.
Chapter 3. Using DFSORT Program Control Statements

297

OUTFIL Control Statements

At least one WHEN=(logexp) clause must be specified before a WHEN=ANY clause. A WHEN=ANY clause can be used without any build or overlay items to just stop IFTHEN processing if any preceding WHEN=(logexp) clause is satisfied. PARSE=(definitions) Defines %nn fixed parsed fields into which variable position/length fields are extracted for each record for which the logical expression in any preceding WHEN=(logexp) clause is true. See OUTFIL PARSE for details. You can only use the %nn parsed fields defined in a WHEN=ANY clause in the BUILD or OVERLAY operand of that WHEN=ANY clause. BUILD=(items) Specifies the build items to be applied to each record for which the logical expression in any preceding WHEN=(logexp) clause is true. See OUTFIL BUILD for details. You can specify all of the items in the same way that you can specify them for OUTFIL BUILD. OVERLAY=(items) Specifies the overlay items to be applied to each record for which the logical expression in any preceding WHEN=(logexp) clause is true. See OUTFIL OVERLAY for details. You can specify all of the items in the same way that you can specify them for OUTFIL OVERLAY. HIT=NEXT Specifies that IFTHEN processing should continue even if the logical expression in a preceding WHEN=(logexp) clause is true. By default (if HIT=NEXT is not specified), IFTHEN processing stops if the logical expression in a preceding WHEN=(logexp) clause is true. Sample Syntax:
OUTFIL FNAMES=OUT3, IFTHEN=(WHEN=(1,3,SS,EQ,CT01,T02,T03), BUILD=(CGroup A,X,1,80),HIT=NEXT), IFTHEN=(WHEN=(1,3,SS,EQ,CT04,T05,T06), BUILD=(CGroup B,X,1,80),HIT=NEXT), IFTHEN=(WHEN=(1,3,SS,EQ,CT07,T08,T09,T10), BUILD=(CGroup C,X,1,80),HIT=NEXT), IFTHEN=(WHEN=ANY,OVERLAY=(16:CGroup Found)

WHEN=NONE clause Specifies build or overlay items to be applied to records for which none of the logical expressions in any WHEN=(logexp) clause is true. If there are no WHEN=(logexp) clauses, the build or overlay items are applied to all of the records. If multiple WHEN=NONE clauses are specified, they are processed in the order in which they are specified. WHEN=NONE clauses are processed after any other type of IFTHEN clauses. PARSE=(definitions) Defines %nn fixed parsed fields into which variable position/length fields are extracted for each record for which no logical expression was true. See OUTFIL PARSE for details. You can only use the %nn parsed fields defined in a WHEN=NONE clause in the BUILD or OVERLAY operand of that WHEN=NONE clause. Sample Syntax:
OUTFIL IFTHEN=(WHEN=(5,2,ZD,GT,+5), PARSE=(%01=(STARTAT=C<,ENDAT=C>,FIXLEN=12), %02=(STARTAFT=BLANKS,FIXLEN=10)), BUILD=(5,2,21:%01,X,%02,HEX)),

298

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

IFTHEN=(WHEN=NONE, PARSE=(%03=(STARTAFT=C(,ENDBEFR=C),FIXLEN=8)), BUILD=(5,2,%03,SFF,M12))

BUILD=(items) Specifies the build items to be applied to each record for which no logical expression was true. See OUTFIL BUILD for details. You can specify all of the items in the same way that you can specify them for OUTFIL BUILD. OVERLAY=(items) Specifies the overlay items to be applied to each record for which no logical expression was true. See OUTFIL OVERLAY for details. You can specify all of the items in the same way that you can specify them for OUTFIL OVERLAY. Sample Syntax:
OUTFIL FNAMES=OUT4, IFTHEN=(WHEN=INIT,BUILD=(1,20,21:CDepartment,31:3X,21,60)), IFTHEN=(WHEN=(5,2,CH,EQ,CD1),OVERLAY=(31:8,3)), IFTHEN=(WHEN=(5,2,CH,EQ,CD2),OVERLAY=(31:12,3)), IFTHEN=(WHEN=NONE,OVERLAY=(31:C***))

Default for IFTHEN clauses: None; must be specified. IFOUTLEN

IFOUTLEN=n

Overrides the OUTFIL LRECL determined by DFSORT from your OUTFIL IFTHEN clauses. DFSORT sets an appropriate LRECL for the output records based on the build and overlay items specified by the IFTHEN clauses. However, DFSORT does not analyze the possible results of WHEN=(logexp) conditions when determining an appropriate OUTFIL LRECL. When you use OUTFIL IFTHEN clauses, you can override the OUTFIL LRECL determined by DFSORT with the OUTFIL IFOUTLEN parameter. Fixed-length records longer than the IFOUTLEN length are truncated to the IFOUTLEN length. Fixed-length records shorter than the IFOUTLEN are padded with blanks to the IFOUTLEN length. Variable-length records longer than the IFOUTLEN length are truncated to the IFOUTLEN length. n specifies the length to use for the OUTFIL LRECL. The value for n must be between 1 and 32767, but must not be larger than the maximum LRECL allowed for the RECFM, and must not conflict with the specified or retrieved LRECL for the fixed-length OUTFIL data set.

Sample Syntax:
OUTFIL FNAMES=OUT5,IFOUTLEN=70, IFTHEN=(WHEN=(5,1,CH,EQ,C1,AND,8,3,ZD,EQ,+10), BUILD=(1,40,CT01-GROUP-A,65)), IFTHEN=(WHEN=(5,1,CH,EQ,C2,AND,8,3,ZD,EQ,+12), BUILD=(1,40,CT02-GROUP-B,65))

Default for IFOUTLEN: The LRECL determined from the IFTHEN clauses.

Chapter 3. Using DFSORT Program Control Statements

299

OUTFIL Control Statements

VTOF or CONVERT

VTOF CONVERT

Specifies that variable-length OUTFIL input records are to be converted to fixed-length OUTFIL output records for this OUTFIL group. You must specify a BUILD or OUTREC parameter. The items you specify produce a reformatted fixed-length OUTFIL output record without an RDW (the data starts at position 1). Any BUILD or OUTREC fields you specify apply to the variable-length OUTFIL input records (the data starts at position 5 after the 4-byte RDW). However, you cannot specify the variable-part of the OUTFIL input records (for example, p or p,HEX). Any BUILD or OUTREC columns you specify apply to the reformatted fixed-length OUTFIL output records. By default, VTOF or CONVERT automatically uses VLFILL=X40 (blank fill byte) to allow processing of variable-length input records which are too short to contain all specified BUILD or OUTREC fields. You can specify VLFILL=byte to change the fill byte. If you do not specify a RECFM for the OUTFIL data set, it will be given a record format of FB. If you specify a RECFM for the OUTFIL data set, it must have a fixed-length record format (for example, FB). If VTOF or CONVERT is specified for fixed-length input records, it will not be used. If VTOF or CONVERT is specified with FTOV, IFTHEN, or OVERLAY, DFSORT will terminate. Sample Syntax:
OUTFIL FNAMES=FIXOUT,VTOF, OUTREC=(1:5,14,35:32,8,50:22,6,7c*)

Default for VTOF or CONVERT: None; must be specified. VLFILL

VLFILL=byte

Allows DFSORT to continue processing if a variable-length OUTFIL input record is found to be too short to contain all specified OUTFIL BUILD or OUTREC fields for this OUTFIL group. Without VLFILL=byte, a short record causes DFSORT to issue message ICE218A and terminate. With VLFILL=byte, missing bytes in OUTFIL BUILD or OUTREC fields are replaced with fill bytes so the filled fields can be processed. If VLFILL=byte is specified for fixed-length input records, it will not be used. If VLFILL=byte is specified with FTOV, IFTHEN, or OVERLAY, DFSORT will terminate.

300

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

byte Cx X'yy' specifies the fill byte. Permissible values are Cx and X'yy'. Character byte: The value x must be one EBCDIC character. If you want to use an apostrophe as the fill byte, you must specify it as C. Hexadecimal byte: The value yy must be one pair of hexadecimal digits (00-FF). Sample Syntax:
OUTFIL FNAMES=FIXOUT,VTOF,OUTREC=(5,20,2X,35,10),VLFILL=C* OUTFIL FNAMES=OUT1,VLFILL=XFF,OUTREC=(1,4,15,5,52)

Default for VLFILL: VLFILL=X40 (blank fill byte) if VTOF or CONVERT is specified. Otherwise, none; must be specified. FTOV

FTOV

Specifies that fixed-length OUTFIL input records are to be converted to variable-length OUTFIL output records for this OUTFIL group. If you do not specify an OUTREC, BUILD, OVERLAY, or IFTHEN parameter, the fixed-length OUTFIL input record is converted to a variable-length OUTFIL output record. A 4-byte RDW is prepended to the fixed-length record before it is written. If you specify an OUTREC, BUILD, OVERLAY, or IFTHEN parameter, the items you specify produce a reformatted fixed-length record that is converted to a variable-length OUTFIL output record. Any OUTREC, BUILD, OVERLAY, or IFTHEN fields you specify apply to the fixed-length OUTFIL input records (the data starts at position 1). A 4-byte RDW is prepended to the reformatted fixed-length record before it is written. If you do not specify a RECFM for the OUTFIL data set, it will be given a record format of VB. If you specify a RECFM for the OUTFIL data set, it must have a variable-length record format (for example, VB or VBS). If you do not specify an LRECL for the OUTFIL data set, it will be given an LRECL that can contain the largest variable-length output record to be produced, up to a maximum of 32756 for an unspanned record format (for example, VB) or up to 32767 for a spanned record format (for example, VBS). If you specify an LRECL for the OUTFIL data set, it must be big enough to contain the largest variable-length output record to be produced. If your largest variable-length output record is between 32757 and 32767 bytes, youll need to specify a spanned record format (for example, VBS) for the output data set. If FTOV is specified for variable-length input records, it will not be used. If FTOV is specified with VTOF, CONVERT or VLFILL=byte, DFSORT will terminate. Sample Syntax:

Chapter 3. Using DFSORT Program Control Statements

301

OUTFIL Control Statements

OUTFIL FNAMES=VAROUT,FTOV OUTFIL FNAMES=V1,FTOV,OUTREC=(1,20,26:21,10,6C*) OUTFIL FNAMES=V2,FTOV, IFTHEN=(WHEN=(12,5,ZD,GT,+20000),OVERLAY=(25:CYes)), IFTHEN=(WHEN=NONE,OVERLAY=(25:CNo))

Default for FTOV: None; must be specified. VLTRIM

VLTRIM=byte

VLTRIM=byte specifies that the trailing bytes are to be removed from the end of variable-length OUTFIL output records for this OUTFIL group before the records are written. The trim byte can be any value, such as blank, binary zero, or asterisk. If DFSORT finds one or more trim bytes at the end of a variable-length OUTFIL data record or report record, it will decrease the length of the record accordingly, effectively removing the trailing trim bytes. However, VLTRIM=byte will not remove the RDW, the ANSI carriage control character (if produced), or the first data byte. For example, say that you have the following 17-byte fixed-length data records that you want to convert to variable-length data records:
123456*********** 0003************* ABCDEFGHIJ*****22 *****************

If you use:
OUTFIL FTOV

the following variable-length output records will be written (4-byte RDW followed by data):
Length | Data 21 123456*********** 21 0003************* 21 ABCDEFGHIJ*****22 21 *****************

but if you use:

OUTFIL FTOV,VLTRIM=C*

the following variable-length output records will be written (4-byte RDW followed by data):
Length | Data 10 123456 8 0003 21 ABCDEFGHIJ*****22 5 *

VLTRIM=C* removed the trailing asterisks from the first and second records. The third record did not have any trailing asterisks to remove. The fourth record had all asterisks, so one asterisk was kept. If VLTRIM=byte is specified for fixed-length output records, it will not be used. byte specifies the trim byte. Permissible values are Cx and Xyy.

302

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Cx Character byte: The value x must be one EBCDIC character. If you want to use an apostrophe as the trim byte, you must specify it as C. Hexadecimal byte: The value yy must be one pair of hexadecimal digits (00-FF)

Xyy Sample Syntax:

Fixed input: OUTFIL FNAMES=TRIM1,FTOV,VLTRIM=C Variable input: OUTFIL FNAMES=TRIM2,VLTRIM=X00 OUTFIL FNAMES=TRIM3,VLTRIM=C*, OUTREC=(1,15,5X,16,8,5X,28)

Default for VLTRIM: None; must be specified. REPEAT

REPEAT=n

Specifies the number of times each OUTFIL output record is to be repeated for this OUTFIL group. Each OUTFIL output record is written n times. If SEQNUM is used in the OUTREC, BUILD, OVERLAY, or IFTHEN parameter for this OUTFIL group, the sequence number will be incremented for each repeated record. For example, if your input is:
RECORD A RECORD B

and you specify:

OUTFIL OUTREC=(1,8,X,SEQNUM,5,ZD),REPEAT=2

your output will be:

RECORD RECORD RECORD RECORD A A B B 00001 00002 00003 00004

If SEQNUM is used in multiple IFTHEN clauses for this OUTFIL group, the sequence number will be incremented for each repeated record that satisfies the IFTHEN clause. For example, if your input is:
RECORD RECORD RECORD RECORD RECORD RECORD RECORD A B C A C B B 1 1 1 2 2 2 3

and you specify:

OUTFIL REPEAT=2, IFTHEN=(WHEN=(8,1,CH,EQ,CA),OVERLAY=(15:SEQNUM,4,ZD)), IFTHEN=(WHEN=(8,1,CH,EQ,CB),OVERLAY=(15:SEQNUM,4,ZD)), IFTHEN=(WHEN=NONE,OVERLAY=(15:SEQNUM,4,ZD))

your output will be:

Chapter 3. Using DFSORT Program Control Statements

303

OUTFIL Control Statements

RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD A A B B C C A A C C B B B B 1 1 1 1 1 1 2 2 2 2 2 2 3 3 0001 0002 0001 0002 0001 0002 0003 0004 0003 0004 0003 0004 0005 0006

If you specify REPEAT=n with / in the OUTREC, BUILD, or IFTHEN BUILD parameter for this OUTFIL group, the first line is written n times, then the second line is written n times, and so on. (For IFTHEN, this means each record that has the SEQNUM item applied to it.) If SEQNUM is used, all lines for the same record are given the same sequence number. For example, if your input is:
RECORD A RECORD B

and you specify:

OUTFIL OUTREC=(CP1>,X,1,6,X,SEQNUM,4,ZD,/, CP2>,X,8,1,X,SEQNUM,4,ZD),REPEAT=2

your output will be:

P1> P1> P2> P2> P1> P1> P2> P2> RECORD RECORD A 0001 A 0002 RECORD RECORD B 0003 B 0004 0001 0002 0003 0004

The REPEAT parameter cannot be used with any of the following report parameters: LINES, HEADER1, TRAILER1, HEADER2, TRAILER2, SECTIONS, and NODETAIL. n specifies the number of times each OUTFIL output record is to be repeated. The value for n starts at 2 (write record twice) and is limited to 28 digits (15 significant digits).

Sample Syntax:
* WRITE EACH OUTPUT RECORD 12 TIMES. OUTFIL FNAMES=OUT1,REPEAT=12 * WRITE EACH INCLUDED AND REFORMATTED OUTPUT RECORD 50 TIMES. * (THE SEQUENCE NUMBER WILL BE INCREMENTED FOR EACH REPETITION.) OUTFIL FNAMES=OUT2,INCLUDE=(5,2,SS,EQ,CB2,C5,M3),

Default for REPEAT: None; must be specified. SPLIT

304

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

SPLIT

Splits the output records one record at a time in rotation among the data sets of this OUTFIL group until all of the output records have been written. As a result, the records will be split as evenly as possible among all of the data sets in the group. As an example, for an OUTFIL group with three data sets: v the first OUTFIL data set in the group will receive records 1, 4, 7, and so on. v the second OUTFIL data set in the group will receive records 2, 5, 8, and so on. v the third OUTFIL data set in the group will receive records 3, 6, 9, and so on. The records are not contiguous in each OUTFIL data set. SPLIT is equivalent to SPLITBY=1. The SPLIT parameter cannot be used with any of the following report parameters: LINES, HEADER1, TRAILER1, HEADER2, TRAILER2, SECTIONS, and NODETAIL. Sample Syntax:
* WRITE RECORD 1 TO PIPE1, RECORD 2 TO PIPE2, RECORD 3 TO PIPE3, * RECORD 4 TO PIPE4, RECORD 5 TO PIPE1, RECORD 6 TO PIPE2, AND SO ON. OUTFIL FNAMES=(PIPE1,PIPE2,PIPE3,PIPE4),SPLIT * SPLIT THE INCLUDED AND REFORMATTED OUTPUT RECORDS EVENLY BETWEEN * TAPE1 AND TAPE2. OUTFIL FNAMES=(TAPE1,TAPE2),SPLIT, INCLUDE=(8,2,ZD,EQ,27),OUTREC=(5X,1,75)

Default for SPLIT: None; must be specified. SPLITBY

SPLITBY=n

Splits the output records n records at a time in rotation among the data sets of this OUTFIL group until all of the output records have been written. As an example, if SPLITBY=10 is specified for an OUTFIL group with three data sets: v the first OUTFIL data set in the group will receive records 1-10, 31-40, and so on. v the second OUTFIL data set in the group will receive records 11-20, 41-50, and so on. v the third OUTFIL data set in the group will receive records 21-30, 51-60, and so on. The records are not contiguous in each OUTFIL data set. SPLITBY=1 is equivalent to SPLIT.

Chapter 3. Using DFSORT Program Control Statements

305

OUTFIL Control Statements

The SPLITBY parameter cannot be used with any of the following report parameters: LINES, HEADER1, TRAILER1, HEADER2, TRAILER2, SECTIONS, and NODETAIL. n specifies the number of records to split by. The value for n starts at 1 and is limited to 28 digits (15 significant digits).

Sample Syntax:
* WRITE RECORDS 1-5 TO PIPE1, RECORDS 6-10 TO PIPE2, RECORDS 11-15 TO * PIPE3, RECORDS 16-20 TO PIPE4, RECORDS 21-25 TO PIPE1, RECORDS 26-30 * TO PIPE2, AND SO ON. OUTFIL FNAMES=(PIPE1,PIPE2,PIPE3,PIPE4),SPLITBY=5 * SPLIT THE INCLUDED AND REFORMATTED OUTPUT RECORDS 100 AT A TIME * BETWEEN TAPE1 AND TAPE2. OUTFIL FNAMES=(TAPE1,TAPE2),SPLITBY=100, INCLUDE=(8,2,ZD,EQ,27),OUTREC=(5X,1,75)

Default for SPLITBY: None; must be specified. SPLIT1R

SPLIT1R=n

Splits the output records n records at a time for one rotation among the data sets of this OUTFIL group until all of the output records have been written. As an example, if SPLIT1R=10 is specified for an input data set with 35 records and an OUTFIL group with three data sets: v the first OUTFIL data set in the group will receive records 1-10. v the second OUTFIL data set in the group will receive records 11-20. v the third OUTFIL data set in the group will receive records 21-35. The records are contiguous in each OUTFIL data set. The SPLIT1R parameter cannot be used with any of the following report parameters: LINES, HEADER1, TRAILER1, HEADER2, TRAILER2, SECTIONS, and NODETAIL. n specifies the number of records to split by. The value for n starts at 1 and is limited to 28 digits (15 significant digits).
* WRITE RECORDS 1-20 TO PIPE1, RECORDS 21-40 TO PIPE2, * RECORDS 41-60 TO PIPE3 AND RECORDS 61-85 TO PIPE4. OUTFIL FNAMES=(PIPE1,PIPE2,PIPE3,PIPE4),SPLIT1R=20 * SPLIT THE INCLUDED AND REFORMATTED OUTPUT RECORDS ONCE * CONTIGUOUSLY BETWEEN TAPE1 AND TAPE2. OUTFIL FNAMES=(TAPE1,TAPE2),SPLIT1R=100, INCLUDE=(8,2,ZD,EQ,27),OUTREC=(5X,1,75)

Sample Syntax:

Default for SPLIT1R: None; must be specified. NULLOFL

306

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

NULLOFL= RC0 RC4 RC16

specifies the action to be taken by DFSORT when there are no data records for a data set associated with this OUTFIL statement, as indicated by a DATA count of 0 in message ICE227I. OUTFIL report records have no affect on the action taken as a result of this option. RC0 specifies that DFSORT should issue message ICE174I, set a return code of 0, and continue processing when there are no data records for a data set associated with this OUTFIL statement. specifies that DFSORT should issue message ICE174I, set a return code of 4, and continue processing when there are no data records for the a data set associated with this OUTFIL statement. specifies that DFSORT should issue message ICE209A, terminate, and give a return code of 16 when there are no data records for a data set associated with this OUTFIL statement.

RC4

RC16

Default for NULLOFL: The NULLOFL installation default. Notes: 1. The NULLOFL value specified for each OUTFIL statement applies to the data sets associated with that OUTFIL statement. If a NULLOFL value is not specified for an OUTFIL statement, the NULLOFL installation default value applies to the data sets associated with that OUTFIL statement. For example, if the installation default is NULLOFL=RC0 (IBMs shipped default) and the following is specified: |
OUTFIL FNAMES=OUT1,NULLOFL=RC16,INCLUDE=(5,3,CH,EQ,CD01) OUTFIL FNAMES=(OUT2,OUT3),INCLUDE=(5,3,CH,EQ,CD02) OUTFIL FNAMES=OUT4,NULLOFL=RC4,SAVE

then NULLOFL=RC16 applies to the data set for OUT1, NULLOFL=RC0 (the installation default) applies to the data sets for OUT2 and OUT3, and NULLOFL=RC4 applies to the data set for OUT4. 2. If you receive message ICE174I or ICE209A, a DATA count of 0 in message ICE227I identifies an OUTFIL data set for which there are no data records. 3. The return code of 0 or 4 resulting from NULLOFL=RC0 or NULLOFL=RC4, respectively, can be overridden by a higher return code set for some other reason, including a return code of 16 resulting from NULLOFL=RC16. 4. NULLOUT applies to the SORTOUT data set. NULLOFL applies to OUTFIL data sets LINES

LINES=n

Chapter 3. Using DFSORT Program Control Statements

307

OUTFIL Control Statements

Specifies the number of lines per page to be used for the reports produced for this OUTFIL group. DFSORT uses ANSI carriage control characters to control page ejects and the placement of the lines in your report, according to your specifications. n specifies the number of lines per page. The value for n must be between 1 and 255. However, n--or the default for n if LINES is not specified--must be greater than or equal to the number of lines needed for each of the following: v The HEADER1 lines v The TRAILER1 lines v The sum of all lines for HEADER2, TRAILER2, HEADER3s, TRAILER3s, and the data lines and blank lines produced from an input record. Sample Syntax:
OUTFIL FNAMES=RPT1,LINES=50

Default for LINES: None; must be specified, unless HEADER1, TRAILER1, HEADER2, TRAILER2, SECTIONS, or NODETAIL is specified, in which case the default for LINES is 60. HEADER1

, HEADER1=( c: r p,m DATE &DATE DATE=(abcd) &DATE=(abcd) DATENS=(abc) &DATENS=(abc) YDDD=(abc) &YDDD=(abc) YDDDNS=(ab) &YDDDNS=(ab) TIME &TIME TIME=(abc) &TIME=(abc) TIMENS=(ab) &TIMENS=(ab) PAGE &PAGE PAGE=( edit ) to &PAGE=( edit ) to )

Specifies the report header to be used for the reports produced for this OUTFIL group. The report header appears by itself as the first page of the report. DFSORT uses ANSI carriage control characters to control page ejects and the placement of the lines in your report, according to your specifications.

308

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

You can use BLKCCH1 to replace the 1 (page eject) for the ANSI carriage control character in the first line of the report header with a blank, thus avoiding forcing a page eject. You can use REMOVECC to remove the ANSI carriage control characters from a report. You can choose to include any or all of the following report elements in your report header: v Blanks, character strings, and hexadecimal strings v Unedited input fields from the first OUTFIL input record v Current date in a variety of different forms v Current time in a variety of different forms v Page number, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on. The report header consists of the elements you select, in the order in which you specify them, and in the columns or lines you specify. c: specifies the column in which the first position of the associated report element is to appear, relative to the start of the data in the report record. Ignore the RDW (variable-length report records only) and carriage control character when specifying c:. That is, 1: indicates the first byte of the data in the report record for both fixed-length and variable-length report records. Unused space preceding the specified column is padded with EBCDIC blanks. The following rules apply: v c must be a number between 1 and 32752. v c: must be followed by a report element, but must not precede / or n/. v c must not overlap the previous report element in the report record. v The colon (:) is treated like the comma (,) or semicolon (;) for continuation to another line. r specifies that blanks, a character string, or a hexadecimal string are to appear in the report record, or that a new report record is to be started in the header, with or without intervening blank lines. These report elements can be specified before or after any other report elements. Consecutive report elements can be specified. Permissible values are nX, nxx...x, nCxx...x, nXyy...yy, /.../ and n/. nX Blanks. n bytes of EBCDIC blanks (X'40') are to appear in the report record. n can range from 1 to 4095. If n is omitted, 1 is used.

nxx...x Character string. n repetitions of the character string constant (xx...x) are to appear in the report record. n can range from 1 to 4095. If n is omitted, 1 is used. x can be any EBCDIC character. You can specify 1 to 256 characters. nCxx...x can be used instead of nxx...x. If you want to include a single apostrophe in the character string, you must specify it as two single apostrophes:
Required: ONEILL Specify: ONEILL or CONEILL

nXyy...yy Hexadecimal string. n repetitions of the hexadecimal string constant (Xyy...yy) are to appear in the report record. n can range from 1 to 4095. If n is omitted, 1 is used.

Chapter 3. Using DFSORT Program Control Statements

309

OUTFIL Control Statements

The value yy represents any pair of hexadecimal digits. You can specify from 1 to 256 pairs of hexadecimal digits /.../ or n/ Blank lines or a new line. A new report record is to be started in the header with or without intervening blank lines. If /.../ or n/ is specified at the beginning or end of the header, n blank lines are to appear in the header. If /.../ or n/ is specified in the middle of the header, n1 blank lines are to appear in the header (thus, / or 1/ indicates a new line with no intervening blank lines). Either n/ (for example, 5/) or multiple /s (for example, /////) can be used. n can range from 1 to 255. If n is omitted, 1 is used. As an example, if you specify:
OUTFIL HEADER1=(2/,First line of text,/, Second line of text,2/, Third line of text,2/)

the report header appears as follows when printed:

blank line blank line First line of text Second line of text blank line Third line of text blank line blank line

p,m specifies that an unedited input field, from the first OUTFIL input record for which a data record appears in the report, is to appear in the report record. p specifies the first byte of the input field relative to the beginning of the OUTFIL input record. The first data byte of a fixed-length record has relative position 1. The first data byte of a variable-length record has relative position 5, because the first four bytes are occupied by the RDW. All fields must start on a byte boundary, and no field can extend beyond byte 32752. See OUTFIL Statements Notes on page 340 for special rules concerning variable-length records. specifies the length in bytes of the input field. The value for m must be between 1 and 256.

DATE specifies that the current date is to appear in the report record in the form mm/dd/yy, where mm represents the month (01-12), dd represents the day (01-31), and yy represents the last two digits of the year (for example, 95). &DATE can be used instead of DATE. DATE=(abcd) specifies that the current date is to appear in the report record in the form adbdc, where a, b, and c indicate the order in which the month, day, and year are to appear and whether the year is to appear as two or four digits, and d is the character to be used to separate the month, day and year.

310

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

For a, b, and c, use M to represent the month (01-12), D to represent the day (01-31), Y to represent the last two digits of the year (for example, 05), or 4 to represent the four digits of the year (for example, 2005). M, D, and Y or 4 can each be specified only once. Examples: DATE=(DMY.) would produce a date of the form dd.mm.yy, which on March 29, 2005, would appear as 29.03.05. DATE=(4MD) would produce a date of the form yyyy-mm-dd, which on March 29, 2005, would appear as 2005-03-29. a, b, c, and d must be specified. &DATE=(abcd) can be used instead of DATE=(abcd). DATENS=(abc) specifies that the current date is to appear in the report record in the form abc, where a, b and c indicate the order in which the month, day, and year are to appear and whether the year is to appear as two or four digits. For a, b and c, use M to represent the month (01-12), D to represent the day (01-31), Y to represent the last two digits of the year (for example, 02), or 4 to represent the four digits of the year (for example, 2002). M, D, and Y or 4 can each be specified only once. Examples: DATENS=(DMY) would produce a date of the form ddmmyy, which on March 29, 2002, would appear as 290302. DATENS=(4MD) would produce a date of the form yyyymmdd, which on March 29, 2002, would appear as 20020329. a, b and c must be specified. &DATENS=(abc) can be used instead of DATENS=(abc). YDDD=(abc) specifies that the current date is to appear in the report record in the form acb, where a and b indicate the order in which the year and day of the year are to appear and whether the year is to appear as two or four digits, and c is the character to be used to separate the year and day of the year. For a and b, use D to represent the day of the year (001-D366), Y to represent the last two digits of the year (for example, 04), or 4 to represent the four digits of the year (for example, 2004). D, and Y or 4 can each be specified only once. Examples: YDDD=(DY-) would produce a date of the form ddd-yy which on April 7, 2004, would appear as 098-04. YDDD=(4D/) would produce a date of the form yyyy/ddd which on April 7, 2004, would appear as 2004/098. a, b and c must be specified. &YDDD=(abc) can be used instead of YDDD=(abc). YDDDNS=(ab) specifies that the current date is to appear in the report record in the form ab, where a and b indicate the order in which the year and day of the year are to appear and whether the year is to appear as two or four digits. For a and b, use D to represent the day of the year (001-366), Y to represent the last two digits of the year (for example, 04), or 4 to represent the four digits of the year (for example, 2004). D, and Y or 4
Chapter 3. Using DFSORT Program Control Statements

311

OUTFIL Control Statements

can each be specified only once. Examples: YDDDNS=(DY) would produce a date of the form dddyy which on April 7, 2004, would appear as 09804. YDDDNS=(4D) would produce a date of the form yyyyddd which on April 7, 2004, would appear as 2004098. a and b must be specified. &YDDDNS=(ab) can be used instead of YDDDNS=(ab). TIME specifies that the current time is to appear in the report record in the form hh:mm:ss, where hh represents the hour (00-23), mm represents the minutes (00-59), and ss represents the seconds (00-59). &TIME can be used instead of TIME. TIME=(abc) specifies that the current time is to appear in the report record in the form hhcmmcss (24-hour time) or hhcmmcss xx (12-hour time). If ab is 24, the time is to appear in the form hhcmmcss (24-hour time) where hh represents the hour (00-23), mm represents the minutes (00-59), ss represents the seconds (00-59), and c is the character used to separate the hours, minutes, and seconds. Example: TIME=(24.) would produce a time of the form hh.mm.ss which at 08:25:13 pm would appear as 20.25.13. If ab is 12, the time is to appear in the form hhcmmcss xx (12-hour time) where hh represents the hour (01-12), mm represents the minutes (00-59), ss represents the seconds (00-59), xx is am or pm, and c is the character used to separate the hours, minutes, and seconds. Example: TIME=(12.) would produce a time of the form hh.mm.ss xx which at 08:25:13 pm would appear as 08.25.13 pm. ab and c must be specified. &TIME=(abc) can be used instead of TIME=(abc). TIMENS=(ab) specifies that the current time is to appear in the report record in the form hhmmss (24-hour time) or hhmmss xx (12-hour time). If ab is 24, the time is to appear in the form hhmmss (24-hour time) where hh represents the hour (00-23), mm represents the minutes (00-59), and ss represents the seconds (00-59). Example: TIMENS=(24) would produce a time of the form hhmmss which at 08:25:13 pm would appear as 202513. If ab is 12, the time is to appear in the form hhmmss xx (12-hour time) where hh represents the hour (01-12), mm represents the minutes (00-59), and ss represents the seconds (00-59). Example: TIMENS=(12) would produce a time of the form hhmmss xx which at 08:25:13 pm would appear as 082513 pm. ab must be specified. &TIMENS=(ab) can be used instead of TIMENS=(ab).

312

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

PAGE specifies that the page number is to appear in the report record. The page number for the report header appears as 1. If HEADER1 is specified with PAGE, PAGE for the report header (first page) will be 1 and PAGE for the next page (second page) will be 2. If HEADER1 is specified without PAGE, PAGE for the page after the report header (second page) will be 1 (typical of a report with a cover sheet). &PAGE can be used instead of PAGE. PAGE=(edit) or PAGE=(to) same as PAGE except that the 15-digit page number appears edited or converted as specified. See p,m,f,edit under OUTREC for further details on the edit fields you can use. See p,m,f,to under OUTREC for further details on the to fields you can use. &PAGE=(edit) or &PAGE=(to) can be used instead of PAGE=(edit) or PAGE=(to). Sample Syntax:
OUTFIL FNAMES=(RPT1,RPT2), HEADER1=(30:January Report,4/, 28:Prepared on ,DATE,//, 32:at ,TIME,//, 28:using DFSORTS OUTFIL,5/, 10:Department: ,12,8,50:Page:,PAGE=(EDIT=(TTT)))

Default for HEADER1: None; must be specified. TRAILER1

Chapter 3. Using DFSORT Program Control Statements

313

OUTFIL Control Statements

, TRAILER1= ( c: r p,m DATE &DATE DATE=(abcd) &DATE=(abcd) DATENS=(abc) &DATENS=(abc) YDDD=(abc) &YDDD=(abc) YDDDNS=(ab) &YDDDNS=(ab) TIME &TIME TIME=(abc) &TIME=(abc) TIMENS=(ab) &TIMENS=(ab) PAGE &PAGE PAGE=( edit ) to &PAGE=( edit ) to COUNT COUNT15 COUNT=( edit ) to COUNT+n=( edit ) to COUNT-n=( edit ) to SUBCOUNT SUBCOUNT15 SUBCOUNT=( edit ) to TOTAL= (p,m,f ) TOT= ,edit ,to MIN= (p,m,f ) ,edit ,to MAX= (p,m,f ) ,edit ,to AVG= (p,m,f ) ,edit ,to Additional Parameters for TRAILER1 )

314

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Additional Parameters for TRAILER1

SUBTOTAL= (p,m,f SUBTOT= ,edit SUB= ,to SUBMIN= (p,m,f ) ,edit ,to SUBMAX= (p,m,f ) ,edit ,to SUBAVG= (p,m,f ) ,edit ,to )

Specifies the report trailer to be used for the reports produced for this OUTFIL group. The report trailer appears by itself as the last page of the report. DFSORT uses ANSI carriage control characters to control page ejects and the placement of the lines in your report, according to your specifications. You can use BLKCCT1 to replace the 1 (page eject) for the ANSI carriage control character in the first line of the report trailer with a blank, thus avoiding forcing a page eject. You can use REMOVECC to remove the ANSI carriage control characters from a report. You can choose to include any or all of the following report elements in your report trailer: v Blanks, character strings, and hexadecimal strings Unedited input fields from the last OUTFIL input record Current date in a variety of different forms Current time in a variety of different forms Page number, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on v Any or all of the following statistics: v v v v Count of data records in the report, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on. You can add a decimal number to the count before converting or editing it (for example, add 1 to account for writing a trailer record, or add 2 to account for writing a header and trailer record). Total, minimum, maximum, or average for each specified ZD, PD, BI, FI, FL, CSF, FS, UFF, or SFF numeric input field in the data records of the report, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on. The report trailer consists of the elements you select, in the order in which you specify them, and in the columns or lines you specify. c: r See c: under HEADER1. specifies that blanks, a character string, or a hexadecimal string are to appear in the report record, or that a new report record is to be started in the trailer, with or without intervening blank lines. These report elements

Chapter 3. Using DFSORT Program Control Statements

315

OUTFIL Control Statements

can be specified before or after any other report elements. Consecutive report elements can be specified. Permissible values are nX, nxx...x, nCxx...x, nXyy...yy, /.../, and n/. nX Blanks. See nX under r for HEADER1.

nxx...x Character string. See nxx...x under r for HEADER1. nCxx...x can be used instead of nxx...x nX'xx...x' Hexadecimal string. See nX'xx...x' under r for HEADER1. /.../ or n/ Blank lines or a new line. A new report record is to be started in the trailer, with or without intervening blank lines. If /.../ or n/ is specified at the beginning or end of the trailer, n blank lines are to appear in the trailer. If /.../ or n/ is specified in the middle of the trailer, n1 blank lines are to appear in the trailer (thus, / or 1/ indicates a new line with no intervening blank lines). Either n/ (for example, 5/) or multiple /s (for example, /////) can be used. n can range from 1 to 255. If n is omitted, 1 is used. p,m specifies that an unedited input field, from the last OUTFIL input record for which a data record appears in the report, is to appear in the report record. p m See p under HEADER1. See m under HEADER1.

DATE See DATE under HEADER1. &DATE can be used instead of DATE. DATE=(abcd) See DATE=(abcd) under HEADER1. &DATE=(abcd) can be used instead of DATE=(abcd). DATENS=(abc) See DATENS=(abc) under HEADER1. &DATENS=(abc) can be used instead of DATENS=(abc). YDDD=(abc) See YDDD=(abc) under HEADER1. &YDDD=(abc) can be used instead of YDDD=(abc). YDDDNS=(ab) See YDDDNS=(ab) under HEADER1. &YDDDNS=(ab) can be used instead of YDDDNS=(ab). TIME See TIME under HEADER1.

316

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

&TIME can be used instead of TIME. TIME=(abc) See TIME=(abc) under HEADER1. &TIME=(abc) can be used instead of TIME=(abc). TIMENS=(ab) See TIMENS=(ab) under HEADER1. &TIMENS=(ab) can be used instead of TIMENS=(ab). PAGE specifies that the current page number is to appear in the report record. The page number for the trailer appears as 6 digits, right-justified, with leading zeros suppressed. For example, if the page is numbered 12, it appears as 12. &PAGE can be used instead of PAGE. PAGE=(edit) or PAGE=(to) same as PAGE except that the 15-digit page number appears edited or converted as specified. See p,m,f,edit under OUTREC for further details on the edit fields you can use. See p,m,f,to under OUTREC for further details on the to fields you can use. &PAGE=(edit) or &PAGE=(to) can be used instead of PAGE=(edit) or PAGE=(to). COUNT specifies that the count of data records in the report is to appear in the report record as 8 digits, right-justified, with leading zeros suppressed. For example, if there are 6810 input records in the report, the count appears as 6810. If slash (/) is used in OUTREC or BUILD to produce multiple data records, COUNT only counts the number of data records processed as input to OUTREC or BUILD. For example, if OUTREC processes 3 input records and creates 2 output records for each input record, the count is 3, not 6 COUNT15 same as COUNT except that the count appears as 15 digits. COUNT=(edit) or COUNT=(to) same as COUNT except that the 15digit count appears edited or converted as specified. See p,m,f,edit under OUTREC for further details on the edit fields you can use. See p,m,f,to under OUTREC for further details on the to fields you can use. For example, if there are 6810 input records, COUNT=(M11,LENGTH=6) produces a count of 006810. COUNT+n=(edit) or COUNT+n=(to) same as COUNT=(edit) or COUNT=(to) except that n is added to the 15-digit count before it is edited or converted. n can be 1 to 3 decimal digits. For example, if there are 6810 input records, COUNT+2=(M11,LENGTH=6) produces a count of 006812. One important use for this parameter is to add 1 for the TRAILER1 record to the count of data records.
Chapter 3. Using DFSORT Program Control Statements

317

OUTFIL Control Statements

COUNT-n=(edit) or COUNT-n=(to) same as COUNT=(edit) or COUNT=(to) except that n is subtracted from the 15-digit count before it is edited or converted. n can be 1 to 3 decimal digits. For example, if there are 6810 input records, COUNT1=(M11,LENGTH=6) produces a count of 006809. One important use for this parameter is to subtract 1 for a header record from the count of all records. SUBCOUNT specifies that the running count of input records in the report is to appear in the report record as 8 digits, right-justified, with leading zeros suppressed. For TRAILER1, the running count is the same as the count, so SUBCOUNT produces the same value as COUNT. If slash (/) is used in OUTREC or BUILD to produce multiple data records, SUBCOUNT counts only the number of data records processed as input to OUTREC or BUILD. For example, if OUTREC processes 3 input records and creates 2 output records for each input record, the running count is 3, not 6. SUBCOUNT15 same as SUBCOUNT except that the running count appears as 15 digits. SUBCOUNT=(edit) or SUBCOUNT=(to) same as SUBCOUNT except that the 15digit running count appears edited or converted as specified. See p,m,f,edit under OUTREC for further details on the edit fields you can use. See p,m,f,to under OUTREC for further details on the to fields you can use. TOTAL specifies that an edited or converted total, for the values of a numeric input field in all data records of the report, is to appear in the report record. TOT can be used instead of TOTAL. p,m,f,edit or p,m,f,to specifies the numeric input field for which the total is to be produced and how the output field (that is, the total) is to be edited or converted. See p,m,f,edit under OUTREC for further details. However, note that PD0, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3, and TM4 are not allowed for TOTAL and that for TOTAL, the default number of digits (d) used for editing or conversion is as follows:
Table 48. Digits for TOTAL Fields Format (f) ZD ZD PD PD BI BI FI Length (m) 1-15 16-31 1-8 9-16 1-4 5-8 1-4 Digits (d) 15 31 15 31 10 20 10

318

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Table 48. Digits for TOTAL Fields (continued) Format (f) FI FL CSF or FS CSF or FS UFF UFF SFF SFF Length (m) 5-8 4 or 8 1-15 16-32 1-15 16-44 1-15 16-44 Digits (d) 20 20 15 31 15 31 15 31

If EDIT or EDxy is specified, the number of digits in the pattern (Is and Ts) is used. MIN specifies that an edited or converted minimum, for the values of a numeric input field in all data records of the report, is to appear in the report record. p,m,f,edit or p,m,f,to specifies the numeric input field for which the minimum is to be produced and how the output field (that is, the minimum) is to be edited or converted. See p,m,f,edit or p,m,f,to under OUTREC for further details. However, note that PD0, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3 and TM4 are not allowed for MIN. MAX specifies that an edited or converted maximum, for the values of a numeric input field in all data records of the report, is to appear in the report record. p,m,f,edit or p,m,f,to specifies the numeric input field for which the maximum is to be produced and how the output field (that is, the maximum) is to be edited or converted. See p,m,f,edit or p,m,f,to under OUTREC for further details. However, note that PD0, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3 and TM4 are not allowed for MAX. AVG specifies that an edited or converted average, for the values of a numeric input field in all data records of the report, is to appear in the report record. The average (or mean) is calculated by dividing the total by the count and rounding down to the nearest integer. For example:
+2305 / 152 = +15 -2305 / 152 = -15

p,m,f,edit or p,m,f,to specifies the numeric input field for which the average is to be produced and how the output field (that is, the average) is to be edited or converted.
Chapter 3. Using DFSORT Program Control Statements

319

OUTFIL Control Statements

See p,m,f,edit or p,m,f,to under OUTREC for further details. However, note that PD0, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3 and TM4 are not allowed for AVG. SUBTOTAL specifies that an edited or converted running total, for the values of a numeric input field in all data records of the report, is to appear in the report record. SUBTOT or SUB can be used instead of SUBTOTAL. For TRAILER1, the running total is the same as the total, so SUBTOTAL produces the same value as TOTAL. p,m,f,edit or p,m,f,to specifies the numeric input field for which the running total is to be produced and how the output field (that is, the running total) is to be edited or converted. See p,m,f,edit or p,m,f,to under TOTAL for further details. SUBMIN specifies that an edited or converted running minimum, for the values of a numeric input field in all data records of the report, is to appear in the report record. For TRAILER1, the running minimum is the same as the minimum, so SUBMIN produces the same value as MIN. p,m,f,edit or p,m,f,to specifies the numeric input field for which the running minimum is to be produced and how the output field (that is, the running minimum) is to be edited or converted. See p,m,f,edit or p,m,f,to under OUTREC for further details. However, note that PD0, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3 and TM4 are not allowed for SUBMIN. SUBMAX specifies that an edited or converted running maximum, for the values of a numeric input field in all data records of the report, is to appear in the report record. For TRAILER1, the running maximum is the same as the maximum, so SUBMAX produces the same value as MAX. p,m,f,edit or p,m,f,to specifies the numeric input field for which the running maximum is to be produced and how the output field (that is, the running maximum) is to be edited or converted. See p,m,f,edit or p,m,f,to under OUTREC for further details. However, note that PD0, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3 and TM4 are not allowed for SUBMAX. SUBAVG specifies that an edited or converted running average, for the values of a numeric input field in all data records of the report, is to appear in the report record.

320

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

For TRAILER1, the running average is the same as the average, so SUBAVG produces the same value as AVG. p,m,f,edit or p,m,f,to specifies the numeric input field for which the running average is to be produced and how the output field (that is, the running average) is to be edited or converted. See p,m,f,edit or p,m,f,to under OUTREC for further details. However, note that PD0, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3 and TM4 are not allowed for SUBAVG. Sample Syntax:
OUTFIL FNAMES=RPT1, TRAILER1=(5/, 10:Summary of Report for Division Revenues,3/, 10:Number of divisions reporting: ,COUNT,2/, 10:Total revenue: ,TOTAL=(25,5,PD,M5),2/, 10:Lowest revenue: ,MIN=(25,5,PD,M5),2/, 10:Highest revenue: ,MAX=(25,5,PD,M5),2/, 10:Average revenue: ,AVG=(25,5,PD,M5)) OUTFIL FNAMES=RPT2,BLKCCT1, TRAILER1=(/,10:Grand Total: ,TOTAL=(25,5,PD,M5))

Default for TRAILER1: None; must be specified. HEADER2

, HEADER2= ( c: r p,m DATE &DATE DATE=(abcd) &DATE=(abcd) DATENS=(abc) &DATENS=(abc) YDDD=(abc) &YDDD=(abc) YDDDNS=(ab) &YDDDNS=(ab) TIME &TIME TIME=(abc) &TIME=(abc) TIMENS=(ab) &TIMENS=(ab) PAGE &PAGE PAGE=( edit ) to &PAGE=( edit ) to )

Specifies the page header to be used for the reports produced for this OUTFIL group. The page header appears at the top of each page of the report, except
Chapter 3. Using DFSORT Program Control Statements

321

OUTFIL Control Statements

for the report header page (if any) and report trailer page (if any). DFSORT uses ANSI carriage control characters to control page ejects and the placement of the lines in your report, according to your specifications. You can use BLKCCH2 to replace the 1 (page eject) for the ANSI carriage control character in the first line of the first page header with a blank, thus avoiding forcing a page eject. You can use REMOVECC to remove the ANSI carriage control characters from a report. You can choose to include any or all of the following report elements in your page header: v Blanks, character strings, and hexadecimal strings v Unedited input fields from the first OUTFIL input record for which a data record appears on the page v Current date in a variety of different forms v Current time in a variety of different forms v Page number, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on. The page header consists of the elements you select, in the order in which you specify them, and in the columns or lines you specify. c: r p,m See c: under HEADER1. See r under HEADER1. specifies that an unedited input field, from the first OUTFIL input record for which a data record appears on the page, is to appear in the report record. See p,m under HEADER1 for further details.

DATE See DATE under HEADER1. &DATE can be used instead of DATE. DATE=(abcd) See DATE=(abcd) under HEADER1. &DATE=(abcd) can be used instead of DATE=(abcd). DATENS=(abc) See DATENS=(abc) under HEADER1. &DATENS=(abc) can be used instead of DATENS=(abc). YDDD=(abc) See YDDD=(abc) under HEADER1. &YDDD=(abc) can be used instead of YDDD=(abc). YDDDNS=(ab) See YDDDNS=(ab) under HEADER1. &YDDDNS=(ab) can be used instead of YDDDNS=(ab). TIME See TIME under HEADER1. &TIME can be used instead of TIME.

322

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

TIME=(abc) See TIME=(abc) under HEADER1. &TIME=(abc) can be used instead of TIME=(abc). TIMENS=(ab) See TIMENS=(ab) under HEADER1. &TIMENS=(ab) can be used instead of TIMENS=(ab). PAGE specifies that the current page number is to appear in the OUTFIL report record. The page number for the header appears as 6 digits, right-justified, with leading zeros suppressed. For example, if the page is numbered 3, it appears as 3. If HEADER1 is specified with PAGE and HEADER2 is specified with PAGE, the page number for the first page header will be 2. If HEADER1 is not specified or is specified without PAGE and HEADER2 is specified with PAGE, the page number for the first page header will be 1. &PAGE can be used instead of PAGE. PAGE=(edit) or PAGE=(to) same as PAGE except that the 15-digit page number appears edited or converted as specified. See p,m,f,edit under OUTREC for further details on the edit fields you can use. See p,m,f,to under OUTREC for further details on the to fields you can use. &PAGE=(edit) or &PAGE=(to) can be used instead of PAGE=(edit) or PAGE=(to). Sample Syntax:
OUTFIL FNAMES=STATUS, HEADER2=(5:Page ,PAGE, of Status Report for ,DATE=(MD4/), at ,TIME=(12:),2/, 10:Item ,20:Status ,35:Count,/, 10:-----,20:------------,35:-----), OUTREC=(10:6,5, 20:14,1,CHANGE=(12, CS,CShip, CH,CHold, CT,CTransfer), NOMATCH=(C*Check Code*), 36:39,4,ZD,M10, 132:X)

Default for HEADER2: None; must be specified. TRAILER2

Chapter 3. Using DFSORT Program Control Statements

323

OUTFIL Control Statements

, TRAILER2= ( c: r p,m DATE &DATE DATE=(abcd) &DATE=(abcd) DATENS=(abc) &DATENS=(abc) YDDD=(abc) &YDDD=(abc) YDDDNS=(ab) &YDDDNS=(ab) TIME &TIME TIME=(abc) &TIME=(abc) TIMENS=(ab) &TIMENS=(ab) PAGE &PAGE PAGE=( edit ) to &PAGE=( edit ) to COUNT COUNT15 COUNT=( edit ) to COUNT+n=( edit to COUNT-n=( edit to SUBCOUNT SUBCOUNT15 SUBCOUNT=( edit to TOTAL= (p,m,f TOT= MIN= MAX= AVG= (p,m,f ,edit ,to (p,m,f ,edit ,to (p,m,f ,edit ,to (p,m,f ,edit ,to ) ,edit ,to SUBMAX= SUBAVG= (p,m,f ,edit ,to (p,m,f ,edit ,to ) ) ) ) ) )

) )

) ) ,edit ,to )

SUBTOTAL= SUBTOT= SUB= SUBMIN= (p,m,f

Specifies the page trailer to be used for the reports produced for this OUTFIL group. The page trailer appears at the very bottom of each page of the report

324

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

(as specified or defaulted by the LINES value), except for the report header page (if any) and report trailer page (if any). DFSORT uses ANSI carriage control characters to control page ejects and the placement of the lines in your report, according to your specifications. You can choose to include any or all of the following report elements in your page trailer: v Blanks, character strings, and hexadecimal strings v Unedited input fields from the last OUTFIL input record for which a data record appears on the page v Current date in a variety of different forms v Current time in a variety of different forms v Page number, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on v Any or all of the following statistics: Count of data records on the page, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on. You can add a decimal number to the count before converting or editing it (for example, add 1 to account for writing a trailer record, or add 2 to account for writing a header and trailer record). Total, minimum, maximum, or average for each specified ZD, PD, BI, FI, FL, CSF, FS, UFF, or SFF numeric input field in the data records on the page, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on. Running total, minimum, maximum, or average for each specified ZD, PD, BI, FI, FL, CSF, FS, UFF, or SFF numeric input field in the data records up to this point, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on. The page trailer consists of the elements you select, in the order in which you specify them, and in the columns or lines you specify. c: r p,m See c: under HEADER1. See r under TRAILER1. specifies that an unedited input field, from the last OUTFIL input record for which a data record appears on the page, is to appear in the report record. See p,m under TRAILER1 for further details.

DATE See DATE under HEADER1. &DATE can be used instead of DATE. DATE=(abcd) See DATE=(abcd) under HEADER1. &DATE=(abcd) can be used instead of DATE=(abcd). DATENS=(abc) See DATENS=(abc) under HEADER1. &DATENS=(abc) can be used instead of DATENS=(abc).

Chapter 3. Using DFSORT Program Control Statements

325

OUTFIL Control Statements

YDDD=(abc) See YDDD=(abc) under HEADER1. &YDDD=(abc) can be used instead of YDDD=(abc). YDDDNS=(ab) See YDDDNS=(ab) under HEADER1. &YDDDNS=(ab) can be used instead of YDDDNS=(ab). TIME See TIME under HEADER1. &TIME can be used instead of TIME. TIME=(abc) See TIME=(abc) under HEADER1. &TIME=(abc) can be used instead of TIME=(abc). TIMENS=(ab) See TIMENS=(ab) under HEADER1. &TIMENS=(ab) can be used instead of TIMENS=(ab). PAGE See PAGE under TRAILER1. &PAGE can be used instead of PAGE. PAGE=(edit) or PAGE=(to) See PAGE=(edit) or PAGE=(to) under TRAILER1. &PAGE=(edit) or &PAGE=(to) can be used instead of PAGE=(edit) or PAGE=(to). COUNT specifies that the count of data records on the page is to appear in the report record as 8 digits, right-justified, with leading zeros suppressed. For example, if page 1 has 40 input records, page 2 has 40 input records, and page 3 has 26 input records, COUNT will show 40 for page 1, 40 for page 2, and 26 for page 3. If slash (/) is used in OUTREC or BUILD to produce multiple data records, COUNT counts only the number of data records processed as input to OUTREC or BUILD. For example, if OUTREC processes 3 input records and creates 2 output records for each input record, the count is 3, not 6. COUNT15 same as COUNT except that the count appears as 15 digits. COUNT=(edit) or COUNT=(to) same as COUNT except that the 15digit count appears edited or converted as specified. See p,m,f,edit under OUTREC for further details on the edit fields you can use. See p,m,f,to under OUTREC for further details on the to fields you can use.

326

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

COUNT+n=(edit) or COUNT+n=(to) same as COUNT=(edit) or COUNT=(to) except that n is added to the 15-digit count before it is edited or converted. n can be 1 to 3 decimal digits. COUNT-n=(edit) or COUNT-n=(to) same as COUNT=(edit) or COUNT=(to) except that n is subtracted from the 15-digit count before it is edited or converted. n can be 1 to 3 decimal digits. SUBCOUNT specifies that the count of input records up to this point in the report is to appear in the report record as 8 digits, right-justified, with leading zeros suppressed. The running count accumulates the count for all pages up to and including the current page. For example, if page 1 has 40 input records, page 2 has 40 input records, and page 3 has 26 input records, SUBCOUNT will show 40 for page 1, 80 for page 2, and 106 for page 3. If slash (/) is used in OUTREC or BUILD to produce multiple data records, SUBCOUNT counts only the number of data records processed as input to OUTREC or BUILD. For example, if OUTREC processes 3 input records and creates 2 output records for each input record, the running count is 3, not 6. SUBCOUNT15 same as SUBCOUNT except that the running count appears as 15 digits. SUBCOUNT=(edit) or SUBCOUNT=(to) same as SUBCOUNT except that the 15digit running count appears edited or converted as specified. See p,m,f,edit under OUTREC for further details on the edit fields you can use. See p,m,f,to under OUTREC for further details on the to fields you can use. TOTAL specifies that an edited or converted total, for the values of a numeric input field in the data records on the page, is to appear in the report record. TOT can be used instead of TOTAL. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under TOTAL for TRAILER1. MIN specifies that an edited or converted minimum, for the values of a numeric input field in the data records on the page, is to appear in the report record. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under MIN for TRAILER1. MAX specifies that an edited or converted maximum, for the values of a numeric input field in the data records on the page, is to appear in the report record. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under MAX for TRAILER1. AVG specifies that an edited or converted average, for the values of a numeric input field in the data records on the page, is to appear in the report record.
Chapter 3. Using DFSORT Program Control Statements

327

OUTFIL Control Statements

p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under AVG for TRAILER1. SUBTOTAL specifies that an edited or converted running total, for the values of a numeric input field in the data records up to this point in the report, is to appear in the report record. The running total accumulates the total for all pages up to and including the current page. For example, if the total for a selected numeric field is +200 for page 1, 250 for page 2, and +90 for page 3, SUBTOTAL will be +200 for page 1, 50 for page 2, and +40 for page 3. SUBTOT or SUB can be used instead of SUBTOTAL. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under SUBTOTAL for TRAILER1. SUBMIN specifies that an edited or converted running minimum, for the values of a numeric input field in the data records up to this point in the report, is to appear in the report record. The running minimum selects the minimum from all pages up to and including the current page. For example, if the minimum for a selected numeric field is +200 for page 1, 250 for page 2, and +90 for page 3, SUBMIN will be +200 for page 1, 250 for page 2, and 250 for page 3. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under SUBMIN for TRAILER1. SUBMAX specifies that an edited or converted running maximum, for the values of a numeric input field in the data records up to this point in the report, is to appear in the report record. The running maximum selects the maximum from all pages up to and including the current page. For example, if the maximum for a selected numeric field is 100 for page 1, +250 for page 2, and +90 for page 3, SUBMAX will be 100 for page 1, +250 for page 2, and +250 for page 3. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under SUBMAX for TRAILER1. SUBAVG specifies that an edited or converted running average, for the values of a numeric input field in the data records up to this point in the report, is to appear in the report record. The running average computes the average for all pages up to and including the current page. For example, if the count of data records and total for a selected numeric field are 60 and +2205 for page 1, respectively, 60 and 6252 for page 2, respectively, and 23 and 320 for page 3, respectively, SUBAVG will be +36 for page 1, 33 for page 2, and 30 for page 3. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under SUBAVG for TRAILER1. Sample Syntax:
OUTFIL FNAMES=STATS, STARTREC=3, OUTREC=(20:23,3,PD,M16, 30:40,3,PD,M16, 80:X), TRAILER2=(/,2:Average on page:, 20:AVG=(23,3,PD,M16),

328

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

30:AVG=(40,3,PD,M16),/, 2:Average so far:, 20:SUBAVG=(23,3,PD,M16), 30:SUBAVG=(40,3,PD,M16))

Default for TRAILER2: None; must be specified. SECTIONS

, , SECTIONS= ( p,m SKIP= P L nL , HEADER3= ( field , TRAILER3= ( field ) ) ,PAGEHEAD )

Specifies the section break processing to be used for the reports produced for this OUTFIL group. A section break field divides the report into sets of sequential OUTFIL input records with the same binary value for that field, which result in corresponding sets of data records (that is, sections) in the report. A break is said to occur when the binary value changes. Of course, because a break can occur in any record, the data records of a section can be split across pages in your report. For each section break field you specify, you can choose to include any or all of the following: v A page eject between sections. v Zero, one or more blank lines to appear between sections on the same page. v A section header to appear before the first data record of each section and optionally, at the top of each page. When a page header and section header are both to appear at the top of a page, the section header will follow the page header. v A section trailer to appear after the last data record of each section. When a page trailer and section trailer are both to appear at the bottom of a page, the page trailer will follow the section trailer. DFSORT uses ANSI carriage control characters to control page ejects and the placement of the lines in your report, according to your specifications. If multiple section break fields are used, they are processed in first-to-last order, in the same way they would be sorted by these fields. In fact, the input data set is generally sorted by the section break fields, to group the records with the same section break values together for the report. This sorting can be done by the same application that produces the report or by a previous application. A break in section break field 1 results in a break in section break fields 2 through n. A break in section break 2 results in a break in section break fields 3 through n, and so on. The section headers appear before each section in
Chapter 3. Using DFSORT Program Control Statements

329

OUTFIL Control Statements

first-to-last order, whereas the section trailers appear in last-to-first order. For example, if section break fields represented by B1 with header H3A and trailer T3A, B2 with header H3B and trailer T3B, and B3 with header H3C and trailer T3C are specified in order, the following can appear:
H3A (header for B1=1 section) H3B (header for B2=1 section) H3C (header for B3=1 section) data records for B1=1, B2=1, T3C (trailer for B3=1 section) H3C (header for B3=2 section) data records for B1=1, B2=1, T3C (trailer for B3=2 section) T3B (trailer for B2=1 section) H3B (header for B2=2 section) H3C (header for B3=1 section) data records for B1=1, B2=2, T3C (trailer for B3=1 section) T3B (trailer for B2=2 section) T3A (trailer for B1=1 section) H3A (header for B1=2 section) H3B (header for B2=2 section) H3C (header for B3=0 section) data records for B1=2, B2=2, T3C (trailer for B3=0 section) H3C (header for B3=1 section) data records for B1=2, B2=2, T3C (trailer for B3=1 section) T3B (trailer for B2=2 section) T3A (trailer for B1=2 section)

B3=1 (new B1, B2, and B3 section) B3=2 (new B3 section)

B3=1 (new B2 and B3 section)

B3=0 (new B1, B2, and B3 section) B3=1 (new B3 section)

p,m specifies a section break field in the OUTFIL input records to be used to divide the report into sections. Each set of sequential OUTFIL input records, with the same binary value for the section break field, results in a corresponding set of data records. Each such set of data records is treated as a section in the report. A break is said to occur when the binary value changes. p m SKIP See p under HEADER1. See m under HEADER1.

SKIP=

P L nL

Specifies, for reports produced for this OUTFIL group, that either: v Each section for the associated section break field is to appear on a new page, or v Zero, one or more blank lines to appear after each section associated with this section break field, when it is followed by another section on the same page. Thus, you can use SKIP to specify how sections will be separated from each other. P specifies that each section is to appear on a new page.

330

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

L nL specifies that one blank line is to appear between sections on the same page. L is the same as 1L. specifies that n blank lines are to appear between sections on the same page. You can specify from 0 to 255 for n.

Sample Syntax:
OUTFIL FNAMES=(PRINT,TAPE), SECTIONS=(10,20,SKIP=P, 42,10,SKIP=3L)

HEADER3

, HEADER3= ( c: r p,m DATE &DATE DATE=(abcd) &DATE=(abcd) DATENS=(abc) &DATENS=(abc) YDDD=(abc) &YDDD=(abc) YDDDNS=(ab) &YDDDNS=(ab) TIME &TIME TIME=(abc) &TIME=(abc) TIMENS=(ab) &TIMENS=(ab) PAGE &PAGE PAGE=( edit ) to &PAGE=( edit ) to )

Specifies the section header to be used with the associated section break field for the reports produced for this OUTFIL group. The section header appears before the first data record of each section. DFSORT uses ANSI carriage control characters to control page ejects and the placement of the lines in your report, according to your specifications. You can choose to include any or all of the following report elements in your section header: v Blanks, character strings, and hexadecimal strings v Unedited input fields from the first OUTFIL input record for which a data record appears in the section v Current date in a variety of different forms v Current time in a variety of different forms v Page number, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on.
Chapter 3. Using DFSORT Program Control Statements

331

OUTFIL Control Statements

The section header consists of the elements you select, in the order in which you specify them, and in the columns or lines you specify. c: r p,m See c: under HEADER1. See r under HEADER1. specifies that an unedited input field, from the first OUTFIL input record for which a data record appears in the section, is to appear in the report record. See p,m under HEADER1 for further details.

DATE See DATE under HEADER1. &DATE can be used instead of DATE. DATE=(abcd) See DATE=(abcd) under HEADER1. &DATE=(abcd) can be used instead of DATE=(abcd). DATENS=(abc) See DATENS=(abc) under HEADER1. &DATENS=(abc) can be used instead of DATENS=(abc). YDDD=(abc) See YDDD=(abc) under HEADER1. &YDDD=(abc) can be used instead of YDDD=(abc). YDDDNS=(ab) See YDDDNS=(ab) under HEADER1. &YDDDNS=(ab) can be used instead of YDDD=(ab). TIME See TIME under HEADER1. &TIME can be used instead of TIME. TIME=(abc) See TIME=(abc) under HEADER1. &TIME=(abc) can be used instead of TIME=(abc). TIMENS=(ab) See TIMENS=(ab) under HEADER1. &TIMENS=(ab) can be used instead of TIMENS=(ab). PAGE specifies that the current page number is to appear in the OUTFIL report record. The page number for the header appears as 6 digits, right-justified, with leading zeros suppressed. For example, if the page is numbered 3, it appears as 3. &PAGE can be used instead of PAGE. PAGE=(edit) or PAGE=(to) same as PAGE except that the 15-digit page number appears edited or

332

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

converted as specified. See p,m,f,edit under OUTREC for further details on the edit fields you can use. See p,m,f,to under OUTREC for further details on the to fields you can use. &PAGE=(edit) or &PAGE=(to) can be used instead of PAGE=(edit) or PAGE=(to). Sample Syntax:
OUTFIL FNAMES=STATUS1, HEADER2=(10:Status Report for all departments,5X, - ,&PAGE, -), SECTIONS=(10,8, HEADER3=(2/,10:Report for department ,10,8, on ,&DATE,2/, 10: Number,25:Average Time,/, 10:Completed,25: (in days),/, 10:---------,25:------------)), OUTREC=(10:21,5,ZD,M10,LENGTH=9, 25:38,4,ZD,EDIT=(III.T),LENGTH=12, 132:X)

PAGEHEAD

PAGEHEAD

Specifies that the section header to be used with the associated section break field is to appear at the top of each page of the report, except for the report header page (if any) and report trailer page (if any), as well as before each section. If you do not specify PAGEHEAD, the section header appears only before each section; so if a section is split between pages, the section header appears only in the middle of the page. PAGEHEAD can be used when you want HEADER3 to be used as a page header as well as a section header. If PAGEHEAD is specified for a section break field for which HEADER3 is not also specified, PAGEHEAD will not be used. Sample Syntax:
OUTFIL FNAMES=STATUS2, HEADER2=(10:Status Report for all departments,5X, - ,&PAGE, -), SECTIONS=(10,8, HEADER3=(2/,10:Report for department ,10,8, on ,&DATE,2/, 10: Number,25:Average Time,/, 10:Completed,25: (in days),/, 10:---------,25:------------), PAGEHEAD,SKIP=P), OUTREC=(10:21,5,ZD,M10,LENGTH=9, 25:38,4,ZD,EDIT=(III.T),LENGTH=12, 132:X)

TRAILER3

Chapter 3. Using DFSORT Program Control Statements

333

OUTFIL Control Statements

, TRAILER3= ( c: r p,m DATE &DATE DATE=(abcd) &DATE=(abcd) DATENS=(abc) &DATENS=(abc) YDDD=(abc) &YDDD=(abc) YDDDNS=(ab) &YDDDNS=(ab) TIME &TIME TIME=(abc) &TIME=(abc) TIMENS=(ab) &TIMENS=(ab) PAGE &PAGE PAGE=( edit ) to &PAGE=( edit ) to COUNT COUNT15 COUNT=( edit ) to COUNT+n=( edit to COUNT-n=( edit to SUBCOUNT SUBCOUNT15 SUBCOUNT=( edit to TOTAL= (p,m,f TOT= MIN= MAX= AVG= (p,m,f ,edit ,to (p,m,f ,edit ,to (p,m,f ,edit ,to (p,m,f ,edit ,to ) ,edit ,to SUBMAX= SUBAVG= (p,m,f ,edit ,to (p,m,f ,edit ,to ) ) ) ) ) )

) )

) ) ,edit ,to )

SUBTOTAL= SUBTOT= SUB= SUBMIN= (p,m,f

Specifies the section trailer to be used with the associated section break field for the reports produced for this OUTFIL group. The section trailer appears

334

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

after the last data record of each section. DFSORT uses ANSI carriage control characters to control page ejects and the placement of the lines in your report, according to your specifications. You can choose to include any or all of the following report elements in your section trailer: v Blanks, character strings, and hexadecimal strings v Unedited input fields from the last OUTFIL input record for which a data record appears in the section v Current date in a variety of different forms v Current time in a variety of different forms v Page number, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on v Any or all of the following statistics: Count of data records in the section, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on. You can add a decimal number to the count before converting or editing it (for example, add 1 to account for writing a trailer record, or add 2 to account for writing a header and trailer record). Total, minimum, maximum, or average for each specified ZD, PD, BI, FI, FL, CSF, FS, UFF, or SFF numeric input field in the data records in the section, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on Running total, minimum, maximum, or average for each specified ZD, PD, BI, FI, FL, CSF, FS, UFF, or SFF numeric input field in the data records up to this point, converted to different numeric formats, or edited to contain signs, decimal points, leading zeros or no leading zeros, and so on. The section trailer consists of the elements you select, in the order in which you specify them, and in the columns or lines you specify. c: r p,m See c: under HEADER1. See r under TRAILER1. specifies that an unedited input field, from the last OUTFIL input record for which a data record appears in the section, is to appear in the report record. See p,m under TRAILER1 for further details. See DATE under HEADER1. can be used instead of DATE.

DATE &DATE

DATE=(abcd) See DATE=(abcd) under HEADER1. &DATE=(abcd) can be used instead of DATE=(abcd). DATENS=(abc) See DATENS=(abc) under HEADER1. &DATENS=(abc) can be used instead of DATENS=(abc). YDDD=(abc) See YDDD=(abc) under HEADER1.

Chapter 3. Using DFSORT Program Control Statements

335

OUTFIL Control Statements

&YDDD=(abc) can be used instead of YDDD=(abc). YDDDNS=(ab) See YDDDNS=(ab) under HEADER1. &YDDDNS=(ab) can be used instead of YDDDNS=(ab). TIME &TIME TIME=(abc) See TIME under HEADER1. can be used instead of TIME. See TIME=(abc) under HEADER1.

&TIME=(abc) can be used instead of TIME=(abc). TIMENS=(ab) See TIMENS=(ab) under HEADER1. &TIMENS=(ab) can be used instead of TIMENS=(ab). PAGE &PAGE See PAGE under TRAILER1. can be used instead of PAGE.

PAGE=(edit) or PAGE=(to) See PAGE=(edit) or PAGE=(to) under TRAILER1. &PAGE=(edit) or &PAGE=(to) can be used instead of PAGE=(edit) or PAGE=(to). COUNT specifies that the count of data records in the section is to appear in the report record as 8 digits, right-justified, with leading zeros suppressed. For example, if the first section has 40 input records, the second section has 40 input records, and the third section has 26 input records, COUNT will show 40 for the first section, 40 for the second section, and 26 for the third section. If slash (/) is used in OUTREC or BUILD to produce multiple data records, COUNT counts only the number of data records processed as input to OUTREC or BUILD. For example, if OUTREC or BUILD processes 3 input records and creates 2 output records for each input record, the count is 3, not 6. COUNT15 same as COUNT except that the count appears as 15 digits.

COUNT=(edit) or COUNT=(to) same as COUNT except that the 15digit count appears edited or converted as specified. See p,m,f,edit under OUTREC for further details on the edit fields you can use. See p,m,f,to under OUTREC for further details on the to fields you can use. COUNT+n=(edit) or COUNT+n=(to) same as COUNT=(edit) or COUNT=(to) except that n is added to the 15-digit count before it is edited or converted. n can be 1 to 3 decimal digits. COUNT-n=(edit) or COUNT-n=(to) same as COUNT=(edit) or COUNT=(to) except that n is subtracted from the 15-digit count before it is edited or converted. n can be 1 to 3 decimal digits. SUBCOUNT specifies that the running count of input records up to this

336

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

point in the report is to appear in the report record 8 digits, right-justified, with leading zeros suppressed. The running count accumulates the count for all sections up to and including the current section. For example, if the first section has 40 input records, the second section has 40 input records, and the third section has 26 input records, SUBCOUNT will show 40 for the first section, 80 for the second section, and 106 for the third section. If slash (/) is used in OUTREC or BUILD to produce multiple data records, SUBCOUNT counts only the number of data records processed as input to OUTREC or BUILD. For example, if OUTREC or BUILD processes 3 input records and creates 2 output records for each input record, the running count is 3, not 6 SUBCOUNT15 same as SUBCOUNT except that the running count appears as 15 digits. SUBCOUNT=(edit) or SUBCOUNT=(to) same as SUBCOUNT except that the 15digit running count appears edited or converted as specified. See p,m,f,edit under OUTREC for further details on the edit fields you can use. See p,m,f,to under OUTREC for further details on the to fields you can use. TOTAL specifies that an edited or converted total, for the values of a numeric input field in the data records in the section, is to appear in the report record. TOT can be used instead of TOTAL. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under TOTAL for TRAILER1. MIN specifies that an edited or converted minimum, for the values of a numeric input field in the data records in the section, is to appear in the report record. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,tounder MIN for TRAILER1. MAX specifies that an edited or converted maximum, for the values of a numeric input field in the data records in the section, is to appear in the report record. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under MAX for TRAILER1. AVG specifies that an edited or converted average, for the values of a numeric input field in the data records in the section, is to appear in the report record. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under AVG for TRAILER1. SUBTOTAL specifies that an edited or converted running total, for the values of a numeric input field in the data records up to this point in the report, is to appear in the report record. The running total accumulates the total for all sections up to and including the current section. For example, if the total for a
Chapter 3. Using DFSORT Program Control Statements

337

OUTFIL Control Statements

selected numeric field is +200 for the first section, 250 for the second section and +90 for the third section, SUBTOTAL will be +200 for the first section, 50 for the second section and +40 for the third section. SUBTOT or SUB can be used instead of SUBTOTAL. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under SUBTOTAL for TRAILER1. SUBMIN specifies that an edited or converted running minimum, for the values of a numeric input field in the data records up to this point in the report, is to appear in the report record. The running minimum selects the minimum from all sections up to and including the current section. For example, if the minimum for a selected numeric field is +200 for the first section, 250 for the second section and +90 for the third section, SUBMIN will be +200 for the first section, 250 for the second section and 250 for the third section. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under SUBMIN for TRAILER1. SUBMAX specifies that an edited or converted running maximum, for the values of a numeric input field in the data records up to this point in the report, is to appear in the report record. The running maximum selects the maximum from all sections up to and including the current section. For example, if the maximum for a selected numeric field is 100 for the first section, +250 for the second section and +90 for the third section, SUBMAX will be 100 for the first section, +250 for the second section and +250 for the third section. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under SUBMAX for TRAILER1. SUBAVG specifies that an edited or converted running average, for the values of a numeric input field in the data records up to this point in the report, is to appear in the report record. The running average computes the average for all sections up to and including the current section. For example, if the count of data records and total for a selected numeric field are 60 and +2205 for the first section, respectively, 60 and 6252 for the second section, respectively, and 23 and 320 for the third section, respectively, SUBAVG will be +36 for the first section, 33 for the second section and 30 for the third section. p,m,f,edit or p,m,f,to See p,m,f,edit or p,m,f,to under SUBAVG for TRAILER1. Sample Syntax:
OUTFIL FNAMES=SECRPT, INCLUDE=(11,4,CH,EQ,CSSD), SECTIONS=(3,5,SKIP=P, HEADER3=(2:Department: ,3,5,4X,Date: ,&DATE,2/), TRAILER3=(2/,2:The average for ,3,5, is , AVG=(40,3,PD,M12),/,

338

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

2:The overall average so far is , SUBAVG=(40,3,PD,M12)), 45,8,SKIP=3L, HEADER3=(4:Week Ending ,45,8,2/, 4:Item Number,20:Completed,/, 4:-,20:-), TRAILER3=(4:The item count for week ending ,45,8, is ,COUNT=(EDIT=(II,IIT)))), OUTREC=(11:16,4,22:40,3,PD,M12,120:X)

Default for SECTIONS: None; must be specified. NODETAIL

NODETAIL

Specifies that data records are not to be output for the reports produced for this OUTFIL group. With NODETAIL, the data records are completely processed with respect to input fields, statistics, counts, sections breaks, and so on, but are not written to the OUTFIL data set and are not included in line counts for determining the end of a page. You can use NODETAIL to summarize the data records without actually showing them. Sample Syntax:
OUTFIL FNAMES=SUMMARY,NODETAIL, HEADER2=( Date: ,DATENS=(DMY.),4X,Page: ,PAGE,2/, 10:Division,25: Total Revenue,/, 10:--------,25:-----------------), SECTIONS=(3,5, TRAILER3=(10:3,5, 25:TOTAL=(25,4,FI,M19, LENGTH=17))), TRAILER1=(5/,10:Summary of Revenue ,4/, 12:Number of divisions reporting is , COUNT,/, 12:Total revenue is , TOTAL=(25,4,FI,M19))

Default for NODETAIL: None; must be specified. Default for OUTFIL Statements: None; must be specified. Multiple OUTFIL statements can be specified in the same and different sources; override is at the ddname level. Applicable Functions for OUTFIL Statements: Sort, merge, and copy. BLKCCH1 specifies that the ANSI carriage control character of 1 (page eject) in the first line of the report header (HEADER1) is to be replaced with a blank. You can use BLKCCH1 to avoid forcing a page eject at the start of the report header. If BLKCCH1 is specified without HEADER1, it will not be used. Sample Syntax:
OUTFIL FNAMES=RPT1,BLKCCH1, HEADER1=(30:January Report,4/)

Default for BLKCCH1: None; must be specified. BLKCCH2 specifies that the ANSI carriage control character of 1 (page eject) in the first
Chapter 3. Using DFSORT Program Control Statements

339

OUTFIL Control Statements

line of the first page header (HEADER2) is to replaced with a blank. You can use BLKCCH2 to avoid forcing a page eject at the start of the first page header. BLKCHH2 does not prevent a page eject for the second and subsequent page headers. If BLKCCH2 is specified without HEADER2, it will not be used. Sample Syntax:
OUTFIL FNAMES=RPT2, * Do page eject for HEADER1, but not for first HEADER2. HEADER1=(30:January Report,2/), BLKCCH2,HEADER2=(5:Account Number,25:Name)

Default for BLKCCH2: None; must be specified. BLKCCT1 specifies that the ANSI carriage control character of 1 (page eject) in the first line of the report trailer (TRAILER1) is to be replaced with a blank. You can use BLKCCT1 to avoid forcing a page eject at the start of the report trailer. If BLKCCT1 is specified without TRAILER1, it will not be used. Sample Syntax:
, OUTFIL FNAMES=RPT3,BLKCCT1 TRAILER1=(5:Grand Total is ,TOT=(21,10,ZD,M5))

Default for BLKCCT1: None; must be specified. REMOVECC

REMOVECC

Specifies that the ANSI carriage control character is to be removed from OUTFIL output records for this OUTFIL group before the records are written. In addition, blank lines are not used to position the page trailer (TRAILER2) at the bottom of the page. If REMOVECC is specified without any of the following report parameters, it will not be used: LINES, HEADER1, TRAILER1, HEADER2, TRAILER2, SECTIONS, or NODETAIL. Sample Syntax:
OUTFIL FNAMES=RPTWOCC, TRAILER1=(3/,Number of records is , COUNT=(TO=ZD,LENGTH=6)), REMOVECC

Default for REMOVECC: None; must be specified.

OUTFIL Statements Notes

v OUTFIL processing is supported for sort, merge, and copy applications, but only by the Blockset technique. v The ODMAXBF value in effect specifies the maximum buffer space to be used for each OUTFIL data set. ODMAXBF can be specified as an installation or run-time option, or in an ICEIEXIT routine. The default value of 2M is recommended for the ODMAXBF option in effect. Lowering ODMAXBF can cause performance degradation for the application, but might be necessary if you consider the amount of storage used for OUTFIL processing to be a

340

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

problem. Raising ODMAXBF can improve EXCPs for the application, but can also increase the amount of storage needed. The storage used for OUTFIL processing will be adjusted automatically according to the total storage available, the storage needed for non-OUTFIL processing, and the number of OUTFIL data sets and their attributes (for example, block size). OUTFIL processing will be subject to the ODMAXBF limit in effect and the system storage limits (for example, IEFUSI), but not to the DFSORT storage limits (that is, SIZE, MAXLIM, and TMAXLIM). DFSORT attempts to use storage above 16MB virtual for OUTFIL processing whenever possible. The VSAMBSP option applies to SORTOUT data sets, but not to OUTFIL data sets. The NOBLKSET option will be ignored if OUTFIL data sets are being processed. An E39 exit routine is entered for the SORTOUT data set, but not for OUTFIL data sets. For fixed-format OUTFIL data sets: DFSORT will determine each OUTFIL data set LRECL based on the length of the reformatted records for the group, or the length of the OUTFIL input records (if OUTREC, BUILD, OVERLAY, and IFTHEN are not specified for the group). For VSAM data sets, the maximum record size defined in the cluster is equivalent to the LRECL. If an OUTFIL data set LRECL is not specified or available, DFSORT will set it to the determined LRECL. If an OUTFIL data set LRECL is specified or available, it must not be less than the determined LRECL, or more than the determined LRECL if the OUTREC, BUILD, OVERLAY, or IFTHEN parameter is specified. In other words, the LRECL value cannot be used to pad the output records, or to truncate the records produced by OUTREC, BUILD, OVERLAY, or IFTHEN parameter processing. In general, OUTREC, BUILD, OVERLAY, or IFTHEN processing should be used to pad the records and OUTREC, BUILD, or IFTHEN processing should be used to truncate the records. In either case, the LRECL should either not be specified or set to the length of the reformatted records. For variable-format OUTFIL data sets: DFSORT will determine each OUTFIL data set maximum LRECL based on the length of the reformatted records for the group, or the length of the OUTFIL input records (if OUTREC, BUILD, OVERLAY, and IFTHEN are not specified for the group). If an OUTFIL data set maximum LRECL is not specified or available, DFSORT will set it to the determined maximum LRECL. For VSAM data sets, the maximum record size defined in the cluster is four bytes more than the maximum LRECL. When you create an OUTFIL report, the length for the longest or only data record must be equal to or greater than the maximum report record length. You can use the OUTREC, BUILD, OVERLAY, or IFTHEN parameter to force a length for the data records that is longer than any report record; you can then either let DFSORT compute and set the LRECL, or ensure that the computed LRECL is equal to the existing or specified LRECL. Remember to allow an extra byte in the LRECL for the ANSI carriage control character. For example, if your data records are 40 bytes, but your longest report record is 60 bytes, you can use an OUTREC parameter such as:
OUTREC=(1,40,80:X)

DFSORT will then set the LRECL to 81 (1 byte for the ANSI carriage control character plus 80 bytes for the length of the data records), and pad the data records with blanks on the right. If you dont want the ANSI carriage control characters to appear in the output data set, use the REMOVECC parameter to remove them. For example, if you specify:
Chapter 3. Using DFSORT Program Control Statements

341

OUTFIL Control Statements

OUTREC=(1,40,80:X),REMOVECC

DFSORT will set the LRECL to 80 instead of 81 and remove the ANSI carriage control character from each record before it is written. System errors can result if you print an OUTFIL report containing records longer than your printer can handle. v DFSORT uses appropriate ANSI carriage controls (for example, C- for triple space) in header and trailer records when possible to reduce the number of report records written. DFSORT always uses the single space carriage control (C ) in data records. Although these carriage control characters may not be shown when you view an OUTFIL data set (depending on how you view it), they will be used if you print the report. If you are creating a report for viewing and want blank lines to appear in headers and trailers, specify a line of blanks instead of using n/. For example, instead of specifying:
OUTFIL FNAMES=RPT, HEADER2=(2/,start of header,2/,next line)

which will result in blank lines for the printer, but not for viewing, specify:
OUTFIL FNAMES=RPT, HEADER2=(X,/,X,/,start of header,/,X,/,next line)

If you dont want the ANSI carriage control characters to appear in the output data set, use the REMOVECC parameter to remove them. v For variable-length records, the first entry in the OUTREC, BUILD or IFTHEN BUILD parameter must specify or include the unedited 4-byte record descriptor word (RDW), that is, the first field must be 1,4 or 1,m with m greater than 4. DFSORT sets the length of the reformatted record in the RDW. If the first field in the data portion of the input record is to appear unedited in the reformatted record immediately following the RDW, the entry in the OUTREC, BUILD, or IFTHEN BUILD parameter can specify both RDW and data field in one (1,m,...). Otherwise, the RDW must be specifically included in the reformatted record (for example, 1,4,1,4,HEX). For variable-length OUTFIL header or trailer records, you must not specify the 4-byte RDW at the beginning of the record. v For variable-length records, OVERLAY or IFTHEN OVERLAY items must not overlay the RDW in bytes 1-4. You must ensure that 1:, 2:, 3: or 4: is not specified or defaulted for any OVERLAY item. Note that the default for the first OVERLAY item is 1:, so you must override it. v With FIELDS, BUILD or IFTHEN BUILD, the variable part of the input record (that part beyond the minimum record length) can be included in the reformatted record and, if included, must be the last part. For example:
OUTFIL BUILD=(1,8,20C*,9)

With OVERLAY, the variable part of the input record must not be included in the reformatted record. v For variable-length records, the FIELDS or BUILD parameter of the INREC and OUTREC statement and the OUTREC or FIELDS parameter of the OUTFIL statement must all specify position-only for the last part, or all not specify position-only for the last part. OVERLAY or IFTHEN, and FIELDS, OUTREC or BUILD, can differ with respect to position-only. See INREC Statement Notes on page 147 for more details.

342

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

v If there are no OUTFIL input records for an OUTFIL group, the headers and trailers appear without any data records. Blanks will be used for any specified unedited input fields, and zero values will be used for any specified statistics fields. v If a variable-length OUTFIL input record is too short to contain a specified unedited input field for a report header or trailer, blanks will be used for the missing bytes. If a variable-length OUTFIL input record is too short to contain a specified section break field or statistics field, zeros will be used for the missing bytes, intentionally or unintentionally. v If a variable-length OUTFIL input record is too short to contain an OUTFIL INCLUDE or OMIT compare field, the action DFSORT takes depends on the settings for VLSCMP/NOVLSCMP and VLSHRT/NOVLSHRT. For details, see the discussion of the VLSCMP and NOVLSCMP options in OPTION Control Statement on page 167. v If a variable-length OUTFIL input record is too short to contain an OUTFIL OUTREC or BUILD field, DFSORT will terminate unless the VLFILL=byte parameter is specified. v If a variable-length OUTFIL input record is too short to contain an OUTFIL OVERLAY or IFTHEN field, blanks will be used for the missing bytes. v If a variable-length OUTFIL output data record is longer than the LRECL of its OUTFIL data set, the action DFSORT takes depends on the settings for VLLONG/NOVLLONG. For details, see the discussion of the VLLONG and NOVLLONG options in OPTION Control Statement on page 167. Note that VLLONG can be used to truncate long OUTFIL data records, but has no effect on long OUTFIL header or trailer records. v If an unedited page number overflows 6 digits, an edited page number overflows 15 digits, a count or running count overflows 15 digits, or a total or running total overflows 31 digits, the overflowing value will be truncated to the number of digits allowed, intentionally or unintentionally. v Multiple OUTFIL statements can be specified in the same and different sources. If a ddname occurs more than once in the same source, the ddname is associated with the first OUTFIL group in which it appears. For example, if the following is specified in SYSIN:
OUTFIL FNAMES=(OUT1,OUT2),INCLUDE=(1,1,CH,EQ,CA) OUTFIL FNAMES=(OUT3,OUT1),SAVE

OUT1 and OUT2 are processed as part of the first OUTFIL group, that is, with INCLUDE. OUT3 is processed as part of the second OUTFIL group, that is, with SAVE; but OUT1 is not because it is a duplicate ddname. If a ddname occurs in more than one source, the ddname is associated with the highest source OUTFIL group in which it appears. For example, if the following is specified in DFSPARM:
OUTFIL FNAMES=(OUT1,OUT2),INCLUDE=(1,1,CH,EQ,CA)

and the following is specified in SYSIN:

OUTFIL FNAMES=(OUT3,OUT1),SAVE

OUT1 and OUT2 are processed as part of the DFSPARM OUTFIL group, that is, with INCLUDE. OUT3 is processed as part of the SYSIN OUTFIL group, that is, with SAVE; but OUT1 is not because it is an overridden ddname. v OUTFIL statements cannot be passed to or returned from an EFS program. The D2 format cannot be specified in the INCLUDE or OMIT parameter of an OUTFIL statement.
Chapter 3. Using DFSORT Program Control Statements

343

OUTFIL Control Statements

v If SZERO is in effect, 0 is treated as negative and +0 is treated as positive for edited or converted input fields, minimums, maximums, decimal constants and the results of arithmetic expressions. If NOSZERO is in effect, 0 and +0 are treated as positive for edited or converted input fields, minimums, maximums, decimal constants, and the results of arithmetic expressions. v If SZERO is in effect, 0 compares as less than +0 when numeric fields and constants are used. If NOSZERO is in effect, 0 compares as equal to +0 when numeric fields and constants are used. Note: OPTION SZERO or OPTION NOSZERO is ignored for OUTFIL INCLUDE=(logexp) or OMIT=(logexp), or for OUTFIL IFTHEN=(WHEN=(logexp),...) unless the OPTION statement is found in a higher source (for example, DFSPARM is a higher source than SYSIN) or before the OUTFIL statement in the same source. For example, NOSZERO will be used in both of the following cases: Case 1:
//DFSPARM DD * OPTION COPY,NOSZERO /* //SYSIN DD * OUTFIL INCLUDE=(1,2,FS,EQ,+0) /*

Case 2:
//SYSIN DD * OPTION COPY,NOSZERO OUTFIL IFTHEN=(WHEN=(1,2,FS,EQ,+0),OVERLAY=(28:CA)), IFTHEN=(WHEN=NONE,OVERLAY=(28:CB)) /*

OUTFIL FeaturesExamples
Example 1
OPTION OUTFIL OUTFIL OUTFIL OUTFIL OUTFIL COPY INCLUDE=(15,6,CH,EQ,CMSG005),FNAMES=M005 INCLUDE=(15,6,CH,EQ,CMSG022),FNAMES=M022 INCLUDE=(15,6,CH,EQ,CMSG028),FNAMES=M028 INCLUDE=(15,6,CH,EQ,CMSG115),FNAMES=M115 SAVE,FNAMES=UNKNOWN

This example illustrates how records can be distributed to different OUTFIL data sets based on criteria you specify: v Input records with MSG005 in bytes 15 through 20 will be written to the OUTFIL data set associated with ddname M005. v Input records with MSG022 in bytes 15 through 20 will be written to the OUTFIL data set associated with ddname M022. v Input records with MSG028 in bytes 15 through 20 will be written to the OUTFIL data set associated with ddname M028. v Input records with MSG115 in bytes 15 through 20 will be written to the OUTFIL data set associated with ddname M115. v Input records with anything else in bytes 15 through 20 will be written to the OUTFIL data set associated with ddname UNKNOWN

344

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Example 2
SORT FIELDS=(18,5,ZD,D) OUTFIL FNAMES=(V,VBU1,VBU2) OUTFIL FNAMES=(F,FBU1), CONVERT,OUTREC=(11,3,X,18,5,X,X0000000F) OUTFIL FNAMES=VINF,OUTREC=(1,4,C*,5,20,C*,25)

This example illustrates how multiple sorted output data sets can be created and how a variable-length record data set can be converted to a fixed-length record data set: v The first OUTFIL statement writes the variable-length input records to the variable-length OUTFIL data sets associated with ddnames V, VBU1, and VBU2. v The second OUTFIL statement reformats the variable-length input records to fixed-length output records and writes them to the fixed-length OUTFIL data sets associated with ddnames F and FBU1. CONVERT is used to indicate that a variable-length data set is to be converted to a fixed-length data set; OUTREC is used to describe how the variable-length input records are to be reformatted as fixed-length output records. v The third OUTFIL statement reformats the variable-length input records and writes them to the variable-length OUTFIL data set associated with ddname VINF. OUTREC is used to insert asterisks between fields. 1,4 represents the RDW. 25 represents the variable part at the end of the input record.

Example 3
SORT FIELDS=(15,6,ZD,A) OUTFIL FNAMES=USA, HEADER2=(5:Parts Completion Report for USA,2/, 5:Printed on ,DATE, at ,TIME=(12:),3/, 5:Part ,20:Completed,35: Value ($),/, 5:------,20:---------,35:------------), OUTREC=(5:15,6,ZD,M11, 20:3,4,ZD,M12,LENGTH=9, 35:38,8,ZD,M18,LENGTH=12, 132:X) OUTFIL FNAMES=FRANCE, HEADER2=(5:Parts Completion Report for France,2/, 5:Printed on ,DATE=(DM4/), at ,TIME,3/, 5:Part ,20:Completed,35: Value (F),/, 5:------,20:---------,35:------------), OUTREC=(5:15,6,ZD,M11, 20:3,4,ZD,M16,LENGTH=9, 35:38,8,ZD,M22,LENGTH=12, 132:X) OUTFIL FNAMES=DENMARK, HEADER2=(5:Parts Completion Report for Denmark,2/, 5:Printed on ,DATE=(DMY-), at ,TIME=(24.),3/, 5:Part ,20:Completed,35: Value (kr),/, 5:------,20:---------,35:------------), OUTREC=(5:15,6,ZD,M11, 20:3,4,ZD,M13,LENGTH=9, 35:38,8,ZD,M19,LENGTH=12, 132:X)

This example illustrates how reports for three different countries can be produced from sorted fixed-length input records. The reports differ only in the way that date, time, and numeric formats are specified: 1. The first OUTFIL statement produces a report that has the date, time, and numeric formats commonly used in the United States.
Chapter 3. Using DFSORT Program Control Statements

345

OUTFIL Control Statements

2. The second OUTFIL statement produces a report that has the date, time, and numeric formats commonly used in France. 3. The third OUTFIL statement produces a report that has the date, time, and numeric formats commonly used in Denmark. Of course, any one of the three reports can be produced by itself using a single OUTFIL statement instead of three OUTFIL statements. (This may be necessary if you are sorting character data according to a specified locale for that country.) The FNAMES parameter specifies the ddname (USA, FRANCE, DENMARK) associated with the fixed-length data set for that report. The HEADER2 parameter specifies the page header to appear at the top of each page for that report, which will consist of: v A line of text identifying the report. Note that all English text in the report can be replaced by text in the language of that country. v A blank line (2/). v A line of text showing the date and time. Note that variations of the DATE, DATE=(abcd), TIME, and TIME=(abc) operands are used to specify the date and time in the format commonly used in that country. v Two blank lines (3/). v Two lines of text showing headings for the columns of data. Note that the appropriate currency symbol can be included in the text. The OUTREC parameter specifies the three columns of data to appear for each input record as follows: v A 6-byte edited numeric value produced by transforming the ZD value in bytes 15 through 20 according to the pattern specified by M11. M11 is a pattern for showing integers with leading zeros. v A 9-byte (LENGTH=9) edited numeric value produced by transforming the ZD value in bytes 3 through 6 according to the pattern for integer values with thousands separators commonly used in that country. M12 uses a comma for the thousands separator. M16 uses a blank for the thousands separator. M13 uses a period for the thousands separator. v A 12-byte (LENGTH=12) edited numeric value produced by transforming the ZD value in bytes 38 through 45 according to the pattern for decimal values with thousands separators and decimal separators commonly used in that country. M18 uses a comma for the thousands separator and a period for the decimal separator. M22 uses a blank for the thousands separator and a comma for the decimal separator. M19 uses a period for the thousands separator and a comma for the decimal separator. Table 43 on page 264 shows the twenty-seven pre-defined edit masks (M0-M26) from which you can choose. 132:X is used at the end of the OUTREC parameter to ensure that the data records are longer than the report records. This will result in an LRECL of 132 for the fixed-length OUTFIL data sets (1 byte for the ANSI control character and 131 bytes for the data). The three reports might look as follows:

346

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Parts Completion Report for USA Printed on 03/25/05 at 01:56:20 pm Part -----000310 001184 029633 192199 821356 Completed --------562 1,234 35 3,150 233 Value ($) -----------8,317.53 23,456.78 642.10 121,934.65 2,212.34

Parts Completion Report for France Printed on 25/03/2005 at 13:56:20 Part -----000310 001184 029633 192199 821356 Completed --------562 1 234 35 3 150 233 Value (F) -----------8 317,53 23 456,78 642,10 121 934,65 2 212,34

Parts Completion Report for Denmark Printed on 25-03-05 at 13.56.20 Part -----000310 001184 029633 192199 821356 Completed --------562 1.234 35 3.150 233 Value (kr) -----------8.317,53 23.456,78 642,10 121.934,65 2.212,34

Example 4
SORT FIELDS=(3,10,A,16,13,A),FORMAT=CH OUTFIL FNAMES=WEST, INCLUDE=(42,6,CH,EQ,CWest), HEADER1=(5/,18: Western Region,3/, 18:Profit and Loss Report,3/, 18: for ,&DATE,3/, 18: Page,&PAGE), OUTREC=(6:16,13,24:31,10,ZD,M5,LENGTH=20,75:X), SECTIONS=(3,10,SKIP=P, HEADER3=(2:Division: ,3,10,5X,Page:,&PAGE,2/, 6:Branch Office,24: Profit/(Loss),/, 6:-------------,24:--------------------), TRAILER3=(6:=============,24:====================,/, 6:Total,24:TOTAL=(31,10,ZD,M5,LENGTH=20),/, 6:Lowest,24:MIN=(31,10,ZD,M5,LENGTH=20),/, 6:Highest,24:MAX=(31,10,ZD,M5,LENGTH=20),/, 6:Average,24:AVG=(31,10,ZD,M5,LENGTH=20),/, 3/,2:Average for all Branch Offices so far:, X,SUBAVG=(31,10,ZD,M5))), TRAILER1=(8:Page ,&PAGE,5X,Date: ,&DATE,5/, 8:Total Number of Branch Offices Reporting: , COUNT,2/, 8:Summary of Profit/(Loss) for all, Western Division Branch Offices,2/, 12:Total:, 22:TOTAL=(31,10,ZD,M5,LENGTH=20),/,
Chapter 3. Using DFSORT Program Control Statements

347

OUTFIL Control Statements

12:Lowest:, 22:MIN=(31,10,ZD,M5,LENGTH=20),/, 12:Highest:, 22:MAX=(31,10,ZD,M5,LENGTH=20),/, 12:Average:, 22:AVG=(31,10,ZD,M5,LENGTH=20))

This example illustrates how a report can be produced with a header and trailer page and sections of columns of data, from a sorted subset of fixed-length input records. The FNAMES parameter specifies the ddname (WEST) associated with the fixed-length data set for the report. The INCLUDE parameter specifies the records to be selected for the report. The HEADER1 parameter specifies the report header to appear as the first page of the report, which will consist of five blank lines (5/) followed by four lines of text, each separated by 2 blank lines (3/). The last two lines of text will show the date (&DATE) and page number (&PAGE), respectively. The OUTREC parameter specifies the two columns of data to appear for each selected input record as follows: v The character string from bytes 16 through 28 of the input record. v A 20-byte (LENGTH=20) edited numeric value produced by transforming the ZD value in bytes 31 through 40 according to the pattern specified by M5. The SECTIONS parameter specifies the section break field (3,10), page ejects between sections (SKIP=P), the header (HEADER3) to appear before each section and the trailer (TRAILER3) to appear after each section. The section header will consist of a line of text showing the page number, a blank line (2/) and two lines of text showing the headings for the columns of data. The section trailer will consist of a line of text separating the data from the trailer, lines of text showing the total (TOTAL), minimum (MIN), maximum (MAX) and average (AVG) for the data in the section as edited numeric values, two blank lines, and a line of text showing the running average (SUBAVG) for all of the data records in the report up to this point. The TRAILER1 parameter specifies the report trailer to appear as the last page of the report, which will consist of a line of text showing the page and date, four blank lines (5/), a text line showing the count of data records in the report, a blank line, a line of text, a blank line, and lines of text showing the total, minimum maximum and average for all of the data in the report as edited numeric values. 75:X is used at the end of the OUTREC parameter to ensure that the data records are longer than the report records. This will result in an LRECL of 76 for the fixed-length OUTFIL data set (1 byte for the ANSI control character and 75 bytes for the data). The report might look as follows:

348

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Western Region Profit and Loss Report for 08/20/05 Page 1

Division:

Chips

Page:

Branch Office ------------Gilroy Los Angeles Morgan Hill Oakland San Francisco San Jose San Martin ============= Total Lowest Highest Average

Profit/(Loss) -------------------554,843.42 (22,340.14) 987,322.32 234,124.32 (32,434.31) 1,232,133.35 889,022.03 ==================== 3,842,670.99 (32,434.31) 1,232,133.35 548,952.99 548,952.99

Average for all Branch Offices so far:

Division:

Ice Cream

Page:

Branch Office ------------Marin Napa San Francisco San Jose San Martin ============= Total Lowest Highest Average

Profit/(Loss) -------------------542,341.23 857,342.83 922,312.45 (234.55) 1,003,467.30 ==================== 3,325,229.26 (234.55) 1,003,467.30 665,045.85 597,325.02

Average for all Branch Offices so far:

Chapter 3. Using DFSORT Program Control Statements

349

OUTFIL Control Statements

Division:

Pretzels

Page:

Branch Office ------------Marin Morgan Hill Napa San Francisco San Jose San Martin ============= Total Lowest Highest Average

Profit/(Loss) -------------------5,343,323.44 843,843.40 5,312,348.56 5,412,300.05 1,234,885.34 (2,343.82) ==================== 18,144,356.97 (2,343.82) 5,412,300.05 3,024,059.49 1,406,236.51

Average for all Branch Offices so far:

Page

Date:

08/20/05

Total Number of Branch Offices Reporting:

18

Summary of Profit/(Loss) for all Western Division Branch Offices Total: Lowest: Highest: Average: 25,312,257.22 (32,434.31) 5,412,300.05 1,406,236.51

Example 5
SORT FIELDS=(6,5,CH,A) OUTFIL FNAMES=STATUS, HEADER2=(1:CPAGE ,&PAGE,C OF STATUS REPORT FOR ,&DATE,2/, 6:CITEM ,16:CSTATUS ,31:CPARTS,/, 6:C-----,16:C------------,31:C-----), OUTREC=(1,4, 10:6,5, 20:14,1,CHANGE=(12, C1,CSHIP, C2,CHOLD, C3,CTRANSFER), NOMATCH=(C*CHECK CODE*), 37:39,1,BI,M10, 120:X)

This example illustrates how a report can be produced with a page header and columns of data from sorted variable-length input records, using a lookup table. The FNAMES parameter specifies the ddname (STATUS) associated with the variable-length data set for the report. The HEADER2 parameter specifies the page header to appear at the top of each page, which will consist of a line of text showing the page number (&PAGE) and date (&DATE), a blank line (2/), and two lines of text showing headings for the columns of data. The OUTREC parameter specifies the RDW and three columns of data to appear for each input record as follows (remember that byte 5 is the first byte of data for variable-length records):

350

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

v The character string from bytes 6 through 10 of the input record v A character string produced by finding a match for byte 14 of the input record in the table defined by CHANGE (lookup and change). NOMATCH indicates the character string to be used if byte 14 does not match any of the entries in the CHANGE table. v An edited numeric value produced by transforming the BI value in byte 39 according to the pattern specified by M10. With variable-length input records, you must account for the RDW when specifying the c: values for OUTREC, but not for headers or trailers. The 1: used for the first line of HEADER2 causes it to start in the first data byte (by contrast, 5: must be used to specify the first OUTREC data byte for variable-length records). Also, because 6: is used for the ITEM heading, 10: must be used for the ITEM data to get the heading and data to line up in columns. 120:X is used at the end of the OUTREC parameter to ensure that the data records are longer than the report records. This will result in a maximum LRECL of 121 for the variable-length OUTFIL data set (1 byte for the ANSI control character and a maximum of 120 bytes for the data). The first page of the printed report might start as follows:
PAGE ITEM ----00082 00123 00300 10321 12140 1 OF STATUS REPORT FOR 07/18/05 STATUS -----------HOLD SHIP *CHECK CODE* TRANSFER SHIP PARTS ----36 106 95 18 120

Example 6
OPTION OUTFIL OUTFIL OUTFIL COPY FNAMES=(A1,A2,A3),SPLIT FNAMES=(B1,B2,B3),SPLITBY=25 FNAMES=(C1,C2,C3),SPLIT1R=25

This example illustrates different ways to split 77 input records among three OUTFIL data sets. The first OUTFIL statement uses SPLIT to rotate the records among the three OUTFIL data sets one record at a time. A1 will have records 1, 4, ...,76. A2 will have records 2, 5, ...,77. A3 will have records 3, 6, ...,75. A1 will have 26 records. A2 will have 26 records. A3 will have 25 records. A1, A2 and A3 will each have non-contiguous records. The second OUTFIL statement uses SPLITBY=25 to rotate the records among the three OUTFIL data sets 25 records at a time. B1 will have records 1-25 and 76-77. B2 will have records 26-50. B3 will have records 51-75. B1 will have 27 records. B2 will have 25 records. B3 will have 25 records. B1 will have non-contiguous records. B2 and B3 will have contiguous records. The third OUTFIL statement uses SPLIT1R=25 to rotate the records once among the three OUTFIL data sets 25 records at a time. C1 will have records 1-25. C2 will

Chapter 3. Using DFSORT Program Control Statements

351

OUTFIL Control Statements

have records 26-50. C3 will have records 51-77. C1 will have 25 records. C2 will have 25 records. C3 will have 27 records. C1, C2 and C3 will have contiguous records.

Example 7
OPTION OUTFIL OUTFIL OUTFIL OUTFIL OUTFIL COPY FNAMES=RANGE1,ENDREC=1000000 FNAMES=RANGE2,STARTREC=1000001,ENDREC=2000000 FNAMES=RANGE3,STARTREC=2000001,ENDREC=3000000 FNAMES=RANGE4,STARTREC=3000001,ENDREC=4000000 FNAMES=(RANGE5,EXTRA),STARTREC=4000001

This example illustrates how specific ranges of output records can be written to different output data sets. A typical application might be database partitioning. The first 1 million records will be written to the data set associated with RANGE1, the second million to RANGE2, the third million to RANGE3, and the fourth million to RANGE4. The remaining records will be written to both the data set associated with RANGE5 and the data set associated with EXTRA (SAVE or STARTREC=4000001 will accomplish the same purpose in this case). Note that the INCLUDE, OMIT, and SAVE parameters of OUTFIL can also be used to select records to be written to different output data sets, based on criteria you specify.

Example 8
OPTION COPY,Y2PAST OUTFIL FNAMES=Y4, OUTREC=(1,19, 21,2,PD0,M11,C/, transform mm 22,2,PD0,M11,C/, transform dd 20,2,Y2P, transform yy to yyyy 24,57)

This example illustrates how to transform an existing data set with a packed decimal date field of the form Pyymmdd (X0yymmddC) in bytes 20-23 into a new data set with a character date field of the form Cmm/dd/yyyy in bytes 20-29. yy represents the two-digit year, yyyy represents the four-digit year, mm represents the month, dd represents the day, and C represents a positive sign. The input data set has an LRECL of 80 and the Y4 data set will have an LRECL of 86. The Y2PAST=26 option sets the century window to be used to transform two-digit years into four-digit years. If the current year is 2006, the century window will be 1980 to 2079. Using this century window, the input and output fields might be as follows:
Input Field (HEX) 20 | 0020505F 0950823C 0980316C 0000316F Output Field (CH) 20 | 05/05/2002 08/23/1995 03/16/1998 03/16/2000

352

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Example 9
OPTION COPY,Y2PAST=1996 OUTFIL FNAMES=SPCL, OUTREC=(1,14, copy positions 1-14 15,6,Y2T, transform yy to yyyy - allow blanks 21,20) copy positions 21 - 40

This example illustrates how to transform an existing data set with a character date field of the form Cyymmdd and blank special indicators in bytes 15-20, into a new date set with a character date field of the form Cyyyymmdd and blank special indicators in bytes 15-22. The input data set has an LRECL of 40 and the SPCL data set will have an LRECL of 42. The Y2PAST=1996 option sets the century window to 1996-2095. The century window will be used to transform the two-digit years into four-digit years, but will not be used for the special blank indicators. The input records might be as follows:
MORGAN HILL SAN JOSE BOCA RATON DENVER 960512 000628 951115 CA CA FL CO

The output records would be as follows:

MORGAN HILL SAN JOSE BOCA RATON DENVER 19960512 20000628 20951115 CA CA FL CO

Example 10
OPTION COPY OUTFIL FNAMES=ALL,OUTREC=(CUS ,1,10,C CWW ,1,10,C OUTFIL FNAMES=(US,WW),SPLIT, OUTREC=(1,10,C is 1,10,C is is in ,11,15,/, is in ,26,20,2/) in ,11,15,/, in ,26,20)

This example illustrates how multiple OUTFIL output and blank records can be produced from each OUTFIL input record. The input data set has an LRECL of 50 and contains the following three records:
Finance San Francisco Buenos Aires Research New York Amsterdam Marketing Los Angeles Mexico City

The first OUTFIL statement creates the data set associated with ddname ALL. This data set will have an LRECL of 40 (the length of the longest output record; the one that includes the 26,20 input field). Each input record will result in two data records followed by two blank records as follows: ALL data set
US Finance WW Finance US Research WW Research is in San Francisco is in Buenos Aires is in New York is in Amsterdam

Chapter 3. Using DFSORT Program Control Statements

353

OUTFIL Control Statements

US Marketing is in Los Angeles WW Marketing is in Mexico City

The second OUTFIL statement creates the two data sets associated with ddnames US and WW. These data sets will have an LRECL of 37 (the length of the longest output record; the one that includes the 26,20 input field). Each input record will result in two data records. SPLIT will cause the first data record to be written to the US data set and the second data record to be written to the WW data set. Thus, each input record will create one record in each OUTFIL data set as follows: US data set
Finance is in San Francisco Research is in New York Marketing is in Los Angeles

WW data set
Finance is in Buenos Aires Research is in Amsterdam Marketing is in Mexico City

Example 11
SORT FIELDS=(6,3,CH,D) OUTFIL FNAMES=SET60,BUILD=(1,60),VLFILL=C OUTFIL FNAMES=VARFIX,VTOF,BUILD=(5,20,5X,28,20),VLFILL=C*

This example illustrates how variable-length records that are too short to contain all OUTFIL BUILD fields can be processed successfully. The input data set has RECFM=VB and LRECL=80. The records in this data set have lengths that vary from 15 bytes to 75 bytes. The first OUTFIL statement creates the data set associated with ddname SET60. This data set will have RECFM=VB and LRECL=60. Every record in this data set will have a length of 60. The 1,60 field truncates records longer than 60 bytes to 60 bytes. Because VLFILL=C is specified, the 1,60 field pads records shorter than 60 bytes to 60 bytes using a blank (C ) as the fill byte. Note: Without VLFILL=byte, this OUTFIL statement would terminate with an ICE218A message because some of the input records are too short to contain the BUILD field. The second OUTFIL statement creates the data set associated with ddname VARFIX. This data set will have RECFM=FB and LRECL=45. VTOF changes the variable-length input records to fixed-length output records according to the fields specified by BUILD. VLFILL=C* allows short input records to be processed. Each missing byte in an OUTFIL BUILD field is replaced with an asterisk (C*) fill byte. Notes: 1. CONVERT can be used instead of VTOF. 2. VLFILL=C* overrides the default of VLFILL=X'40' for VTOF or CONVERT.

354

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Example 12
OPTION COPY OUTFIL OUTREC=(SEQNUM,4,BI,Z,8,5,ZD,TO=PD,Z, 31,2,PD,TO=FI,LENGTH=2),Z, 16,3,ZD,ADD,+1,TO=FI,LENGTH=2,Z, (16,3,ZD,MAX,31,2,PD),MUL,+2,TO=ZD,LENGTH=4)

This example illustrates how a sequence number can be generated, how values in one numeric format can be converted to another numeric format, and how arithmetic expressions involving fields and decimal constants can be used. The input data set has an LRECL of 50 and the SORTOUT data set will have an LRECL of 19. The OUTFIL statement creates output records with the following fields: v A binary sequence number in bytes 1-4 that starts at 1 and increments by 1. v X00 in byte 5. v A PD field in bytes 6-8 containing the converted ZD field from input bytes 8-12 v X00 in position 9. v An FI field in bytes 10-11 containing the converted PD field from input bytes 31-32. v X00 in position 12. v An FI field in bytes 13-14 containing the converted result of the ZD field from input bytes 16-18 incremented by 1. v X00 in position 15. v A ZD field in bytes 16-19 containing the converted result of the maximum of the ZD field from input bytes 16-18 and the PD field from input bytes 31-32, multiplied by 2.

Example 13
SORT FIELDS=COPY OUTFIL FNAMES=VAROUT1,FTOV OUTFIL FNAMES=VAROUT2,FTOV, OUTREC=(20,8,35,10) OUTFIL FNAMES=VAROUT3,FTOV,VLTRIM=X40

This example illustrates several ways to convert a fixed-length record data set to a variable-length record data set using the FTOV parameter of OUTFIL. The input data set has an RECFM=FB and LRECL=60. v The first OUTFIL statement converts the fixed-length input data set to a variable-length OUTFIL data set associated with ddname VAROUT1. VAROUT1 will have RECFM=VB and LRECL=64. All of its records will be 64 bytes long (4-byte RDW plus 60-byte input record). v The second OUTFIL statement converts the fixed-length input data set to a variable-length OUTFIL data set associated with ddname VAROUT2. OUTREC is used to select two input fields for the output records, bytes 20-27 and bytes 35-44. VAROUT2 will have RECFM=VB and LRECL=22. All of its records will be 22 bytes long (4-byte RDW plus 8-byte input field plus 10-byte input field). v The third OUTFIL statement converts the fixed-length input data set to a variable-length OUTFIL data set associated with ddname VAROUT3. VAROUT3 will have RECFM=VB and LRECL=64. VLTRIM=X40 is used to remove the

Chapter 3. Using DFSORT Program Control Statements

355

OUTFIL Control Statements

trailing blanks from the variable-length output records. The records can vary from 5 bytes long to 64 bytes long depending on the number of trailing blanks in each record.

Example 14
OPTION OUTFIL OUTFIL OUTFIL COPY FNAMES=OUT1,OUTREC=(DATE1(/),X,TIME1(:),X,1,80) FNAMES=OUT2,OUTREC=(DATE2P,TIME3P,1,80) FNAMES=OUT3,OUTREC=(DATE3(.),X,TIME2,X,1,80)

This example illustrates several different ways to insert timestamps into your records. The input data set has RECFM=FB and LRECL=80. The first OUTFIL statement creates the data set associated with ddname OUT1. This data set will have LRECL=100. Each output record will have a timestamp consisting of the date and time of the run in the form Cyyyy/mm/dd hh:mm:ss (20 bytes), followed by the original input record (80 bytes). The second OUTFIL statement creates the data set associated with ddname OUT2. This data set will have LRECL=86. Each output record will have a timestamp consisting of the date of the run in the form Pyyyymm (4 bytes) and the time of the run in the form Phh (2 bytes), followed by the original input record (80 bytes). The third OUTFIL statement creates the data set associated with ddname OUT3. This data set will have LRECL=94. Each output record will have a timestamp consisting of the date and time of the run in the form Cyyyy.ddd hhmm (14 bytes), followed by the original input record (80 bytes).

Example 15
OPTION COPY OUTREC FIELDS=(1,4,11,4,DT1,7,4,TM1,60:X) OUTFIL NODETAIL, TRAILER1=(//, 3:Earliest SMF timestamp is , MIN=(5,14,ZD,EDIT=(TTTT/TT/TT TT:TT:TT)),/, 3:Latest SMF timestamp is MAX=(5,14,ZD,EDIT=(TTTT/TT/TT TT:TT:TT)))

This example illustrates how the earliest and latest timestamps from a set of SMF records can be displayed. The OUTREC statement uses the DT1 format to convert the SMF date in input bytes 11-15 to a Zyyyymmdd value in bytes 5-12, and uses the TM1 format to convert the SMF time in input bytes 7-10 to a Zhhmmss value in bytes 13-18. The OUTFIL statement uses the Zyyyymmddhhmmss value created by OUTREC in bytes 5-18 to determine the minimum (earliest) and maximum (latest) timestamp, and displays those timestamps in a trailer record in the form Cyyyy/mm/dd hh:mm:ss. The report might look as follows:
Earliest SMF timestamp is 2001/01/09 10:27:04 Latest SMF timestamp is 2001/04/24 06:13:22

356

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

Example 16
SORT FIELDS=(1,20,BI,A) OUTFIL FNAMES=FUPPER,OUTREC=(1,80,TRAN=LTOU) OUTFIL FNAMES=FHEX,OUTREC=(1,80,HEX) OUTFIL FNAMES=FTR,OUTREC=(1,80,TRAN=ALTSEQ) ALTSEQ CODE=(005C)

This example illustrates three types of conversion for fixed length records: lowercase to uppercase conversion, hex conversion, and conversion using an ALTSEQ table. The input data set has RECFM = FB and LRECL = 80. The first OUTFIL statement creates the data set associated with ddname FUPPER. This data set will have RECFM = FB and LRECL = 80. All of the lowercase EBCDIC characters (a-z) from byte 1 to byte 80 will be converted to uppercase EBCDIC characters (A-Z). Other characters will remain unchanged. For example, the characters san jose, ca 95193 will be converted to SAN JOSE, CA 95193. The second OUTFIL statement creates the data set associated with ddname FHEX. This data set will have RECFM = FB and LRECL = 160 (2 * 80 data bytes). Each byte from 1 to 80 will be converted to the two bytes representing its hex value. For example, the three characters A12 will be converted to the six characters C1F1F2. The third OUTFIL statement creates the data set associated with ddname FTR. This data set will have RECFM = FB and LRECL = 80. Each binary zero (X00) from byte 1 to byte 80 will be converted to an * (X5C). Other characters will remain unchanged. Note: The ALTSEQ table is not used for the SORT field because its format is BI and not AQ.

Example 17
OPTION OUTFIL OUTFIL OUTFIL ALTSEQ COPY FNAMES=VUPPER,OUTREC=(1,4,5,TRAN=UTOL) FNAMES=VHEX,OUTREC=(1,4,5,HEX) FNAMES=VTR,OUTREC=(1,4,5,TRAN=ALTSEQ) CODE=(F040,5C40)

This example illustrates three types of conversion for variable-length records: uppercase to lowercase conversion, hex conversion, and conversion using an ALTSEQ table. The input data set has RECFM = VB and LRECL = 5000. The first OUTFIL statement creates the data set associated with ddname VUPPER. This data set will have RECFM = VB and LRECL = 5000. All of the uppercase EBCDIC characters (A-Z) from bytes 5 (after the RDW) to the end of each record will be converted to lowercase EBCDIC characters (a-z). Other characters will remain unchanged. For example, the characters SAN JOSE, CA 95193 will be converted to san jose, ca 95193. The second OUTFIL statement creates the data set associated with ddname VHEX. This data set will have RECFM = VB and LRECL = 9996 (4 for RDW plus 2 * 4996 data bytes). Each byte from 5 (after the RDW) to the end of each record will be converted to the two bytes representing its hex value. For example, the three characters A12 will be converted to the six characters C1F1F2.
Chapter 3. Using DFSORT Program Control Statements

357

OUTFIL Control Statements

The third OUTFIL statement creates the data set associated with ddname VTR. This data set will have RECFM = VB and LRECL = 5000. Each 0 (XF0) and * (X5C) character from bytes 5 (after the RDW) to the end of each record will be converted to a space (X40). Other characters will remain unchanged.

Example 18
SORT FIELDS=(22,8,CH,A) OUTFIL FNAMES=SAMP1,REMOVECC,HEADER1=(Sample 1,2/), STARTREC=120,SAMPLE=(20,4), OUTREC=(1,8,9,5,PD,ZD,C***,14,50) OUTFIL FNAMES=SAMP2,REMOVECC,HEADER1=(Sample 2,2/), SAMPLE=1000,ENDREC=5001

This example illustrates how to take different samples of sorted output records. Sorted records 120, 121, 122, 123, 140, 141, 142, 143, and so on will be reformatted as indicated by the OUTREC parameter and written to the output data set associated with SAMP1. The heading Sample 1 will appear before the sample output records. Sorted records 1, 1001, 2001, 3001, 4001 and 5001 will be written to the output data set associated with SAMP2. The heading Sample 2 will appear before the sample output records.

Example 19
OPTION COPY OUTFIL FNAMES=R500,REPEAT=500 OUTFIL FNAMES=R100,OUTREC=(SEQNUM,4,ZD,80XFF),REPEAT=100

This example illustrates how one record can be used to generate many records. The first OUTFIL statement writes each output record 500 times to the data set associated with R500. Each set of 500 records will be identical. The second OUTFIL statement writes each reformatted output record 100 times to the data set associated with R100. Each set of 100 records will be identical except for the sequence number. The 100 records written from the first output record will have sequence numbers 1-100, the 100 records written from the second output record will have sequence numbers 101-200, and so on.

Example 20
OPTION COPY OUTFIL OMIT=(56,6,CH,EQ,C******), OVERLAY=(121:SEQNUM,8,ZD,56:56,6,TRAN=UTOL)

This example illustrates how you can use the OVERLAY parameter with OUTFIL to add sequence numbers at the end of your records, and to convert uppercase EBCDIC characters to lowercase EBCDIC characters in certain columns, without affecting the rest of the record. The input data set has RECFM=FB and LRECL=120. The output data set will have RECFM=FB and LRECL=128. The OMIT parameter removes records which have asterisks in positions 56-61. 121:SEQNUM,8,ZD in the OVERLAY parameter adds an 8-byte sequence number in positions 121-128 of every record. The LRECL is increased from 120 to 128 to hold the sequence number.

358

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

56:56,6,TRAN=UTOL in the OVERLAY parameter converts uppercase EBCDIC characters in positions 56-61 to lowercase EBCDIC characters in positions 56-61. Only the two overlaid fields are changed; all of the other data in the records is unaffected.

Example 21
OPTION COPY OUTFIL FNAMES=RPT1, HEADER2=(1:Type,9:Date,21:Time,/, 1:----,9:--------,21:------), IFTHEN=(WHEN=(5,2,BI,EQ,X'0001'), BUILD=(1,4,5:5,2,BI,M11,LENGTH=4, 13:8,4,DT1,25:15,4,TM1)), IFTHEN=(WHEN=(5,2,BI,EQ,X'0002'), BUILD=(1,4,5:5,2,BI,M11,LENGTH=4, 13:12,8,DC1,25:12,8,TC1)), IFTHEN=(WHEN=(5,2,BI,EQ,X'0003'), BUILD=(1,4,5:5,2,BI,M11,LENGTH=4, 13:17,8,DE1,25:17,8,TE1)), IFTHEN=(WHEN=NONE, BUILD=(1,4,5:5,2,BI,M11,LENGTH=4, 13:Cn/a,25:Cn/a)) OUTFIL FNAMES=RPT2, HEADER2=(1:Type,9:Date,21:Time,/, 1:----,9:-------,21:--------), IFTHEN=(WHEN=(5,2,BI,EQ,X'0001'), BUILD=(1,4,5:5,2,BI,M11,LENGTH=4, 13:8,4,DT3,25:15,4,TM4)), IFTHEN=(WHEN=(5,2,BI,EQ,X'0002'), BUILD=(1,4,5:5,2,BI,M11,LENGTH=4, 13:12,8,DC3,25:12,8,TC4)), IFTHEN=(WHEN=(5,2,BI,EQ,X'0003'), BUILD=(1,4,5:5,2,BI,M11,LENGTH=4, 13:17,8,DE3,25:17,8,TE4)), IFTHEN=(WHEN=NONE, BUILD=(1,4,5:5,2,BI,M11,LENGTH=4, 13:Cn/a,25:Cn/a))

This example illustrates how you can use IFTHEN clauses to reformat different records in different ways. The input data set has RECFM=VB and consists of several different types of input records as follows: v Type1: Has X'0001' in positions 5-6, a 4-byte SMF date in positions 8-11 and a 4-byte SMF time in positions 15-18. v Type2: Has X'0002' in positions 5-6 and an 8byte TOD date and time in positions 1219. v Type3: Has X'0003' in positions 5-6 and an 8byte ETOD date and time in positions 1724. v Other types: Do not have X'0001', X'0002' or X'0003' in positions 5-6, and do not have a date or time value. The first OUTFIL statement produces a report with RECFM=VBA and LRECL=31 that might look like this:
Type ---0001 0003 Date -------20040827 20040907 Time -----124531 230603

Chapter 3. Using DFSORT Program Control Statements

359

OUTFIL Control Statements

0008 0002 0001 0004 n/a 20040901 20040731 n/a n/a 061559 152201 n/a

The first IFTHEN clause operates only against Type1 records; it converts the SMF date using DT1 and the SMF time using TM1. The second IFTHEN clause only operates against Type2 records; it converts the TOD date using DC1 and the TOD time using TC1. The third IFTHEN clause only operates against Type3 records; it converts the ETOD date using DE1 and the ETOD time using TE1. The fourth IFTHEN clause operates against all other types of records; it uses n/a for the date and time. The second OUTFIL statement produces a report with RECFM=VBA and LRECL=33 that looks like this:
Type ---0001 0003 0008 0002 0001 0004 Date ------2004240 2004251 n/a 2004245 2004213 n/a Time -------12453184 23060373 n/a 06155903 15220150 n/a

The first IFTHEN clause operates only against Type1 records; it converts the SMF date using DT3 and the SMF time using TM4. The second IFTHEN clause operates only against Type2 records; it converts the TOD date using DC3 and the TOD time using TC4. The third IFTHEN clause operates only against Type3 records; it converts the ETOD date using DE3 and the ETOD time using TE4. The fourth IFTHEN clause operates against all other types of records; it uses n/a for the date and time.

Example 22
OPTION COPY OUTFIL BUILD=(1,80,SQZ=(SHIFT=LEFT,PAIR=APOST,MID=C,))

This example illustrates how you can create FB output records with comma separated values from FB input records containing fields in fixed positions. The 80-byte FB input records might look like this:
John Lewis Ted Blank Marilyn Carlson Rex Otis -12.83 +128.37 -282.83 +2.83 Research Manufacturing Technical Support Marketing

Note that the data has three fields in fixed positions. The first field is a character string surrounded by apostrophes. The second field is a numeric value. The third field is another character string surrounded by apostrophes. The 80-byte FB output records are in the form of comma separated values as follows:
John Lewis,-12.83,Research Ted Blank,+128.37,Manufacturing Marilyn Carlson,-282.83,Technical Support Rex Otis,+2.83,Marketing

We use OUTFIL BUILD to build the output records with comma separated values. We use SQZ to squeeze out the blanks between the fields, shift the remaining

360

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

characters to the left and insert commas between the fields. SHIFT=LEFT shifts the characters to the left. PAIR=APOST ensures that blanks within paired apostrophes are not squeezed out (for example, we want to keep the blank in the John Lewis field.) MID=C, inserts a comma for each group of blanks removed between the fields (for example, between John Lewis and -12.83).

Example 23
OPTION COPY OUTFIL IFTHEN=(WHEN=INIT, OVERLAY=(5:5,18,JFY=(SHIFT=LEFT,LEAD=C,TRAIL=C), 34:34,19,JFY=(SHIFT=LEFT,LEAD=C,TRAIL=C))), IFTHEN=(WHEN=INIT, BUILD=(1,4,5,60,SQZ=(SHIFT=LEFT,PAIR=APOST,MID=C,))), VLTRIM=C

This example illustrates how you can create VB output records with comma separated values from VB input records containing fields in fixed positions. The 84-byte VB input records might look like this (4-byte RDW followed by data):
Length 45 50 54 51 | Data John Lewis Ted Blank Marilyn Carlson Rex Otis -12.83 +128.37 -282.83 +2.83 Research Manufacturing Technical Support Marketing

Note that the data has three fields in fixed positions. The first field is a character string. The second field is a numeric value. The third field is another character string. (In the previous example, the character strings were surrounded by apostrophes; in this example the apostrophes must be added around the character strings.) The 84-byte VB output records are in the form of comma separated values as follows:
Length 34 39 49 32 | Data John Lewis,-12.83,Research Ted Blank,+128.37,Manufacturing Marilyn Carlson,-282.83,Technical Support Rex Otis,+2.83,Marketing

We use OUTFIL IFTHEN to ensure that short records are padded on the right with blanks. (OUTFIL BUILD would terminate due to the short records.) WHEN=INIT reformats every record. OVERLAY surrounds the character strings with apostrophes. BUILD builds the output records with comma separated values. We use JFY to surround the character strings with apostrophes without removing embedded blanks (for example, John Lewis is changed to John Lewis). After the first IFTHEN, the records look like this:
Length 52 52 54 52 | Data John Lewis Ted Blank Marilyn Carlson Rex Otis -12.83 +128.37 -282.83 +2.83 Research Manufacturing Technical Support Marketing

We then use SQZ to squeeze out the blanks between the fields, shift the remaining characters to the left and insert commas between the fields. SHIFT=LEFT shifts the characters to the left. PAIR=APOST ensures that blanks within paired apostrophes are not squeezed out (for example, we want to keep the blank in the John Lewis field.) MID=C, inserts a comma for each group of blanks removed between the fields (for example, between John Lewis and -12.83).
Chapter 3. Using DFSORT Program Control Statements

361

OUTFIL Control Statements

Finally, we use VLRTIM=C to remove trailing blanks at the end of each VB record by adjusting its length appropriately.

Example 24
OPTION COPY OUTFIL REMOVECC, HEADER1=(C<?xml version="1.0"?>,/, 3:C<booklist>), BUILD=(5:C<book>,/, 7:1,20,JFY=(SHIFT=LEFT,LEAD=C<title>,TRAIL=C</title>, LENGTH=36),/, 7:24,15,SQZ=(SHIFT=LEFT,LEAD=C<author>,MID=C, , TRAIL=C</author>,LENGTH=33),/, 5:C</book>), TRAILER1=(3:C</booklist>)

This example illustrates how you can generate XML statements from FB input records containing fields in fixed positions. The 40-byte FB input records might look like this:
Modern Poetry Intro to Computers Marketing Friedman KR Chatterjee CL Maxwell G

Note that the data has three character fields in fixed positions. The 42-byte FB output records look like this:
<?xml version="1.0"?> <booklist> <book> <title>Modern Poetry</title> <author>Friedman, KR</author> </book> <book> <title>Intro to Computers</title> <author>Chatterjee, CL</author> </book> <book> <title>Marketing</title> <author>Maxwell, G</author> </book> </booklist>

We use OUTFIL HEADER1 to generate the xml and booklist starting tags that precede the set of tags for each record. We use OUTFIL BUILD to generate the set of tags for each record as follows: v A constant is used to generate the book starting tag. v JFY is used to generate the title tags and data from the first input field. LEAD generates the title starting tag before the input field from the record. TRAIL generates the title ending tag after the last nonblank character from the input field. JFY keeps embedded blanks between the first nonblank character and the last nonblank character of the input field. LENGTH ensures that the addition of the LEAD and TRAIL strings does not cause truncation by increasing the output length to 36 bytes (overriding the default of 20 bytes from the input field). v SQZ is used to generate the author tags and data from the second and third input fields. LEAD generates the author starting tag before the input field from the record. MID replaces the blanks between the second and third input fields with a comma and one blank. TRAIL generates the author ending tag after the last nonblank character from the input fields. LENGTH ensures that the addition

362

z/OS V1R10.0 DFSORT Application Programming Guide

OUTFIL Control Statements

of the LEAD, MID and TRAIL strings does not cause truncation by increasing the output length to 33 bytes (overriding the default of 15 bytes from the input field). We use OUTFIL TRAILER1 to generate the booklist ending tag that follows the set of tags for each record.

Example 25
OPTION COPY OUTFIL HEADER2=(1:First,13:Initial,22:Last,37:Score,/, 1:10-,13:7-,22:11-,35:7-), PARSE=(%00=(STARTAFT=CLAST-> ,ENDBEFR=C ,FIXLEN=11), %01=(STARTAFT=CFIRST-> ,ENDBEFR=C ,FIXLEN=11), %02=(STARTAFT=CINITIAL-> ,ENDBEFR=C ,FIXLEN=7), %03=(STARTAFT=CSCORE-> ,FIXLEN=7)), BUILD=(1:%01,13:%02,22:%00, 35:%03,SFF,EDIT=(SIIIT.T),SIGNS=(,-))

This example illustrates how you can create a report from FB input records with variable position/length fields, such as keyword delimited values. The 70-byte input records might look like this:
LAST-> Clark FIRST-> Oscar INITIAL-> D SCORE-> +98.2 LAST-> Roberts FIRST-> Harriet INITIAL-> SCORE-> -152.6 LAST-> Stein FIRST-> Gertrude INITIAL-> V SCORE-> +5.1

Note that each record has four variable fields each identified by a specific keyword. The fields do not start and end in the same position in every record and they have different lengths in different records. The output report has RECFM=FBA and LRECL=42 and looks like this:
First ---------Oscar Harriet Gertrude Initial Last Score ------- ----------- ------D Clark 98.2 Roberts -152.6 V Stein 5.1

In order to create a report like this from variable position/length fields, we use HEADER2 to create the page header, and PARSE and BUILD to create a fixed parsed field from each variable field. We use %00 to create an 11-byte fixed parsed field with the extracted LAST-> value. We use %01 to create an 11-byte fixed parsed field with the extracted FIRST-> value. We use %02 to create a 7-byte fixed parsed field with the extracted INITIAL-> value. We use %03 to create a 7-byte fixed parsed field with the extracted SCORE-> value. Since the fourth field (%03) is extracted as signed and padded on the right with blanks, we treat it as SFF format in order to edit it.

Example 26
INREC IFTHEN=(WHEN=INIT, PARSE=(%1=(FIXLEN=10,STARTAFT=CFirst=",ENDBEFR=C"))), IFTHEN=(WHEN=INIT, PARSE=(%2=(FIXLEN=10,STARTAFT=CMiddle=",ENDBEFR=C"))), IFTHEN=(WHEN=INIT, PARSE=(%3=(FIXLEN=10,STARTAFT=CLast=",ENDBEFR=C"))), IFTHEN=(WHEN=INIT, PARSE=(%4=(FIXLEN=10,STARTAFT=CWife=",ENDBEFR=C")), BUILD=(%1,13:%2,25:%3,37:%4))

Chapter 3. Using DFSORT Program Control Statements

363

OUTFIL Control Statements

SORT FIELDS=(25,10,CH,A,1,10,CH,A,13,10,CH,A) OUTFIL HEADER2=(First,13:Middle, 25:CLast,37:Wife,/,10C-,13:10C-, 25:10C-,37:10C-)

This example illustrates how you can create a sorted report from FB input records with keyword values that can occur in any order or not occur at all. The 80-byte input records might look like this:
Last="Buchanan" First="James" Wife="Louisa" First="John" Middle="Quincy" Last="Adams" First="George" Last="Washington" Wife="Martha" Last="Clinton" Wife="Hillary" Middle="Jefferson" First="William" First="John" Wife="Abigail" Last="Adams"

Note that each record has up to four variable fields each identified by a specific keyword (First, Middle, Last, Wife). In each record, the fields can be in any order, do not start and end in the same position and can have different lengths. We want to sort the records by last name, first name and middle name, and create a report with fixed headings and values for the first name, middle name, last name and wifes name that looks like this:
First ---------John John James William George Middle Last ---------- ---------Adams Quincy Adams Buchanan Jefferson Clinton Washington Wife ---------Abigail Louisa Hillary Martha

In order to extract and sort variable fields like these, we use a separate IFTHEN PARSE clause for each keyword. This allows us to find a particular keyword anywhere in the record or ignore it if it is not in the record. If we used PARSE instead of IFTHEN PARSE, a missing keyword would cause any keywords that followed to be ignored. But because each IFTHEN PARSE starts scanning at position 1 by default, we can look for each keyword independently of the others. If a keyword is missing, the parsed field is set to all blanks (for example, %2 and %4 are set to blanks for the James Buchanan record). We use %1 to create a 10-byte fixed parsed field into which we extract the first name. We use %2 to create a 10-byte fixed parsed field into which we extract the middle name. We use %3 to create a 10-byte fixed parsed field into which we extract the last name. We use %4 to create a 10-byte fixed parsed field into which we extract the wifes name. We use BUILD to reformat the records to contain the fixed parsed fields. Then we SORT on the fixed parsed fields. Finally, we use OUTFIL to create the headings.

364

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

OUTREC Control Statement

, OUTREC PARSE=( definition ) , ( , OVERLAY=( , item ) item )

FIELDS= BUILD=

IFTHEN=(clause) IFOUTLEN=n

The OUTREC control statement allows you to reformat the input records after they are sorted, merged or copied. The OUTREC control statement supports a wide variety of parsing, editing, and 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. For variable fields, such as delimited fields, comma separated values (CSV), tab separated values, blank separated values, keyword separated fields, null-terminated strings (and many other types), you define rules that allow DFSORT to extract the relevant data into fixed parsed fields, and then use the parsed fields as you would use fixed fields. v Insertion of blanks, zeros, strings, current date, future date, past date, current time, sequence numbers, decimal constants, and the results of arithmetic expressions before, between, and after the input fields in the reformatted records. v Sophisticated conversion capabilities, such as hexadecimal display, conversion of EBCDIC letters from lowercase to uppercase or uppercase to lowercase, conversion of characters using the ALTSEQ translation 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 and shift right). v Sophisticated editing capabilities, such as control of the way numeric fields are presented with respect to length, leading or suppressed zeros, thousands separators, decimal points, leading and trailing positive and negative signs, and so on. Twenty-seven pre-defined editing masks are available for commonly used numeric editing patterns, encompassing many of the numeric notations used throughout the world. In addition, a virtually unlimited number of numeric editing patterns are available via the user-defined editing masks. v Transformation of SMF, TOD, and ETOD date and time values to more usable forms.

Chapter 3. Using DFSORT Program Control Statements

365

OUTREC Control Statement

v Transformation of various forms of two-digit year dates to various forms of four-digit year dates using a specified fixed or sliding century window. v Selection of a character constant, hexadecimal constant, or input field from a lookup table, based on a character, hexadecimal, or bit string as input (that is, lookup and change). You can create the reformatted OUTREC records in one of the following three ways using unedited, edited, or converted input fields (p,m for fixed fields, or %nn for parsed fields - see PARSE), and a variety of constants: v BUILD or FIELDS: Reformat each record by specifying all of its items one by one. Build gives you complete control over the items you want in your reformatted OUTREC records and the order in which they appear. You can delete, rearrange and insert fields and constants. Example:
OUTREC BUILD=(1,20,CABC,26:5C*, 15,3,PD,EDIT=(TTT.TT),21,30,80:X)

v OVERLAY: Reformat each record by specifying just the items that overlay specific columns. Overlay lets you change specific existing columns without affecting the entire record. Example:
OUTREC OVERLAY=(45:45,8,TRAN=LTOU)

v IFTHEN clauses: Reformat different records in different ways by specifying how build or overlay items are applied to records that meet given criteria. IFTHEN clauses let you use sophisticated conditional logic to choose how different record types are reformatted. Example:
OUTREC IFTHEN=(WHEN=(1,5,CH,EQ,CTYPE1), BUILD=(1,40,C**,+1,TO=PD)), IFTHEN=(WHEN=(1,5,CH,EQ,CTYPE2), BUILD=(1,40,+2,TO=PD,XFFFF)), IFTHEN=(WHEN=NONE),OVERLAY=(45:CNONE))

You can choose to include any or all of the following items in your reformatted OUTREC records: v Fixed position/length fields or variable position/length fields. For fixed 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, null-terminated strings (and many other types), you define rules that allow DFSORT to extract the relevant data into fixed parsed fields, and then use the parsed fields as you would use fixed fields. v Blanks, binary zeros, character strings, and hexadecimal strings v Current date, future date, past date and current time in various forms v Unedited input fields aligned on byte, halfword, fullword, and doubleword boundaries v Hexadecimal representations of binary input fields v Left-justified, right-justified, left-squeezed, or right-squeezed input fields. v Numeric input fields of various formats converted to different numeric formats, or to character format edited to contain signs, thousands separators, decimal points, leading zeros or no leading zeros, and so on. v Decimal constants converted to different numeric formats, or to character format edited to contain signs, thousands separators, decimal points, leading zeros or no leading zeros, and so on. v The results of arithmetic expressions combining fields, decimal constants, operators (MIN, MAX, MUL, DIV, MOD, ADD and SUB) and parentheses

366

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

converted to different numeric formats, or to character format edited to contain signs, thousands separators, decimal points, leading zeros or no leading zeros, and so on. SMF, TOD and ETOD date and time fields converted to different numeric formats, or to character format edited to contain separators, leading zeros or no leading zeros, and so on. Two-digit year input dates of various formats converted to four-digit year dates in different numeric formats, or to character format edited to contain separators, leading zeros or no leading zeros, and so on. Sequence numbers in various formats. A character constant, hexadecimal constant or input field selected from a lookup table, based on a character, hexadecimal or bit constant as input.

v v

For information concerning the interaction of INREC and OUTREC, see INREC Statement Notes on page 147 and OUTREC Statement Notes on page 386. See OUTFIL Control Statements on page 221 for complete details on the OUTFIL OUTREC parameter. PARSE

, , PARSE=( %nn= %= ( FIXLEN=m ABSPOS=p ADDPOS=x SUBPOS=y , STARTAFT=string STARTAFT=BLANKS STARTAT=string STARTAT=BLANKS STARTAT=NONBLANK , ENDBEFR=string ENDBEFR=BLANKS ENDAT=string ENDAT=BLANKS PAIR=APOST PAIR=QUOTE ) )

This operand allows you to extract variable position/length fields into fixed parsed fields. Parsed fields (%nn) can be used where fixed position/length fields (p,m) can be used in the BUILD (or FIELDS) or OVERLAY operands as described later in this section. PARSE can be used for many different types of variable fields including delimited fields, comma separated values (CSV), tab separated values, blank separated values, keyword separated fields, null-terminated strings, and so on. You can assign up to 100 %nn parsed fields (%00-%99) to the variable fields you want to extract.
Chapter 3. Using DFSORT Program Control Statements

367

OUTREC Control Statement

Note that if all of the fields in your records have fixed positions and lengths, you dont need to use PARSE. But if any of the fields in your records have variable positions or lengths, you can use PARSE to treat them as fixed parsed fields in BUILD or OVERLAY. You can mix p,m fields (fixed fields) and %nn fields (parsed fields) in BUILD and OVERLAY. See PARSE under OUTFIL Control Statements for complete details. Sample Syntax:
OUTREC PARSE=(%00=(ENDBEFR=C*,FIXLEN=3), %01=(ENDBEFR=BLANKS,FIXLEN=6), %02=(STARTAT=CMAX,FIXLEN=8), %03=(STARTAFT=C(,ENDBEFR=C),FIXLEN=6), %04=(STARTAFT=BLANKS,FIXLEN=5)), BUILD=(%03,X,%03,HEX,21:%02,31:%01,SFF,M26,LENGTH=7, 18,6,%00,UFF,M11,LENGTH=3,%04,JFY=(SHIFT=RIGHT))

Default for PARSE: None; must be specified. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. FIELDS or BUILD

368

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

, FIELDS= BUILD= ( c: s p,m ,a %nn p p,m,HEX %nn,HEX p,HEX p,m,TRAN=LTOU %nn,TRAN=LTOU p,TRAN=LTOU p,m,TRAN=UTOL %nn,TRAN=UTOL p,TRAN=UTOL p,m,TRAN=ALTSEQ %nn,TRAN=ALTSEQ p,TRAN=ALTSEQ p,m,Y2x %nn,Y2x p,m,Y2x(c) %nn,Y2x(c) p,m,Y2xP %nn,Y2xP p,m,f ,edit %nn,f ,to (p,m,f) (%nn,f) deccon ,edit (deccon) ,to arexp ,edit (arexp) ,to p,m,Y2x ,edit ,to %nn,Y2x ,edit ,to p,m,lookup %nn,lookup p,m,justify %nn,justify p,m,squeeze %nn,squeeze seqnum )

Specifies all of the items in the reformatted OUTREC record in the order in which they are to be included. The reformatted OUTREC record consists of the separation fields, edited and unedited input fields (p,m for fixed fields, or %nn for parsed fields - see PARSE), edited decimal constants, edited results of arithmetic expressions, and sequence numbers you select, in the order in which you select them, aligned on the boundaries or in the columns you indicate. For variable-length records, the first item in the BUILD or FIELDS parameter must specify or include the unedited 4-byte record descriptor word (RDW), that is, you must start with 1,m with m equal to or greater than 4. If you want to include the bytes from a specific position to the end of each input record at the end of each reformatted output record, you can specify that starting position (p) as the last item in the BUILD or FIELDS parameter. For example:
Chapter 3. Using DFSORT Program Control Statements

369

OUTREC Control Statement

OUTREC FIELDS=(1,4, 1,2,BI,TO=ZD,LENGTH=5, C|, 5) unedited RDW display RDW length in decimal | separator display input positions 5 to end

For fixed-length records, the first input and output data byte starts at position 1. For variable-length records, the first input and output data byte starts at position 5, after the RDW in positions 1-4. The BUILD or FIELDS parameter of the OUTREC statement differs from the BUILD or OUTREC parameter of the OUTFIL statement in the following ways: v The BUILD or FIELDS parameter of the OUTREC statement applies to all input records; the BUILD or OUTREC parameter of the OUTFIL statement only applies to the OUTFIL input records for its OUTFIL group. v The BUILD or OUTREC parameter of the OUTFIL statement supports the slash (/) separator for creating blank records and new records; the BUILD or FIELDS parameter of the OUTREC statement does not. c: specifies the position (column) for a separation field, input field decimal constant, arithmetic expression, or sequence number, relative to the start of the reformatted output record. Unused space preceding the specified column is padded with EBCDIC blanks. The following rules apply: v c must be a number between 1 and 32752. v c: must be followed by a separation field, input field, decimal constant, or arithmetic expression. v c must not overlap the previous input field or separation field in the reformatted output record. v For variable-length records, c: must not be specified before the first input field (the record descriptor word) nor after the variable part of the input record. v The colon (:) is treated like the comma (,) or semicolon (;) for continuation to another line. See Table 25 on page 130 for examples of valid and invalid column alignment. s specifies that a separation field (blanks, zeros, character string, hexadecimal string, current date, future date, past date, or current time) is to appear in the reformatted output record. It can be specified before or after any input field. Consecutive separation fields may be specified. For variable-length records, separation fields must not be specified before the first input field (the record descriptor word) or after the variable part of the input record. Permissible values are nX, nZ, nCxx...x, nXyy...yy, and various date and time constants. nX Blank separation. n bytes of EBCDIC blanks (X'40') are to appear in the reformatted output records. n can range from 1 to 4095. If n is omitted, 1 is used. See Table 26 on page 131 for examples of valid and invalid blank separation. nZ Binary zero separation. n bytes of binary zeros (X'00') are to appear in the reformatted output records. n can range from 1 to 4095. If n is omitted, 1 is used. See Table 27 on page 131 for examples of valid and invalid binary zero separation. nCxx...x Character string separation. n repetitions of the character

370

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

string constant (Cxx...x) are to appear in the reformatted output records. n can range from 1 to 4095. If n is omitted, 1 is used. x can be any EBCDIC character. You can specify from 1 to 256 characters. If you want to include a single apostrophe in the character string, you must specify it as two single apostrophes:
Required: ONEILL Specify: CONEILL

See Table 28 on page 131 for examples of valid and invalid character string separation. nX'yy...yy' Hexadecimal string separation. n repetitions of the hexadecimal string constant (X'yy...yy') are to appear in the reformatted output records. n can range from 1 to 4095. If n is omitted, 1 is used. The value yy represents any pair of hexadecimal digits. You can specify from 1 to 256 pairs of hexadecimal digits. See Table 29 on page 132 for examples of valid and invalid hexadecimal string separation. DATEn, DATEn(c), DATEnP Constant for current date. The date of the run is to appear in the reformatted output records. See DATEn, DATEn(c), DATEnP under OUTFIL OUTREC for details. &DATEn, &DATEn(c), &DATEnP can be used instead of DATEn, DATEn(c), and DATEnP, respectively. DATEn+r, DATEn(c)+r, DATEnP+r Constant for future date. A future date relative to the current date of the run is to appear in the reformatted output records. See DATEn+r, DATEn(c)+r, DATEnP+r under OUTFIL OUTREC for details. &DATEn+r, &DATEn(c)+r, &DATEnP+r can be used instead of DATEn+r, DATEn(c)+r, and DATEnP+r, respectively. DATEn-r, DATEn(c)-r, DATEnP-r Constant for past date. A past date relative to the current date of the run is to appear in the reformatted output records. See DATEn-r, DATEn(c)-r, DATEnP-r under OUTFIL OUTREC for details. &DATEn-r, &DATEn(c)-r, &DATEnP-r Can be used instead of DATEn-r, DATEn(c)-r, and DATEnP-r, respectively TIMEn, TIMEn(c), TIMEnP Constant for current time. The time of the run is to appear in the reformatted output records. See TIMEn, TIMEn(c), TIMEnP under OUTFIL OUTREC for details. &TIMEn, &TIMEn(c), &TIMEnP Can be used instead of TIMEn, TIMEn(c), and TIMEnP, respectively. DATE specifies that the current date is to appear in the
Chapter 3. Using DFSORT Program Control Statements

371

OUTREC Control Statement

reformatted output records in the form mm/dd/yy. See DATE under OUTFIL OUTREC for details. &DATE can be used instead of DATE.

DATE=(abcd) specifies that the current date is to appear in the reformatted output records in the form adbdc. See DATE=(abcd) under OUTFIL OUTREC for details. &DATE=(abcd) can be used instead of DATE=(abcd). DATENS=(abc) specifies that the current date is to appear in the reformatted output records in the form abc. See DATENS=(ab) under OUTFIL OUTREC for details. &DATENS=(abc) can be used instead of DATENS=(abc). YDDD=(abc) specifies that the current date is to appear in the reformatted output records in the form acb. See YDDD=(abc) under OUTFIL OUTREC for details. can be used instead of YDDD=(abc). YDDDNS=(ab) specifies that the current date is to appear in the reformatted output records in the form ab. See YDDDNS=(ab) under OUTFIL OUTREC for details. &YDDDNS=(ab) can be used instead of YDDDNS=(ab). TIME specifies that the current time is to appear in the reformatted output records in the form hh:mm:ss. See TIME under OUTFIL OUTREC for details. can be used instead of TIME. specifies that the current time is to appear in the reformatted output records in the form hhcmmcss (24-hour time) or hhcmmcss xx (12-hour time). See TIME=(abc) under OUTFIL OUTREC for details.

&YDDD=(abc)

&TIME TIME=(abc)

&TIME=(abc) can be used instead of TIME=(abc). TIMENS=(ab) specifies that the current time is to appear in the reformatted output record in the form hhmmss (24-hour time) or hhmmss xx (12-hour time). See TIMENS=(ab) under OUTFIL OUTREC for details. &TIMENS=(ab) can be used instead of TIMENS=(ab). p,m,a specifies that an unedited input field is to appear in the reformatted output record. p specifies the first byte of the input field relative to the beginning of the

372

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

input record.12 The first data byte of a fixed-length record has relative position 1. The first data byte of a variable-length record has relative position 5, because the first four bytes are occupied by the RDW. All fields must start on a byte boundary, and no field may extend beyond byte 32752. See OUTREC Statement Notes on page 386 for special rules concerning variable-length records. m specifies the length of the input field. It must include the sign if the data is signed and must be a whole number of bytes. See OUTREC Statement Notes on page 386 for more information. a specifies the alignment (displacement) of the input field in the reformatted output record relative to the start of the reformatted output record. The permissible values of a are: H Halfword aligned. The displacement (p-1) of the field from the beginning of the reformatted input record, in bytes, is a multiple of 2 (that is, position 1, 3, 5, and so forth). F Fullword aligned. The displacement is a multiple of 4 (that is, position 1, 5, 9, and so forth).

D Doubleword aligned. The displacement is a multiple of 8 (that is, position 1, 9, 17, and so forth). Alignment can be necessary if, for example, the data is to be used in a COBOL application program where items are aligned through the SYNCHRONIZED clause. Unused space preceding aligned fields are always padded with binary zeros. %nn specifies that an unedited parsed input field is to appear in the reformatted output record. See PARSE for details of parsed fields. See p,m,a for further details. Note that alignment (H, F, D) is not permitted for %nn fields (for example, %nn,F results in an error message and ermination). p | | specifies that the unedited part of the variable input record (that part beyond the minimum record length), is to appear in the reformatted output record, as the last field. p without m can only be used for variable-length records; not for fixed-length records. Attention: If the reformatted input record includes only the RDW and the variable part of the input record, null records containing only an RDW may result. A value must be specified for p that is less than or equal to the minimum record length (RECORD statement L4 value) plus 1 byte. p,m,HEX specifies that the hexadecimal representation of an input field is to appear in the reformatted output record. See p,m,HEX under OUTFIL OUTREC for details. %nn,HEX specifies that the hexadecimal representation of a parsed input field is to appear in the reformatted output record. See PARSE for details of parsed fields. See p,m,HEX for further details.

12. If INREC is specified, p must refer to the record as reformatted by INREC. If your E15 user exit reformats the record, and INREC is not specified, p must refer to the record as reformatted by your E15 user exit. Chapter 3. Using DFSORT Program Control Statements

373

OUTREC Control Statement

p,HEX specifies that the hexadecimal representation of the variable part of the input record (that part beyond the minimum record length), is to appear in the reformatted output record, as the last field. p,HEX can only be used for variable-length records; not for fixed-length records. See p,HEX under OUTFIL OUTREC for details. p,m,TRAN=LTOU specifies that lowercase EBCDIC letters (that is, a-z) in an input field are to appear as uppercase EBCDIC letters (that is, A-Z) in the reformatted output record. See p,m,TRAN=LTOU under OUTFIL OUTREC for details. %nn,TRAN=LTOU specifies that lowercase EBCDIC letters (that is, a-z) in a parsed input field are to appear as uppercase EBCDIC letters (that is, A-Z) in the reformatted output record. See PARSE for details of parsed fields. See p,m,TRAN=LTOU for further details. p,TRAN=LTOU specifies that lowercase EBCDIC letters (that is, a-z) in the variable part of the input record (that part beyond the minimum record length), are to appear as uppercase EBCDIC letters (that is, A-Z) in the reformatted output record, as the last field. p,TRAN=LTOU can only be used for variable-length records; not for fixed-length records. See p,TRAN=LTOU under OUTFIL OUTREC for details. p,m,TRAN=UTOL specifies that uppercase EBCDIC letters (that is, A-Z) in an input field are to appear as lowercase EBCDIC letters (that is, a-z) in the reformatted output record. See p,m,TRAN=UTOL under OUTFIL OUTREC for details. %nn,TRAN=UTOL specifies that uppercase EBCDIC letters (that is, A-Z) in a parsed input field are to appear as lowercase EBCDIC letters (that is, a-z) in the reformatted output record. See PARSE for details of parsed fields. See p,m,TRAN=UTOL for further details. p,TRAN=UTOL specifies that uppercase EBCDIC letters (that is, A-Z) in the variable part of the input record (that part beyond the minimum record length), are to appear as lowercase EBCDIC letters (that is, a-z) in the reformatted output record, as the last field. p,TRAN=UTOL can only be used for variable-length records; not for fixed-length records. See p,TRAN=UTOL under OUTFIL OUTREC for details. p,m,TRAN=ALTSEQ specifies that the characters in an input field are to be changed according to the ALTSEQ translation table in effect in the reformatted output record. See p,m,TRAN=ALTSEQ under OUTFIL OUTREC for details. %nn,TRAN=ALTSEQ specifies that the characters in a parsed input field are to be changed according to the ALTSEQ translation table in effect in the reformatted output record. See PARSE for details of parsed fields. See p,m,TRAN=ALTSEQ for further details. p,TRAN=ALTSEQ specifies that the characters in the variable part of the input record (that part beyond the minimum record length), are to be changed according to the ALTSEQ translation table in effect in the reformatted output record, as the last field. p,TRAN=ALTSEQ can only be used for variable-length records; not for fixed-length records. See p,TRAN=ALTSEQ under OUTFIL OUTREC for

| |

| |

| |

| |

374

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

details.
Sample Syntax: Fixed input records OUTREC FIELDS=(1:5,10,15:8C0, 25:20,15,TRAN=LTOU,80:X) Variable input records OUTREC FIELDS=(1,4,C RDW=,1,4,HEX,C FIXED=, 5,20,HEX,C VARIABLE=,21,HEX)

p,m,Y2x specifies that the four-digit year CH date representation of a two-digit year input date field is to appear in the reformatted output record. Real dates are transformed using the century window established by the Y2PAST option in effect. The century window is not used for special indicators; they are just expanded appropriately (for example, p,6,Y2T transforms C000000 to C00000000). See p,m,Y2x under OUTFIL OUTREC for details. Sample Syntax:
OUTREC FIELDS=(21,3,Y2V,X,12,5,Y2W)

%nn,Y2x specifies that the four-digit year CH date representation of a two-digit year parsed input date field is to appear in the reformatted output record. See PARSE for details of parsed fields. See p,m,Y2x for further details. p,m,Y2x(c) specifies that the four-digit CH date representation with separators of a two-digit year input date field is to appear in the reformatted output record. Real dates are transformed using the century window established by the Y2PAST option in effect. The century window is not used for special indicators; they are just expanded appropriately (for example, p,6,Y2T(/) transforms C000000 to C0000/00/00). See p,m,Y2x(c) under OUTFIL OUTREC for details. Sample Syntax:
OUTREC FIELDS=(25,6,Y2T(-),X,14,2,Y2U(/))

%nn,Y2x(c) specifies that the four-digit year CH date representation with separators of a two-digit year parsed input date field is to appear in the reformatted output record. See PARSE for details of parsed fields. See p,m,Y2x(c) for further details. p,m,Y2xP specifies that the four-digit year PD date representation of a two-digit year input date field is to appear in the reformatted output record. Real dates are transformed using the century window established by the Y2PAST option in effect. The century window is not used for special indicators; they are just expanded appropriately (for example, p,6,Y2TP transforms C000000 to P00000000). See p,m,Y2xP under OUTFIL OUTREC for details. Sample Syntax:
OUTREC FIELDS=(11,3,Y2XP,X,21,4,Y2WP)

%nn,Y2xP specifies that the four-digit year PD date representation of a two-digit year

Chapter 3. Using DFSORT Program Control Statements

375

OUTREC Control Statement

parsed input date field is to appear in the reformatted output record. See PARSE for details of parsed fields. See p,m,Y2xP for further details. p,m,f,edit or (p,m,f),edit specifies that an edited numeric input field is to appear in the reformatted output record. You can edit BI, FI, PD, PD0, ZD, FL, CSF, FS, UFF, SFF, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3 or TM4 fields using either pre-defined edit masks (M0-M26) or specific edit patterns you define. You can control the way the edited fields look with respect to length, leading or suppressed zeros, thousands separators, decimal points, leading and trailing positive and negative signs, and so on. See p,m,f,edit under OUTFIL OUTREC for details. Sample Syntax:
OUTREC FIELDS=(5:(21,8,ZD),M19,X,46,5,ZD,M13, 31:35,4,FL,SIGNS=(,,+,-),LENGTH=10, 51:8,4,PD,EDIT=(**II,IIT.TTXS),SIGNS=(,,+,-))

%nn,f,edit or (%nn,f),edit specifies that an edited numeric parsed input field is to appear in the reformatted output record. See PARSE for details of parsed fields. See p,m,f,edit or (p,m,f),edit for further details. p,m,f,to or (p,m,f),to specifies that a converted numeric input field is to appear in the reformatted output record. You can convert BI, FI, PD, PD0, ZD, FL, CSF, FS, UFF, SFF, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3, or TM4 fields to BI, FI, PD, PDC, PDF, ZD, ZDF, ZDC, CSF, or FS fields. See p,m,f,to under OUTFIL OUTREC for details. Sample Syntax:
OUTREC FIELDS=(21,4,BI,TO=PDF,X,8,4,ZD,FI,LENGTH=2)

%nn,f,to or (%nn,f),to specifies that a converted numeric parsed input field is to appear in the reformatted output record. See PARSE for details of parsed fields. See p,m,f,to or (p,m,f),to for further details. deccon,edit or (deccon),edit specifies that an edited decimal constant is to appear in the reformatted output record. The decimal constant must be in the form +n or n where n is 1 to 31 decimal digits. The sign (+ or ) must be specified. A decimal constant produces a signed, 31-digit zoned decimal (ZD) result to be edited as specified. See deccon,edit under OUTFIL OUTREC for details. Sample Syntax:
OUTREC FIELDS=(-5000,EDIT=(-T,TT.T),21:(+0),M11,LENGTH=7)

deccon,to or (deccon),to specifies that a converted decimal constant is to appear in the reformatted output record. The decimal constant must be in the form +n or n where n is 1 to 31 decimal digits. The sign (+ or ) must be specified. A decimal constant produces a signed, 31-digit zoned decimal (ZD) result to be converted as specified. See deccon,to under OUTFIL OUTREC for details. Sample Syntax:

376

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

OUTREC FIELDS=(+1,PD,LENGTH=6,(-1),PD,LENGTH=6, -50,TO=ZD,LENGTH=8)

arexp,edit or (arexp),edit specifies that the edited result of an arithmetic expression is to appear in the reformatted output record. The arithmetic expression can consist of input fields, decimal constants, operators and parentheses. An arithmetic expression produces a signed, 31-digit zoned decimal (ZD) result to be edited as specified. See arexp,edit under OUTFIL OUTREC for details. Sample Syntax:
OUTREC FIELDS=(C**,27,2,FI,SUB, 83,4,PD,EDIT=(STTTTTTT),SIGNS=(+,-), 25:(((15,5,ZD,MUL,+2),ADD,+100),MAX,62,2,PD),M25,LENGTH=12)

arexp,to or (arexp),to specifies that the converted result of an arithmetic expression is to appear in the reformatted output record. The arithmetic expression can consist of input fields, decimal constants, operators and parentheses. An arithmetic expression produces a signed, 31-digit zoned decimal (ZD) result to be converted as specified. See arexp,to under OUTFIL OUTREC for details. Sample Syntax:
OUTREC FIELDS=((15,6,FS,DIV,+5),ADD,(-1,ADD,36,6,FS),TO=FI,X, 3,2,FI,MAX,-6,LENGTH=4,TO=FS)

p,m,Y2x,edit specifies that an edited four-digit year CH date representation of a two-digit year input date field is to appear in the reformatted output record. See p,m,Y2x,edit under OUTFIL OUTREC for details. %nn,Y2x,edit specifies that an edited four-digit year CH date representation of a two-digit year parsed input date field is to appear in the reformatted output record. See PARSE for details of parsed fields. See p,m,Y2x,edit for further details. p,m,Y2x,to specifies that a converted four-digit year date representation of a two-digit year input date field is to appear in the reformatted output record. See p,m,Y2x,to under OUTFIL OUTREC for details. %nn,Y2x,to specifies that a converted four-digit year CH date representation of a two-digit year parsed input date field is to appear in the reformatted output record. See PARSE for details of parsed fields. See p,m,Y2x,to for further details p,m,lookup or %nn,lookup specifies that a character constant, hexadecimal constant, input field (p,m) or parsed input field (%nn) from a lookup table is to appear in the reformatted output record. You can use p,m,lookup or %nn,lookup to select a specified character set constant (that is, a character or hexadecimal string) or set field (that is, an input field or parsed input field) based on matching an input value against find constants (that is, character, hexadecimal, or bit constants). See p,m,lookup or %nn,lookup under OUTFIL OUTREC for details. Sample Syntax:

Chapter 3. Using DFSORT Program Control Statements

377

OUTREC Control Statement

OUTREC FIELDS=(11,1, CHANGE=(6, CR,CREAD, CU,CUPDATE, XFF,CEMPTY, CA,CALTER), NOMATCH=(11,6), 4X, 21,1, CHANGE=(10, B.1......,CVSAM, B.0......,CNON-VSAM))

p,m,justify specifies that a left-justified or right-justified input field is to appear in the reformatted output record. For a left-justified field, leading blanks are removed and the characters from the first nonblank to the last nonblank are shifted left, with blanks inserted on the right if needed. For a right-justified field, trailing blanks are removed and the characters from the last nonblank to the first nonblank are shifted right, with blanks inserted on the left if needed. Optionally: v specific leading and trailing characters can be changed to blanks before justification begins v a leading string can be inserted v a trailing string can be inserted v the output length can be changed (its equal to the input length by default) See p,m,justify under OUTFIL OUTREC for details. Sample Syntax:
OUTREC FIELDS=(1,10, 21,20,JFY=(SHIFT=LEFT),5X, 52,12,JFY=(SHIFT=RIGHT,PREBLANK=C+,LEAD=C$,TRAIL=C.00))

%nn,justify specifies that a left-justified or right-justified parsed input field is to appear in the reformatted output record. See PARSE for details of parsed fields. See p,m,justify for further details. p,m,squeeze specifies that a left-squeezed or right-squeezed input field is to appear in the reformatted output record. For a left-squeezed field, all blanks are removed and the characters from the first nonblank to the last nonblank are shifted left, with blanks inserted on the right if needed. For a right-justified field, all blanks are removed and the characters from the last nonblank to the first nonblank are shifted right, with blanks inserted on the left if needed. Optionally: v specific characters can be changed to blanks before squeezing begins v a leading string can be inserted v a trailing string can be inserted v a string (for example, a comma delimiter) can be inserted wherever a group of blanks is removed between the first nonblank and the last nonblank. v blanks can be kept as is between paired apostrophes (AB CD EF) or paired quotes (AB CD EF) v the output length can be changed (its equal to the input length by default) See p,m,squeeze under OUTFIL OUTREC for details. Sample Syntax:
OUTREC FIELDS=(21,20,SQZ=(SHIFT=RIGHT),5X, 152,18,SQZ=(SHIFT=LEFT,PREBLANK=X05, LEAD=CVOL=SER=,MID=C,,PAIR=QUOTE,LENGTH=30))

378

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

%nn,squeeze specifies that a left-squeezed or right-squeezed parsed input field is to appear in the reformatted output record. See PARSE for details of parsed fields. See p,m,squeeze for further details. seqnum specifies that a sequence number is to appear in the reformatted output record. The sequence numbers are assigned in the order in which the records are received for OUTREC processing. You can create BI, PD, ZD, CSF, or FS sequence numbers and control their lengths, starting values and increment values. You can restart the sequence number at the start value each time a specified input field (p,m) or parsed input field (%nn) changes. See seqnum under OUTFIL OUTREC for details. Sample Syntax:
OUTREC FIELDS=(SEQNUM,6,ZD,START=1000,INCR=50,RESTART=(21,5),1,60)

Default for BUILD or FIELDS: None; must be specified. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. OVERLAY

Chapter 3. Using DFSORT Program Control Statements

379

OUTREC Control Statement

, OVERLAY=( c: s p,m ,a %nn p,m,HEX %nn,HEX p,m,TRAN=LTOU %nn,TRAN=LTOU p,m,TRAN=UTOL %nn,TRAN=UTOL p,m,TRAN=ALTSEQ %nn,TRAN=ALTSEQ p,m,Y2x %nn,Y2x p,m,Y2x(c) %nn,Y2x(c) p,m,Y2xP %nn,Y2xP p,m,f ,edit %nn,f ,to (p,m,f) (%nn,f) deccon ,edit (deccon) ,to arexp ,edit (arexp) ,to p,m,Y2x ,edit ,to %nn,Y2x ,edit ,to p,m,lookup %nn,lookup p,m,justify %nn,justify p,m,squeeze %nn,squeeze seqnum )

Specifies each item that is to overlay specific columns in the reformatted record. Columns that are not overlaid remain unchanged. If you want to insert, rearrange, or delete fields, use BUILD or FIELDS rather than OVERLAY. Use OVERLAY only to overlay existing columns or to add fields at the end of every record. OVERLAY can be easier to use then BUILD or FIELDS when you just want to change a few fields without rebuilding the entire record. For fixed-length records, the first input and output data byte starts at position 1. For variable-length records, the first input and output data byte starts at position 5, after the RDW in positions 1-4. Use c: (column) to specify the output positions to be overlaid. If you do not specify c: for the first item, it defaults to 1:. If you do not specify c: for any other item, it starts after the previous item. For example, if you specify:
OUTREC OVERLAY=(25,2,11:CA,15,3,C**)

380

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

Input positions 25-26 are placed at output positions 1-2; CA is placed at output position 11; input positions 15-17 are placed at output positions 12-14; and C** is placed at output positions 15-16. The rest of the record remains unchanged. You can specify items in any order, you can change the same item multiple times and you can overlap output columns. Changes to earlier items affect changes to later items. For example, say you specify:
OUTREC OVERLAY=(21:8,4,ZD,MUL,+10,TO=ZD,LENGTH=6, 5:5,1,TRAN=UTOL, 5:5,1,CHANGE=(1,Ca,CX,Cb,CY),NOMATCH=(5,1))

and input position 5 has A. The second item (UTOL) would change A to a and the third item (CHANGE) would change a again to X. If you specify an OVERLAY item that extends the overlay record beyond the end of the input record, the reformatted record length is automatically increased to that length, and blanks are filled in on the left as needed. For variable-length records, the RDW length is also increased to correspond to the larger reformatted record length after all of the OVERLAY items are processed. For example, if your input record has a length of 40 and you specify:
OUTREC OVERLAY=(16:CABC,51:5C*,35:15,2)

the output record is given a length of 55. Blanks are filled in from columns 41-50. For variable-length records, the length in the RDW is changed from 40 to 55 after all of the OVERLAY items are processed. Missing bytes in specified input fields are replaced with blanks so the padded fields can be processed. The OVERLAY parameter of the OUTREC statement applies to all input records whereas the OVERLAY parameter of the OUTFIL statement only applies to the OUTFIL input records for its OUTFIL group. See OUTREC FIELDS for details of the items listed in the OVERLAY syntax diagram above. You can specify all of the items for OVERLAY in the same way that you can specify them for BUILD or FIELDS with the following exceptions: v You cannot specify p or p,HEX or p,TRAN=value for OVERLAY. v For p,m,H or p,m,F or p,m,D specified for OVERLAY, fields are aligned as necessary without changing the preceding bytes. v For variable-length records, you must not overlay positions 1-4 (the RDW) for OVERLAY, so be sure to specify the first column (c:) as 5 or greater. If you do not specify the first column, it will default to 1: which is invalid for variable-length records with OVERLAY. Whereas FIELDS=(1,m,...) is required, OVERLAY=(1,m) is not allowed since it would overlay the RDW. Sample Syntax: Fixed input records:
OUTREC OVERLAY=(21:21,4,ZD,TO=PD,LENGTH=4, 2:5,8,HEX,45:C*,32,4,C*,81:SEQNUM,5,ZD)

Variable input records:

OUTREC OVERLAY=(5:X0001,28:CDate is ,YDDDNS=(4D), 17:5C*)

Default for OVERLAY: None; must be specified. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741.
Chapter 3. Using DFSORT Program Control Statements

381

OUTREC Control Statement

IFTHEN

, IFTHEN=( WHEN=INIT ,PARSE=(definitions) ,BUILD=(items) ,OVERLAY=(items) WHEN=(logexp) ,PARSE=(definitions) ,BUILD=(items) ,HIT=NEXT ,OVERLAY=(items) WHEN=ANY ,PARSE=(definitions) ,BUILD=(items) ,HIT=NEXT ,OVERLAY=(items) WHEN=NONE ,PARSE=(definitions) ,BUILD=(items) ,OVERLAY=(items) )

IFTHEN clauses allow you to reformat different records in different ways by specifying how build or overlay items are to be applied to records that meet given criteria. IFTHEN clauses let you use simple or complex conditional logic to choose how different record types are reformatted. If you want to insert, rearrange, or delete fields in the same way for every record, use BUILD or FIELDS rather than IFTHEN. If you want to overlay existing columns in the same way for every record, use OVERLAY rather than IFTHEN. Use IFTHEN clauses if you want to insert, rearrange, delete or overlay fields in different ways for different records. You can use four types of IFTHEN clauses as follows: v WHEN=INIT: Use one or more WHEN=INIT clauses to apply build or overlay items to all of your input records. WHEN=INIT clauses are processed before any of the other IFTHEN clauses. v WHEN=(logexp): Use one or more WHEN=(logexp) clauses to apply build or overlay items to your input records that meet specified criteria. A WHEN=(logexp) clause is satisfied when the logical expression evaluates as true. v WHEN=ANY: Use a WHEN=ANY clause after multiple WHEN=(logexp) clauses to apply additional build or overlay items to your input records if they satisfied the criteria for any of the preceding WHEN=(logexp) clauses. v WHEN=NONE: Use one or more WHEN=NONE clauses to apply build or overlay items to your input records that did not meet the criteria for any of the WHEN=(logexp) clauses. WHEN=NONE clauses are processed after any of the other IFTHEN clauses. If you do not specify a WHEN=NONE clause, only the WHEN=INIT changes (if any) are applied to input records that do not meet the criteria for any of the WHEN=(logexp) clauses. IFTHEN clauses are processed in the following order: v WHEN=INIT clauses v WHEN=(logexp) clauses and WHEN=ANY clauses v WHEN=NONE clauses Processing of IFTHEN clauses continues unless one of the following occurs: v A WHEN=(logexp) or WHEN=ANY clause is satisfied, and HIT=NEXT is not specified. v There are no more IFTHEN clauses to process. When processing of IFTHEN clauses stops, the IFTHEN record created so far is used as the output record.

382

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

Example:
OUTREC IFTHEN=(WHEN=(12,1,BI,ALL,X3F),OVERLAY=(18:CYes)), IFTHEN=(WHEN=(35,2,PD,EQ,+14),BUILD=(1,40,45,3,HEX),HIT=NEXT), IFTHEN=(WHEN=(35,2,PD,GT,+17),BUILD=(1,40,41,5,HEX),HIT=NEXT), IFTHEN=(WHEN=ANY,BUILD=(1,55,CABC,70:X)), IFTHEN=(WHEN=(63,2,CH,EQ,CAB),OVERLAY=(18:CNo)), IFTHEN=(WHEN=NONE,BUILD=(1,40,51,8,TRAN=LTOU))

For this example, the IFTHEN clauses are processed as follows: v If IFTHEN clause 1 is satisfied, its overlay item is applied and IFTHEN processing stops. v If IFTHEN clause 1 is not satisfied, its overlay item is not applied and IFTHEN processing continues. v If IFTHEN clause 2 is satisfied, its build items are applied and IFTHEN processing continues. v If IFTHEN clause 2 is not satisfied, its build items are not applied and IFTHEN processing continues. v If IFTHEN clause 3 is satisfied, its build items are applied and IFTHEN processing continues. v If IFTHEN clause 3 is not satisfied, its build items are not applied and IFTHEN processing continues. v If IFTHEN clause 4 is satisfied, its build items are applied and IFTHEN processing stops. v If IFTHEN clause 4 is not satisfied, its build items are not applied and IFTHEN processing continues. v If IFTHEN clause 5 is satisfied, its overlay item is applied and IFTHEN processing stops. v If IFTHEN clause 5 is not satisfied, its overlay item is not applied and IFTHEN processing continues. v If IFTHEN clause 6 is satisfied, its build items are applied and IFTHEN processing stops. v If IFTHEN clause 6 is not satisfied, its build items are not applied and IFTHEN processing stops. All of the IFTHEN clauses operate sequentially on an IFTHEN record. The IFTHEN record is created initially from the input record. Each IFTHEN clause tests and changes the IFTHEN record, as appropriate. Thus, changes made by earlier IFTHEN clauses are seen by later IFTHEN clauses. For example, if you have a 40-byte input record and specify:
OUTREC IFTHEN=(WHEN=INIT,OVERLAY=(8:8,4,ZD,ADD,+1,TO=ZD,LENGTH=4)), IFTHEN=(WHEN=(8,4,ZD,EQ,+27),OVERLAY=(28:CYes)), IFTHEN=(WHEN=NONE,OVERLAY=(28:CNo))

The WHEN=INIT clause adds 1 to the ZD value and stores it in the IFTHEN record. The WHEN=(8,4,ZD,EQ,+27) clause tests the incremented ZD value in the IFTHEN record rather than the original ZD value in the input record. The IFTHEN record is adjusted as needed for the records created or changed by the IFTHEN clauses. For fixed-length records, blanks are filled in on the left as needed. For variable-length records, the RDW length is adjusted as needed each time the IFTHEN record is changed. Missing bytes in specified input fields are replaced with blanks so the padded fields can be processed. DFSORT sets an appropriate LRECL (or reformatted record length if the OUTREC record is further modified) for the output records based on the build
Chapter 3. Using DFSORT Program Control Statements

383

OUTREC Control Statement

and overlay items specified by the IFTHEN clauses. However, DFSORT does not analyze the possible results of WHEN=(logexp) conditions when determining an appropriate LRECL. When you use OUTREC IFTHEN clauses, you can override the OUTREC LRECL determined by DFSORT with the OUTREC IFOUTLEN parameter. If SEQNUM is used in multiple IFTHEN clauses, the sequence number will be incremented for each record that satisfies the IFTHEN clause, that is, a separate SEQNUM counter will be kept for each IFTHEN clause. For example, if your input is:
RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD A B B C A C B D 1 1 2 1 2 2 3 1

and you specify:

OUTREC IFTHEN=(WHEN=(8,1,CH,EQ,CA),OVERLAY=(15:SEQNUM,4,ZD)), IFTHEN=(WHEN=(8,1,CH,EQ,CB),OVERLAY=(16:SEQNUM,4,ZD)), IFTHEN=(WHEN=NONE,OVERLAY=(17:SEQNUM,4,ZD))

your output will be:

RECORD RECORD RECORD RECORD RECORD RECORD RECORD RECORD A B B C A C B D 1 1 2 1 2 2 3 1 0001 0001 0002 0001 0002 0002 0003 0003

Separate SEQNUM counters are kept for the A record, for the B record, and for the NONE records. The IFTHEN clauses of the OUTREC statement apply to all input records whereas the IFTHEN clauses of the OUTFIL statement only apply to the OUTFIL input records for its OUTFIL group. WHEN=INIT clause See WHEN=INIT clause under OUTFIL IFTHEN for details. Note that / cannot be used to create blank records or new records. Sample Syntax:
OUTREC IFTHEN=(WHEN=INIT, BUILD=(1,20,21:CDepartment,31:3X,21,60)), IFTHEN=(WHEN=(5,2,CH,EQ,CD1),OVERLAY=(31:8,3)), IFTHEN=(WHEN=(5,2,CH,EQ,CD2),OVERLAY=(31:12,3))

WHEN=(logexp) clause See WHEN=(logexp) clause under OUTFIL IFTHEN for details. Note that although / can be used create blank records and new records with OUTFIL, it cannot be used with OUTREC. Sample Syntax:
OUTREC IFTHEN=(WHEN=(1,3,CH,EQ,CT01,AND, 18,4,ZD,LE,+2000),OVERLAY=(42:CType1 <= 2000),HIT=NEXT), IFTHEN=(WHEN=(1,3,CH,EQ,CT01,AND,6,1,BI,BO,X03), BUILD=(1,21,42,13)),

384

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

IFTHEN=(WHEN=(1,3,CH,EQ,CT01,AND, 18,4,ZD,GT,+2000),OVERLAY=(42:CType1 > 2000 ),HIT=NEXT), IFTHEN=(WHEN=(1,3,CH,EQ,CT01,AND,6,1,BI,BO,X01), BUILD=(1,25,42,13))

WHEN=ANY clause See WHEN=ANY clause under OUTFIL IFTHEN for details. Note that although / can be used create blank records and new records with OUTFIL, it cannot be used with OUTREC. Sample Syntax:
OUTREC IFTHEN=(WHEN=(1,3,SS,EQ,CT01,T02,T03), BUILD=(CGroup A,X,1,80),HIT=NEXT), IFTHEN=(WHEN=(1,3,SS,EQ,CT04,T05,T06), BUILD=(CGroup B,X,1,80),HIT=NEXT), IFTHEN=(WHEN=(1,3,SS,EQ,CT07,T08,T09,T10), BUILD=(CGroup C,X,1,80),HIT=NEXT), IFTHEN=(WHEN=ANY,OVERLAY=(16:CGroup Found)

WHEN=NONE clause See WHEN=NONE clause under OUTFIL IFTHEN for details. Note that although / can be used create blank records and new records with OUTFIL, it cannot be used with OUTREC. Sample Syntax:
OUTREC IFTHEN=(WHEN=INIT,BUILD=(1,20,21:CDepartment,31:3X,21,60)), IFTHEN=(WHEN=(5,2,CH,EQ,CD1),OVERLAY=(31:8,3)), IFTHEN=(WHEN=(5,2,CH,EQ,CD2),OVERLAY=(31:12,3)), IFTHEN=(WHEN=NONE,OVERLAY=(31:C***))

Default for IFTHEN clauses: None; must be specified. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. IFOUTLEN

IFOUTLEN=n

Overrides the OUTREC LRECL (or reformatted record length if the OUTREC record is further modified) determined by DFSORT from your OUTREC IFTHEN clauses. DFSORT sets an appropriate LRECL for the output records based on the build and overlay items specified by the IFTHEN clauses. However, DFSORT does not analyze the possible results of WHEN=(logexp) conditions when determining an appropriate OUTREC LRECL. When you use OUTREC IFTHEN clauses, you can override the OUTREC LRECL determined by DFSORT with the OUTREC IFOUTLEN parameter. Fixed-length records longer than the IFOUTLEN length are truncated to the IFOUTLEN length. Fixed-length records shorter than the IFOUTLEN are padded with blanks to the IFOUTLEN length. Variable-length records longer than the IFOUTLEN length are truncated to the IFOUTLEN length. n specifies the length to use for the OUTREC LRECL (or for the reformatted record length if the OUTREC record is further modified) . The value for n must be between 1 and 32767, but must not be larger than the maximum LRECL allowed for the RECFM, and must not conflict with the specified or retrieved LRECL for the fixed-length output data set.

Chapter 3. Using DFSORT Program Control Statements

385

OUTREC Control Statement

Sample Syntax:
OUTREC IFOUTLEN=70, IFTHEN=(WHEN=(5,1,CH,EQ,C1,AND,8,3,ZD,EQ,+10), BUILD=(1,40,CT01-GROUP-A,65)), IFTHEN=(WHEN=(5,1,CH,EQ,C2,AND,8,3,ZD,EQ,+12), BUILD=(1,40,CT02-GROUP-B,65))

Default for IFOUTLEN: The LRECL determined from the IFTHEN clauses.

OUTREC Statement Notes

v If input records are reformatted by INREC or E15, OUTREC must refer to fields in the appropriate reformatted record (see INREC Statement Notes on page 147). v When you specify OUTREC, you must be aware of the change in record size and layout of the resulting reformatted output records. v If the SORTOUT LRECL is specified or available, DFSORT will use it even if it does not match the reformatted OUTREC record length; this can cause padding or truncation of the reformatted OUTREC records, or termination. If the SORTOUT LRECL is not specified or available, DFSORT can automatically use the reformatted OUTREC record length as the SORTOUT LRECL, when appropriate. See the discussion of the SOLRF and NOSOLRF options in OPTION Control Statement on page 167 for details. For VSAM data sets, the maximum record size defined in the cluster is equivalent to the LRECL when processing fixed-length records, and is four bytes more than the LRECL when processing variable-length records. See VSAM Considerations on page 15 for more information. v For variable-length records, the first entry in the FIELDS, BUILD, or IFTHEN BUILD parameter must specify or include the unedited 4-byte RDW, that is, the first field must be 1,4 or 1,m with m greater than 4. DFSORT sets the length of the reformatted record in the RDW. If the first field in the data portion of the input record is to appear unedited in the reformatted record immediately following the RDW, the entry in the FIELDS, BUILD, or IFTHEN BUILD parameter can specify both RDW and data field in one. (1,m,...). Otherwise, the RDW must be specifically included in the reformatted record (for example, 1,4,1,4,HEX).. v For variable-length records, OVERLAY or IFTHEN OVERLAY items must not overlay the RDW in bytes 1-4. You must ensure that 1:, 2:, 3: or 4: is not specified or defaulted for any OVERLAY item. Note that the default for the first OVERLAY item is 1:, so you must override it. v With FIELDS, BUILD or IFTHEN BUILD, the variable part of the input record (that part beyond the minimum record length) can be included in the reformatted record as the last part. In this case, a value must be specified for pn that is less than or equal to the minimum record length (RECORD statement L4 value) plus 1 byte, and mn and an must be omitted. For example,
OUTREC FIELDS=(1,8,20C*,9)

With OVERLAY, the variable part of the input record must not be included in the reformatted record. v If INREC with FIELDS or BUILD and OUTREC with FIELDS and BUILD are specified, either both must specify position-only for the last part, or neither must specify position-only for the last part. OVERLAY or IFTHEN, and FIELDS or BUILD, can differ with respect to position-only. See INREC Statement Notes on page 147 for more details. v If the reformatted record includes only the RDW and the variable part of the input record, null records containing only an RDW may result.

386

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

v The reformatted output records are in the format specified by OUTREC regardless of whether INREC was specified. v Fields referenced in OUTREC statements can overlap each other or control fields. v If input is variable records, the output is also variable. This means that each record is given the correct RDW by DFSORT before output. v When OUTREC is specified, your E35 user exit routine must refer to fields in the reformatted output record. v DFSORT issues a message and terminates processing if an OUTREC statement is specified for a tape work data set sort or conventional merge application. v When you specify OUTREC, VLSHRT is not used. If VLSHRT is specified, it is ignored. v If SZERO is in effect, 0 is treated as negative and +0 is treated as positive for edited or converted input fields, decimal constants, and the results of arithmetic expressions. If NOSZERO is in effect, 0 and +0 are treated as positive for edited or converted input fields, decimal constants, and the results of arithmetic expressions. v If SZERO is in effect, -0 compares as less than +0 when numeric fields and constants are used. If NOSZERO is in effect, -0 compares as equal to +0 when numeric fields and constants are used. Note: OPTION SZERO or OPTION NOSZERO is ignored for OUTREC IFTHEN=(WHEN=(logexp),...) unless the OPTION statement is found in a higher source (for example, DFSPARM is a higher source than SYSIN) or before the OUTREC statement in the same source. For example, NOSZERO will be used in both of the following cases: Case 1:
//DFSPARM DD * OPTION COPY,NOSZERO /* //SYSIN DD * OUTREC IFTHEN=(WHEN=(1,2,FS,EQ,+0),OVERLAY=(22:CYes)), IFTHEN=(WHEN=NONE,OVERLAY=(22:CNo )) /*

Case 2:
//SYSIN DD * OPTION COPY,NOSZERO OUTREC IFTHEN=(WHEN=(1,2,FS,EQ,+0),OVERLAY=(28:CA)), IFTHEN=(WHEN=NONE,OVERLAY=(28:CB)) /*

Reformatting Records After Processing Examples

Both INREC and OUTREC can be used to reformat records, either separately or together. The two control statements perform similar functions, although INREC reformats records before sort, merge, or copy processing, whereas OUTREC reformats records after sort, merge, or copy processing. This section shows OUTREC examples. See Reformatting Records Before Processing Examples on page 149 for INREC examples.

Example 1
OUTREC FIELDS=(11,32)

This statement specifies that the output record is to contain 32 bytes beginning with byte 11 of the input record. This statement can be used only with fixed-length input records, because it does not include the first 4 bytes.
Chapter 3. Using DFSORT Program Control Statements

387

OUTREC Control Statement

Example 2
OUTREC FIELDS=(1,4,11,32,D,101)

This statement is for variable-length records of minimum length 100 bytes, and specifies that the output record is to contain an RDW plus 32 bytes of the input record starting at byte 11 (aligned on a doubleword boundary, relative to the start of the record) plus the entire variable portion of the input record.

Example 3
OUTREC FIELDS=(1,42,D,101)

This statement is for variable-length records of minimum length 100 bytes, and specifies that the output record should contain an RDW plus the first 38 data bytes of the input record plus the entire variable portion of the input record. The D parameter has no effect because the first field is always placed at the beginning of the output record.

Example 4
SORT FIELDS=(20,4,CH,D,10,3,CH,D) OUTREC FIELDS=(7:20,4,C FUTURE ,20,2,10,3,1Z,1,9,13,7, 24,57,TRAN=LTOU,6XFF)

This example illustrates how a fixed-length input data set can be sorted and reformatted for output. The SORTIN LRECL is 80 bytes. The reformatted output records are fixed length with a record size of 103 bytes. SOLRF (the IBM-supplied default) is in effect, so unless the SORTOUT LRECL is specified or available, it will automatically be set to the reformatted record length of 103. The reformatted records look as follows: Position 1-6 7-10 11-18 19-20 21-23 24 25-33 34-40 41-97 98-103 Contents EBCDIC blanks for column alignment Input positions 20 through 23 Character string: C FUTURE Input positions 20 through 21 Input positions 10 through 12 Binary zero Input positions 1 through 9 Input positions 13 through 19 Input positions 24 through 80 with lowercase EBCDIC letters converted to uppercase EBCDIC letters Hexadecimal string: X'FFFFFFFFFFFF'

Example 5
SORT FIELDS=(12,4,PD,D) RECORD TYPE=V,LENGTH=(,,,100) OUTREC FIELDS=(1,7,5Z,5X,28,8,6X,101)

This example illustrates how a variable-length input data set can be sorted and reformatted for output. The variable part of the input records is included in the output records. The minimum input record size is 100 bytes and the maximum input record size (SORTIN LRECL or maximum record size for VSAM) is 200 bytes. The reformatted output records are variable-length with a maximum record size of 131 bytes. The reformatted records look as follows:

388

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

Position 1-4 5-7 8-12 13-17 18-25 26-31 32-n Contents RDW (input positions 1 through 4) Input positions 5 through 7 Binary zeros EBCDIC blanks Input positions 28 through 35 EBCDIC blanks Input positions 101 through n (variable part of input records)

Example 6
MERGE FIELDS=(28,4,BI,A) OUTREC BUILD=(1,4,5Z,5X,5,3,28,8,6Z,DATE3-1)

This example illustrates how input files can be merged and reformatted for output, with yesterdays date included. The variable part of the input records is not to be included in the output records. The SORTINnn LRECL is 50 bytes. The reformatted output records are variable-length with a maximum record size of 38 bytes. The reformatted records look as follows: Position 1-4 5-9 10-14 15-17 18-25 26-31 32-38 Contents RDW (input positions 1 through 4) Binary zeros EBCDIC blanks Input positions 5 through 7 Input positions 28 through 35 Binary zeros Yesterdays date in the form Cyyyyddd

Example 7
OPTION COPY,Y2PAST=1985 OUTREC FIELDS=(SEQNUM,8,ZD,START=1000,INCR=100, 11:8,4,PD,M12, 31:15,4,Y2V(/), 51:2,1,CHANGE=(3, X01,CL92,X02,CM72,X03,CJ42), NOMATCH=(C???))

This example illustrates how a sequence number can be generated, how numeric and date values can be edited, and how a lookup table can be used. The reformatted output records look as follows: Position 1-8 1120 31-40 Contents A zoned decimal sequence number that starts at 1000 and increments by 100. A CH field containing the PD field from input positions 8 through 11 edited according to the M12 edit mask. A Cyyyy/mm/dd date field containing the Pyymmdd date field from input positions 15-18 transformed according to the specified century window of 1985-2084. A CH field containing CL92, CM72, CJ42 or C??? as determined by using a lookup table for the input field in position 2.

5153

Chapter 3. Using DFSORT Program Control Statements

389

OUTREC Control Statement

Example 8
SORT FIELDS=(11,4,CH,D) OUTREC FIELDS=(1,20, (5,4,FI,ADD,3,2,FI,ADD,23,2,FI),DIV,+1000, EDIT=(STTTTTTT),SIGNS=(,-),2X, 9,5,ZD,MIN,16,5,FS,TO=ZD,LENGTH=5,2X, 21,40)

This example illustrates how input records can be reformatted for output to contain the results of arithmetic expressions involving input fields, decimal constants, operators and parentheses. The reformatted output records look as follows: Position 1-20 21-28 Contents Input positions 1 through 20 A CH field containing the total of the FI fields from positions 5 through 8, 3 through 4 and 23 through 24, divided by 1000, and edited according to the specified edit pattern. EBCDIC blanks A ZD field containing the minimum of the ZD field in positions 9 through 13 and the FS field in positions 16 through 20. EBCDIC blanks Input positions 21-60

29-30 31-35 36-37 38-77

Example 9
OPTION COPY OUTREC IFTHEN=(WHEN=(3,2,SS,EQ,CFR,MX,GR), OVERLAY=(11:DATE=(DM4.),TIME1(.))), IFTHEN=(WHEN=(3,2,SS,EQ,CCN,US,EN), OVERLAY=(11:DATE=(4MD/),TIME1(:)))

This example illustrates how you can use IFTHEN clauses with OUTREC to reformat different records in different ways. For records with FR, GR or MX in positions 3-4, positions 11-20 of the reformatted output records are overlaid with a date of the form dd.mm.yyyy and positions 21-28 are overlaid with a time of the form hh.mm.ss. The data before positions 11-28 and after positions 11-28 are not affected. For records with CN, US or EN in positions 3-4, positions 11-20 of the reformatted output records are overlaid with a date of the form yyyy/mm/dd and positions 21-28 are overlaid with a time of the form hh:mm:ss. The data before positions 11-28 and after positions 11-28 are not affected. Since an IFTHEN clause with WHEN=NONE is not specified, records without FR, GR, MX, CN, US or EN in positions 3-4 are not changed.

Example 10
OPTION COPY OUTREC OVERLAY=(31:11,10,ZD,DIV,+1200,TO=PD,LENGTH=6, 37:11,10,ZD,MOD,+1200,TO=PD,LENGTH=4)

This example illustrates how you can use the OVERLAY parameter with OUTREC to change certain columns in your records without affecting other columns. Positions 31-36 of the reformatted input records are overlaid with a 6-byte PD value equal to the quotient of the 10-byte ZD value at positions 11-20 divided by

390

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

+1200. Positions 37-40 of the reformatted input records are overlaid with a 4-byte PD value equal to the remainder of the 10-byte ZD value at positions 11-20 divided by +1200. The data before positions 31-40 and after positions 31-40 are not affected.

Example 11
OPTION COPY OUTREC IFTHEN=(WHEN=INIT, OVERLAY=(81:11,10, 11:81,10,ZD,DIV,+1200,TO=PD,LENGTH=6, 17:81,10,ZD,MOD,+1200,TO=PD,LENGTH=4)), IFOUTLEN=80

In the previous example (Example 10), we used OVERLAY to overlay positions 31-40 with PD fields for the quotient and remainder of the 10-byte ZD value at positions 11-20 divided by +1200. In this example, we want to overlay positions 11-20 with the quotient and remainder. The input records are 80 bytes and fixed-length and we want the output records to be 80 bytes and fixed-length as well. If we just overlaid the fields directly as before, we would ruin the ZD value before we could use it to get the remainder; the PD quotient would overlay positions 11-16, so positions 11-20 would no longer contain the ZD value we need to get the remainder. In order to overlay the ZD value itself with the PD values, we make a copy of the 10 byte ZD value after the end of the record, and then overlay the original ZD value with the quotient and remainder derived from the copy of the ZD value. By making a copy of the 10 byte ZD value at the end of the record, we extend the record length from 80 bytes to 90 bytes. Since we want the final record length to be 80 bytes, we must remove the extra 10 bytes. So instead of just using the OVERLAY parameter, we use an IFTHEN WHEN=INIT clause with OVERLAY, and IFOUTLEN=80. Alternatively, we could use an OVERLAY parameter on the OUTREC statement, followed by an OUTFIL statement, to remove the extra 10 bytes like this:
OPTION COPY OUTREC OVERLAY=(81:11,10, 11:81,10,ZD,DIV,+1200,TO=PD,LENGTH=6, 17:81,10,ZD,MOD,+1200,TO=PD,LENGTH=4) OUTFIL OUTREC=(1,80)

Example 12
OPTION COPY OUTREC OVERLAY=(11:11,16,JFY=(SHIFT=RIGHT,LEAD=C(, TRAIL=C),LENGTH=18))

This example illustrates how you can right-justify fields within your records. The 50-byte FB input records might look like this:
0001 0002 0003 0004 9-1-632-731 011-276-321-7836 753-218-307 528-314

Note that the second field has left-justified numeric values in various forms. We want to right-justify these values and surround them with a left parenthesis and right parenthesis.

Chapter 3. Using DFSORT Program Control Statements

391

OUTREC Control Statement

The 50-byte FB output records look like this:
0001 0002 0003 0004 (9-1-632-731) (011-276-321-7836) (753-218-307) (528-314)

We use OUTFIL OVERLAY to limit the changes to the second field. We use JFY to right-justify the second field with surrounding parentheses. SHIFT=RIGHT shifts the characters to the right. LEAD=C( adds a left parenthesis before the first non-blank character. TRAIL=C) adds a right parenthesis after the last non-blank character. LENGTH=18 increases the output length by 2 bytes to allow for the parentheses (overriding the default of 16 from the input length).

Example 13
OPTION COPY OUTREC PARSE=(%01=(ABSPOS=2,FIXLEN=13,ENDBEFR=C","), %=(ENDBEFR=C","), %03=(FIXLEN=6,ENDBEFR=C","), %04=(FIXLEN=6,ENDBEFR=C","), %05=(FIXLEN=12,ENDBEFR=C")), BUILD=(%01,20:%03,SFF,ADD,%04,SFF,EDIT=(SIIT.T),SIGNS=(,-), 31:%05)

This example illustrates how you can reformat records containing variable position/length fields, such as comma separated values. The 80-byte input records might look like this:
"Buffy "Bruce "Clark "Diana Summers","F","+725.8","-27.3","Sunnydale" Wayne","M","-5.3","-173.2","Gotham City" Kent","M","+21.3","-15.8","Metropolis" Prince","F","-16.4","+128.9","Gateway City"

Note that each record has five variable fields, each enclosed in quotes and separated by a comma. The fields do not start and end in the same position in every record and they have different lengths in different records. The 42-byte output records should look like this:
Buffy Bruce Clark Diana Summers Wayne Kent Prince 698.5 -178.5 5.5 112.5 Sunnydale Gotham City Metropolis Gateway City

The first fixed-length output field corresponds to the first variable input field. The second fixed-length output field corresponds to the total of the third and fourth variable input fields. The third fixed-length output field corresponds to the fifth variable input field. In order to reformat the input records for output, we use PARSE and BUILD to create the fixed parsed fields we need from the variable position/length fields; the quotes around each value are removed. %00 is used for the first input field. % is used to ignore the second input field. %03 and %04 are used for the third and fourth input fields which are added together using SFF format. %05 is used for the fifth input field.

Example 14
OPTION COPY OUTREC IFTHEN=(WHEN=INIT, PARSE=(%00=(FIXLEN=3,ENDBEFR=C.), %01=(FIXLEN=3,ENDBEFR=C.),

392

z/OS V1R10.0 DFSORT Application Programming Guide

OUTREC Control Statement

%02=(FIXLEN=3,ENDBEFR=C.), %03=(FIXLEN=3)), BUILD=(%00,4:C.,5:%01,8:C.,9:%02,12:C.,13:%03)), IFTHEN=(WHEN=(1,3,CH,EQ,C167,AND,13,3,CH,EQ,C99), OVERLAY=(5:C113,9:C75 ,1:1,15,SQZ=(SHIFT=LEFT))), IFTHEN=(WHEN=NONE, BUILD=(1:1,15,SQZ=(SHIFT=LEFT)))

This example illustrates how you can modify variable position/length fields, such as ftp addresses. The 15-byte input records might look like this:
167.113.117.99 167.90.18.99 167.80.118.98 165.250.89.562 167.125.890.95 168.250.89.99 167.125.890.99 0.0.0.0 167.90.580.99

We want to convert each FTP address of the form 167.x.y.99 to 167.113.75.99. x and y can be any 1-3 digit value. Thus, the 15-byte output records should look like this:
167.113.75.99 167.113.75.99 167.80.118.98 165.250.89.562 167.125.890.95 168.250.89.99 167.113.75.99 0.0.0.0 167.113.75.99

In order to reformat the input records for output, we use IFTHEN clauses as follows: v IFTHEN WHEN=INIT clause: We PARSE the four variable numeric values into four 3-byte fixed parsed fields using %00, %01, %02 and %03 respectively. We reformat the record with %00, a period, %01, a period, %02, a period and %03. At this point, the reformatted records look like this:
167.113.117.99 167.90 .18 .99 167.80 .118.98 165.250.89 .562 167.125.890.95 168.250.89 .99 167.125.890.99 0 .0 .0 .0 167.90 .580.99

v IFTHEN WHEN=(logexp) clause: If the first fixed-length field is 167 and the fourth fixed-length field is 99 , we overlay the second fixed-length field with 113 and the third fixed-length field with 75. Then we squeeze the fields to the left to remove the blanks. v IFTHEN WHEN=NONE clause: If the first fixed-length field is not 167 or the fourth fixed-length field is not 99 , we squeeze the fields to the left to remove the blanks.

Chapter 3. Using DFSORT Program Control Statements

393

RECORD Control Statement

RECORD Control Statement

RECORD TYPE= F V D LENGTH=( L1 TYPE =F, L1 )

, L2 ,
L1 LENGTH=( L1 L2 )

, L3

TYPE= V , D L1

, L2 ,
L1 , L1 , L1 , L1 , L1 L2 L2 , L3 L2 , L3 ,
L4

, L3 L2 , L2 , L3 ,
L4

, L4 L3 ,
L4

, L5 , L5 , L5 , L6 , L7 , L6

The RECORD control statement can be used to specify the type and lengths of the records being processed, and the minimum and average record lengths for a variable-length sort. The RECORD control statement is required when: v A user exit changes record lengths. v A user exit supplies all of the input records. v A Conventional merge or tape work data set sort uses VSAM input. TYPE

TYPE=x

Can be used to specify the record type when input is VSAM, or an E15 or E32 exit supplies all of the input records. The record type can be: v Fixed-length (F). The records are processed without an RDW, so the data starts in position 1. Control statement positions should be specified accordingly. An RRDS can always be processed as fixed-length. A KSDS, ESDS or VRRDS used for input should only be processed as fixed-length if all of its records have a length equal to the maximum record size defined for the cluster.

394

z/OS V1R10.0 DFSORT Application Programming Guide

RECORD Control Statement

Otherwise, input records which are shorter than the maximum record size are padded with bytes that may or may not be zeros (that is, garbage bytes). v Variable-length (V). The records are processed with an RDW in positions 1-4, so the data starts in position 5. Control statement positions should be specified accordingly. An RRDS, KSDS, ESDS or VRRDS can always be processed as variable-length. For VSAM input, DFSORT reads each record and prepends an RDW to it. For VSAM output, DFSORT removes the RDW before writing each record. TYPE is only required for a Conventional merge or tape work data set sort that uses VSAM input or an E15 or E32 exit that supplies all of the input records. If input is non-VSAM, DFSORT determines the record type from the RECFM of the input data set and ignores TYPE. If input is VSAM, or an E15 or E32 exit supplies all of the input records, DFSORT determines or assigns the record type as follows, using the information in the order listed: 1. F or V from RECORD TYPE if specified. 2. F or V from SORTOUT RECFM if available. 3. V if OUTFIL VTOF, CONVERT or VLFILL is specified, or F if OUTFIL FTOV is specified. 4. F or V from OUTFIL RECFM if available. 5. V if SORTIN is VSAM and SORTOUT is VSAM; otherwise F. Notes: a. If the selected record type is not what you want DFSORT to use, specify RECORD TYPE=F or RECORD TYPE=V as appropriate. b. For a Conventional merge or tape work data set sort, you must specify RECORD TYPE=F or RECORD TYPE=V as appropriate. x can be one of the following: F fixed-length record processing. Note: FB can be used instead of F. V variable-length record processing. Note: VB can be used instead of V. D ISCII/ASCII variable-length record processing. Note: DB can be used instead of D. Default: F or V as described above. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. LENGTH

Chapter 3. Using DFSORT Program Control Statements

395

RECORD Control Statement

LENGTH= L1 , L2 L1 , L1 , L1 , L1 , L1 , L1 L2 L2 , L3 L2 , L3 , L4 L2 , L3 , L4 , L5 L2 , L3 , L4 , L5 , L6 , L7 , L6 , L5 , L4 , L3 ( )

Can be used to specify various record lengths. L1 through L3 apply to fixed-length and variable-length record processing. L4 and L5 apply to variable-length record processing. L6 and L7 are accepted, but not used. LENGTH is required only if: v A user exit changes record lengths. v A user exit supplies all of the input records. L1 Input record length. For variable-length records, maximum input record length. Notes: 1. L1 is ignored if the input record length is available from SORTIN. 2. L1 is required if there is no SORTIN or SORTINnn data set, unless L2 is specified. Default: The SORTIN or SORTINnn record length. For VSAM data sets, the maximum record size (RECSZ value). L2 Record length after E15. For variable-length records, maximum record length after E15. Notes: 1. L2 is ignored if E15 is not used. 2. An accurate value for L2 must be specified if E15 changes the record length. 3. L2 must be at least 18 bytes if tape work data sets are used. 4. L2 is ignored if there is no SORTIN or SORTINnn data set, unless L1 is not specified. Default: L1. L3 Output record length. For variablelength records, maximum output record length. Note: L3 is ignored if the record length (LRECL or VSAM RECSZ) is available from SORTOUT, or if NOSOLRF is in effect and E35, INREC, OUTREC, and OUTFIL are not used. Default: One of the following, in the order listed: 1. SORTOUT record length if available 2. OUTREC record length if SOLRF is in effect

396

z/OS V1R10.0 DFSORT Application Programming Guide

RECORD Control Statement

3. 4. 5. 6. INREC record length if SOLRF is in effect L2 if specified providing an E15 is used SORTIN or SORTINnn record length if available L1

L4 Minimum record length. Notes: 1. L4 is not used if the Blockset technique is selected 2. L4 is only used for variable-length record sort applications. 3. Specifying L4 may improve performance, but if L4 is too large, DFSORT could fail with message ICE015A. Default: The minimum length needed to contain all control fields. This number must be at least 18 bytes if the maximum input record length is greater than 18 bytes; otherwise, DFSORT sets L4 to 18 bytes. L5 Average record length. Notes: 1. L5 is not used if the Blockset technique is selected 2. L5 is overridden by the AVGRLEN parameter if both are specified 3. L5 is only used for variable-length sorts. Default: None; optional. L6, L7 Record lengths that are accepted but are reserved for future use. Notes: 1. You can drop values from the right. For example, LENGTH=(80,70,70,70). 2. You can omit values from the middle or left, provided you indicate their omission by a comma or semicolon. For example, LENGTH=(,,,30,80). 3. Parentheses are optional when L1 alone is specified. If any of L2 through L7 is specified, with or without L1, parentheses are required. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741.

Describing the Record Format and LengthExamples

Example 1
MODS E15=(INEX,1000,EXIT),E35=(OUTEX,2000,EXIT) RECORD LENGTH=(,175,180)

This example illustrates how the RECORD statement can be used to indicate that E15 and E35 exits change the record length. The record type (F) and input record length (200) are obtained automatically from the RECFM and LRECL of the input data set, respectively. LENGTH L2 specifies that the E15 exit passes back 175 byte records. L3 specifies that the E35 exit passes back 180 byte records.

Example 2
MODS E15=(E15ONLY,1000,EXIT) RECORD TYPE=V,LENGTH=60

Chapter 3. Using DFSORT Program Control Statements

397

RECORD Control Statement

This example illustrates how the RECORD statement can be used to set the record type and maximum input record length when an E15 exit supplies all of the input as variable-length records. TYPE V specifies that the E15 exit inserts variable-length records, that is, the inserted records contain an RDW in positions 1-4 and the data starts in position 5.

LENGTH L1 specifies that the E15 exit inserts records with a maximum length of 60 bytes.

SORT Control Statement

|
SORT FIELDS= (

, p,m,f,s , p,m, f, COPY )

, FORMAT=f

|
, , CKPT DYNALLOC = d (,n) (d,n) OFF

EQUALS NOEQUALS FILSZ= x Ex Ux SIZE= y Ey Uy SKIPREC=z STOPAFT=n Y2PAST= s f

The SORT control statement must be used when a sorting application is performed; this statement describes the control fields in the input records on which the program sorts. A SORT statement can also be used to specify a copy application. User labels will not be copied to the output data sets. The way in which DFSORT processes short SORT control fields depends on the setting for VLSHRT/NOVLSHRT. A short field is one where the variable-length record is too short to contain the entire field, that is, the field extends beyond the

398

z/OS V1R10.0 DFSORT Application Programming Guide

SORT Control Statement

record. For details about sorting short records, see the discussion of the VLSHRT and NOVLSHRT options in OPTION Control Statement on page 167. The options available on the SORT statement can be specified in other sources as well. A table showing all possible sources for these options and the order of override is given in Appendix B, Specification/Override of DFSORT Options, on page 741. When an option can be specified on either the SORT or OPTION statement, it is preferable to specify it on the OPTION statement. DFSORT accepts but does not process the following SORT operands: WORK=value and ORDER=value. DFSORTs collating behavior can be modified according to your cultural environment. The cultural environment is established by selecting the active locale. The active locales collating rules affect SORT processing as follows: v DFSORT produces sorted records for output according to the collating rules defined in the active locale. This provides sorting for single- or multi-byte character data, based on defined collating rules that retain the cultural and local characteristics of a language. If locale processing is to be used, the active locale will only be used to process character (CH) control fields. For more information on locale processing, see Cultural Environment Considerations on page 7 or LOCALE in OPTION Control Statement on page 167. FIELDS

, FIELDS=( p,m,f,s )

Requires four facts about each control field in the input records: the position of the field within the record, the length of the field, the format of the data in the field, and the sequence into which the field is to be sorted. These facts are communicated to DFSORT by the values of the FIELDS operand, represented by p, m, f, and s. The value for f can optionally be specified by the FORMAT=f parameter as explained later in this section. All control fields must be located within the first 32752 bytes of a record. Control fields must not extend beyond the shortest record to be sorted unless VLSHRT is in effect. The collected control fields (comprising the control word) must not exceed 4092 bytes (or 4088 bytes when EQUALS is in effect). The FIELDS operand can be written in two ways. The program examines the major control field first, and it must be specified first. The minor control fields are specified following the major control field. p, m, f, and s describe the control fields. The text that follows gives specifications in detail.
Chapter 3. Using DFSORT Program Control Statements

399

SORT Control Statement

p specifies the first byte of a control field relative to the beginning of the input record. 13 The first data byte of a fixed-length record has relative position 1. The first data byte of a variable-length record has relative position 5. The first 4 bytes contain the record descriptor word. All control fields, except binary, must begin on a byte boundary. The first byte of a floating-point field is interpreted as a signed exponent; the rest of the field is interpreted as the fraction. Fields containing binary values are described in a bytes.bits notation as follows: 1. First, specify the byte location relative to the beginning of the record and follow it with a period. 2. Then, specify the bit location relative to the beginning of that byte. Remember that the first (high-order) bit of a byte is bit 0 (not bit 1); the remaining bits are numbered 1 through 7. Thus, 1.0 represents the beginning of a record. A binary field beginning on the third bit of the third byte of a record is represented as 3.2. When the beginning of a binary field falls on a byte boundary (say, for example, on the fourth byte), you can write it in one of three ways:
4.0 4. 4

Other examples of this notation are shown in Figure 14:

byte 1 bits 0 - 7

byte 2 bits 0 - 7

byte 3 bits 0 - 7

1.0 1. 1

1.6

2.2

3.0 3.1 3. 3

Figure 14. Examples of Notation for Binary Fields

m specifies the length of the control field. Values for all control fields except binary fields must be expressed in integer numbers of bytes. Binary fields

13. If INREC is specified, p must refer to the record as reformatted by INREC. If your E15 user exit reformats the record, and INREC is not specified, p must refer to the record as reformatted by your E15 user exit.

400

z/OS V1R10.0 DFSORT Application Programming Guide

SORT Control Statement

can be expressed in the notation bytes.bits. The length of a binary control field that is an integer value (d) can be expressed in one of three ways:
d.0 d. d

The number of bits specified must not exceed 7. A control field 2 bits long would be represented as 0.2. The total number of bytes occupied by all control fields must not exceed 4092 (or, when the EQUALS option is in operation, 4088 bytes). When you determine the total, count a binary field as occupying an entire byte if it occupies any part of it. For example, a binary field that begins on byte 2.6 and is 3 bits long occupies two bytes. All fields must be completely contained within the first 32752 bytes of the record. f specifies the format of the data in the control field. Acceptable control field lengths (in bytes) and available formats are shown in Table 49.
Length 1 to 4092 bytes 1 to 4092 bytes 1 to 256 bytes 1 to 256 bytes 2 to 8 bytes 1 to 256 bytes 1 bit to 4092 bytes 1 to 256 bytes 1 to 4092 bytes 1 to 32 bytes 1 to 44 bytes 1 to 44 bytes 2 to 256 bytes 2 to 256 bytes 1 to 256 bytes 1 to 256 bytes 2 to 256 bytes 2 to 256 bytes Description Character
14

Table 49. Control Field Formats and Lengths Format CH AQ ZD PD PD0 FI BI FL AC CSF or FS UFF SFF CSL or LS CST or TS CLO or OL CTO or OT ASL AST

Character with alternate collating sequence Signed zoned decimal Signed packed decimal Packed decimal with sign and first digit ignored Signed fixed-point Unsigned binary Signed hexadecimal floating-point ISCII/ASCII character Signed numeric with optional leading floating sign Unsigned free form numeric Signed free form numeric Signed numeric with leading separate sign Signed numeric with trailing separate sign Signed numeric with leading overpunch sign Signed numeric with trailing overpunch sign Signed ISCII/ASCII numeric with leading separate sign Signed ISCII/ASCII numeric with trailing separate sign

14. If CHALT is in effect, CH is treated as AQ. Chapter 3. Using DFSORT Program Control Statements

401

SORT Control Statement

Table 49. Control Field Formats and Lengths (continued) Format D1 Y2T Length 1 to 4092 bytes 3 to 6 bytes Description User-defined data type (requires an EFS program) Character or zoned yyx...x full date format with special indicators Packed decimal yyx and yyxxx full date format with special indicators Packed decimal yyxx and yyxxxx full date format with special indicators Character or zoned x...xyy full date format with special indicators Packed decimal xyy and xxxyy full date format with special indicators Packed decimal xxyy and xxxxyy full date format with special indicators Two-digit character or zoned-decimal year data Two-digit packed-decimal year data Two-digit decimal year data Two-digit character or zoned-decimal year data with special indicators Two-digit binary year data

Y2U

2 or 3 bytes

Y2V

3 or 4 bytes

Y2W

3 to 6 bytes

Y2X

2 or 3 bytes

Y2Y

3 or 4 bytes

Y2C or Y2Z Y2P Y2D Y2S

2 bytes 2 bytes 1 byte 2 bytes

Y2B

1 byte

Note: See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions.

CSF, FS, UFF, SFF, Y2 and PD0 format fields can only be used if Blockset is selected. For Y2 format fields, real dates are collated using the century window established by the Y2PAST option in effect, but the century window is not used for special indicators. Thus the Y2 formats will collate real dates and special indicators as follows: v Y2T and Y2W: Ascending: BI zeros, blanks, CH/ZD zeros, lower century dates (for example, 19yy), upper century dates (for example, 20yy), CH/ZD nines, BI ones. Descending: BI ones, CH/ZD nines, upper century dates (for example, 20yy), lower century dates (for example, 19yy), CH/ZD zeros, blanks, BI zeros. v Y2U, Y2V, Y2X and Y2Y:

402

z/OS V1R10.0 DFSORT Application Programming Guide

SORT Control Statement

Ascending: PD zeros, lower century dates (for example, 19yy), upper century dates (for example, 20yy), PD nines. Descending: PD nines, upper century dates (for example, 20yy), lower century dates (for example, 19yy), PD zeros. v Y2C, Y2Z, Y2P, Y2D and Y2B: Ascending: Lower century years (for example, 19yy), upper century years (for example, 20yy). Descending: Upper century years (for example, 20yy), lower century years (for example, 19yy). v Y2S: Ascending: BI zeros, blanks, lower century years (for example, 19yy), upper century years (for example, 20yy), BI ones. Descending: BI ones, upper century years (for example, 20yy), lower century years (for example, 19yy), blanks, BI zeros. | | The AC format sequences EBCDIC data using the ISCII/ASCII collating sequence shown in Appendix D. For example, if AC is used with ascending sequence, the EBCDIC numbers (0-9) will collate before the EBCDIC uppercase letters (A-Z) which in turn will collate before the EBCDIC lowercase letters (a-z). You can use p,m,s rather than p,m,f,s if you use FORMAT=f to supply the format for the field, as described later in this section. All floating-point data must be normalized before the program can collate it properly. You can use an E15 or E61 user exit to do this during processing. If you use E61, specify the E option for the value of s in the FIELDS operand for each control field you are going to modify with this user exit. s specifies how the control field is to be ordered. The valid codes are: A D E ascending order descending order control fields to be modified

Specify E if you include an E61 user exit to modify control fields before the program sorts them. After an E61 user exit modifies the control fields, DFSORT collates the records in ascending order using the formats specified. 15 For information on how to add a user exit, see Chapter 4, Using Your Own User Exit Routines, on page 413. Default: None; must be specified. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details.

15. With a conventional merge or a tape work data set sort, control fields for which E is specified are treated as binary byte format regardless of the actual formats specified. Chapter 3. Using DFSORT Program Control Statements

403

SORT Control Statement

Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. FORMAT

FORMAT=f

FORMAT=f can be used to specify a particular format for one or more control fields. f from FORMAT=f is used for p,m,s fields. f from FORMAT=f is ignored for p,m,f,s fields. For example, the following are all equivalent:
SORT FIELDS=(5,5,ZD,A,12,6,PD,D,21,3,PD,A,35,7,ZD,A) SORT FORMAT=ZD,FIELDS=(5,5,A,12,6,PD,D,21,3,PD,A,35,7,A) SORT FIELDS=(5,5,ZD,A,12,6,D,21,3,A,35,7,ZD,A),FORMAT=PD

The permissible field formats are shown under the description of f for fields. If you have specified the COPY operand, FORMAT=f cannot be specified. Default: None; FORMAT=f must be specified if any field is specified as p,m,s rather than p,m,f,s. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. Note: DFSORT issues an informational message and ignores FORMAT=f if all of the fields are specified as p,m,f,s. | FIELDS=COPY

FIELDS=COPY

See the discussion of the COPY option discussed in OPTION Control Statement on page 167. CKPT

CKPT

See the discussion of this option discussed in OPTION Control Statement on page 167. DYNALLOC

404

z/OS V1R10.0 DFSORT Application Programming Guide

SORT Control Statement

|
DYNALLOC = d (,n) (d,n) OFF

See the discussion of this option in OPTION Control Statement on page 167. EQUALS or NOEQUALS

EQUALS NOEQUALS

See the discussion of these options in OPTION Control Statement on page 167. FILSZ or SIZE

FILSZ=

x Ex Ux y Ey Uy

SIZE=

See the discussion of these options in OPTION Control Statement on page 167. SKIPREC

SKIPREC=z

See the discussion of this option in OPTION Control Statement on page 167. STOPAFT

STOPAFT=n

See the discussion of this option in OPTION Control Statement on page 167. Y2PAST

Chapter 3. Using DFSORT Program Control Statements

405

SORT Control Statement

Y2PAST= s f

See the discussion of this option in OPTION Control Statement on page 167. Note: CENTURY=value and CENTWIN=value can be used instead of Y2PAST=value.

SORT/MERGE Statement Notes

v If records are reformatted by INREC (SORT and MERGE) or E15 (SORT), FIELDS must refer to fields in the appropriate reformatted records. v If SZERO is in effect, 0 collates before +0 in ascending order and after +0 in descending order when numeric fields are sorted or merged. If NOSZERO is in effect, 0 collates equally with +0 when numeric fields are sorted or merged. However, SZERO is always used for a conventional merge or tape work data set sort application.

Specifying a SORT or COPYExamples

Example 1
SORT FIELDS=(2,5,FS,A),FILSZ=29483

FIELDS The control field begins on the second byte of each record in the input data set, is five bytes long, and contains floating sign data. It is to be sorted in ascending order. FILSZ The data set to be sorted contains exactly 29483 records.

Example 2
SORT FIELDS=(7,3,CH,D,1,5,FI,A,398.4,7.6,BI,D,99.0,230.2, BI,A,452,8,FL,A),DYNALLOC=(3390,4)

FIELDS The first four values describe the major control field. It begins on byte 7 of each record, is 3 bytes long, and contains character (EBCDIC) data. It is to be sorted in descending order. The next four values describe the second control field. It begins on byte 1, is 5 bytes long, contains fixed-point data, and is to be sorted in ascending order. The third control field begins on the fifth bit (bits are numbered 0 through 7) of byte 398. The field is 7 bytes and 6 bits long (occupies 9 bytes), and contains binary data to be placed in descending order. The fourth control field begins on byte 99, is 230 bytes and 2 bits long, and contains binary data. It is to be sorted in ascending order. The fifth control field begins on byte 452, is 8 bytes long and contains normalized hexadecimal floating-point data, which is to be sorted in ascending order. If the data in this field were not normalized, you could specify E instead of A and include your own E61 user exit routine to normalize the field before the program examined it.

406

z/OS V1R10.0 DFSORT Application Programming Guide

SORT Control Statement

DYNALLOC Four work data sets are allocated on 3390.

Example 3
SORT FIELDS=(3,8,ZD,E,40,6,CH,D)

FIELDS The first four values describe the major control field. It begins on byte 3 of each record, is 8 bytes long, and contains zoned decimal data that is modified by your routine before sort examines the field. The second field begins on byte 40, is 6 bytes long, contains character (EBCDIC) data, and is sorted in descending sequence.

Example 4
SORT FIELDS=(7025,4,A,5048,8,A),FORMAT=ZD,EQUALS

FIELDS The major control field begins on byte 7025 of each record, is 4 bytes long, contains zoned decimal data (FORMAT=ZD), and is to be sorted in ascending sequence. The second control field begins on byte 5048, is 8 bytes long, has the same data format as the first field, and is also to be sorted in ascending order. FORMAT FORMAT=ZD is used to supply ZD format for the p,m,s fields and is equivalent to specifying p,m,ZD,s for these fields. With FORMAT=f, you can mix p,m,s and p,m,f,s fields when thats convenient such as when all or most of the fields have the same format (although you can always code p,m,f,s for all fields and not use FORMAT=f, if you prefer). For example, the following are also valid uses of the FORMAT=f parameter:
SORT FORMAT=BI,FIELDS=(21,4,A,5,4,PD,A,31.3,1.4,A,52,20,A) SORT FIELDS=(16,4,A,22,8,BI,D,3,2,A),FORMAT=FI

EQUALS specifies that the sequence of equal collating records is to be preserved from input to output.

Example 5
SORT FIELDS=COPY

FIELDS The input data set is copied to the output data set without sorting or merging.

Example 6
OPTION Y2PAST=1950 SORT FIELDS=(21,6,Y2T,A,13,3,Y2X,D)

Y2PAST Sets a century window of 19502049. FIELDS Sorts on a Cyymmdd (or Zyymmdd) date in positions 21-26 in ascending order, and on a Pdddyy date in positions 13-15 in descending order. Real dates are sorted using the century window of 1950-2049. Special indicators are sorted correctly relative to the real dates.

Chapter 3. Using DFSORT Program Control Statements

407

SUM Control Statement

SUM Control Statement

|
SUM FIELDS= (

, p,m,f , p,m ,f NONE )

, FORMAT=f

The SUM control statement specifies that, whenever two records are found with equal sort or merge control fields, the contents of their summary fields are to be added, the sum is to be placed in one of the records, and the other record is to be deleted. If the EQUALS option is in effect the first record of summed records is kept. If the NOEQUALS option is in effect, the record to be kept is unpredictable. For further details, see SUM Statement Notes on page 410. If the ZDPRINT option is in effect, positive summed ZD values are printable. If the NZDPRINT option is in effect, positive summed ZD values are not printable. For further details, see SUM Statement Notes on page 410. The way in which DFSORT processes short SUM summary fields depends on whether the VLSHRT or NOVLSHRT option is in effect. A short field is one where the variable-length record is too short to contain the entire field; that is, the field extends beyond the record. For details about sorting, merging and summing short records, see the discussion of the VLSHRT and NOVLSHRT options in OPTION Control Statement on page 167. FIELDS

, FIELDS= ( p,m,f )

Designates numeric fields in the input record as summary fields. p specifies the first byte of the field relative to the beginning of the input record. 16 The first data byte of a fixed-length record has relative position 1. The first data byte of a variable-length record has relative position 5, as the first four bytes are occupied by the RDW. All fields must start on a byte boundary and no field can extend beyond byte 32752

m specifies the length in bytes of the summary fields to be added. See below for permissible length values. f specifies the format of the data in the summary field:

16. If INREC is specified, p must refer to the record as reformatted by INREC. If your E15 user exit reformats the record, and INREC is not specified, p must refer to the record as reformatted by your E15 user exit.

408

z/OS V1R10.0 DFSORT Application Programming Guide

SUM Control Statement

Table 50. Summary Field Formats and Lengths Format Code BI FI FL PD ZD Length 2, 4, or 8 bytes 2, 4, or 8 bytes 4, 8, or 16 bytes 1 to 16 bytes 1 to 31 bytes Description Unsigned binary Signed fixed-point Signed hexadecimal floating-point Signed packed decimal Signed zoned decimal

The value for f can optionally be specified by the FORMAT=f parameter as explained later in this section. Note: See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions. | NONE eliminates records with duplicate keys. Only one record with each key is kept and no summing is performed. Note: The FIRST operand of ICETOOLs SELECT operator can be used to perform the same function as SUM FIELDS=NONE with OPTION EQUALS. Additionally, SELECTs FIRSTDUP, ALLDUPS, NODUPS, HIGHER(x), LOWER(y), EQUAL(v), LASTDUP, and LAST operands can be used to select records based on other criteria related to duplicate and non-duplicate keys. SELECTs DISCARD(savedd) operand can be used to save the records discarded by FIRST, FIRSTDUP, ALLDUPS, NODUPS, HIGHER(x), LOWER(y), EQUAL(v), LASTDUP, or LAST. See SELECT Operator on page 566 for complete details on the SELECT operator. Default: None; must be specified. Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. FORMAT

FORMAT=f

FORMAT=f can be used to specify a particular format for one or more summary fields. f from FORMAT=f is used for p,m fields. f from FORMAT=f is ignored for p,m,f fields. For example, the following are all equivalent:
SUM FIELDS=(5,5,ZD,12,6,PD,21,3,PD,35,7,ZD) SUM FORMAT=ZD,FIELDS=(5,5,12,6,PD,21,3,PD,35,7) SUM FIELDS=(5,5,ZD,12,6,21,3,35,7,ZD),FORMAT=PD

The permissible field formats are shown under the description of f for fields. Default: None. FORMAT=f must be specified if any field is specified as p,m rather than p,m,f. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details.
Chapter 3. Using DFSORT Program Control Statements

409

SUM Control Statement

Applicable Functions: See Appendix B, Specification/Override of DFSORT Options, on page 741. Note: DFSORT issues an informational message and ignores FORMAT=f if all of the fields are specified as p,m,f.

SUM Statement Notes

v If overflow might occur during summation, INREC can be used to create a larger SUM field in the reformatted input record (perhaps resulting in a larger record for sorting or merging) so that overflow does not occur. Example 5 on page 412 illustrates this technique. v An invalid PD or ZD sign or digit results in a data exception (0C7 ABEND); 0-9 are invalid for the sign and A-F are invalid for the digit. For example, a ZD value such as 3.5 (X'F34BF5') results in an 0C7 because . (X'4B') is treated as an invalid digit. ICETOOLs DISPLAY or VERIFY operator can be used to identify decimal values with invalid digits. ICETOOLs VERIFY operator can be used to identify decimal values with invalid signs. v Whether or not positive summed ZD results have printable numbers depends on whether NZDPRINT or ZDPRINT is in effect (as set by the ZDPRINT installation option and the NZDPRINT and ZDPRINT parameters of the OPTION statement): If NZDPRINT is in effect, positive summed ZD results do not consist of printable numbers, regardless of whether the original values consisted of printable numbers or not. For example, if X'F2F3F1' (prints as 231) and X'F3F0F6' (prints as 306) are summed, the result with NZDPRINT in effect is X'F5F3C7' (prints as 53G). If ZDPRINT is in effect, positive summed ZD results consist of printable numbers, regardless of whether the original values consisted of printable numbers or not. For example, if X'F2F3C1' (prints as 23A) and X'F3F0F6' (prints as 306) are summed, the result with ZDPRINT in effect is X'F5F3F7' (prints as 537). Thus, ZDPRINT must be in effect to ensure that positive summed ZD results are printable. Unsummed positive ZD values retain their original signs, regardless of whether NZDPRINT or ZDPRINT is in effect. For example, if X'F2F8C5' is not summed, it remains X'F2F8C5' (prints as 28E). OUTFILs OUTREC parameter can be used to ensure that all summed or unsummed ZD values are printable, as illustrated by Example 4 below. v If input records are reformatted by INREC or E15, SUM must refer to fields in the appropriate reformatted record (see the preceding description of p). v Summary fields must not be control fields. They must not overlap control fields, or each other, and must not overlap the RDW. v FL (hexadecimal floating-point) values to be summed can be normalized or unnormalized. However, the resulting FL values are always normalized. Normalization processing by the hardware can produce different sums for FL values summed in different orders. v Exponent overflow for summed FL values results in an exponent overflow exception (0CC ABEND) v Exponent underflow for summed FL values results in a true zero result. v When records are summed, you can predict which record is to receive the sum (and be retained) and which record is to be deleted only when EQUALS is in effect, overflow does not occur, and the BLOCKSET technique is used. In this

410

z/OS V1R10.0 DFSORT Application Programming Guide

SUM Control Statement

case, the first record (based on the sequence described under the discussion of the EQUALS or NOEQUALS parameter of the OPTION Control Statement on page 167) is chosen to contain the sum. Fields other than summary fields remain unchanged and are taken from the record that receives the sum. v You can control the action that DFSORT takes when overflow occurs for BI, FI, PD or ZD values with the OVFLO parameter as described in OPTION Control Statement on page 167. v DFSORT issues a message and terminates processing if a SUM statement is specified for a tape work data set sort or Conventional merge. v DFSORT does not support the XSUM parameter provided by a competitive sort product to write records deleted by SUM processing to a SORTXSUM DD data set. However, ICETOOLs SELECT operator can perform the same function as XSUM with FIELDS=NONE. For example, this ICETOOL job:
//S1EXEC PGM=ICETOOL //TOOLMSG DD SYSOUT=* //DFSMSG DD SYSOUT=* //SORTIN DD DSN=... //SORTOUT DD DSN=... //SORTXSUM DD DSN=... //TOOLIN DD * SELECT FROM(SORTIN) TO(SORTOUT)ON(5,4,CH) FIRST DISCARD(SORTXSUM) /*

is equivalent to this XSUM job:

//S1 EXEC PGM=ICEMAN //SYSOUT DD SYSOUT=* //SORTIN DD DSN=... //SORTOUT DD DSN=... //SORTXSUM DD DSN=... //SYSIN DD * SORT FIELDS=(5,4,CH,A) SUM FIELDS=NONE,XSUM /*

Tip: You can also perform additional functions with ICETOOLs SELECT operator that are not available with XSUM. See Chapter 6, Using ICETOOL, on page 479 for complete details of ICETOOLs SELECT operator.

Adding Summary FieldsExamples

Example 1
SUM FIELDS=(15021,8,PD,15011,4,FI)

This statement designates an 8-byte packed decimal field at byte 15021, and a 4-byte fixed-integer field at byte 15011, as summary fields.

Example 2
SUM FIELDS=NONE

This statement illustrates the elimination of duplicate records.

Example 3
SUM FIELDS=(41,8,49,4),FORMAT=ZD OPTION ZDPRINT

Chapter 3. Using DFSORT Program Control Statements

411

SUM Control Statement

These statements illustrate the use of the FORMAT operand and the ZDPRINT option. The SUM statement designates two zoned decimal fields, one 8 bytes long starting at byte 41, and the other 4 bytes long starting at byte 49. As a result of the ZDPRINT option, the positive summed ZD values will be printable. Note, however, that the ZDPRINT option does not affect ZD values which are not summed due to overflow or unique keys. The next example shows how to use OUTFIL to make all summary fields printable.

Example 4
SUM FIELDS=(41,8,49,4),FORMAT=ZD OUTFIL OUTREC=(1,40,41,8,ZD,M11,49,4,ZD,M11,53,28)

These statements illustrate the use of the OUTFIL statement to ensure that all positive ZD summary fields in the output data set are printable. Whereas the ZDPRINT option affects only positive summed ZD fields, OUTFIL can be used to edit positive or negative BI, FI, PD, or ZD values, whether they are summed or not. OUTFIL can also be used to produce multiple output data sets, reports, and so on. See OUTFIL Control Statements on page 221 for complete details about OUTFIL processing. Note: For purposes of illustration, this example assumes that the input records are 80 bytes long.

Example 5
* Add Z0 before the ZD SUM field to prevent overflow. * Add P0 before the PD SUM field to prevent overflow. INREC FIELDS=(1,10, Copy bytes before ZD SUM field 11:C0,12:11,4, Add Z0 before ZD SUM field 16:15,6, Copy bytes after ZD SUM field 22:X00,23:21,2, Add P0 before PD SUM field 25:23,5, Copy SORT field 30:28,53) Copy bytes after SORT field * Sort on key in its new position. SORT FIELDS=(25,5,CH,A) * Sum on the expanded ZD and PD fields in * their new positions. SUM FIELDS=(11,5,ZD,22,3,PD)

These statements illustrate a technique for preventing overflow of summed fields by using INREC to make the fields larger before they are summed. The fields that might overflow when they are summed are a 4 byte ZD field starting at position 11 and a 2 byte PD field starting at position 21. In order to prevent them from overflowing, we expand each field on the left with an appropriate zero byte; C0 (Z0) for the ZD field and P0 (X00) for the PD field. We can then sum on the new 5 byte ZD field and on the new 3 byte PD field. Note that adding these extra bytes increases the length of the record and changes the starting position of various fields. In the SORT and SUM statements, we must specify the starting positions of the fields in the reformatted record rather than the starting positions of the fields in the input record. For example, although the SORT field starts in position 23 in the input record, we must use its starting position of 25 in the reformatted record.

412

z/OS V1R10.0 DFSORT Application Programming Guide

Chapter 4. Using Your Own User Exit Routines

User Exit Routine Overview . . . . . . . . DFSORT Program Phases . . . . . . . . . Functions of Routines at User Exits . . . . . . DFSORT Input/User Exit/Output Logic Examples . . . . . . . . . . . . . . Opening and Initializing Data Sets . . . . . Modifying Control Fields . . . . . . . . Inserting, Deleting, and Altering Records . . . Summing Records . . . . . . . . . . . Handling Special I/O . . . . . . . . . Routines for Read Errors . . . . . . . Routines for Write Errors . . . . . . . VSAM User Exit Functions . . . . . . . . Determining Action when Intermediate Storage Is Insufficient . . . . . . . . . . . . Closing Data Sets . . . . . . . . . . . Terminating DFSORT . . . . . . . . . . Addressing and Residence Modes for User Exits How User Exit Routines Affect DFSORT Performance . . . . . . . . . . . . . . Summary of Rules for User Exit Routines . . . . Loading User Exit Routines . . . . . . . User Exit Linkage Conventions . . . . . . Linkage Examples . . . . . . . . . . Dynamically Link-Editing User Exit Routines Assembler User Exit Routines (Input Phase User Exits) . . . . . . . . . . . . . . . . E11 User Exit: Opening Data Sets/Initializing Routines . . . . . . . . . . . . . . E15 User Exit: Passing or Changing Records for Sort and Copy Applications . . . . . . . Information DFSORT Passes to Your Routine at E15 User Exit . . . . . . . . . . E15 Return Codes . . . . . . . . . . Storage Usage for E15 User Exit . . . . . E16 User Exit: Handling Intermediate Storage Miscalculation . . . . . . . . . . . . E16 Return Codes . . . . . . . . . . E17 User Exit: Closing Data Sets . . . . . . E18 User Exit: Handling Input Data Sets . . . Using E18 User Exit with QSAM/BSAM . . Using E18 User Exit with VSAM . . . . . E19 User Exit: Handling Output to Work Data Sets . . . . . . . . . . . . . . . Using E19 User Exit with QSAM/BSAM . . E61 User Exit: Modifying Control Fields . . . Some Uses of E61 User Exit . . . . . . Information DFSORT Passes to Your Routine at E61 User Exit . . . . . . . . . . 413 414 416 416 417 418 418 418 418 419 419 419 419 419 419 419 420 420 421 421 422 423 423 423 424 425 425 426 427 427 427 427 428 429 431 431 432 432 433 Assembler User Exit Routines (Output Phase User Exits) . . . . . . . . . . . . . . . . E31 User Exit: Opening Data Sets/Initializing Routines . . . . . . . . . . . . . . E32 User Exit: Handling Input to a Merge Only Information DFSORT Passes to Your Routine at E32 User Exit . . . . . . . . . . E32 Return Codes . . . . . . . . . . E35 User Exit: Changing Records . . . . . . Information DFSORT Passes to Your Routine at E35 User Exit . . . . . . . . . . E35 Return Codes . . . . . . . . . . Storage Usage for E35 User Exit . . . . . E37 User Exit: Closing Data Sets . . . . . . E38 User Exit: Handling Input Data Sets . . . Using E38 User Exit with VSAM . . . . . E39 User Exit: Handling Output Data Sets . . . Using E39 User Exit with QSAM/BSAM . . Using E39 User Exit with VSAM . . . . . Sample Routines Written in Assembler . . . . . E15 User Exit: Altering Record Length . . . . E16 User Exit: Sorting Current Records When NMAX Is Exceeded . . . . . . . . . . E35 User Exit: Altering Record Length . . . . E61 User Exit: Altering Control Fields . . . . COBOL User Exit Routines . . . . . . . . . COBOL User Exit Requirements . . . . . . COBOL Requirements for Copy Processing COBOL Storage Requirements . . . . . . COBOL User Exit Routines (Input Phase User Exit) COBOL E15 User Exit: Passing or Changing Records for Sort . . . . . . . . . . . E15 Interface with COBOL . . . . . . . E15 LINKAGE SECTION Fields for Fixed-Length and Variable-Length Records . E15 Return Codes . . . . . . . . . . E15 Procedure Division Requirements . . . COBOL User Exit Routines (Output Phase User Exit) . . . . . . . . . . . . . . . . COBOL E35 User Exit: Changing Records . . . E35 Interface with COBOL . . . . . . . E35 LINKAGE SECTION Fields for Fixed-Length and Variable-Length Records . E35 Return Codes . . . . . . . . . . E35 Procedure Division Requirements . . . Sample Routines Written in COBOL . . . . . . COBOL E15 User Exit: Altering Records . . . COBOL E35 User Exit: Inserting Records . . . E15/E35 Return Codes and EXITCK . . . . . . 433 434 434 434 435 435 436 437 438 438 439 439 439 439 439 440 440 441 441 442 443 443 444 444 445 445 445 448 449 450 451 451 451 453 454 456 456 456 457 458

User Exit Routine Overview

DFSORT can pass program control to your own routines at points in the executable code called user exits. Your user exit routines can perform a variety of functions including deleting, inserting, altering, and summarizing records.
Copyright IBM Corp. 1973, 2006

413

User Exit Routine Overview

If you need to perform these tasks, you should be aware that DFSORT already provides extensive facilities for working with your data in the various DFSORT program control statements. See the discussions of the INCLUDE, OMIT, INREC, OUTFIL, OUTREC, and SUM program control statements in Chapter 3, Using DFSORT Program Control Statements, on page 81. You might decide that using a program control statement to work with your records is more appropriate to your needs. Although this chapter discusses only routines written in assembler or COBOL, you can write your exit routines in any language that can: v Pass and accept the address into general register 1 of a: Record Full word of zeros Parameter list. v Pass a return code in register 15. You can easily activate user exit routines at run-time with the MODS program control statement (see MODS Control Statement on page 160). Alternatively, under certain circumstances you can also activate a user exit routine by passing the address of your exit routine in the invocation parameter list. See Chapter 5, Invoking DFSORT from a Program, on page 461 for details. Parameters that affect the way user exit routines are handled include: v The MODS statement, explained in MODS Control Statement on page 160 v The E15=COB and E35=COB PARM options of the EXEC statement, explained in Specifying EXEC/DFSPARM PARM Options on page 29 v The COBEXIT option of the OPTION statement, explained in OPTION Control Statement on page 167 v The EXITCK option of the OPTION statement, explained in OPTION Control Statement on page 167. Note: To avoid ambiguity in this chapter, it is assumed that the IBM default, EXITCK=STRONG, was selected at your site. Certain user exit routines can be written in COBOL, using a special interface. If you write your exit routines in PL/I, you must use the PL/I subroutine facilities. You might need to reserve space to be used by your exits. See Use Main Storage Efficiently on page 689 for more information about storage.

DFSORT Program Phases

A DFSORT program phase is a large DFSORT component designed to perform a specific task such as writing the output file. Various user exits are contained in the input and output phases and are activated at a particular time during DFSORT processing. The input phase is used only for a sort or copy. When the output phase is completed, DFSORT returns control to the operating system or invoking program. Figure 15 on page 415 is a representation of DFSORT input/output logic.

414

z/OS V1R10.0 DFSORT Application Programming Guide

DFSORT Program Phases

INPUT/EXIT/OUTPUT LOGIC FOR SORT APPLICATION
START A
INPUT PHASE

INPUT/EXIT/OUTPUT LOGIC FOR COPY APPLICATION

START A

INPUT/EXIT/OUTPUT LOGIC FOR MERGE APPLICATION

START

READ RECORD FROM SORTIN

INPUT/ OUTPUT PHASE

READ RECORD FROM SORTIN

OUPUT READ RECORD PHASE FROM EACH SORTINnn

A E15
E15 CHOOSE A RECORD MORE INPUT RECORDS? NO E15 WRITE RECORD TO SORTOUT AND/OR OUTFIL DATA SETS YES A E35 E35

RETURNS RC=8

WRITE RECORD TO SORTOUT AND/OR OUTFIL DATA SETS YES YES

SORT THE RECORDS

MORE INPUT RECORDS? NO

B
OUTPUT PHASE

MORE INPUT RECORDS?

NO E35

READ RECORD FROM SORTINnn

GET SORTED RECORD

E15

A
E35 RETURNS RC=8 RETURNS RC=8

WRITE RECORD TO SORTOUT AND/OR OUTFIL DATA SETS MORE SORTED YES RECORDS? NO E35

E35

EXIT

RETURNS RC=8

EXIT

RETURNS RC=8

EXIT

Figure 15. Examples of DFSORT Input/User Exit/Output Logic

Chapter 4. Using Your Own User Exit Routines

415

Functions of Routines at User Exits

Functions of Routines at User Exits

You can use exit routines to accomplish a variety of tasks: v Open and initialize data sets v Modify control fields v Insert, delete, or alter records v Sum records v Handle special I/O conditions v Determine action when intermediate storage is insufficient v Close data sets v Terminate DFSORT. Figure 15 on page 415, Table 51 on page 417, and Table 52 on page 417 summarize the functions of user exit routines and the exits and phases with which they can be associated. | | | | | | | | | | | The following restrictions apply to the applications for which specific user exits can be used: v E11. E16, E17, E18 and E19 can be used for sort applications, but are ignored for copy or merge applications. v E15 can be used for sort or copy applications, but is ignored for merge applications. v E32 can be used for merge applications, but is ignored for copy or sort applications. v E61 can be used for sort or merge applications, but is ignored for copy applications. v E31, E35, E37, E38 and E39 can be used for sort, copy or merge applications.

DFSORT Input/User Exit/Output Logic Examples

Figure 15 on page 415 gives examples of the logic flow for sort, copy, and merge applications as it relates to SORTINnn, E15 or E35 user exits, and SORTOUT. The intent is to show how your E15 and E35 user exits fit into the logic of an application. All possible paths are not covered. For simplicity, it is assumed that all of the applicable data sets and exits are present and that records are not inserted or deleted. (For a merge, similar logic would be used if an E32 user exit supplied the records rather than SORTINnn data sets.) Figure 15 on page 415 illustrates the following logic: v E15 and E35 user exits continue to be entered until they pass back a return code of 8. If your user exit passes a return code of 8 to DFSORT when input records still remain to be processed, the records are processed by DFSORT without being passed to your exit. v During a sort, each record is read from SORTIN and passed to E15 user exit. When all of the records have been processed in this manner, they are sorted by DFSORT, then each sorted record is passed to E35 and written to the output data sets. v During a copy, each record is read from SORTIN, passed to E15 and E35 user exits, and written to the output data sets. v During a merge, one record is initially read from each SORTINnn data set. The record to be output is chosen, passed to E35, and written to the output data sets. The chosen record is then replaced by reading a record from the same SORTINnn data set and the process continues.

416

z/OS V1R10.0 DFSORT Application Programming Guide

Functions of Routines at User Exits

Note: For a merge application, records deleted during an E35 user exit routine are not sequence-checked. If you use an E35 user exit routine without an output data set, sequence checking is not performed at the time the records are passed to the E35 user exit; therefore, you must ensure that input records are in correct sequence.
Table 51. Functions of Routines at Program User Exits (Sort) Functions Open/Initialize Modify control fields Insert, Delete/Alter Sum records Handle special I/O conditions: QSAM/BSAM and VSAM SORTIN QSAM/BSAM SORTOUT VSAM SORTOUT E18 user exit E19 user exit2 N/A E38 user exit2 E39 user exit3 E39 user exit3 N/A E35, E37 user exits E35 user exit Sort Input Phase E11, E15 user exits E61 user exit E15 user exit Sort Output Phase E31 user exit N/A E35 user exit E35 user exit1

Determine action when intermediate storage E16 user exit4 is insufficient Close/housekeeping Terminate DFSORT E15, E17 user exits E15 user exit

Notes: 1. The SUM control statement can be used instead of your own routine to sum records. 2. Applies only to a tape work data set sort. 3. E39 can be used for SORTOUT, but not for OUTFIL data sets. 4. Applies only to a tape work data set sort or a Peerage/Vale sort without work data sets. Table 52. Functions of Routines at Program User Exits (Copy and Merge) Functions Open/Initialize Modify control fields Insert Delete/alter Sum records Handle special I/O conditions: QSAM/BSAM and VSAM SORTIN(nn) QSAM/BSAM and VSAM SORTOUT Close/housekeeping Terminate DFSORT Note: 1. The SUM control statement can be used instead of your own routine to sum records. E38 user exit E39 user exit E35, E37 user exits E15, E35 user exits E38 user exit E39 user exit E35, E37 user exits E32, E35 user exits Copy E15, E31 user exits N/A E15, E35 user exits E15, E35 user exits E35 user exit Merge E31 user exit E61 user exit E32, E35 user exits E35 user exit E35 user exit1

Opening and Initializing Data Sets

You can write your own routines to open data sets and perform other forms of initialization; you must associate these routines with the E11, E15, E31 and E35 user exits.

Chapter 4. Using Your Own User Exit Routines

417

Functions of Routines at User Exits

To check labels on input files, use the E18 and E38 user exits.

Modifying Control Fields

You can write a routine to alter control fields before DFSORT compares them. This allows you, for example, to normalize floating-point control fields. It also allows you to modify the order in which the records are finally sorted or merged, a function for which you would usually use DFSORTs ALTSEQ program control statement. You must associate this routine with the E61 user exit. When an E61 user exit is used, the subsequent comparisons always arrange the modified control fields in ascending order. Note: Although you are altering control fields before a compare, your original records are not altered.

Inserting, Deleting, and Altering Records

You can write your own routines to delete, insert, or alter records. You must associate these routines with the E15, E32, and E35 user exits. Note: DFSORT also provides INCLUDE and OMIT statements, and OUTFIL INCLUDE and OMIT parameters that automatically include or delete records based on your field criteria. For more information on these control statements, refer to Chapter 3, Using DFSORT Program Control Statements, on page 81.

Summing Records
You can sum records for output by using the E35 user exit. However, you can also use DFSORTs SUM program control statement to accomplish this without a user exit. See SUM Control Statement on page 408.

Handling Special I/O

DFSORT contains four exits to handle special I/O conditions: E18 and E38 user exits for SORTIN and SORTINnn, and E19 and E39 user exits for SORTOUT (but not for OUTFIL data sets). They are particularly useful for a tape work data set sort. With all disk work data set sorts, E19 and E38 user exits are ignored. You can use these exits to incorporate your own or your sites I/O error recovery routines into DFSORT. Your read and write error routines must reside in a partitioned data set (library). Your library routines are brought into main storage with their associated phases. When DFSORT encounters an uncorrectable I/O error, it passes the same parameters as those passed by QSAM/BSAM or VSAM. If no user routines are supplied and an uncorrectable read or write error is encountered, DFSORT issues an error message and then terminates. With QSAM/BSAM, the following information is passed to your synchronous error routine: v General registers 0 and 1 are unchanged; they contain the information passed by QSAM/BSAM, as documented in the data management publications. v General register 14 contains the return address of DFSORT. v General register 15 contains the address of your error routine.

418

z/OS V1R10.0 DFSORT Application Programming Guide

Functions of Routines at User Exits

VSAM will go directly to any routine specified in the EXLST macro you passed to DFSORT via the E18, E38, or E39 user exit, as appropriate. Your routine must return to VSAM via register 14. For details, see z/OS DFSMS Macro Instructions for Data Sets or z/OS DFSMS Using Data Sets

Routines for Read Errors

You must associate these routines with the E18 and E38 user exits. They must pass certain control block information back to DFSORT to tell it whether to accept the record as it is, skip the block, or request termination. They can also attempt to correct the error.

Routines for Write Errors

You must associate these routines with the E19 and E39 user exits. These routines can perform any necessary abnormal end-of-task operations for SORTOUT before DFSORT is terminated.

VSAM User Exit Functions

There are three user exits that can be used with VSAM SORTIN, SORTINnn, and SORTOUT data sets (but not with OUTFIL data sets), to supply passwords or a user exit list to journal a VSAM data set. They can carry out other VSAM exit functions except EODAD. The user exits are E18 for sort SORTIN, E38 for merge SORTINnn or copy SORTIN, and E39 for SORTOUT.

Determining Action when Intermediate Storage Is Insufficient

You can write a routine to direct DFSORT program action if DFSORT determines that insufficient intermediate storage is available to handle the input data set. You must associate this routine with the E16 user exit for sorts using tape work data sets. For a sort that uses tape data sets, you can choose between sorting current records only, trying to complete the sort, or terminating DFSORT. For more details, see Exceeding Tape Work Space Capacity on page 738.

Closing Data Sets

You can write your own routines to close data sets and perform any necessary housekeeping; you must associate these routines with the E15, E17, E35, and E37 user exits. To write SORTOUT labels, use the E19 and E39 user exits. If you have an end-of-file routine you want to use for SORTIN, include it at the E18 user exit.

Terminating DFSORT
You can write an exit routine to terminate DFSORT before all records have been processed. You must associate these routines with the E15, E16, E32, and E35 user exits.

Addressing and Residence Modes for User Exits

To allow user exits called by Blockset or Peerage/Vale to reside above or below 16MB virtual, use either 24-bit or 31-bit addressing, and use a user exit address constant, DFSORT supplies these features: v To ensure that DFSORT enters your user exit with the correct addressing mode, you must observe these rules: If the user exit name is specified in a MODS control statement, the user exit is entered with the addressing mode indicated by the linkage editor attributes of the routine (for example, 31-bit addressing in effect if AMODE 31 is specified).
Chapter 4. Using Your Own User Exit Routines

419

Addressing and Residence Modes for User Exits

If the address of the exit is passed to DFSORT (preloaded exit) via the 24-bit list, the user exit is entered with 24-bit addressing in effect. If the address of the user exit is passed to DFSORT via the extended parameter list (preloaded exit), the user exit is entered with 24-bit addressing in effect if bit 0 of the user exit address in the list is 0 or with 31-bit addressing in effect if bit 0 of the user exit address in the list is 1. v User exits can return to DFSORT with either 24-bit or 31-bit addressing in effect. The return address that DFSORT placed in register 14 must be used. v Except for the user exit address constant (which is passed to either the assembler E15, E32, or E35 user exit unchanged), DFSORT handles the user exit parameter list addresses (that is, the pointer to the parameter list and the addresses in the parameter list) as follows: If the user exit is entered with 24-bit addressing in effect, DFSORT passes clean (zeros in the first 8 bits) 24-bit addresses to the user exit. Such a user exit must pass 24-bit addresses back to DFSORT. These must be clean 24-bit addresses if the user exit returns to DFSORT with 31-bit addressing in effect. If the user exit is entered with 31-bit addressing in effect, DFSORT passes clean 24-bit addresses to the user exit. Such a user exit must pass 31-bit addresses or clean 24-bit addresses back to DFSORT. The only exception is when the high-order byte is used to identify an optional address being passed (for example, E18 SYNAD address). In this case, DFSORT cleans the 24-bit address. Note: For a conventional merge or tape work data set sort application, user exits: must reside below 16MB virtual must use 24-bit addressing mode must not use a user exit address constant.

How User Exit Routines Affect DFSORT Performance

Before writing a user exit routine, consider the following factors: v Your routines occupy main storage that would otherwise be available to DFSORT. Because its main storage is restricted, DFSORT might need to perform extra passes to sort the data. This, of course, increases sorting time. v User exit routines increase the overall run-time. Attention: Several of the user exits give your routine control once for each record until you pass a do not return return code to DFSORT. You must remember this when designing your routines. v Using INCLUDE, OMIT, INREC, OUTFIL, OUTREC, and SUM instead of user exit routines allows DFSORT to perform more efficiently.

Summary of Rules for User Exit Routines

When preparing your routines, remember that: v User-written routines must follow standard linkage conventions and use the required interfaces. COBOL E15 and E35 user exits must use the special interface provided. v To use an E32 user exit, your invoking program must pass its address to DFSORT in the parameter list.

420

z/OS V1R10.0 DFSORT Application Programming Guide

Summary of Rules for User Exit Routines

v To use any other user exit, you must associate your routine with the appropriate user exits using the MODS control statement. See MODS Control Statement on page 160. v Your invoking program can alternatively pass the address of an E15, E18, E35, and E39 user exit to DFSORT in the parameter list. v When Blockset or Peerage/Vale is used and your user exits are reenterable, the entire DFSORT program is reenterable. v If you are using ISCII/ASCII input, remember that data presented to your user exits at user exits are in EBCDIC format. If the E61 user exit is used to resolve ISCII/ASCII collating for special alphabetic characters, substituted characters must be in EBCDIC, but the sequencing result depends on the byte value of the ISCII/ASCII translation for the substituted character.

Loading User Exit Routines

You must assemble or compile each user exit as a separate program. If your user exit operates independently, link-edit it separately into a partitioned data set (library) with the member name to be used in the MODS statement. If your user exit operates in conjunction with other user exits in the same phase (for example, E11, E15, and E17 user exits all use the same DCB), you can request DFSORT to dynamically link-edit them together (see MODS statement). Alternatively, you can link-edit them together into a partitioned data set following these rules: 1. Specify RENT as a linkage editor parameter. 2. Include an ALIAS statement for each user exit using the external entry name of the routine (for example, the CSECT name). 3. Specify the appropriate ALIAS name for each user exit on the MODS statement. DFSORT includes the names and locations of your user exits in the list of modules to be run during each phase. No user exit is loaded more than once in a program phase, but the same user exit can appear in different phases. For example, you can use the same Read Error user exit in both phases, but not twice in one phase. The length you specify for a user exit must include storage for the user exit itself as well as any storage used by the user exit outside of the load modules such as I/O buffers or COBOL library subroutines. If you specify a ddname for a user exit in the MODS statement, it must match the DD statement that defines the library containing that user exit. For example:
//MYLIB DD DSNAME=MYRTN, etc. . . . MODS E15=(MODNAME,500,MYLIB,N)

User Exit Linkage Conventions

To enter a user exit, DFSORT loads the address of the DFSORT return point in register 14 and the address of the user exit routine in register 15. A branch to the address in register 15 is then performed. The general registers used by DFSORT for linkage and communication of parameters observe operating system conventions. When your routine gets control, the general registers have the following contents: Register Contents
Chapter 4. Using Your Own User Exit Routines

421

Summary of Rules for User Exit Routines

1 13 DFSORT places the address of a parameter list in this register. DFSORT places the address of a standard save area in this register. The area can be used to save contents of registers used by your user exit. The first word of the area contains the characters SM1 in its three low-order bytes. Contains the address of DFSORT return point. Contains the address of your user exit. This register can be used as a base register for your user exit; your user exit can also use it to pass return codes to DFSORT.

14 15

You can return control to DFSORT by performing a branch to the DFSORT return point address in register 14 or by using a RETURN macro instruction. The RETURN instruction can also be used to set return codes when multiple actions are available at a user exit. Your user exit must save all the general registers it uses. You can use the SAVE macro instruction to do this. If you save registers, you must also restore them; you can do this with the RETURN macro instruction.

Linkage Examples
When calling your user exit, DFSORT places the return address in general register 14 and your routines entry point address in general register 15. DFSORT has already placed the registers save area address in general register 13. DFSORT then makes a branch to your routine. Your routine for the E15 user exit might incorporate the following assembler instructions:
ENTRY E15 . . E15 SAVE (5,9) . . RETURN (5,9)

This coding saves and restores the contents of general registers 5 through 9. The macro instructions are expanded into the following assembler language code:
ENTRY E15 . . E15 STM 5,9,40(13) . . LM 5,9,40(13) BR 14

If multiple actions are available at a user exit, your routine sets a return code in general register 15 to inform DFSORT of the action it is to take. The following macro instruction can be used to return to DFSORT with a return code of 12 in register 15:
RETURN RC=12

A full explanation of linkage conventions and the macro instructions discussed in this section is in z/OS DCE Application Development Reference

422

z/OS V1R10.0 DFSORT Application Programming Guide

Summary of Rules for User Exit Routines

Dynamically Link-Editing User Exit Routines

You can dynamically link-edit any user exit routine written in any language that has the ability to pass the location or address of a record or parameter in general register 1 and a return code in register 15 (see MODS statement). This does not include E15 and E35 user exits written in COBOL. Dynamic link-editing does not support AMODE 31 or RMODE 31 for the link-edit option T. The user exits that are link-edited together by DFSORT are not loaded above 16MB virtual and cannot be entered in 31-bit addressing mode. User exits link-edited with the S option retain the AMODE and RMODE attributes of the object modules and are loaded above or below 16MB virtual depending upon the load modules RMODE; they are entered in the addressing mode of the user exit. Notes: 1. The Blockset technique is not used for dynamic link-editing. 2. Dynamic link-editing cannot be used with copy. When the link-edit option T is specified for a user exit routine, that routine must contain an entry point whose name is that of the associated program user exit. This is to accommodate special DFSORT dynamic link-edit requirements. For example, when the link-edit option T is specified on the MODS statement for E35, the following assembler instructions must be included in the user exit routine associated with the E35 user exit:
ENTRY E35 . .

E35

or
E35 CSECT . .

In all other circumstances, the user exit is not required to have an entry point that has the same name as that of the associated program user exit.

Assembler User Exit Routines (Input Phase User Exits)

You can use these program user exits in the DFSORT input phase: E11 E15 E16 E17 E18 E19 E61 These user exits are discussed in sequence. To determine whether a particular user exit can be used for your application, refer to Table 51 on page 417 and Table 52 on page 417.

E11 User Exit: Opening Data Sets/Initializing Routines

You might use routines at this user exit to open data sets needed by your other routines in the input phase. It can also be used to initialize your other routines. Return codes are not used, however.

Chapter 4. Using Your Own User Exit Routines

423

Assembler User Exit Routines (Input Phase User Exits)

Note: To avoid special linkage editor requirements (see Summary of Rules for User Exit Routines on page 420), you can include these functions in your E15 user exit rather than in a separate E11 user exit routine.

E15 User Exit: Passing or Changing Records for Sort and Copy Applications
If you write your E15 user exit in COBOL, see COBOL User Exit Routines on page 443 and COBOL E15 User Exit: Passing or Changing Records for Sort on page 445. The EXITCK option affects the way DFSORT interprets certain return codes from user exit E15. To avoid ambiguity, this section assumes that the IBM default, EXITCK=STRONG, was selected at your site. For complete information about E15 return codes in various situations with EXITCK=STRONG and EXITCK=WEAK, see E15/E35 Return Codes and EXITCK on page 458. DFSORT enters the E15 user exit routine each time a new record is brought into the input phase. DFSORT continues to enter E15 (even when there are no input records) until the user exit tells DFSORT, with a return-code of 8, not to return. See Figure 15 on page 415 for logic flow details. Some uses for the E15 user exit are: v Adding records to an input data set v Passing an entire input data set to DFSORT v Deleting records from an input data set v Changing records in an input data set. Notes: 1. If your E15 user exit is processing variable-length records, include a 4-byte RDW at the beginning of each record you change or insert, before you pass it back to DFSORT. The format of an RDW is described in z/OS DFSMS Using Data Sets or System Programming Reference. (Alternatively, you can pad records to the maximum length and process them as fixed-length.) 2. DFSORT uses the specified or defaulted value for L2 in the RECORD statement to determine the length of the records your E15 user exit passes back to DFSORT. For fixed-length records, be sure that the length of each record your E15 user exit changes or inserts corresponds to the specified or defaulted L2 value. For variable-length records, be sure that the RDW of each record your E15 user exit changes or inserts indicates a length that is less than or equal to the specified or defaulted L2 value. Unwanted truncation or abends may occur if DFSORT uses the wrong length for the records passed to it by your E15 user exit. For details of the L2 value, see RECORD Control Statement on page 394. 3. If you use the E15 user exit to pass all your records to DFSORT, you can omit the SORTIN DD statement, in which case you must include a RECORD statement in the program control statements. 4. If you invoke DFSORT from an assembler program and pass the address of your E15 user exit in the parameter list, DFSORT ignores the SORTIN data set and terminates if you specify E15 in a MODS statement. 5. If you omit the SORTIN DD statement, or it is ignored, all input records are passed to DFSORT through your routine at user exit E15. The address of each input record in turn is placed in general register 1, and you return to DFSORT with a return code of 12. When DFSORT returns to the E15 user exit after the

424

z/OS V1R10.0 DFSORT Application Programming Guide

Assembler User Exit Routines (Input Phase User Exits)

last record has been passed, you return to DFSORT with a return code of 8 in register 15, which indicates do not return. 6. DFSORT continues to reenter your E15 user exit until a return code of 8 is received. However, if STOPAFT is in effect, no additional records are inserted to DFSORT after the STOPAFT count is satisfied (even if you pass back a return code of 12). 7. An RDW must be built for variable-length VSAM records (see z/OS DFSMS Using Data Sets).

Information DFSORT Passes to Your Routine at E15 User Exit

Your E15 user exit routine is entered each time a new record is brought into the input phase. DFSORT passes two words to your routine each time it is entered: v The address of the new record. End of input is reached when there are no more records to pass to your E15 user exit; DFSORT indicates end of input by setting this address to zero before entering your E15 user exit. If there are no records in the input data set (or no input data set), this address is zero the first time your E15 is entered. After end of input is reached, DFSORT continues to enter your user exit routine until you pass back a return code of 8. Your E15 user exit must not change the address of the new record. v The user exit address constant. If you invoked DFSORT with a user exit address constant in the parameter list, the address constant is passed to your E15 user exit the first time it is entered. This address constant can be changed by your E15 user exit any time it is entered; the address constant is passed along on subsequent entries to your E15 user exit and also on the first entry to your E35 user exit. For example, you can obtain a dynamic storage area, use it in your E15 user exit, and pass its address to your E35 user exit. Note: The user exit address constant must not be used for a tape work data set sort application. In general register 1, DFSORT places the address of a parameter list that contains the record address and the user address constant. The list is two fullwords long and begins on a fullword boundary. The format of the parameter list is:
Table 53. E15 User Exit Parameter List Bytes 1 through 4 Bytes 5 through 8 Address of the new record User exit address constant

E15 Return Codes

Your E15 routine must pass a return code to DFSORT. Following are the return codes for the E15 user exit: Return Code 00 (X'00') 04 (X'04') 08 (X'08') 12 (X'0C') 16 (X'10') Description No Action/Record Altered Delete Record Do Not Return Insert Record Terminate DFSORT

0: No Action If you want DFSORT to retain the record unchanged, place the address of the record in general register 1 and return to DFSORT with a return code of 0 (zero).
Chapter 4. Using Your Own User Exit Routines

425

Assembler User Exit Routines (Input Phase User Exits)

0: Record Altered If you want to change the record before passing it back to DFSORT, your routine must move the record into a work area, perform whatever modification you want, place the address of the modified record in general register 1, and return with a return code of 0 (zero). 4: Delete Record If you want DFSORT to delete the record from the input data set, return to DFSORT with a return code of 4. You need not place the address of the record in general register 1. 8: Do Not Return DFSORT continues to return control to the user routine until it receives a return code of 8. After that, the user exit is not used again during the DFSORT application. You need not place an address in general register 1 when you return with a return code of 8. Unless you are inserting records after the end of the data set, you must pass a return code of 8 when the program indicates the end of the data set. It does this by passing your routine a zero address in the parameter list. If your user exit routine passes a return code of 8 to DFSORT when input records still remain to be processed, the remaining records are processed by DFSORT, but are not passed to your user exit. 12: Insert Record To add a record before the record whose address was just passed to your routine, place the address of the record to be added in general register 1 and return to DFSORT with a return code of 12. DFSORT keeps returning to your routine with the same record address as before so that your routine can insert more records at that point or alter the current record. You can make insertions after the last record in the input data set (after DFSORT places a zero address in the parameter list). DFSORT keeps returning to your routine until you pass a return code of 8. 16: Terminate DFSORT If you want to terminate DFSORT, return with a code of 16. DFSORT then returns to its calling program or to the system with a return code of 16. See E15/E35 Return Codes and EXITCK on page 458 for complete details of the meanings of return codes in various situations.

Storage Usage for E15 User Exit

DFSORT obtains storage (using GETMAIN or STORAGE OBTAIN) for the parameter list and the records it passes to your E15 user exit routine. You must not attempt to modify or free the storage obtained by DFSORT. If you need to obtain storage for use by your E15 user exit routine, such as to pass altered records to DFSORT, you can use the following strategy: 1. The first time your exit is called, obtain the storage you need 2. Use the storage you obtained each time your exit is called 3. Free the storage before you pass back return code 8 to DFSORT Note: When you obtain your storage you can save its address in the user exit address constant and restore it on each subsequent call to your exit.

426

z/OS V1R10.0 DFSORT Application Programming Guide

Assembler User Exit Routines (Input Phase User Exits)

E16 User Exit: Handling Intermediate Storage Miscalculation

For a tape work data set sort or a Peerage/Vale sort without work data sets, you would use a routine at this user exit to decide what to do if the sort exceeds its calculated estimate of the number of records it can handle for a given amount of main storage and intermediate storage. This user exit is ignored for a sort with work data sets because DFSORT uses the WRKSEC option to determine whether secondary allocation is allowed. See SORTWKdd DD Statement on page 72. See also Exceeding Tape Work Space Capacity on page 738. Note: When using magnetic tape, remember that the system uses an assumed tape length of 2400 feet. If you use tapes of a different length, the Nmax figure is not accurate; for shorter tapes, capacity can be exceeded before NMAX EXCEEDED is indicated.

E16 Return Codes

Your E16 routine must pass a return code to DFSORT. Following are the return codes for the E16 user exit: Return Code 00 (X'00') 04 (X'04') 08 (X'08') Description Sort Current Records Only Try to Sort Additional Records Terminate DFSORT

0: Sort Current Records Only If you want DFSORT to continue with only that part of the input data set it estimates it can handle, return with a return code of 0 (zero). Message ICE054I contains the number of records with which sort is continuing. You can sort the remainder of the data set on one or more subsequent runs, using SKIPREC to skip over the records already sorted. Then you can merge the sort outputs to complete the operation. 4: Try to Sort Additional Records If you want DFSORT to continue with all of the input data set, return with a return code of 4. If tapes are used, enough space might be available for DFSORT to complete processing. If enough space is not available, DFSORT generates a message and terminates. Refer to Exceeding Tape Work Space Capacity on page 738. 8: Terminate DFSORT If you want DFSORT to terminate, return with a return code of 8. DFSORT then returns to its calling program or to the system with a return code of 16.

E17 User Exit: Closing Data Sets

Your E17 user exit routine is entered once at the end of the input phase. It can be used to close data sets used by your other routines in the phase or to perform any housekeeping functions for your routines. Note: To avoid special linkage editor requirements (see Summary of Rules for User Exit Routines on page 420), you can include these functions in your E15 user exits rather than in a separate E17 user exit routine.

E18 User Exit: Handling Input Data Sets

You can use this user exit to handle special I/O conditions for QSAM/BSAM and VSAM input data sets.

Chapter 4. Using Your Own User Exit Routines

427

Assembler User Exit Routines (Input Phase User Exits)

Using E18 User Exit with QSAM/BSAM

Your routines at this user exit can pass DFSORT a parameter list containing the specifications for three data control block (DCB) fields: SYNAD, EXLST, and EROPT. Your E18 user exit routine can also pass a fourth DCB field (EODAD) to DFSORT. Note: If you are using a disk sorting technique, the EROPT option is ignored. Your routines are entered at the beginning of each phase so that DFSORT can obtain the parameter lists. The routines are entered again during processing of the phase at the points indicated in the parameter lists. For example, if you choose the EXLST option, DFSORT enters your E18 user exit routine early in the sort (input) phase. DFSORT picks up the parameter list including the EXLST address. Later in the phase, DFSORT enters your routine again at the EXLST address when the data set is opened. Information Your Routine Passes to DFSORT at E18 User Exit: Before returning control to DFSORT, your routine passes the DCB fields in a parameter list by placing the parameter list address in general register 1. The parameter list must begin on a fullword boundary and be a whole number of fullwords long. The high-order byte of each word must contain a character code that identifies the parameter. One or more of the words can be omitted. A word of all zeros marks the end of the list. If VSAM parameters are specified, they are accepted but ignored. The format of the list is shown as follows:
Byte 1 01 02 03 04 00 00 00 Byte 2 Byte 3 SYNAD field EXLST field 00 EODAD field 00 00 EROPT code Byte 4

SYNAD Contains the location of yourread synchronous error routine. This routine is entered only after the operating system has tried unsuccessfully to correct the error. The routine must be assembled as part of your E18 user exit routine. When the routine receives control, it must not store registers in the save area pointed to by register 13. EXLST Contains the location of a list of pointers to routines that you want used to check labels and accomplish other tasks not handled by data management. The list, and the routines to which it points, must be included in your read error routine. This parameter can only be used for EXLST routines associated with opening the first SORTIN data set. EROPT Indicates what action DFSORT must take when it encounters an uncorrectable read error. The three possible actions and the codes associated with them are: X'80' Accept the record (block) as is X'40' Skip the record (block) X'20' Terminate the program.

428

z/OS V1R10.0 DFSORT Application Programming Guide

Assembler User Exit Routines (Input Phase User Exits)

If you include this parameter in the DCB field list, you must place one of the above codes in byte 4 of the word. Bytes 2 and 3 of the word must contain zeros. When you use the EROPT option, the SYNAD field and the EODAD field must contain the appropriate address in bytes 2 through 4. Or, if no routine is available, bytes 2 and 3 must contain zeros, and byte 4 must contain X'01'. You can use the assembler instruction DC AL3(1) to set up bytes 2 through 4. EODAD Contains the address of your end-of-file routine. If you specify EODAD, you must include the end-of-file routine in your own routine. A full description of these DCB fields is contained in z/OS DFSMS Macro Instructions for Data Sets.

Using E18 User Exit with VSAM

If input to DFSORT is a VSAM data set, you can use the E18 user exit to perform various VSAM user exit functions and to insert passwords in VSAM input ACBs. E18 User Exit Restrictions: If passwords are to be entered through a user exit and Blockset is not selected, the data set cannot be opened during the initialization phase. This means that MAINSIZE|SIZE=MAX must not be used because the program cannot make the necessary calculations. Information Your Routine Passes to DFSORT at E18 User Exit: When you return to DFSORT, you must place the address of a parameter list in general register 1:
Byte 1 05 06 00 Bytes 2 through 4 Address of VSAM user exit list Address of password list 000000

If QSAM parameters are passed instead, they are accepted but ignored. Either address entry can be omitted; if they both are included, they can be in any order. E18 Password List: A password list included in your routine must have the following format: Two bytes on a halfword boundary:
Number of entries in list

Followed by the 16-byte entries:

8 bytes: ddname 8 bytes: Password

The last byte of the ddname field is destroyed by DFSORT. This list must not be altered at any time during the program. MAINSIZE|SIZE=MAX must not be used if this function is used.

Chapter 4. Using Your Own User Exit Routines

429

Assembler User Exit Routines (Input Phase User Exits)

E18 User Exit List: The VSAM user exit list must be built using the VSAM EXLST macro instruction giving the addresses of your routines handling VSAM user exit functions. VSAM branches directly to your routines which must return to VSAM via register 14. Any VSAM user exit function available for input data sets can be used except EODAD. If you need to do EODAD processing, write a LERAD user exit and check for X'04' in the FDBK field of the RPL. This will indicate input EOD. This field must not be altered when returning to VSAM because it is also needed by DFSORT. For details, see z/OS DFSMS Macro Instructions for Data Sets.

430

z/OS V1R10.0 DFSORT Application Programming Guide

Assembler User Exit Routines (Input Phase User Exits)

Figure 16 shows an example of code your program can use to return control to DFSORT.
E18 . . E18 LA RETURN CNOP PARMLST DC DC DC DC DC DC DC DC DC DC DC DC DC DC . . VSAMEXL EXLST PWDLST DC DC DC USYNAD ... ULERAD ... SER ... LST DC RTN ... QSAMEOD ... ENTRY

1,PARMLST 0,4 X01 AL3(SER) X02 AL3(LST) X03 X000080 A(0) X04 AL3(QSAMEOD) X05 AL3(VSAMEXL) X06 AL3(PWDLST) A(0)

EROPT CODE

SYNAD=USYNAD,LERAD=ULERAD H1 CL8SORTIN SORTIN DDNAME CL8INPASS SORTIN PASSWORD VSAM SYNCH ERROR RTN VSAM LOGIC ERROR RTN QSAM ERROR RTN X85,AL3(RTN) EXLST ADDRESS LIST1 EXLST ROUTINE QSAM END OF FILE ROUTINE

Figure 16. E18 User Exit Example

1

X'85'= X'80' plus X'05', where: X'80' means this entry is the LAST ENTRY of the list. X'05' means this user exit is the data control block user exit.

For more information, refer to z/OS DFSMS Using Data Sets.

E19 User Exit: Handling Output to Work Data Sets

This user exit is used to handle write error conditions in the input phase when DFSORT is unable to correct a write error to a work data set. It is used only for a tape work data set sort.

Using E19 User Exit with QSAM/BSAM

Your routines at this user exit can pass DFSORT a parameter list containing the specifications for two DCB fields (SYNAD and EXLST). Your routines are entered first early in the input phase so that DFSORT can obtain the parameter lists. The routines are entered again later in the phase at the points indicated by the options in the parameter lists. Information Your Routine Passes to DFSORT at E19 User Exit: Before returning control to DFSORT, your routine passes the DCB fields in a parameter list by placing the parameter list address in general register 1. The list must begin on a fullword boundary and must be a whole number of fullwords long. The first byte of each word must contain a character code that identifies the parameter. Either word can be omitted. A word of all zeros indicates the end of the list. If VSAM parameters are passed, they are accepted but ignored.

Chapter 4. Using Your Own User Exit Routines

431

Assembler User Exit Routines (Input Phase User Exits)

The format of the list is shown below.
Byte 1 01 02 00 00 Byte 2 Byte 3 SYNAD field EXLST field 00 00 Byte 4

SYNAD This field contains the location of your write synchronous error routine. This routine is entered only after the operating system has unsuccessfully tried to correct the error. It must be assembled as part of your own routine. EXLST The EXLST field contains the location of a list of pointers. These pointers point to routines that are used to process labels and accomplish other tasks not handled by data management. This list, and the routines to which it points, must be included as part of your own routine. A full description of these DCB fields can be found in z/OS DFSMS Macro Instructions for Data Sets.

E61 User Exit: Modifying Control Fields

You can use a routine at this user exit to lengthen, shorten, or alter any control field within a record. The E option for the s parameter on the SORT or MERGE control statement must be specified for control fields changed by this routine as described in MERGE Control Statement on page 156 and SORT Control Statement on page 398. After your routine modifies the control field, DFSORT collates the records in ascending order using the format(s) specified.17 Notes: 1. Routine E61 will not be used with EFS fields that have a D1 format. 2. Although your E61 routine alters control fields before a compare, your original records are not altered. 3. If locale processing is used for SORT or MERGE fields, an E61 user exit must not be used. DFSORTs locale processing may eliminate the need for an E61 user exit. See OPTION Control Statement on page 167 for information related to locale processing.

Some Uses of E61 User Exit

Your routine can normalize floating-point control fields or change any other type of control field in any way that you desire. You need to be familiar with the standard data formats used by the operating system before modifying control fields. If you want to modify the collating sequence of EBCDIC data, for example, to permit the alphabetic collating of national characters, you can do so without the need for an E61 user exit routine by using the ALTSEQ control statement (as described in ALTSEQ Control Statement on page 89).

17. With a conventional merge or a tape work data set sort, control fields for which E is specified are treated as binary byte format regardless of the actual format(s) specified.

432

z/OS V1R10.0 DFSORT Application Programming Guide

Assembler User Exit Routines (Input Phase User Exits)

Information DFSORT Passes to Your Routine at E61 User Exit

DFSORT places the address of a parameter list in general register 1. The list begins on a fullword boundary and is three fullwords long. The parameter list for the E61 user exit is as follows:
Byte 1 00 00 Not Used Byte 2 00 Byte 3 00 Byte 4 Control Field No.

Address of Control Field Image Control Field Length

The control field length allows you to write a more generalized modification routine. To alter the control field, change the control field image at the indicated address (changing the address itself will have no effect). The control field number is relative to all fields in the SORT or MERGE statement. For example, if you specify:
SORT FIELDS=(4,2,CH,A,8,10,CH,E,25,2,BI,E)

field numbers 2 and 3 will be passed to user exit E61. For all fields except binary, the total number of bytes DFSORT passes to your routine is equal to the length specified in the m parameter of the SORT or MERGE statement. All binary fields passed to your routine contain a whole number of bytes; all bytes that contain any bits of the control field are passed. If the control field is longer than 256 bytes, DFSORT splits it into fields of 256 bytes each and passes them one at a time to your routine. Your routine cannot physically change the length of the control field. If you must increase the length for collating purposes, you must previously specify that length in the m parameter of the SORT or MERGE statement. If you must shorten the control field, you must pad it to the specified length before returning it to DFSORT. Your routine must return the field to DFSORT with the same number of bytes that it contained when your routine was entered. When user exit E61 is used, records are always ordered into ascending sequence. If you need some other sequence, you can modify the fields further; for example, if after carrying out your planned modification for a binary control field, and before handing back control to DFSORT, you reverse all bits, the field is, in effect, collated in descending order as illustrated by the E61 example in Figure 22 on page 443. Note that if E61 is used to resolve ISCII/ASCII collating for special alphabetic characters, substituted characters must be in EBCDIC, but the sequencing depends upon the byte value of the ISCII/ASCII translation for the substituted character.

Assembler User Exit Routines (Output Phase User Exits)

You can use these program user exits located in the DFSORT output phase: E31 E32 E35
Chapter 4. Using Your Own User Exit Routines

433

Assembler User Exit Routines (Output Phase User Exits)

E37 E38 E39 The functions of these user exits are discussed in sequence.

E31 User Exit: Opening Data Sets/Initializing Routines

You might use routines at this user exit to open data sets needed by your other routines in the output phase or to initialize your other routines. Return codes are not used. Note: To avoid special linkage editor requirements (see Summary of Rules for User Exit Routines on page 420), you can include these functions in your E35 user exit rather than in a separate E31 routine.

E32 User Exit: Handling Input to a Merge Only

This user exit can be used only in a merge operation invoked from a program and cannot be specified on the MODS statement. When an E32 user exit is activated, it must supply all input to the merge. DFSORT ignores SORTINnn data sets when an E32 user exit is used. You must indicate the number of input files you want to merge using either (1) the FILES=n option on the MERGE control statement, or (2) the X'04' entry in the 24-bit parameter list. Your E32 user exit routine must insert records for these files as DFSORT requests them. If input is variable-length records, you must be sure the beginning of each record contains a 4-byte RDW before merged. The format of an RDW is described in z/OS DFSMS Macro Instructions for Data Sets (Alternatively, you can declare the records as fixed-length and pad them to the maximum length.) See Figure 15 on page 415 for logic flow details.

Information DFSORT Passes to Your Routine at E32 User Exit

Your E32 user exit routine is entered each time the merge program requires a new input record. DFSORT passes three words to your routine: v The increment of the next file to be used for input. The file increment is 0,4,8,...,N4, where N is four times the number of input files. Thus, the increment 0 (zero) represents the first input file, 4 the second file, 8 the third, and so on. v The address of the next input record. Your routine must provide a separate input buffer for each input file used. An input buffer containing the first record for a file must not be altered until you have passed the first record from each file to DFSORT. v The user exit address constant. If you invoked DFSORT with a user exit address constant in the parameter list, the address constant is passed to your E32 user exit the first time it is entered. This address constant can be changed by your E32 user exit any time it is entered; the address constant is passed along on subsequent entries to your E32 user exit and E35 user exit. For example, you can obtain a dynamic storage area, use it in your E32 user exit, and pass its address to your E35 user exit. Note: The user exit address constant must not be used for a Conventional merge application.

434

z/OS V1R10.0 DFSORT Application Programming Guide

Assembler User Exit Routines (Output Phase User Exits)

In general register 1, DFSORT places the address of a parameter list that contains the file increment, the record address and the user address constant. The list is three fullwords long and begins on a fullword boundary. The format of the parameter list is:
Table 54. E32 User Exit Parameter List Bytes 1 through 4 Bytes 5 through 8 Bytes 9 through 12 Increment of next file to be used for input Address of next input record User exit address constant

Before returning control to DFSORT, you must: v Place the address of the next input record from the requested input file in the second word of the parameter list v Put the return code in register 15.

E32 Return Codes

Your E32 routine must pass a return code to DFSORT. Following are the return codes for the E32 user exit: Return Code 08 (X'08') 12 (X'0C') 16 (X'10') Description End of input for requested file Insert record Terminate DFSORT

8: End of input for requested file DFSORT continues to return control to the user routine until it receives a return code of 8 for every input file. After that, the user exit is not used again during the DFSORT application. You need not place an address in the second word of the parameter list when you return with a return code of 8. 12: Insert Record To add a record from the requested input file, place the address of the record to be added in the second word of the parameter list and return to DFSORT with a return code of 12. DFSORT keeps returning to your routine until you pass a return code of 8 for every input file. 16: Terminate DFSORT If you want to terminate DFSORT, return with a code of 16. DFSORT then returns to its calling program with a return code of 16.

E35 User Exit: Changing Records

If you write your E35 user exit in COBOL, see COBOL User Exit Routines on page 443 and COBOL E35 User Exit: Changing Records on page 451. The EXITCK option affects the way DFSORT interprets certain return codes from user exit E35. To avoid ambiguity, this section assumes that the IBM default, EXITCK=STRONG, was selected at your site. For complete details of the meaning of E35 return codes in various situations with EXITCK=STRONG and EXITCK=WEAK, see E15/E35 Return Codes and EXITCK on page 458. DFSORT enters the E35 user exit routine each time it prepares to place a record in the output area. See Figure 15 on page 415 for logic flow details. Some uses for the E35 user exit are:
Chapter 4. Using Your Own User Exit Routines

435

Assembler User Exit Routines (Output Phase User Exits)

v Adding records for output data sets v Omitting records for output data sets v Changing records for output data sets Notes: 1. If your E35 user exit is processing variable-length records, include a 4-byte RDW at the beginning of each record you change or insert, before you pass it back to DFSORT. The format of an RDW is described in z/OS DFSMS Using Data Sets or System Programming Reference. (Alternatively, you can pad records to the maximum length and process them as fixed-length.) 2. DFSORT uses the specified or defaulted value for L3 in the RECORD statement to determine the length of the records your E35 user exit passes back to DFSORT. For fixed-length records, be sure that the length of each record your E35 user exit changes or inserts corresponds to the specified or defaulted L3 value. For variable-length records, be sure that the RDW of each record your E35 user exit changes or inserts indicates a length that is less than or equal to the specified or defaulted L3 value. Unwanted truncation or abends may occur if DFSORT uses the wrong length for the records passed to it by your E35 user exit. For details of the L3 value, see RECORD Control Statement on page 394. 3. If you use the E35 user exit to dispose of all your output records, you can omit the SORTOUT DD statement. 4. If you invoke DFSORT from a program and you pass the address of your E35 user exit in the parameter list: v DFSORT ignores the SORTOUT data set (but not any OUTFIL data sets). v DFSORT terminates if you specify E35 in a MODS statement. 5. If you omit the SORTOUT DD statement or it is ignored, and you do not specify any OUTFIL data sets, your E35 user exit routine must dispose of each output record and return to DFSORT with a return code of 4. When DFSORT returns to your routine after you have disposed of the last record, return to DFSORT with a return code of 8 to indicatedo not return. 6. Remember that if input records are variable-length from a VSAM data set, they will have been prefixed by a 4-byte RDW. 7. After records have been put into the output area, their lengths cannot be increased. 8. For a merge application, records deleted by an E35 user exit routine are not sequence-checked. If you use an E35 user exit routine without an output data set, sequence checking is not performed. In this case, you must ensure that the records are sequenced correctly.

Information DFSORT Passes to Your Routine at E35 User Exit

Your E35 user exit routine is entered each time DFSORT prepares to place a record (including the first record) in the output area. DFSORT passes three words to your routine: v The address of the record leaving DFSORT, which usually follows the record in the output area. End of input is reached when there are no more records to pass to your E35 user exit; DFSORT indicates end of input by setting this address to zero before entering your E35 user exit. After end of input is reached, DFSORT continues to enter your user exit routine until a return code of 8 is passed back. Your E35 user exit must not change the address of the record leaving DFSORT.

436

z/OS V1R10.0 DFSORT Application Programming Guide

Assembler User Exit Routines (Output Phase User Exits)

v The address of a record in the output area is zero the first time your routine is entered because there is no record in the output area at that time. It remains zero provided you pass a return code of 4 (delete record) to DFSORT. Note: If the record pointed to is variable-length, it has an RDW at this point even if output is to a VSAM data set. v The user exit address constant is passed to your user exit exactly as it was set by your E15 or E32 user exit or invoking programs parameter list. Note: The user exit address constant must not be used for a Conventional merge or tape work data set sort application. In general register 1, DFSORT places the address of a parameter list that contains the two record addresses and the user address constant. The list is three fullwords long and begins on a fullword boundary. The format of the parameter list is:
Table 55. E35 User Exit Parameter List Bytes 1 through 4 Bytes 5 through 8 Bytes 9 through 12 Address of record leaving DFSORT Address of record in output area User exit address constant

E35 Return Codes

Your E35 routine must pass a return code to DFSORT. Following are the return codes for the E35 user exit: Return Code 00 (X'00') 04 (X'04') 08 (X'08') 12 (X'0C') 16 (X'10') Description No Action/Record Altered Delete Record Do Not Return Insert Record Terminate DFSORT

0: No Action If you want DFSORT to retain the record unchanged, load the address of the record leaving DFSORT in general register 1 and return to DFSORT with a return code of 0 (zero). 0: Record Altered If you want to change the record before having it placed in the output data set, move the record to a work area, make the change, load the address of the modified record into general register 1, and return to DFSORT with a return code of 0 (zero). 4: Delete Record Your routine can delete the record leaving DFSORT by returning to DFSORT with a return code of 4. You need not place an address in general register 1. 8: Do Not Return DFSORT keeps returning to your routine until you pass a return code of 8. After that, the user exit is not used again during the DFSORT application. When you return with a return code of 8, you need not place an address in general register 1. Unless you are inserting records after the end of the data set, you must pass a return code of 8 when DFSORT indicates the end of the data set. This is done by passing a zero as the address of the record leaving DFSORT. If you do not have an output data set and would usually return with a return code of 8 before EOF, you can avoid getting the ICE025A message by
Chapter 4. Using Your Own User Exit Routines

437

Assembler User Exit Routines (Output Phase User Exits)

| specifying NOCHECK on the OPTION control statement (if installation option CHECK=NO had not already been specified). If your user exit routine passes a return code of 8 to DFSORT when input records still remain to be processed, the remaining records are processed by DFSORT, but are not passed to your user exit. 12: Insert Record To add an output record ahead of the record leaving DFSORT, place the address of the new record in general register 1 and return to DFSORT with a return code of 12. DFSORT returns to your routine with the same address as passed on the previous call to the user exit for the record leaving DFSORT. DFSORT passes the address of the inserted record as the address of the record in the output area. You can make more insertions at that point, or delete the record leaving DFSORT. DFSORT does not perform sequence checking for disk work data set sorts. For tape work data set sorts, DFSORT does not perform sequence checking on records that you insert unless you delete the record leaving DFSORT and insert a record to replace it. DFSORT keeps returning to your routine until you pass a return code of 8. 16: Terminate DFSORT If you want to terminate DFSORT, return with a code of 16. DFSORT then returns to its calling program or to the system with a return code of 16. See E15/E35 Return Codes and EXITCK on page 458 for complete details of the meanings of return codes in various situations. Summing Records at E35 User Exit: You can use the SUM control statement to sum records. However, you can sum records for output by changing the record in the output area and then, if you want, by deleting the record leaving DFSORT. DFSORT returns to your routine with the address of a new record leaving DFSORT, and the same record remains in the output area, so that you can continue summing. If you do not delete the record leaving DFSORT, that record is added to the output area, and its address replaces the address of the previous record in the output area. DFSORT returns with the address of a new record leaving DFSORT.

Storage Usage for E35 User Exit

DFSORT obtains storage (using GETMAIN or STORAGE OBTAIN) for the parameter list and the records it passes to your E35 user exit routine. You must not attempt to modify or free the storage obtained by DFSORT. If you need to obtain storage for use by your E35 user exit routine, such as to pass altered records to DFSORT, you can use the following strategy: 1. The first time your exit is called, obtain the storage you need 2. Use the storage you obtained each time your exit is called 3. Free the storage before you pass back return code 8 to DFSORT. Note: When you obtain your storage you can save its address in the user exit address constant and restore it on each subsequent call to your exit.

E37 User Exit: Closing Data Sets

Your E37 user exit routine is entered once at the end of the output phase. It can be used to close data sets used by your other routines in the phase or to perform any housekeeping functions for your routines.

438

z/OS V1R10.0 DFSORT Application Programming Guide

Assembler User Exit Routines (Output Phase User Exits)

Note: To avoid special linkage editor requirements (see Summary of Rules for User Exit Routines on page 420), you can include these functions in your E35 user exit rather than in a separate E37 user exit.

E38 User Exit: Handling Input Data Sets

The routine here is the same as for E18. If the Blockset or Peerage/Vale technique is selected, I/O error conditions cannot be handled through the E38 user exit.

Using E38 User Exit with VSAM

This user exit can be used during a merge or copy to insert VSAM passwords into VSAM input ACBs and to perform various VSAM user exit functions. The following example shows code your program can use to return control to DFSORT.
ENTRY E38 . . E38 LA 1,PARMLST RETURN CNOP 0,4 PARMLST DS 0H DC X05 DC AL3(VSAMEXL) DC X06 DC AL3(PWDLST) DC A(0) . . VSAMEXL EXLST SYNAD=USYNAD,LERAD=ULERAD PWDLST DC H2 DC CL8SORTIN01 SORTIN01 DDNAME DC CL8INPASS1 SORTIN01 PASSWORD DC CL8SORTIN02 SORTIN02 DDNAME DC CL8INPASS2 SORTIN02 PASSWORD USYNAD ... VSAM SYNCH ERROR RTN ULERAD ... VSAM LOGIC ERROR RTN

Figure 17. E38 User Exit Example

E39 User Exit: Handling Output Data Sets

Your E39 user exit routine is entered for the SORTOUT data set, but not for OUTFIL data sets.

Using E39 User Exit with QSAM/BSAM

The technique is the same as for E19 for QSAM/BSAM. See E19 User Exit: Handling Output to Work Data Sets on page 431 for details.

Using E39 User Exit with VSAM

For VSAM, this user exit can be used to insert VSAM passwords intothe VSAM SORTOUT ACB and to perform various VSAM user exit functions. The example below shows code your program can use to return control to DFSORT.

Chapter 4. Using Your Own User Exit Routines

439

Sample Routines Written in Assembler

ENTRY . . E39 LA RETURN CNOP PARMLST DS DC DC DC DC DC . . VSAMEXL EXLST PWDLST DC DC DC USYNAD ... ULERAD ...

E39 1,PARMLST 0,4 0H X05 AL3(VSAMEXL) X06 AL3(PWDLST) A(0) SYNAD=USYNAD,LERAD=ULERAD H1 CL8SORTOUT SORTOUT DDNAME CL8OUTPASS SORTOUT PASSWORD VSAM SYNCH ERROR RTN VSAM LOGIC ERROR RTN

Figure 18. E39 User Exit Example

Sample Routines Written in Assembler

This section provides some sample program user exits written in assembler.

E15 User Exit: Altering Record Length

This routine changes the variable-length input records making them all the same length.

440

z/OS V1R10.0 DFSORT Application Programming Guide

Sample Routines Written in Assembler

E15 CSECT * IF A RECORD IS GREATER THAN 204 BYTES, TRUNCATE IT TO 204 BYTES. * IF A RECORD IS LESS THAN 204 BYTES, PAD IT OUT TO 204 BYTES. * ALL OF THE RESULTING RECORDS WILL BE 204 BYTES LONG * (4 BYTES FOR THE RDW AND 200 BYTES OF DATA). USING E15,12 SHOW BASE REG STM 14,12,12(13) SAVE ALL REGS EXCEPT 13 LA 12,0(0,15) SET BASE REG ST 13,SAVE15+4 SAVE BACKWARD POINTER LA 14,SAVE15 SET FORWARD POINTER ST 14,8(13) IN SAVE AREA LR 13,14 SET OUR SAVE AREA LR 2,1 SAVE PARM LIST POINTER L 3,0(,2) LOAD ADDR OF RECORD LTR 3,3 EOF BZ EOF YES - DO NOT RETURN LH 4,0(,3) GET RDW CH 4,CON204 IS RDW EQ 204 BE ACCEPT YES-ACCEPT IT BL PAD LESS THAN 204-PAD LH 4,CON204 LIMIT LENGTH TO 204 B TRUNC MORE THAN 204-TRUNCATE PAD DS 0H PAD OR TRUNCATE MVI DATA,X00 ZERO OUT THE BUFFER MVC DATA+1(199),DATA TRUNC DS 0H PAD OR TRUNCATE BCTR 4,0 DECREASE RDW FOR EXECUTE EX 4,MVPAD MOVE RECORD INTO PAD/TRUNCATE BUFFER MVC NEWRDW(2),CON204 SET NEW RDW TO 204 LA 3,BUFFER POINT TO PADDED/TRUNCATED RECORD ACCEPT DS 0H SR 15,15 SET RC=0 LR 1,3 SET RECORD POINTER B GOBACK EOF LA 15,8 EOF - SET RC=8 GOBACK L 13,4(,13) L 14,12(,13) LM 2,12,28(13) RESTORE REGS BR 14 RETURN MVPAD MVC BUFFER(*-*),0(3) FOR EXECUTE SAVE15 DS 18F CON204 DC H204 BUFFER DS 0H NEWRDW DS H NEW RDW OF 204 DC H0 DATA DC XL20000 BUFFER FOR PADDING/TRUNCATING END

Figure 19. E15 User Exit Example

E16 User Exit: Sorting Current Records When NMAX Is Exceeded

This routine tells DFSORT that, when DFSORT issues the message NMAX EXCEEDED, it must sort only the records already read in.
E16 CSECT LA BR END

15,0 14

SET RETURN CODE

Figure 20. E16 User Exit Example

E35 User Exit: Altering Record Length

This routine changes the variable-length output records making them all the same length.

Chapter 4. Using Your Own User Exit Routines

441

Sample Routines Written in Assembler

E35 CSECT * IF A RECORD IS GREATER THAN 204 BYTES, TRUNCATE IT TO 204 BYTES. * IF A RECORD IS LESS THAN 204 BYTES, PAD IT OUT TO 204 BYTES. * ALL OF THE RESULTING RECORDS WILL BE 204 BYTES LONG * (4 BYTES FOR THE RDW AND 200 BYTES OF DATA). USING E35,12 SHOW BASE REG STM 14,12,12(13) SAVE ALL REGS EXCEPT 13 LA 12,0(0,15) SET BASE REG ST 13,SAVE15+4 SAVE BACKWARD POINTER LA 14,SAVE15 SET FORWARD POINTER ST 14,8(13) IN SAVE AREA LR 13,14 SET OUR SAVE AREA LR 2,1 SAVE PARM LIST POINTER L 3,0(,2) LOAD ADDR OF RECORD LTR 3,3 EOF BZ EOF YES - DO NOT RETURN LH 4,0(,3) GET RDW CH 4,CON204 IS RDW EQ 204 BE ACCEPT YES-ACCEPT IT BL PAD LESS THAN 204-PAD LH 4,CON204 LIMIT LENGTH TO 204 B TRUNC MORE THAN 204-TRUNCATE PAD DS 0H PAD OR TRUNCATE MVI DATA,X00 ZERO OUT THE BUFFER MVC DATA+1(199),DATA TRUNC DS 0H PAD OR TRUNCATE BCTR 4,0 DECREASE RDW FOR EXECUTE EX 4,MVPAD MOVE RECORD INTO PAD/TRUNCATE BUFFER MVC NEWRDW(2),CON204 SET NEW RDW TO 204 LA 3,BUFFER POINT TO PADDED/TRUNCATED RECORD ACCEPT DS 0H SR 15,15 SET RC=0 LR 1,3 SET RECORD POINTER B GOBACK EOF LA 15,8 EOF - SET RC=8 GOBACK L 13,4(,13) L 14,12(,13) LM 2,12,28(13) RESTORE REGS BR 14 RETURN MVPAD MVC BUFFER(*-*),0(3) FOR EXECUTE SAVE15 DS 18F CON204 DC H204 BUFFER DS 0H NEWRDW DS H NEW RDW OF 204 DC H0 DATA DC XL20000 BUFFER FOR PADDING/TRUNCATING END

Figure 21. E35 User Exit Example

E61 User Exit: Altering Control Fields

This routine can be used to change the order of binary control fields passed to it (that is, those for which E is specified) from ascending order to descending order.

442

z/OS V1R10.0 DFSORT Application Programming Guide

COBOL User Exit Routines

* E61 PARAMETER LIST DSECT PARML DSECT DS 3C PARMNUM DS C CONTROL FIELD NUMBER PARMPTR DS A ADDRESS OF CONTROL FIELD DS 2C PARMLEN DS H CONTROL FIELD LENGTH * E61REV CSECT * CHANGE THE ORDER OF EACH CONTROL FIELD PASSED TO THIS ROUTINE * FROM ASCENDING TO DESCENDING BY REVERSING ALL OF THE BITS. * ASSUMES THAT ONLY BI CONTROL FIELDS ARE PASSED. USING E61REV,12 SHOW BASE REG STM 14,12,12(13) SAVE ALL REGS EXCEPT R13 LA 12,0(0,15) SET BASE REG ST 13,SAVE61+4 SAVE BACKWARD POINTER LA 14,SAVE61 SET FORWARD POINTER ST 14,8(13) IN SAVE AREA LR 13,14 SET OUR SAVE AREA LR 3,1 SET PARM LIST POINTER USING PARML,3 L 4,PARMPTR GET POINTER TO CONTROL FIELD IMAGE LH 5,PARMLEN GET LENGTH OF CONTROL FIELD BCTR 5,0 SUBTRACT 1 FOR EXECUTE EX 5,REVCF CHANGE FROM ASCENDING TO DESCENDING GOBACK L 13,4(,13) LM 14,12,12(13) RESTORE REGS BR 14 RETURN REVCF XC 0(*-*,4),REVFF REVERSE CONTROL FIELD BITS SAVE61 DS 18F REVFF DC 256XFF LTORG END

Figure 22. E61 User Exit Example

COBOL User Exit Routines

You can perform the same tasks with E15 and E35 user exit routines written in COBOL that you can perform with E15 and E35 user exit routines written in assembler. However, COBOL routines differ from assembler routines in the way they pass information between themselves and DFSORT. v COBOL routines must pass information through fields described in the LINKAGE SECTION of the DATA DIVISION. Assembler uses general register 1 and pointers in a parameter list. v COBOL routines must use RETURN-CODE, a COBOL special register. Assembler uses register 15 for the return code. v COBOL routines must use return code 20 to alter or replace a record. Assembler uses return code 0. v COBOL routines can use the user exit area for E15/E35 communication. Assembler uses the user address constant.

COBOL User Exit Requirements

The following rules apply to COBOL user exits. Failure to observe these COBOL user exit rules can result in termination or unpredictable results. v User exits written in COBOL must not use STOP RUN statements. To return to DFSORT, use the GOBACK statement. v VS COBOL II user exits must be compiled with the RES and RENT compiler options. v If a user exit contains a DISPLAY statement, the DFSORT messages normally written to SYSOUT must be directed to another data set using the MSGDDN parameter. For DISPLAY statements, COBOL also writes to SYSOUT. The messages to SYSOUT can, therefore, be lost because of interleaving of output.
Chapter 4. Using Your Own User Exit Routines

443

COBOL User Exit Routines

An alternative is to direct the COBOL output to another data set by using the OUTDD compiler option. COBOL user exits must not contain a SORT or a MERGE verb. When coding the MODS control statement to describe a COBOL user exit, use C for the fourth parameter. This instructs DFSORT to build the correct parameter list. If invoking DFSORT from a COBOL program, you can use a COBOL E15 if the FASTSRT option is in effect for input and a COBOL E35 if FASTSRT is in effect for output. COBOL library routines in Language Environment must be available at run time.

v v

COBOL Requirements for Copy Processing

For copy processing, all sort requirements apply except for the following restrictions: v When you directly invoke DFSORT, you can use either a separately compiled COBOL E15 user exit or a separately compiled COBOL E35 user exit, but not both. v When you invoke DFSORT from a COBOL program, the following limitations apply when FASTSRT is in effect for: Input only: You can use a separately compiled E15 user exit, but not a separately compiled E35 user exit. Output only: You can use a separately compiled E35 user exit, but not a separately compiled E15 user exit. Input and output: You can use either a separately compiled E15 or a separately compiled E35, but not both together. If separately compiled E15 and E35 user exits are found together, DFSORT copy processing terminates. Message ICE161A is issued.

COBOL Storage Requirements

If you are running COBOL user exits compiled with the RES compiler option, make sure that you have enough storage available for the COBOL library subroutines. (This does not apply if the library has been installed resident.) Besides the minimum DFSORT main storage requirements, you need an additional 1200KB of storage in your REGION to run Language Environment. Under certain conditions, DFSORT can use all the storage in your REGION below 16MB virtual, thus leaving no room to load the COBOL library subroutines required during processing of your user exit. Main storage is available above 16MB virtual unless the TMAXLIM or SIZE/MAINSIZE options specify an extremely high value (for example, your system limit for main storage above 16MB virtual). In that case, you can use the ARESALL or ARESINV option to release storage. During processing, the actual amount of storage required for the COBOL library subroutines depends on the functions performed in the COBOL user exit. You must add a minimum of 20KB to the size of the user exit. If the user exit does I/O, additional storage must be reserved for the I/O buffers. Additional storage for buffers is specified by the m parameter on the MODS statement. When SIZE/MAINSIZE=MAX is in effect, an alternative way to release storage is to use the RESALL or RESINV option.

444

z/OS V1R10.0 DFSORT Application Programming Guide

COBOL User Exit Routines

Note: You might need to release an additional 70KB of storage when you are: v Calling both E15 and E35 user exits v Running with nonresident library subroutines v Performing a sort with DFSORT residing above 16MB virtual. This can be done by adding 70KB more to one of the following: v The m parameter of the MODS statement for the E35 user exit (m = E35 user exit size + 20KB + 70KB) v The RESALL option when SIZE/MAINSIZE=MAX is in effect.

COBOL User Exit Routines (Input Phase User Exit) COBOL E15 User Exit: Passing or Changing Records for Sort
The EXITCK option affects the way DFSORT interprets certain return codes from user exit E15. To avoid ambiguity, this section assumes that the IBM default, EXITCK=STRONG, was selected at your site. For complete information about E15 return codes in various situations with EXITCK=STRONG and EXITCK=WEAK, see E15/E35 Return Codes and EXITCK on page 458. DFSORT enters the E15 user exit routine each time a new record is brought into the input phase. DFSORT continues to enter E15 (even when there are no input records) until the user exit tells DFSORT, with a return code of 8, not to return. See Figure 15 on page 415 for logic flow details. Some uses for the E15 user exit are: v Adding records to an input data set v Passing an entire input data set to DFSORT v Deleting records from an input data set v Changing records in an input data set. Notes: 1. If both E15 and E35 user exits are used, they must be in the same version of COBOL. 2. If you use the E15 user exit to pass all your records to DFSORT, you can omit the SORTIN DD statement, in which case you must include a RECORD statement in the program control statements. 3. If you omit the SORTIN DD statement, all input records are passed to DFSORT through your COBOL E15 user exit. You return to DFSORT with a return code of 12. When DFSORT returns to the E15 user exit after the last record has been passed, you return to DFSORT with a return code of 8 in register 15, which indicates do not return. 4. DFSORT continues to reenter your E15 user exit until a return code of 8 is received. However, if STOPAFT is in effect, no additional records are inserted to DFSORT after the STOPAFT count is satisfied (even if you pass back a return code of 12). 5. You cannot use dynamic link-editing with a COBOL E15 user exit.

E15 Interface with COBOL

Each time the E15 user exit is called, DFSORT supplies the following fields: v Record flags v New record v Length of the new record (for variable-length records) v Length of user exit area
Chapter 4. Using Your Own User Exit Routines

445

COBOL User Exit Routines (Input Phase User Exit)

v User exit area. When E15 returns to DFSORT, the E15 user exit provides to DFSORT some or all of the fields mentioned below. The first field is required; the others can be modified as appropriate. v RETURN-CODE (assigned by the user exit by setting the COBOL special register RETURN-CODE) v Return record v Length of the return record (for VLR) v Length of user exit area v User Exit area. For more information on how these fields are used in a COBOL E15 user exit, see E15 LINKAGE SECTION Fields for Fixed-Length and Variable-Length Records on page 448. Figure 23 on page 447 details the interface to COBOL for the E15 user exit.

446

z/OS V1R10.0 DFSORT Application Programming Guide

COBOL User Exit Routines (Input Phase User Exit)

Figure 23. E15 DFSORT Interface with COBOL

E15 LINKAGE SECTION Examples: Figure 24 on page 448 is an example of the LINKAGE SECTION code for a fixed-length record (FLR) data set with a logical record length (LRECL) of 100. The example shows the layout of the fields passed to your COBOL routine.

Chapter 4. Using Your Own User Exit Routines

447

COBOL User Exit Routines (Input Phase User Exit)

LINKAGE SECTION. 01 RECORD-FLAGS PIC 9(8) BINARY. 88 FIRST-REC VALUE 00. 88 MIDDLE-REC VALUE 04. 88 END-REC VALUE 08. 01 NEW-REC PIC X(100). 01 RETURN-REC PIC X(100). 01 UNUSED1 PIC 9(8) BINARY. 01 UNUSED2 PIC 9(8) BINARY. 01 UNUSED3 PIC 9(8) BINARY. 01 UNUSED4 PIC 9(8) BINARY. 01 UNUSED5 PIC 9(8) BINARY. 01 EXITAREA-LEN PIC 9(4) BINARY. 01 EXITAREA. 05 EAREA OCCURS 1 TO 256 TIMES DEPENDING ON EXITAREA-LEN PIC X.

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

Figure 25 is an example of the LINKAGE SECTION code for a variable-length record (VLR) data set with a maximum LRECL of 200. The example shows the layout of the fields passed to your COBOL routine.
LINKAGE SECTION. 01 RECORD-FLAGS PIC 9(8) BINARY. 88 FIRST-REC VALUE 00. 88 MIDDLE-REC VALUE 04. 88 END-REC VALUE 08. 01 NEW-REC. 05 NREC OCCURS 1 TO 200 TIMES DEPENDING ON NEW-REC-LEN PIC X. 01 RETURN-REC. 05 RREC OCCURS 1 TO 200 TIMES DEPENDING ON RETURN-REC-LEN PIC X. 01 UNUSED1 PIC 9(8) BINARY. 01 UNUSED2 PIC 9(8) BINARY. 01 NEW-REC-LEN PIC 9(8) BINARY. 01 RETURN-REC-LEN PIC 9(8) BINARY. 01 UNUSED3 PIC 9(8) BINARY. 01 EXITAREA-LEN PIC 9(4) BINARY. 01 EXITAREA. 05 EAREA OCCURS 1 TO 256 TIMES DEPENDING ON EXITAREA-LEN PIC X.

Figure 25. LINKAGE SECTION Code Example for E15 (Variable-Length Record)

E15 LINKAGE SECTION Fields for Fixed-Length and Variable-Length Records

The fields in the LINKAGE SECTION are used by DFSORT and your routine as stated below. For clarity, the field names from Figure 25 have been used. v To give your COBOL routine the status of the passed records, DFSORT uses the record flags field (RECORD-FLAGS) in the following way: 0 (FIRST-REC) The new record is the first passed record. 4 (MIDDLE-REC) The new record is not the first passed record. 8 (END-REC) All records have been passed to your routine or there were no records to pass. v DFSORT places the next input record in the new record field (NEW-REC). A VLR does not contain an RDW, but DFSORT places the length of this VLR in the new record length field (NEW-REC-LEN). The value in the NEW-REC-LEN field is the length of the record only and does not include the 4 bytes for the RDW. v When your routine places an insertion/replacement record in the return record field (RETURN-REC), the VLR must not contain an RDW; your routine must place the length of this record in the return record length field

448

z/OS V1R10.0 DFSORT Application Programming Guide

COBOL User Exit Routines (Input Phase User Exit)

(RETURN-REC-LEN). The value of the RETURN-REC-LEN field is the length of the record only and must not include the 4 bytes for the RDW. v Each time DFSORT calls your COBOL E15 or COBOL E35 user exit, it passes the user exit a 256-byte user exit area field (EXITAREA). The first time the user exit area field is passed to your COBOL E15 user exit, it contains 256 blanks, and the user exit area length field (EXITAREA-LEN) contains 256. Any changes you make to the user exit area field or user exit area length fields are passed back both to your COBOL E15 user exit and your COBOL E35 user exit. Notes: 1. Do not set the user exit area length field to more than 256 bytes. 2. If the data used for input was not created by a COBOL run, you need to know the LRECL defined for your data set. For a VLR, the maximum length of the record defined in your COBOL user exit is 4 bytes less than the LRECL value, because COBOL does not include the RDW as part of the record. (Each VLR begins with an RDW field of 4 bytes. The RDW is not included in the record passed to your COBOL user exit.) 3. You need to code only up to the last field that your routine actually uses (for example, up to RETURN-REC if you do not use the user exit area). 4. DFSORT uses the specified or defaulted value for L2 in the RECORD statement to determine the length of the records your E15 user exit passes back to DFSORT. For fixed-length records, be sure that each record your E15 user exit changes or inserts has a length that is equal to the specified or defaulted L2 value. For variable-length records, be sure that each record your E15 user exit changes or inserts has a length that is less than or equal to the specified or defaulted L2 value. Unwanted truncation or abends may occur if DFSORT uses the wrong length for the records passed to it by your E15 user exit. For details of the L2 value, see RECORD Control Statement on page 394.

E15 Return Codes

Your COBOL E15 routine must pass a return code to DFSORT in the RETURN-CODE field, a COBOL special register. Following are the return codes for the E15 user exit: Return Code 00 (X'00') 04 (X'04') 08 (X'08') 12 (X'0C') 16 (X'10') 20 (X'14') Description No Action Delete Record Do Not Return Insert Record Terminate DFSORT Alter or Replace Record

0: No Action If you want DFSORT to retain the record unchanged, return with RETURN-CODE set to 0. 4: Delete Record If you want DFSORT to delete the record, return with RETURN-CODE set to 4. 8: Do Not Return DFSORT continues to enter your routine until you return with RETURN-CODE set to 8. After that, the user exit is not used again during the DFSORT application. Unless you are inserting records after the end of the data set, you must set RETURN-CODE to 8 when DFSORT indicates the end of the data set, which it does by entering your routine with the record flags field set to 8.
Chapter 4. Using Your Own User Exit Routines

449

COBOL User Exit Routines (Input Phase User Exit)

If your user exit routine passes a return code of 8 to DFSORT when input records still remain to be processed, the remaining records are processed by DFSORT but are not passed to your user exit. 12: Insert Record If you want DFSORT to add a record before the new record in the input data set: v Move the insert record to the return record field v For VLR, move the length to the return record length field (Do not include the 4-byte RDW in this length.) v Return with RETURN-CODE set to 12. DFSORT returns to your routine with the same record as before in the new record field, allowing your routine to insert more records or handle the new record. You can also insert records after the end of the data set. DFSORT keeps returning to your routine as long as you pass it a RETURN-CODE of 12 and until you return with a RETURN-CODE set to 8. 16: Terminate DFSORT If you want to terminate DFSORT, return with RETURN-CODE set to 16. DFSORT then returns to its calling program or to the system with a return code of 16. 20: Alter Record If you want to change the new record: v Move the new record to the return record field. v Change the record in the return record field. v For VLR records, move the length to the return record length field. v Return with RETURN-CODE set to 20. Note: If your routine changes record size, you must indicate the new size on the RECORD statement. 20: Replace Record If you want to replace the new record: v Move the replacement record to the return record field. v For VLR records, move the length to the return record length field. (Do not include the 4-byte RDW in this length.) v Return with RETURN-CODE set to 20. See E15/E35 Return Codes and EXITCK on page 458 for complete details of the meanings of return codes in various situations.

E15 Procedure Division Requirements

When coding the PROCEDURE DIVISION, the following requirements must be met: v To return control to DFSORT, you must use the GOBACK statement. v In the USING option of the PROCEDURE DIVISION header, you must specify each 01-level name in the LINKAGE SECTION. You must specify each name in order up to the last one you plan to use even when you do not use all the 01-level names preceding the header. Examples: For the FLR example, Figure 24 on page 448, you would code:

450

z/OS V1R10.0 DFSORT Application Programming Guide

COBOL User Exit Routines (Input Phase User Exit)

PROCEDURE DIVISION USING RECORD-FLAGS, NEW-REC, RETURN-REC, UNUSED1, UNUSED2, UNUSED3, UNUSED4, UNUSED5, EXITAREA-LEN, EXITAREA.

For the VLR example, Figure 25 on page 448, you would code:
PROCEDURE DIVISION USING RECORD-FLAGS, NEW-REC, RETURN-REC, UNUSED1, UNUSED2, NEW-REC-LEN, RETURN-REC-LEN, UNUSED3, EXITAREA-LEN, EXITAREA.

COBOL User Exit Routines (Output Phase User Exit) COBOL E35 User Exit: Changing Records
The EXITCK option affects the way DFSORT interprets certain return codes from user exit E35. To avoid ambiguity, this section assumes that the IBM default, EXITCK=STRONG, was selected at your site. For complete information about E35 return codes in various situations with EXITCK=STRONG and EXITCK=WEAK, see E15/E35 Return Codes and EXITCK on page 458. DFSORT enters the E35 user exit routine each time it prepares to place a record in the output area. See Figure 15 on page 415 for logic flow details. Some uses for the E35 user exit are: v Adding records for output data sets v Omitting records for output data sets v Changing records for output data sets When DFSORT indicates the end of the data set (record flags field set to 8), you must set RETURN-CODE to 8 (unless you are inserting records after the end of the data set); otherwise, DFSORT continues to enter E35. Notes: 1. If both E15 and E35 user exits are used, they must be in the same version of COBOL. 2. If you use the E35 user exit to dispose of all your output records, you can omit the SORTOUT DD statement. 3. If you omit the SORTOUT DD statement and you do not specify any OUTFIL data sets, your E35 user exit routine must dispose of each output record and return to DFSORT with a return code of 4. When DFSORT returns to your routine after you have disposed of the last record, return to DFSORT with a return code of 8 to indicate do not return. 4. You cannot use dynamic link-editing with a COBOL E35 user exit.

E35 Interface with COBOL

Each time your E35 user exit is called, DFSORT supplies the following fields: v Record flags v Record leaving DFSORT v Length of record leaving DFSORT (for variable-length records) v Length of user exit area v User Exit area. When your E35 user exit returns to DFSORT, the E35 user exit provides to DFSORT some or all of the fields mentioned below. The first field is required; the others can be modified as appropriate.
Chapter 4. Using Your Own User Exit Routines

451

COBOL User Exit Routines (Output Phase User Exit)

v RETURN-CODE (assigned by the user exit by setting the COBOL special register RETURN-CODE) v Return record v Length of return record (for variable-length records) v Length of user exit area v User exit area. For more information on how these fields are used in a COBOL E35 user exit, see E35 LINKAGE SECTION Fields for Fixed-Length and Variable-Length Records on page 453. Figure 26 details the interface to COBOL for the E35 user exit.

Figure 26. E35 Interface with COBOL

E35 LINKAGE SECTION Examples: Figure 27 is an example of the LINKAGE SECTION code for a fixed-length record (FLR) data set with a logical record length (LRECL) of 100. The example shows the layout of the fields passed to your

452

z/OS V1R10.0 DFSORT Application Programming Guide

COBOL User Exit Routines (Output Phase User Exit)

COBOL routine.
LINKAGE SECTION. 01 RECORD-FLAGS PIC 9(8) BINARY. 88 FIRST-REC VALUE 00. 88 MIDDLE-REC VALUE 04. 88 END-REC VALUE 08. 01 LEAVING-REC PIC X(100). 01 RETURN-REC PIC X(100). 01 OUTPUT-REC PIC X(100). 01 UNUSED1 PIC 9(8) BINARY. 01 UNUSED2 PIC 9(8) BINARY. 01 UNUSED3 PIC 9(8) BINARY. 01 UNUSED4 PIC 9(8) BINARY. 01 EXITAREA-LEN PIC 9(4) BINARY. 01 EXITAREA. 05 EAREA OCCURS 1 TO 256 TIMES DEPENDING ON EXITAREA-LEN PIC X.

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

Figure 28 is an example of the LINKAGE SECTION code for a variable-length record (VLR) data set with a maximum LRECL of 200. The example shows the layout of the fields passed to your COBOL routine.
LINKAGE SECTION. 01 RECORD-FLAGS PIC 9(8) BINARY. 88 FIRST-REC VALUE 00. 88 MIDDLE-REC VALUE 04. 88 END-REC VALUE 08. 01 LEAVING-REC. 05 LREC OCCURS 1 TO 200 TIMES DEPENDING ON LEAVING-REC-LEN PIC X. 01 RETURN-REC. 05 RREC OCCURS 1 TO 200 TIMES DEPENDING ON RETURN-REC-LEN PIC X. 01 OUTPUT-REC. 05 OREC OCCURS 1 TO 200 TIMES DEPENDING ON OUTPUT-REC-LEN PIC X. 01 UNUSED1 PIC 9(8) BINARY. 01 LEAVING-REC-LEN PIC 9(8) BINARY. 01 RETURN-REC-LEN PIC 9(8) BINARY. 01 OUTPUT-REC-LEN PIC 9(8) BINARY. 01 EXITAREA-LEN PIC 9(4) BINARY. 01 EXITAREA. 05 EAREA OCCURS 1 TO 256 TIMES DEPENDING ON EXITAREA-LEN PIC X.

Figure 28. LINKAGE SECTION Code Example for E35 (Variable-Length Records)

E35 LINKAGE SECTION Fields for Fixed-Length and Variable-Length Records

The fields in the LINKAGE SECTION are used by DFSORT and your routine as stated below. For clarity, the field names from Figure 28 have been used. v To give your COBOL routine the status of the passed records, DFSORT uses the record flags field (RECORD-FLAGS) in the following way: 0 (FIRST-REC) The record leaving DFSORT is the first passed record. 4 (MIDDLE-REC) The record leaving DFSORT is not the first passed record. 8 (END-REC) There is no record leaving DFSORT to pass; all records have been passed to your routine or there were no records to pass. v DFSORT places the next output record, which usually follows the record in the output area, in the record leaving field (LEAVING-REC). A VLR does not contain an RDW; DFSORT places the length of this VLR in the record-leaving length

Chapter 4. Using Your Own User Exit Routines

453

COBOL User Exit Routines (Output Phase User Exit)

field (LEAVING-REC-LEN). The value in the LEAVING-REC-LEN field is the length of the record only and does not include the 4 bytes for the RDW. v When your routine places an insertion or replacement record in the return record field (RETURN-REC), the VLR must not contain an RDW; your routine must place the length of this record in the return record length field (RETURN-REC-LEN). The value in the RETURN-REC-LEN field is the length of the record only and does not include the 4 bytes for the RDW. v DFSORT places the record already in the output area in the record in output area field (OUTPUT-REC). A VLR does not contain an RDW. DFSORT places the length, not including the 4 bytes for RDW, of this VLR in the record in output area length field (OUTPUT-REC-LEN). v DFSORT passes your COBOL E35 routine a 256-byte user exit area field (EXITAREA) that can contain information passed by your COBOL E15 routine. If no information is passed in the EXITAREA field by your COBOL E15 routine the first time the field is passed to your COBOL E35 routine, EXITAREA contains 256 blanks, and the user exit area length field (EXITAREA-LEN) contains 256. Any changes you make to the user exit area field or user exit area length field are passed back to your COBOL E35 routine each time it is called by DFSORT. Notes: 1. Do not set the user exit area length field to more than 256 bytes. 2. VLR records have a 4-byte RDW field at the beginning of each record. The maximum record length plus the RDW will be the length defined for the LRECL attribute of your output data set. COBOL programs do not use the RDW and, therefore, the maximum length defined in your COBOL user exit is 4 bytes less than the LRECL value. 3. You need to code only up to the last field your routine actually uses (for example, up to OUTPUT-REC-LEN if you do not use the user exit area). 4. DFSORT uses the specified or defaulted value for L3 in the RECORD statement to determine the length of the records your E35 user exit passes back to DFSORT. For fixed-length records, be sure that each record your E35 user exit changes or inserts has a length that is equal to the specified or defaulted L3 value. For variable-length records, be sure that each record your E35 user exit changes or inserts has a length that is less than or equal to the specified or defaulted L3 value. Unwanted truncation or abends may occur if DFSORT uses the wrong length for the records passed to it by your E35 user exit. For details of the L3 value, see RECORD Control Statement on page 394.

E35 Return Codes

Your COBOL E35 routine must pass a return code to DFSORT in the RETURN-CODE field, a COBOL special register. Following are the return codes for the E35 exit: Return Code 00 (X'00') 04 (X'04') 08 (X'08') 12 (X'0C') 16 (X'10') 20 (X'14') Description No Action Delete Record Do Not Return Insert Record Terminate DFSORT Alter or Replace Record

0: No Action If you want DFSORT to retain the record leaving DFSORT unchanged, return with RETURN-CODE set to 0.

454

z/OS V1R10.0 DFSORT Application Programming Guide

COBOL User Exit Routines (Output Phase User Exit)

4: Delete Record If you want DFSORT to delete the record leaving DFSORT, return with RETURN-CODE set to 4. 8: Do Not Return DFSORT keeps returning to your routine until you pass a RETURN-CODE set to 8. After that, the user exit is not used again during the DFSORT application. Unless you are inserting records after the end of the data set, you must set RETURN-CODE to 8 when DFSORT indicates the end of the data set. This is done by entering your routine with the record flags field set to 8. If your user exit routine passes a return code of 8 to DFSORT when input records still remain to be processed, the remaining records are processed by DFSORT but are not passed to your user exit. If you do not have an output data set and would usually return with a return code of 8 before EOF, you can avoid getting the ICE025A message by specifying NOCHECK on the OPTION control statement (if installation option CHECK=NO had not already been specified). 12: Insert Record If you want DFSORT to add an output record before the record leaving DFSORT: v Move the insert record to the return record field v For VLR records, move the length to the return record length field v Return with RETURN-CODE set to 12. DFSORT returns to your routine with the inserted record in the record output area field and with the same record as before in the record leaving DFSORT field. In this way, your routine can insert more records or handle the record leaving DFSORT. You can also insert records after the end of the data set. DFSORT keeps returning to your routine as long as you pass it a RETURN-CODE 12 and until you return with RETURN-CODE set to 8. DFSORT does not perform sequence checking for disk work data set sorts. For tape work data set sorts, DFSORT does not perform sequence checking on inserted records unless you delete the record leaving DFSORT and then replace it. 16: Terminate DFSORT If you want to terminate DFSORT, return with RETURN-CODE set to 16. DFSORT then returns to its calling program or to the system with a return code of 16. 20: Alter Record If you want to change the record leaving DFSORT: v Move the record leaving DFSORT to the return record field v Change the record in the return record field v For VLR records, move the length to the return record length field v Return with RETURN-CODE set to 20. Note: If your routine changes record size, you must indicate the new size on the RECORD statement. 20: Replace Record If you want to replace the record leaving DFSORT: v Move the replacement record to the return record field v For VLR records, move the length to the return record length field v Return with RETURN-CODE set to 20.
Chapter 4. Using Your Own User Exit Routines

455

COBOL User Exit Routines (Output Phase User Exit)

See E15/E35 Return Codes and EXITCK on page 458 for complete details of the meanings of return codes in various situations.

E35 Procedure Division Requirements

When coding the PROCEDURE DIVISION, the following requirements must be met: v To return control to DFSORT, you must use the GOBACK statement. v In the USING option of the PROCEDURE DIVISION header, you must specify each 01-level name in the LINKAGE SECTION. You must specify each name in order up to the last one you plan to use even when you do not use all the 01-level names preceding the header. Examples: For the FLR example, Figure 27 on page 453, you would code:
PROCEDURE DIVISION USING RECORD-FLAGS, LEAVING-REC, RETURN-REC, OUTPUT-REC, UNUSED1, UNUSED2, UNUSED3, UNUSED4, EXITAREA-LEN, EXITAREA.

For the VLR example, Figure 28 on page 453, you would code:
PROCEDURE DIVISION USING RECORD-FLAGS, LEAVING-REC, RETURN-REC, OUTPUT-REC, UNUSED1, LEAVING-REC-LEN, RETURN-REC-LEN, OUTPUT-REC-LEN, EXITAREA-LEN, EXITAREA.

Sample Routines Written in COBOL

This section provides some sample program user exits written in COBOL.

COBOL E15 User Exit: Altering Records

Figure 29 shows an example of a COBOL E15 routine for a data set with fixed-length records of 100 bytes. It examines the department field in the passed record and takes the following action: v If the department is D29, it changes it to J99. v If the department is not D29, it accepts the record unchanged.

456

z/OS V1R10.0 DFSORT Application Programming Guide

Sample Routines Written in COBOL

IDENTIFICATION DIVISION. PROGRAM-ID. CE15. ENVIRONMENT DIVISION. DATA DIVISION. LINKAGE SECTION. 01 RECORD-FLAGS 88 FIRST-REC 88 MIDDLE-REC 88 END-REC 01 NEW-REC. 05 NFILL1 05 NEW-DEPT 05 NFILL2 01 RETURN-REC. 05 RFILL1 05 RETURN-DEPT 05 RFILL2

PIC 9(8) BINARY. VALUE 00. VALUE 04. VALUE 08. PIC X(10). PIC X(3). PIC X(87). PIC X(10). PIC X(3). PIC X(87).

PROCEDURE DIVISION USING RECORD-FLAGS, NEW-REC, RETURN-REC. IF END-REC MOVE 8 TO RETURN-CODE ELSE IF NEW-DEPT EQUAL TO "D29" MOVE NEW-REC TO RETURN-REC MOVE "J99" TO RETURN-DEPT MOVE 20 TO RETURN-CODE ELSE MOVE 0 TO RETURN-CODE ENDIF ENDIF GOBACK.

Figure 29. COBOL E15 Routine Example (FLR)

COBOL E35 User Exit: Inserting Records

Figure 30 shows an example of a COBOL E35 routine for a data set with variable-length records up to 200 bytes. It examines the department field in each passed record (records are assumed to be sorted by the department field) and takes the following action: v It inserts a record for department K22 in the proper sequence. v It accepts all passed records unchanged.

Chapter 4. Using Your Own User Exit Routines

457

E15/E35 Return Codes and EXITCK

IDENTIFICATION DIVISION. PROGRAM-ID. CE35. ENVIRONMENT DIVISION. DATA DIVISION. WORKING-STORAGE SECTION. 01 INSERT-DONE PIC 9(1) VALUE 0. 01 K22-REC. 05 K22-MANAGER PIC X(20) VALUE "J. DOE". 05 K22-DEPT PIC X(3) VALUE "K22". 05 K22-FUNC PIC X(20) VALUE "ACCOUNTING". 05 K22-LATER PIC X(30) VALUE SPACES. 01 LEAVING-VAR-LEN PIC 9(8) BINARY. LINKAGE SECTION. 01 RECORD-FLAGS PIC 9(8) BINARY. 88 FIRST-REC VALUE 00. 88 MIDDLE-REC VALUE 04. 88 END-REC VALUE 08. 01 LEAVING-REC. 05 LREC-MANAGER PIC X(20). 05 LREC-DEPT PIC X(3). 05 LREC-FUNC PIC X(20). 05 LREC-LATER OCCURS 1 TO 157 TIMES DEPENDING ON LEAVING-VAR-LEN PIC X. 01 RETURN-REC. 05 RREC OCCURS 1 TO 200 TIMES DEPENDING ON RETURN-REC-LEN PIC X. 01 OUTPUT-REC. 05 OREC OCCURS 1 TO 200 TIMES DEPENDING ON OUTPUT-REC-LEN PIC X. 01 UNUSED1 PIC 9(8) BINARY. 01 LEAVING-REC-LEN PIC 9(8) BINARY. 01 RETURN-REC-LEN PIC 9(8) BINARY. 01 OUTPUT-REC-LEN PIC 9(8) BINARY. PROCEDURE DIVISION USING RECORD-FLAGS, LEAVING-REC, RETURN-REC, OUTPUT-REC, UNUSED1, LEAVING-REC-LEN, RETURN-REC-LEN, OUTPUT-REC-LEN. IF END-REC MOVE 8 TO RETURN-CODE ELSE IF INSERT-DONE EQUAL TO 1 MOVE 0 TO RETURN-CODE ELSE SUBTRACT 43 FROM LEAVING-REC-LEN GIVING LEAVING-VAR-LEN. IF LREC-DEPT GREATER THAN K22-DEPT MOVE 1 TO INSERT-DONE MOVE 43 TO RETURN-REC-LEN MOVE K22-REC TO RETURN-REC MOVE 12 TO RETURN-CODE ELSE MOVE 0 TO RETURN-CODE ENDIF ENDIF GOBACK.

Figure 30. COBOL E35 Routine Example (VLR)

E15/E35 Return Codes and EXITCK

DFSORTs interpretation of E15 and E35 return codes depends upon whether EXITCK=STRONG or EXITCK=WEAK is in effect. See the discussion of the EXITCK option in OPTION Control Statement on page 167 for more information. The following tables show the exact meaning of each E15 and E35 return code with EXITCK=STRONG and EXITCK=WEAK in all possible situations. Notes: 1. You can determine whether EXITCK=STRONG or EXITCK=WEAK is in effect from message ICE132I. 2. Use of EXITCK=WEAK can make it difficult to detect errors in the logic of your E15 and E35 user exit routines.

458

z/OS V1R10.0 DFSORT Application Programming Guide

E15/E35 Return Codes and EXITCK

3. EXITCK=WEAK is treated like EXITCK=STRONG if tape work data sets are specified for a sort application or if the Blockset technique is not selected for a merge application.
Table 56. E15 Without a SORTIN Data Set E15 Return Code 0 4 8 12 16 20 (COBOL only) All others Meaning with EXITCK=STRONG Invalid Invalid Do not return Insert record Terminate DFSORT Invalid Invalid Meaning with EXITCK=WEAK Do not return Do not return Do not return Insert record Terminate DFSORT Do not return Invalid

Table 57. E15 With a SORTIN Data Set Before End of Input E15 Return Code 0 4 8 12 16 20 (COBOL only) All others Meaning with EXITCK=STRONG or EXITCK=WEAK No action/record altered Delete record Do not return Insert record Terminate DFSORT Alter/replace record Invalid

Table 58. E15 With a SORTIN Data Set After End of Input E15 Return Code 0 4 8 12 16 20 (COBOL only) All others Meaning with EXITCK=STRONG Invalid Invalid Do not return Insert record Terminate DFSORT Invalid Invalid Meaning with EXITCK=WEAK Do not return Do not return Do not return Insert record Terminate DFSORT Do not return Invalid

Table 59. E35 With a SORTOUT or OUTFIL Data Set Before End of Input E35 Return Code 0 4 8 12 16 Meaning with EXITCK=STRONG or EXITCK=WEAK No action/record altered Delete record Do not return Insert record Terminate DFSORT
Chapter 4. Using Your Own User Exit Routines

459

E15/E35 Return Codes and EXITCK

Table 59. E35 With a SORTOUT or OUTFIL Data Set Before End of Input (continued) E35 Return Code 20 (COBOL only) All others Meaning with EXITCK=STRONG or EXITCK=WEAK Alter/replace record Invalid

Table 60. E35 Without a SORTOUT or OUTFIL Data Set Before End of Input E35 Return Code 0 4 8 12 16 20 (COBOL only) All others Meaning with EXITCK=STRONG Invalid Delete record Do not return Invalid Terminate DFSORT Invalid Invalid Meaning with EXITCK=WEAK Delete record Delete record Do not return Delete record Terminate DFSORT Delete record Invalid

Table 61. E35 With a SORTOUT or OUTFIL Data Set After End of Input E35 Return Code 0 4 8 12 16 20 (COBOL only) All others Meaning with EXITCK=STRONG Invalid Invalid Do not return Insert record Terminate DFSORT Invalid Invalid Meaning with EXITCK=WEAK Do not return Do not return Do not return Insert record Terminate DFSORT Do not return Invalid

Table 62. E35 without a SORTOUT or OUTFIL Data Set After End of Input E35 Return Code 0 4 8 12 16 20 (COBOL only) All others Meaning with EXITCK=STRONG Invalid Invalid Do not return Invalid Terminate DFSORT Invalid Invalid Meaning with EXITCK=WEAK Do not return Do not return Do not return Do not return Terminate DFSORT Do not return Invalid

460

z/OS V1R10.0 DFSORT Application Programming Guide

Chapter 5. Invoking DFSORT from a Program

Invoking DFSORT Dynamically . . . . . . What Are System Macro Instructions? . . . . Using System Macro Instructions . . . . . . Using JCL DD Statements . . . . . . . . Overriding DFSORT Control Statements from Programs . . . . . . . . . . . . . . Invoking DFSORT With the 24-Bit Parameter List Providing Program Control Statements . . . CONTROL Statement Images Example . . Format of the 24-Bit Parameter List . . . . . . . 461 461 461 462 Invoking DFSORT With The Extended Parameter List . . . . . . . . . . . . . . . . Providing Program Control Statements . . . Format of the Extended Parameter List . . Writing the Macro Instruction . . . . . . . Parameter List Examples . . . . . . . Restrictions for Dynamic Invocation . . . . . Merge Restriction . . . . . . . . . . Copy Restrictions . . . . . . . . . . . . . . . . . . 470 470 470 473 473 477 477 477

. 462 463 . 463 . 463 . 464

Invoking DFSORT Dynamically

DFSORT can be invoked dynamically from programs written in COBOL or PL/I. Specific information on dynamic invocation is covered in the COBOL and PL/I programming guides. JCL requirements are the same as those for assembler. This section explains what you need to know to initiate DFSORT from within your assembler program using a system macro instruction instead of an EXEC job control statement in the input stream. Specific restrictions on invoking DFSORT from PL/I and COBOL are listed in Restrictions for Dynamic Invocation on page 477.

What Are System Macro Instructions?

System macro instructions are macro instructions provided by IBM for communicating service requests to the control program. You can use these instructions only when programming in assembler language. They are processed by the assembler program using macro definitions supplied by IBM and placed in the macro library when your control program was installed. You can specify one of three system macro instructions to pass control to the program: LINK, ATTACH, or XCTL. | | | | | | | When you issue one of these instructions, the first load module of DFSORT is brought into main storage. The linkage relationship between your program and DFSORT differs according to which of the instructions you have used. For a complete description of the macro instructions and how to use them, refer to z/OS MVS Programming: Assembler Services Guide, z/OS MVS Programming: Assembler Services Reference ABE-HSP, and z/OS MVS Programming: Assembler Services Reference IAR-XCT.

Using System Macro Instructions

To initiate DFSORT processing with a system macro instruction, you must: v Write the required job control language (JCL) DD statements. v Write DFSORT control statements as operands of assembler DC instructions. (Using DFSPARM or SORTCNTL data sets to specify program control statements can be more convenient. See Chapter 3, Using DFSORT Program Control Statements, on page 81 for details.)

Copyright IBM Corp. 1973, 2006

461

Using System Macro Instructions

v Write a parameter list containing information to be passed to DFSORT and a pointer containing the address of the parameter list. DFSORT accepts two types of parameter lists: a 24-bit parameter list and an extended parameter list. Although you can choose either parameter list, the extended parameter list can perform a superset of the functions in the 24-bit parameter list; therefore, it should be used for new DFSORT applications. Note: DFSORT can also be called using the systems EXEC PARM parameter list, provided that the rules for passing it are followed (for example, the parameter list must reside below 16MB virtual). DFSORT interprets a call using the EXEC PARM parameter list as a direct invocation rather than a program invocation. v Prepare the macro instruction specifying one of the following as the entry point name: ICEMAN, SORT, IERRCO00, or IGHRCO00. Note: The save area passed to DFSORT must begin on a fullword boundary. In addition, the following rule applies: v If you are invoking DFSORT repeatedly (for example, from an E15 or E35 user exit), you must always wait for the last invoked sort to end before you can give control back to any of your user exits in an earlier invoked sort.

Using JCL DD Statements

JCL DD statements are usually required when invoking DFSORT from another program. The statements and their necessary parameters are described in detail.

Overriding DFSORT Control Statements from Programs

You can override the control statements generated or passed by a program (for example, a COBOL SORT verb or PLISRTx routine) with DFSORTs DFSPARM data set. For example, you could use the following to override the SORT statement generated by a COBOL SORT verb in order to use DFSORTs Year 2000 features:
//DFSPARM DD * OPTION Y2PAST=1956 * set fixed CW of 1956-2055 SORT FIELDS=(11,6,Y2T,A, * sort Cyymmdd using CW 31,10,CH,A) * sort other key /*

You can also use DFSPARM to provide different DFSORT control statements for multiple invocations of DFSORT from a program. However, the control statements must be located in temporary or permanent data sets and FREE=CLOSE must be used. Heres an example of using DFSPARM to override the control statements for a COBOL program with three SORT verbs:
//DFSPARM DD DSN=DP1,DISP=SHR,FREE=CLOSE //DFSPARM DD DSN=DP2,DISP=SHR,FREE=CLOSE //DFSPARM DD DSN=DP3,DISP=SHR,FREE=CLOSE

462

z/OS V1R10.0 DFSORT Application Programming Guide

Overriding DFSORT Control Statements from Programs

DP1, DP2, and DP3 can contain any DFSORT control statements you like. The statements in DP1 will be used for the first call to DFSORT, the statements in DP2 for the second and the statements in DP3 for the third. For complete details on DFSPARM, see DFSPARM DD Statement on page 77. COBOL also offers additional methods for overriding DFSORT parameters and control statements such as SORT special registers and the IGZSRTCD data set. See your COBOL publications for details.

Invoking DFSORT With the 24-Bit Parameter List Providing Program Control Statements
When using the 24-bit parameter list, you must supply the starting and ending address of a valid image of each control statement to be used during run-time. You must provide the image as a character string in EBCDIC format using assembler DC instructions. The rules for preparing the program control statements are as follows: v At least one control statement must be specifiedgenerally SORT or MERGE. If more than 15 control statements are specified, only the first 15 control statements are accepted and all others are ignored. Control statements can also be specified in SORTCNTL or DFSPARM. v The MODS statement is required when user exits other than E15, E32, and E35 are to be used. It is also required when the E15 or E35 routine addresses are not passed by the parameter list. v The following control statements can be passed using the 24-bit parameter list: SORT or MERGE, RECORD, ALTSEQ, DEBUG, MODS, SUM, INREC, OUTREC, INCLUDE or OMIT, and OUTFIL. v At least one blank must follow the operation definer (SORT, for example). A control statement can start and end with one or more blanks; however, no other blanks are allowed. v The content and format of the statements are as described in Chapter 3, Using DFSORT Program Control Statements, on page 81, except: Labels are not allowed although a leading blank is optional. Because each control statement image must be defined contiguously by one or more assembler DC instructions, explicit and implicit continuation of statements is neither necessary nor allowed. v Neither comment statements, blank statements, nor remark fields are permitted. v If you use ATTACH to initiate the program, you cannot use the checkpoint/restart facility and must not specify CKPT in the SORT statement image. For full override and applicability details, see Appendix B, Specification/ Override of DFSORT Options, on page 741.

CONTROL Statement Images Example

SORTBEG SORTEND DC DC C SORT FIELDS=(10,15,CH,A) C

This form, with a trailing blank separately defined, allows you to refer to the last byte of the statement (SORT statement end address) by the name SORTEND.
INCLBEG INCLEND DC DC C INCLUDE COND=(5,3,CH,NE,CJ82) C

Chapter 5. Invoking DFSORT from a Program

463

Invoking DFSORT with the 24-Bit Parameter List

Note: Assembler requires two single apostrophes to represent one single apostrophe.

Format of the 24-Bit Parameter List

Figure 31 on page 465 shows the format of the 24-bit parameter list and the pointer containing its address which you must pass to DFSORT. Detailed specifications for each of the entries in the parameter list follow. For full override and applicability details, see Appendix B, Specification/Override of DFSORT Options, on page 741.

464

z/OS V1R10.0 DFSORT Application Programming Guide

Invoking DFSORT with the 24-Bit Parameter List

Register 1 X '80' Offset (Hex) (Dec) -2 2 6 A E 12 16 1A 1E 22 26 2A 2E 32 36 3A 3E 42 46 4A 4E 52 56 5A 5E 62 66 6A 6E 72 76 7A 7E -2 2 6 10 14 18 22 26 30 34 38 42 46 50 54 58 62 66 70 74 78 82 86 90 94 98 102 106 110 114 118 122 126 Byte 1 Unused X'00' X'00' X'00' X'00' X'00' X'00' X'02' X'00' X'00' X'01' X'03' X'04' X'05' X'00' X'06' X'00' X'F6' X'F7' X'FD' X'FE' X'FF' Address of parameter list Byte 2 Unused Byte 3 and 4 Length of parameter list in bytes Notes 1,3 1,5 1,3 1,5 1 1 2,3 2,5 2 2 2 2,4 2,3 2,5 2,3 2,5 2 2 2 2

Starting address of SORT or MERGE statement image Ending address of SORT or MERGE statement image Starting address of RECORD statement image (zeros, if none) Ending address of RECORD statement image (zeros, if none) Address of E15 or E32 routine (zeros, if none) Address of E35 routine (zeros, if none) Starting address of MODS statement image Ending address of MODS statement image Main storage value Reserved storage value Address of 8-character message ddname Number of input files (MERGE with E32) Starting address of DEBUG statement image Ending address of DEBUG statement image Starting address of ALTSEQ statement image Ending address of ALTSEQ statement image Address of 256-byte ALTSEQ translation table User exit address constant The three bytes after X'FD' are ignored Address of a pointer to 104-byte ESTAE work area (or zeros) Message option

2 2 2,3 2,5 2,3 2,5 2,3 2,5 2,3 2,5 2,3 2,5

4-character prefix for "SORT" DD statement names X'07' X'00' X'08' X'00' X'09' X'00' X'0A' X'00' X'0B' X'00' Starting address of SUM statement image Ending address of SUM statement image Starting address of INCLUDE or OMIT statement image Ending address of INCLUDE or OMIT statement image Starting address of OUTREC statement image Ending address of OUTREC statement image Starting address of INREC statement image Ending address of INREC statement image Starting address of OUTFIL statement image Ending address of OUTFIL statement image

Figure 31. The 24-Bit Parameter List

Notes to Figure 31:

Chapter 5. Invoking DFSORT from a Program

465

Invoking DFSORT with the 24-Bit Parameter List

1. 2. Required entry. Must appear in the relative position shown. The offset shown is the actual offset of this entry. Optional entry. Can appear anywhere after the required entries. The displayed offset is for identification purposes onlythe actual offset of this entry can vary. Optional entries must be consecutive but can appear in any order. A specific control statement. Shown for illustrative purposes only. SORT or MERGE, RECORD, ALTSEQ, DEBUG, MODS, SUM, INREC, OUTREC, INCLUDE or OMIT, and OUTFIL can be passed using any of the following hex entry codes: X00 (see Note 1), X02, X05 through X0B, X10, X16, X18 and X20 through X29. Required entry if the MERGE statement is present and input is supplied through an E32 user exit. This entry is not required if the FILES option of the MERGE statement is specified. Required entry. Contains the ending address for a control statement and must immediately follow the entry containing the starting address for that same control statement.

3.

4.

5.

The specifications for each of the parameter list entries follow: Byte 2 to 1 0 to +1 Explanation Unused. The byte count. This 2-byte field contains the length in bytes of the parameter list. This two byte field is not included when counting the number of bytes occupied by the list. The total length of the required entries is 24 (X'0018'). All optional entries are four bytes long except those referring to control statement images which are eight bytes each. 2-5 The starting address of the SORT or MERGE statement image. Must be in the last three bytes of this fullword. The first byte must contain X'00'. The ending address of the SORT or MERGE statement image. Must be in the last three bytes. The first byte must contain X'00'. The starting address of the RECORD statement image, if any; otherwise, all zeros. Must be in the last three bytes. The first byte must contain X'00'. The ending address of the RECORD statement image, if any; otherwise, all zeros. Must be in the last three bytes. The first byte must contain X'00'. The address of the E15 or E32 routine that your program has placed in main storage, if any; otherwise, all zeros. Must be in the last three bytes. The first byte must contain X'00'. The address of the E35 routine that your program has placed in main storage, if any; otherwise, all zeros. Must be in the last three bytes. The first byte must contain X'00'. The starting address of the MODS statement image. Must be in the last three bytes. The first byte must contain X'02'. The ending address of the MODS statement. Must be in the last three bytes. The first byte must contain X'00'.

6-9 10-13

14-17

18-21

22-25

26-29 30-33

466

z/OS V1R10.0 DFSORT Application Programming Guide

Invoking DFSORT with the 24-Bit Parameter List

34-37 Main storage value. The first byte must contain X'00'. The next three bytes contain either the characters MAX or a hexadecimal value. You can use this option to temporarily override the SIZE installation option. For full override and applicability details, see Appendix B, Specification/Override of DFSORT Options, on page 741. For an explanation of this value, see the discussion of the MAINSIZE parameter in OPTION Control Statement on page 167. A reserved main storage value. The first byte must contain X'01'. The next three bytes contain a hexadecimal value that specifies a number of bytes to be reserved, where the minimum is 4K. For an explanation of this value, see the explanation of the RESINV parameter in OPTION Control Statement on page 167. You can use this option to temporarily override the RESINV installation option. For full override and applicability details, see Appendix B, Specification/Override of DFSORT Options, on page 741. 42-45 Message ddname. The first byte must contain X03. The next three bytes contain the address of an 8-byte DD statement name for the message data set, padded with blanks on the right if necessary. The name can be any valid DD statement name, but must be unique. You can use this option to temporarily override the MSGDDN installation option. For full override details, see Appendix B, Specification/Override of DFSORT Options, on page 741. For details on the use of the message data set, see z/OS DFSORT Messages, Codes and Diagnosis Guide. 46-49 Number of input files to a merge. This entry is needed only if the MERGE statement is present without the FILES option and input to the merge is supplied through the E32 user exit. The first byte must contain X'04'. The next three bytes contain the number of files in hexadecimal. For full override and applicability details, see Appendix B, Specification/Override of DFSORT Options, on page 741. The starting address of the DEBUG statement image. Must be in the last three bytes. The first byte must contain X'05'. The ending address of the DEBUG statement image. Must be in the last three bytes. The first byte must contain X'00'. The starting address of the ALTSEQ statement image. Must be in the last three bytes. The first byte must contain X'06'. The ending address of the ALTSEQ statement image. Must be in the last three bytes. The first byte must contain X'00'. The address of a 256-byte translate table supplied instead of an ALTSEQ statement. The first byte must contain X'F6'. If this parameter is present, the X'06' parameter is ignored. For full override and applicability details, see Appendix B, Specification/Override of DFSORT Options, on page 741. User exit address constant. These 4 bytes are passed to E15 (at offset 4 in the E15 parameter list), to E32 (at offset 8 in the E32 parameter list) or to E35 (at offset 8 in the E35 parameter list) after DFSORT replaces the X'F7' with X'00'.
Chapter 5. Invoking DFSORT from a Program

38-41

50-53 54-57 58-61 62-65 66-69

70-73

467

Invoking DFSORT with the 24-Bit Parameter List

Note: The user exit address constant must not be used for a Conventional merge or tape work data set sort application. 74-77 X'FD' in the first byte (the VLSHRT option) specifies that DFSORT is to continue processing if it finds a variable-length input record too short to contain all specified control fields, compare fields, or summary fields. For full details of this option, see the discussion of the VLSHRT parameter in OPTION Control Statement on page 167. You can use this option to temporarily override the VLSHRT installation option. For full override and applicability details, see Appendix B, Specification/Override of DFSORT Options, on page 741. If the first byte contains X'FE', you can use the next three bytes to pass an address of a 104-byte field save area where ESTAE information is saved. These bytes must contain zeros if the ESTAE information is not saved. If a system or user exit abend occurs, the DFSORT ESTAE recovery routine will copy the first 104 bytes of the SDWA into this area before returning to any higher level ESTAE recovery routines. For more information on the DFSORT ESTAE recovery routine, see Appendix E, DFSORT Abend Processing, on page 787 82-85 The message option. The first byte must contain X'FF'. The following three bytes contain the characters NOF, (I), or (U). You can use this option to temporarily override the MSGPRT installation option.

78-81

NOF Messages and control statements are not printed. Critical messages are written to the master console. (I) All messages except diagnostic messages (ICE800I to ICE999I) are printed. Critical messages are also written to the master console. Control statements are printed only if LIST is in effect. (U) Only critical messages are printed. They are also written to the master console. Control statements are not printed (NOLIST is forced). All messages are written to the message data set. For details on use of the message data set, see z/OS DFSORT Messages, Codes and Diagnosis Guide For full override and applicability details, see Appendix B, Specification/Override of DFSORT Options, on page 741. For compatibility reasons, the forms (NO, (AB, (AP, (AC, (CB, (CC, (CP, (PC, (SC, and (SP are also accepted. The following list shows the equivalent specifications for these aliases:
Table 63. Aliases for Message Option Option (NO (AB (AP (AC MSGPRT NONE ALL ALL NONE MSGCON NONE ALL CRITICAL ALL

468

z/OS V1R10.0 DFSORT Application Programming Guide

Invoking DFSORT with the 24-Bit Parameter List

Table 63. Aliases for Message Option (continued) Option (CB (CC (CP (PC (SC (SP MSGPRT CRITICAL NONE CRITICAL ALL ALL CRITICAL MSGCON CRITICAL CRITICAL CRITICAL ALL CRITICAL ALL

86-89

Four characters, which replace SORT in the following ddnames: SORTIN, SORTOUT, SORTINn, SORTINnn, SORTOFd, SORTOFdd, SORTWKd, SORTWKdd, and SORTCNTL. You must use this option when you dynamically invoke DFSORT more than once in a program step. The four characters must all be alphanumeric or national ($, #, or @) characters. The first character must be alphabetic, and the reserved names DIAG, BALN, OSCL, POLY, CRCX, PEER, LIST, and SYSc (where c is any alphanumeric character) must not be used. Otherwise, the four characters are ignored. For example, if you use ABC# as replacement characters, DFSORT uses statements ABC#IN, ABC#CNTL, ABC#WKdd, and ABC#OUT instead of SORTIN, SORTCNTL, SORTWKdd, and SORTOUT. Note: This parameter is equivalent to the SORTDD=cccc run-time option.

90-93 94-97 98-101 102-105 106-109 110-112 114-116 118-121 122-125 126-129

The starting address of the SUM statement image. Must be in the last three bytes. The first byte must contain X'07'. The ending address of the SUM statement image. Must be in the last three bytes. The first byte must contain X'00'. The starting address of the INCLUDE or OMIT statement image. Must be in the last three bytes. The first byte must contain X'08'. The ending address of the INCLUDE or OMIT statement image. Must be in the last three bytes. The first byte must contain X'00'. The starting address of the OUTREC statement image. Must be in the last three bytes. The first byte must contain X'09'. The ending address of the OUTREC statement image. Must be in the last three bytes. The first byte must contain X'00'. The starting address of the INREC statement image. Must be in the last three bytes. The first byte must contain X'0A'. The ending address of the INREC statement image. Must be in the last three bytes. The first byte must contain X'00'. The starting address of the OUTFIL statement image. Must be in the last three bytes. The first byte must contain X'0B'. The ending address of the OUTFIL statement image. Must be in the last three bytes. The first byte must contain X'00'.

Chapter 5. Invoking DFSORT from a Program

469

Invoking DFSORT With The Extended Parameter List

Invoking DFSORT With The Extended Parameter List Providing Program Control Statements
When using the extended parameter list, the control statements are written in a single area to which the parameter list points. The control statement area consists of: v A 2-byte field containing the length (in binary) of the character string to follow. v A character string in EBCDIC format using assembler DC instructions and containing valid images of the control statements to be used during run-time. The rules for preparing the program control statements are: v The control statements must be separated by one or more blanks. A blank preceding the first statement is optional; however, a trailing blank is required. No labels, comment statements, or remark fields are allowed. Because each control statement image must be defined contiguously by one or more assembler DC instructions, explicit and implicit continuation of statements is not necessary or allowed. v The MODS statement is required when user exits other than E15, E18, E32, E35, and E39 are to be used or when the E15, E18, E35, or E39 routine addresses are not passed by the parameter list. v All of the control statements described in Chapter 3, Using DFSORT Program Control Statements, on page 81 can be specified. None is required, but SORT, MERGE, or OPTION COPY must be specified in the parameter list, SORTCNTL, or DFSPARM. v If you use ATTACH to initiate the program, you cannot use the checkpoint/restart facility. Do not specify CKPT on the SORT or OPTION statement. For full override and applicability details, see Appendix B, Specification/Override of DFSORT Options, on page 741.

Format of the Extended Parameter List

Figure 32 on page 471 shows the format of the extended parameter list and the pointer, which you must pass to DFSORT, containing its address. The first parameter must be specified. A 4-byte field containing X'FFFFFFFF' must be used to indicate the end of the parameter list. It can be coded anywhere after the first parameter. If a parameter is specified, it must appear in the indicated position and must contain a 31-bit address or a clean (the first 8 bits containing zeros) 24-bit address. If a parameter is not specified, it is treated as if it were specified as zeros. For full override and applicability details, see Appendix B, Specification/Override of DFSORT Options, on page 741.

470

z/OS V1R10.0 DFSORT Application Programming Guide

Invoking DFSORT With The Extended Parameter List

Figure 32. The Extended Parameter List

Detailed specifications for each of the entries in the parameter list follow: Byte 0-3 Explanation Required. The address of the area containing the DFSORT control statements, if any; otherwise, all zeros. The high order bit must be 0 to identify this as an extended parameter list. Refer to the previous section for the format of the control statement area. Attention: The area must start with a two-byte length field. If you specify this parameter as zeros, you must supply all the required control statements in DFSPARM or SORTCNTL. 4-7 Optional. The address of the E15 or E32 user exit routine that your program has placed in main storage (for example, via LOAD), if any; otherwise, all zeros. f (bit 0) has the following meaning: 0 = Enter the user exit with 24-bit addressing in effect (AMODE 24). 1 = Enter the user exit with 31-bit addressing in effect (AMODE 31). Note: If the Blockset or Peerage/Vale technique is not selected, the user exit is always entered with 24-bit addressing in effect (AMODE 24). 8-11 Optional. The address of the E35 user exit routine that your program has placed in main storage (for example, via LOAD), if any; otherwise, all zeros. f (bit 0) has the following meaning: 0 = Enter the user exit with 24-bit addressing in effect (AMODE 24). 1 = Enter the user exit with 31-bit addressing in effect (AMODE 31).

Chapter 5. Invoking DFSORT from a Program

471

Invoking DFSORT With The Extended Parameter List

Note: If the Blockset or Peerage/Vale technique is not selected, the user exit is always entered with 24-bit addressing in effect (AMODE 24). 12-15 Optional. This field will be passed to the E15, E32 or E35 user exit routines. Note: The user exit address constant must not be used for a Conventional merge or tape work data set sort application. 16-19 | Optional. The address of a 256-byte ALTSEQ translation table supplied instead of an ALTSEQ statement, if any; otherwise, all zeros. You can use this option to override an ALTSEQ installation option. For full override and applicability details, see Appendix B, Specification/Override of DFSORT Options, on page 741. Optional. The address of a 4-byte field containing the address of a 112-byte work area where ESTAE information is saved, or all zeros if the ESTAE information is not saved. If a system or user exit abend occurs, the DFSORT recovery routine will copy the first 112 bytes of the software diagnostic work area (SDWA) into this area before returning to your ESTAE recovery routine. 24-27 Optional. The address of the E18 user exit routine that your program has placed in main storage (for example, via LOAD), if any; otherwise, all zeros. Note: This parameter is ignored for a merge application and for a tape work data set sort application. f (bit 0) has the following meaning: 0 = Enter the user exit with 24-bit addressing in effect (AMODE 24). 1 = Enter the user exit with 31-bit addressing in effect (AMODE 31). Note: If the Blockset or Peerage/Vale technique is not selected, the user exit is always entered with 24-bit addressing in effect (AMODE 24). 28-31 Optional. The address of the E39 user exit routine that your program has placed in main storage (for example, via LOAD), if any; otherwise, all zeros. Note: This parameter is ignored for a conventional merge application and for a tape work data set sort application. f (bit 0) has the following meaning: 0 = Enter the user exit with 24-bit addressing in effect (AMODE 24). 1 = Enter the user exit with 31-bit addressing in effect (AMODE 31). Note: If the Blockset or Peerage/Vale technique is not selected, the user exit is always entered with 24-bit addressing if effect (AMODE 24). 32-35 Optional. 4 characters to be used as an identifier for this call to DFSORT. This field can be used to uniquely identify each call to DFSORT from a program that calls DFSORT more than once. DFSORT prints message ICE200I to display the field identifier exactly as you specify it; the field is not checked for valid characters. If the field identifier is specified, it must appear in the indicated position. If the identifier field contains zeros (X'00000000'), or X'FFFFFFFF' is used to end the parameter list before or at the field identifier, DFSORT does not print message ICE200I.

20-23

472

z/OS V1R10.0 DFSORT Application Programming Guide

Invoking DFSORT With The Extended Parameter List

Note: The list can be ended after any parameter. The last parameter in the list must be followed by X'FFFFFFFF'.

Writing the Macro Instruction

When writing the LINK, ATTACH, or XCTL macro instruction, you must: v Specify SORT (the entry point) in the EP parameter of the instruction. (This applies to sort, merge, and copy jobs.) v Load the address of the pointer to the parameter list into register 1 (or pass it in the MF parameter of the instruction). Note: If you are using ATTACH, you might also need the ECB parameter. If you provide an E15 user exit routine address in the parameter list, DFSORT ignores the SORTIN data set; your E15 routine must pass all input records to DFSORT. The same applies to a merge if you specify an E32 routine address. This means that your routine must issue a return code of 12 (insert record) until the input data set is complete, and then a return code of 8 (do not return). DFSORT ignores the SORTOUT data set if you provide an E35 routine address in the parameter list. Unless you use OUTFIL processing, your routine is then responsible for disposing of all output records. It must issue a return code of 4 (delete record) for each record in the output data set. When the program has deleted all the records, your routine issues a return code of 8 (do not return). When DFSORT is done, it passes control to the routine that invoked it. When a single task attaches two or more program applications, you must modify the standard ddnames so that they are unique. For ways of doing this, and for the rules of override, see Appendix B, Specification/Override of DFSORT Options, on page 741. If you ATTACH more than one DFSORT application from the same program, you must wait for each to complete before attaching the next unless DFSORT and your user exits are installed re-entrant. When you initiate DFSORT via XCTL, you must give special consideration to the area where the parameter list, address list, optional parameters, and modification routines (if any) are stored. This information must not reside in the module that issues the XCTL because the module is overlaid by DFSORT. There are two ways to overcome this problem. First, the control information can reside in a task that attaches the module that issues the XCTL. Second, the module issuing the XCTL can first issue a GETMAIN macro instruction and place the control information in the main storage area it obtains. This area is not overlaid when the XCTL is issued. The address of the control information in the area must be passed to DFSORT in general register 1.

Parameter List Examples

24-Bit Parameter List Example 1 Figure 33 on page 474 shows the format of the 24-bit parameter list you would use to specify the main storage option for a sort application.

Chapter 5. Invoking DFSORT from a Program

473

Writing The Macro Instruction

(Hex) (Dec) -2 2 6 A E 12 16 1A -2 2 6 10 14 18 22 26

Byte 1 Unused X '00' X '00' X '00' X '00' X '00' X '00' X '00'

Byte 2

Bytes 3 and 4 X '001C'

Starting address of SORT statement Ending address of SORT statement Starting address of RECORD statement Ending address of RECORD statement Zeros (no E15 routine provided) Zeros (no E35 routine provided) Main storage value (in hexadecimal)

Figure 33. Specifying the Main Storage Option (24-Bit Parameter List)

24-Bit Parameter List Example 2 Figure 34 shows the format of the 24-bit parameter list that you would use for a merge application when you want to supply input through an E32 routine and give control to the ESTAE routine if the program fails.

(Hex) (Dec) -2 2 6 A E 12 16 1A 1E -2 2 6 10 14 18 22 26 30

Byte 1 Unused X '00' X '00' X '00' X '00' X '00' X '00' X '04' X 'FE'

Byte 2

Bytes 3 and 4 X '001C'

Starting address of MERGE statement Ending address of MERGE statement Starting address of RECORD statement Ending address of RECORD statement Address of E32 routine Zeros (no E35 routine provided) Number of input files Zeros-no work area address provided)

Figure 34. Specifying E32 and ESTAE Routine (24-Bit Parameter List)

24-Bit Parameter List Example 3 Figure 35 on page 475 shows how a 24-bit parameter list might appear in main storage. General register 1 contains a pointer to the address of the parameter list which is at location 1000. The address points to the parameter list which begins at location 1006. The first 2-byte field of the parameter list contains, right-justified in hexadecimal, the number of bytes in the list (36 decimal).

474

z/OS V1R10.0 DFSORT Application Programming Guide

Writing The Macro Instruction

Reg 1

00 00 10 00

(pointer to address)

1000

80 00 10 06

(address of parameter list)

1004 1008 100C 1010 1014 1018 101C 1020 1024 102C

00 00 00 24 00 00 10 36 00 00 10 5B 00 00 10 5C 00 00 10 75 00 00 20 00 00 00 30 00 A B C # Optional

1036 # S O R T # F I E L D S = ( 1 0 , 1 5 , C H , A ) , F I L S Z = 4 7 8 0 6 # 105B

105C # R E C ORD # L E N G T H = 1 0 0 , T Y PE = F # 1075

00 00 65 90 FF ( U )

Parameter List
Figure 35. The 24-Bit Parameter List in Main Storage

The first two fullwords in the parameter list point to the beginning (location 1036) and end (location 105B) of the SORT control statement. The next two fullwords point to the beginning (location 105C) and end (location 1075) of the RECORD statement. The fifth and sixth fullwords in the list contain the entry point addresses for the E15 user exit (location 2000) and E35 user exit (location 3000). The next fullword in the list contains four characters to replace the letters SORT in the ddnames of standard DD statements. The next two fullwords in the list specify a main storage value for this application and a message option. 24-Bit Parameter List Example 4 The example in Figure 36 on page 476 shows, in assembler language, how to code the parameters and statement images needed for the 24-bit parameter list in Figure 35. It also shows how to pass control to DFSORT.

Chapter 5. Invoking DFSORT from a Program

475

Writing The Macro Instruction

LA 1,PARLST LOAD ADDR OF PARAM POINTER IN R1 ATTACH EP=SORT INVOKE SORT . . . PARLST DC X80,AL3(ADLST) POINTER FLAG/ADDRESS OF PARAM LIST . . . CNOP 2,4 ALIGN TO CORRECT BOUNDARY ADLST DC AL2(LISTEND-LISTBEG) PARAM LIST LENGTH LISTBEG DC A(SORTA) BEGINNING ADDRESS OF SORT STMT DC A(SORTZ) END ADDRESS OF SORT STMT DC A(RECA) BEGINNING ADDR OF RECORD STMT DC A(RECZ) END ADDR OF RECORD STMT DC A(MOD1) ADDR OF E15 RTN DC A(MOD2) ADDR OF E35 RTN DC CABC# DDNAME CHARACTERS DC F720000 OPTIONAL MAIN STORAGE VALUE DC XFF MESSAGE OPTION FLAG BYTE DC C(U) MESSAGE OPTION LISTEND EQU * SORTA DC C SORT FIELDS=(10,15,CH,A), SORT CONTROL STMT DC CFILSZ=E4780 (CONTINUED) SORTZ DC C DELIMITER RECA DC C RECORD LENGTH=100,TYPE=F RECORD CONTROL STMT RECZ DC C DELIMITER DS 0H USING *,15 MOD1 (routine for E15 user exit) . . USING *,15 MOD2 (routine for E35 user exit)

Figure 36. Coding a 24-Bit Parameter List

Extended Parameter List Example 1 The example in Figure 37 on page 477 shows, in assembler language, how to use an extended parameter list to code parameters and statement images and how to pass control to DFSORT.

476

z/OS V1R10.0 DFSORT Application Programming Guide

Restrictions for Dynamic Invocation

. . . LA * ST *

R1,PL1 R2,PL4

LINK EP=SORT . . . PL1 DC A(CTLST) ADDRESS OF CONTROL STATEMENTS PL2 DC A(E15) ADDRESS OF E15 ROUTINE PL3 DC A(0) NO E35 ROUTINE PL4 DS A USER EXIT ADDRESS CONSTANT PL5 DC F-1 INDICATE END OF LIST CTLST DS 0H CONTROL STATEMENTS AREA DC AL2(CTL2-CTL1) LENGTH OF CHARACTER STRING CTL1 DC C SORT FIELDS=(4,5,CH,A) DC C OPTION DC CRESINV=2048,FILSZ=E25000,MSGDDN=MSGOUT DC C OMIT COND=(5,8,EQ,13,8),FORMAT=FI DC C RECORD TYPE=F,LENGTH=80 CTL2 EQU * OUT DCB DDNAME=SYSOUT,... MYSORT USES SYSOUT E15 DS 0H E15 ROUTINE . . . BR R14 RETURN TO SORT/MERGE * MAPPING OF PARAMETER LIST PASSED TO E15 FROM SORT/MERGE SRTLST DS A ADDRESS OF RECORD GMA DS A ADDRESS OF AREA GETMAINED BY * MYSORT . . .

SET ADDRESS OF PARAMETER LIST TO BE PASSED TO SORT/MERGE SET ADDRESS OF GETMAINED AREA TO BE PASSED TO E15 INVOKE SORT/MERGE

Figure 37. Coding an Extended Parameter List

Restrictions for Dynamic Invocation Merge Restriction

Merge applications cannot be done when DFSORT is invoked from a PL/I program.

Copy Restrictions
Copy applications cannot be done when DFSORT is invoked from a PL/I program. If you invoke DFSORT from a COBOL program, the following restrictions apply: v The OPTION COPY statement can be placed in either the COBOL IGZSRTCD data set or the DFSORT SORTCNTL or DFSPARM data set. v If using the FASTSRT compiler option for any part or all of the COBOL SORT statement, a copy application can be done. v If using the COBOL MERGE statement, a copy application cannot be done. See COBOL Requirements for Copy Processing on page 444 for user exit requirements.
Chapter 5. Invoking DFSORT from a Program

477

478

z/OS V1R10.0 DFSORT Application Programming Guide

Chapter 6. Using ICETOOL

Overview. . . . . . . . . . . . . . . ICETOOL/DFSORT Relationship . . . . . . ICETOOL JCL Summary . . . . . . . . . ICETOOL Operator Summary . . . . . . . Complete ICETOOL Examples . . . . . . . Using Symbols . . . . . . . . . . . . Invoking ICETOOL . . . . . . . . . . Putting ICETOOL to Use . . . . . . . . Obtaining Various Statistics. . . . . . . Creating Multiple Versions/Combinations of Data Sets . . . . . . . . . . . . . Job Control Language for ICETOOL . . . . . . JCL Restrictions . . . . . . . . . . . ICETOOL Statements . . . . . . . . . . . General Coding Rules . . . . . . . . . COPY Operator . . . . . . . . . . . . Operand Descriptions . . . . . . . . . COPY Examples . . . . . . . . . . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Example 3 . . . . . . . . . . . . COUNT Operator . . . . . . . . . . . . Operand Descriptions . . . . . . . . . COUNT Examples . . . . . . . . . . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Example 3 . . . . . . . . . . . . DEFAULTS Operator . . . . . . . . . . . Operand Descriptions . . . . . . . . . DEFAULTS Example . . . . . . . . . . DISPLAY Operator . . . . . . . . . . . Simple Report . . . . . . . . . . . . Tailored Report . . . . . . . . . . . . Sectioned Report . . . . . . . . . . . Operand Descriptions . . . . . . . . . DISPLAY Examples . . . . . . . . . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Example 3 . . . . . . . . . . . . Example 4 . . . . . . . . . . . . Example 5 . . . . . . . . . . . . Example 6 . . . . . . . . . . . . Example 7 . . . . . . . . . . . . Example 8 . . . . . . . . . . . . Example 9 . . . . . . . . . . . . Example 10 . . . . . . . . . . . . Example 11 . . . . . . . . . . . . Example 12 . . . . . . . . . . . . Example 13 . . . . . . . . . . . . MODE Operator . . . . . . . . . . . . Operand Descriptions . . . . . . . . . MODE Example . . . . . . . . . . . OCCUR Operator . . . . . . . . . . . . Simple Report . . . . . . . . . . . . Tailored Report . . . . . . . . . . . . Operand Descriptions . . . . . . . . .
Copyright IBM Corp. 1973, 2006

480 480 481 481 482 483 483 484 484 485 487 489 490 490 491 491 493 493 493 494 494 495 497 497 497 497 497 498 499 502 503 504 505 505 531 531 531 532 532 534 534 535 537 539 541 542 544 545 546 547 547 548 549 550 551

OCCUR Examples . . . . . . . . . . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Example 3 . . . . . . . . . . . . Example 4 . . . . . . . . . . . . Example 5 . . . . . . . . . . . . RANGE Operator . . . . . . . . . . . . Operand Descriptions . . . . . . . . . RANGE Example . . . . . . . . . . . SELECT Operator . . . . . . . . . . . . Operand Descriptions . . . . . . . . . SELECT Examples . . . . . . . . . . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Example 3 . . . . . . . . . . . . Example 4 . . . . . . . . . . . . Example 5 . . . . . . . . . . . . Example 6 . . . . . . . . . . . . Example 7 . . . . . . . . . . . . Example 8 . . . . . . . . . . . . Example 9 . . . . . . . . . . . . SORT Operator . . . . . . . . . . . . . Operand Descriptions . . . . . . . . . SORT Examples . . . . . . . . . . . Example 1 . . . . . . . . . . . . Example 2 . . . . . . . . . . . . Example 3 . . . . . . . . . . . . SPLICE Operator . . . . . . . . . . . . Operand Descriptions . . . . . . . . . SPLICE Examples . . . . . . . . . . . Example 1 - Create one spliced record for each match in two files . . . . . . . . Example 2 - Combine complete records from four files . . . . . . . . . . . . . Example 3 - Create files with matching and non-matching records . . . . . . . . Example 4 - Create multiple spliced records for each match in two types of records . . . Example 5 - Pull records from a master file in sorted order . . . . . . . . . . . . Example 6 - Pull records from a master file in their original order . . . . . . . . . Example 7 - Create a report showing if needed parts are on-hand . . . . . . . Example 8 - Create a report showing if needed parts are on-hand - advanced . . . Example 9 - Create spliced variable-length records from two files . . . . . . . . STATS Operator . . . . . . . . . . . . Operand Descriptions . . . . . . . . . STATS Example . . . . . . . . . . . UNIQUE Operator . . . . . . . . . . . Operand Descriptions . . . . . . . . . UNIQUE Example . . . . . . . . . . . VERIFY Operator . . . . . . . . . . . . Operand Descriptions . . . . . . . . .

560 560 561 561 562 563 563 564 565 566 568 571 571 571 571 572 572 572 573 573 574 575 575 577 577 577 578 579 584 587 587 589 591 592 594 596 597 599 602 603 603 604 605 605 606 607 607

479

Using ICETOOL
VERIFY Example . . . . . Calling ICETOOL from a Program TOOLIN Interface . . . . . Parameter List Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 609 609 609 Explanation of Fields . . . . . Parameter List Interface Example . ICETOOL Notes and Restrictions . . . ICETOOL Return Codes . . . . . . . . . . . . . . . . . . . . . . 610 612 615 616

Overview
This chapter describes ICETOOL, a multi-purpose DFSORT utility. ICETOOL uses the capabilities of DFSORT to perform multiple operations on one or more data sets in a single job step. These operations include the following: v Creating multiple copies of sorted, edited, or unedited input data sets v Creating output data sets containing subsets of input data sets based on various criteria for character and numeric field values or the number of times unique values occur v Creating output data sets containing different field arrangements of input data sets v Creating list data sets showing character and numeric fields in a variety of simple, tailored, and sectioned report formats, allowing control of title, date, time, page numbers, headings, lines per page, field formats, and total, maximum, minimum and average values for the columns of numeric data v Printing messages that give statistical information for selected numeric fields such as minimum, maximum, average, total, count of values, and count of unique values v Printing messages that identify invalid decimal values v Printing messages that give record counts v Setting RC=12, RC=4, or RC=0 based on record counts v Creating a list data set showing the DFSORT installation defaults in use v Creating list data sets showing unique values for selected character and numeric fields and the number of times each occurs, in a variety of simple and tailored report formats v Creating list and output data sets for records with: duplicate values, non-duplicate values, or values that occur n times, less than n times or more than n times v Creating output data sets with information spliced together from two or more input records with duplicate values. The information in the input records can originate from different data sets, helping you to perform various file join and match operations. v Using three different modes (stop, continue, and scan) to control error checking and actions after error detection for groups of operators. Restriction: You can use ICETOOL for SORT and COPY operations, but you cannot use ICETOOL for MERGE operations.

ICETOOL/DFSORT Relationship
ICETOOL is a batch front-end utility that uses the capabilities of DFSORT to perform the operations you request. ICETOOL includes thirteen operators that perform sort, copy, statistical, report, selection, and splice operations. Most of the operations performed by ICETOOL require only simple JCL and operator statements. Some ICETOOL operations require or allow you to specify complete DFSORT control statements (such as SORT, INCLUDE or OMIT, INREC, and OUTFIL) to take full advantage of DFSORTs capabilities.

480

z/OS V1R10.0 DFSORT Application Programming Guide

Overview
ICETOOL automatically calls DFSORT with the particular DFSORT control statements and options required for each operation (such as DYNALLOC for sorting). ICETOOL also produces messages and return codes describing the results of each operation and any errors detected. Although you generally do not need to look at the DFSORT messages produced as a result of an ICETOOL run, they are available in a separate data set if you need them. ICETOOL can be called directly or from a program. ICETOOL allows operator statements (and comments) to be supplied in a data set or in a parameter list passed by a calling program. For each operator supplied in the parameter list, ICETOOL puts information in the parameter list pertaining to that operation, thus allowing the calling program to use the information derived by ICETOOL.

ICETOOL JCL Summary

The JCL statements used with ICETOOL are summarized below. See Job Control Language for ICETOOL on page 487 for more detailed information. See also JCL Restrictions on page 489 and ICETOOL Notes and Restrictions on page 615. //JOBLIB DD //STEPLIB DD //TOOLMSG DD //DFSMSG DD //SYMNAMES DD //SYMNOUT DD //TOOLIN DD //indd DD Defines your program link library if it is not already known to the system. Same as //JOBLIB DD Defines the ICETOOL message data set for all operations. Defines the DFSORT message data set for all operations. Defines the SYMNAMES data set containing statements to be used for symbol processing. Defines the data set in which SYMNAMES statements and the symbol table are to be listed. Contains ICETOOL control statements. Defines an input data set for a COPY, COUNT, DISPLAY, OCCUR, RANGE, SELECT, SORT, SPLICE, STATS, UNIQUE, or VERIFY operation. Defines an output data set for a COPY, SELECT, SORT, or SPLICE operation. Defines an output data set for a SELECT operation. Defines a list data set for a DEFAULTS, DISPLAY, or OCCUR operation. Contains DFSORT control statements for a COPY, COUNT, SELECT, SORT, or SPLICE operation.

//outdd DD //savedd DD //listdd DD //xxxxCNTL DD

ICETOOL Operator Summary

ICETOOL has thirteen operators that are used to perform a variety of functions. The functions of these operators are summarized below. See ICETOOL Statements on page 490 for more detailed information. Additionally, information pertaining to each operator is provided to calling programs that supply statements to ICETOOL using a parameter list. See Parameter List Interface on page 609 for details.
Chapter 6. Using ICETOOL

481

Overview
COPY COUNT Copies a data set to one or more output data sets. Prints a message containing the count of records in a data set. COUNT can also be used to set RC=12, RC=4, or RC=0 based on meeting criteria for the number of records in a data set. Prints the DFSORT installation defaults in a separate list data set. Prints the values or characters of specified numeric or character fields in a separate list data set. Simple, tailored, or sectioned reports can be produced. Three modes are available that can be set or reset for groups of operators: v STOP mode (the default) stops subsequent operations if an error is detected v CONTINUE mode continues with subsequent operations if an error is detected v SCAN mode allows ICETOOL statement checking without actually performing any operations. Prints each unique value for specified numeric or character fields and how many times it occurs in a separate list data set. Simple or tailored reports can be produced. The values printed can be limited to those for which the value count meets specified criteria (for example, only duplicate values or only non-duplicate values). Prints a message containing the count of values in a specified range for a specified numeric field in a data set. Selects records from a data set for inclusion in an output data set based on meeting criteria for the number of times specified numeric or character field values occur (for example, only duplicate values or only non-duplicate values). Records that are not selected can be saved in a separate output data set. Sorts a data set to one or more output data sets. Splices together specified fields from records that have the same specified numeric or character field values (that is, duplicate values), but different information. Specified fields from two or more records can be combined to create an output record. The fields to be spliced can originate from records in different data sets, so you can use SPLICE to do various join and match operations. Prints messages containing the minimum, maximum, average, and total for specified numeric fields in a data set. Prints a message containing the count of unique values for a specified numeric or character field. Examines specified decimal fields in a data set and prints a message identifying each invalid value found for each field.

DEFAULTS DISPLAY

MODE

OCCUR

RANGE SELECT

SORT SPLICE

STATS UNIQUE VERIFY

Complete ICETOOL Examples

ICETOOL Example on page 729 contains a complete ICETOOL sample job with all required JCL and control statements. The example below shows the JCL and control statements for a simple ICETOOL job.

482

z/OS V1R10.0 DFSORT Application Programming Guide

Overview

//EXAMP JOB A402,PROGRAMMER //RUNIT EXEC PGM=ICETOOL,REGION=1024K //TOOLMSG DD SYSOUT=A //DFSMSG DD SYSOUT=A //TOOLIN DD * * Show installation defaults DEFAULTS LIST(SHOWDEF) * Create three copies of a data set COPY FROM(IN1) TO(OUT1,OUT2,OUT3) * Print a report DISPLAY FROM(IN2) LIST(REPORT) DATE TITLE(Monthly Report) PAGE HEADER(Location) ON(1,25,CH) HEADER(Revenue) ON(23,10,FS) HEADER(Profit) ON(45,10,FS) TOTAL(Totals) AVERAGE(Averages) BLANK * Select all records with duplicate (non-unique) keys SELECT FROM(IN2) TO(DUPKEYS) ON(1,25,CH) ALLDUPS * Save all records with non-duplicate (unique) keys DISCARD (UNQKEYS) /* //SHOWDEF DD SYSOUT=A //IN1 DD DSN=FLY.INPUT1,DISP=SHR //IN2 DD DSN=FLY.INPUT2,DISP=SHR //OUT1 DD DSN=FLY.NEW,DISP=OLD //OUT2 DD DSN=FLY.BU1,DISP=OLD //OUT3 DD DSN=FLY.BU2,DISP=OLD //DUPKEYS DD DSN=FLY.DUPS,DISP=OLD //UNQKEYS DD DSN=FLY.UNQS,DISP=OLD //REPORT DD SYSOUT=A

Figure 38. Simple ICETOOL Job

Using Symbols
You can define and use a symbol for any field or constant in the following ICETOOL operators: COUNT, DISPLAY, OCCUR, RANGE, SELECT, SPLICE, STATS, UNIQUE, and VERIFY. You can also use symbols in the DFSORT control statements you specify for an ICETOOL run. This makes it easy to create and reuse collections of symbols (that is, mappings) representing information associated with various record layouts. You can use system symbols (for example, &JOBNAME.) in your symbol constants. See Chapter 7, Using Symbols for Fields and Constants, on page 617 for complete details.

Invoking ICETOOL
ICETOOL can be invoked in the following three ways: v Directly (that is, not from a program) using the TOOLIN Interface v From a program using the TOOLIN Interface v From a program using the Parameter List Interface. With the TOOLIN Interface, you supply ICETOOL statements in a data set defined by the TOOLIN DD statement. ICETOOL prints messages in the data set defined by the TOOLMSG DD statement.

Chapter 6. Using ICETOOL

483

Overview
With the Parameter List Interface, your program supplies ICETOOL statements in a parameter list. ICETOOL prints messages in the data set defined by the TOOLMSG DD statement and also puts information in the parameter list for use by your program.

Putting ICETOOL to Use

By using various combinations of the thirteen ICETOOL operators, you can easily create applications that perform many complex tasks. The two small samples that follow show some things you can do with ICETOOL.

Obtaining Various Statistics

Table 64. Obtaining Various Statistics MODE STOP VERIFY FROM(DATA1) ON(22,7,PD) DISPLAY FROM(DATA1) LIST(SALARIES) TITLE(Employee Salaries) DATE TIME HEADER(Employee Name) HEADER(Salary) ON(1,20,CH) ON(22,7,PD) BLANK AVERAGE(Average Salary) STATS FROM(DATA1) ON(22,7,PD) RANGE FROM(DATA1) ON(22,7,PD) LOWER(20000) RANGE FROM(DATA1) ON(22,7,PD) HIGHER(19999) LOWER(40000) RANGE FROM(DATA1) ON(22,7,PD) HIGHER(40000) OCCUR FROM(DATA1) LIST(SALARIES) TITLE(Employees Receiving Each Salary) DATE TIME HEADER(Salary) HEADER(Employee Count) ON(22,7,PD) ON(VALCNT) BLANK

Assume that you specify DD statements with the following ddnames for the indicated data sets: DATA1 A data set containing the name, salary, department, location and so on, of each of your employees. The name field is in positions 1 through 20 in character format and the salary field is in positions 22 through 28 in packed decimal format. A SYSOUT data set.

SALARIES

You can use the ICETOOL operators in Table 64 to do the following: MODE STOP If an error is found while processing one of the operators, subsequent operators are not processed (that is, each operator is dependent on the success of the previous operator). Prints error messages in the TOOLMSG data set identifying any invalid values in the packed decimal salary field. Prints a report with each employees name and salary and the average for all employee salaries in the SALARIES list data set. Prints messages in the TOOLMSG data set showing the minimum, maximum, average, and total of the individual salaries. The three RANGE operators print messages in the

VERIFY

DISPLAY

STATS

RANGE

484

z/OS V1R10.0 DFSORT Application Programming Guide

Overview
TOOLMSG data set showing the number of salaries below $20,000, from $20,000 to $39,999, and above $40,000. OCCUR Prints a report with each unique salary and the number of employees who receive it in the SALARIES list data set.

Creating Multiple Versions/Combinations of Data Sets

Table 65. Creating Multiple Versions/Combinations of Data Sets * GROUP 1 MODE CONTINUE COPY FROM(DATA1) TO(DATA2) COPY FROM(MSTR1) TO(MSTR2) SELECT FROM(DATA1) TO(SMALLDPT) ON(30,4,CH) LOWER(10) UNIQUE FROM(MSTR1) ON(30,4,CH) * GROUP 2 MODE STOP COPY FROM(DATA1) TO(TEMP1) USING(NEW1) COPY FROM(DATA1) TO(TEMP2) USING(NEW2) COPY FROM(DATA1) TO(TEMP3) USING(NEW3) SORT FROM(CONCAT) TO(FINALD,FINALP) USING(FINL)

Assume that you specify DD statements with the following ddnames for the indicated data sets: DATA1 A data set containing the name, salary, department, location, and so on, of each of your employees. The department field is in positions 30 through 33 in character format. Master data set containing only the name and department of each of your employees. The department field is in positions 30 through 33 in character format.

MSTR1

DATA2, MSTR2, and SMALLDPT Permanent data sets. NEW1CNTL A data set containing DFSORT control statements to INCLUDE employees in department X100 and change the records to match the format of MSTR1. Same as NEW1CNTL but for department X200. Same as NEW1CNTL but for department X300.

NEW2CNTL NEW3CNTL

TEMP1, TEMP2, and TEMP3 Temporary data sets. FINLCNTL CONCAT FINALD FINALP A data set containing a DFSORT control statement to sort by department and employee name. A concatenation of the TEMP1, TEMP2, TEMP3, and MSTR1 data sets. A permanent data set. A SYSOUT data set.

You can use the ICETOOL operators in Table 65 to do the following: MODE CONTINUE If an error is found while processing any of the group 1 operators, subsequent group 1 operators

Chapter 6. Using ICETOOL

485

Overview
are still processed; that is, group 1 operators are not dependent on the success of the previous group 1 operators. COPY SELECT The two copy operators create backup copies of DATA1 and MSTR1. Creates a permanent output data set containing the name, salary, department, location, and so on, of each employee in departments with less than 10 people. Prints a message in the TOOLMSG data set showing the number of unique departments. If an error is found while processing one of the group 2 operators, subsequent group 2 operators are not processed; that is, each group 2 operator is dependent on the success of previous group 2 operators. The three COPY operators create an output data set for the employees in each department containing only name and department. Note that the ddname requested by the USING(xxxx) operand is xxxxCNTL. For example, USING(NEW1) requests ddname NEW1CNTL. Sorts the three output data sets created by the COPY operators along with the master name/department data set and creates permanent and SYSOUT data sets containing the resulting sorted records.

UNIQUE MODE STOP

COPY

SORT

You can combine both of these examples into a single ICETOOL job step.

486

z/OS V1R10.0 DFSORT Application Programming Guide

Job Control Language for ICETOOL

Job Control Language for ICETOOL

An overview of the job control language (JCL) statements for ICETOOL is given below followed by discussions of each ICETOOL DD statement and the use of reserved DD statements and ddnames.
Table 66. JCL Statements for ICETOOL
//EXAMPL JOB ... //* ICETOOL CAN BE CALLED DIRECTLY OR FROM A PROGRAM //STEP EXEC PGM=ICETOOL (or PGM=program_name) //* THE FOLLOWING DD STATEMENTS ARE ALWAYS REQUIRED //TOOLMSG DD SYSOUT=A (or DSN=...) //DFSMSG DD SYSOUT=A //* THE FOLLOWING DD STATEMENTS ARE USED FOR SYMBOL PROCESSING //* SYMNAMES DD ... //* SYMNOUT DD SYSOUT=A (OR DSN=...) //* THE TOOLIN DD STATEMENT IS ONLY REQUIRED IF THE TOOLIN INTERFACE //* IS USED. //TOOLIN DD * ICETOOL statements /* //* THE FOLLOWING DD STATEMENTS ARE ONLY REQUIRED IF SPECIFIED IN //* ICETOOL STATEMENTS. //indd DD ... . . . //outdd DD ... . . . //listdd DD SYSOUT=A (or DSN=...) . . . //xxxxCNTL DD * DFSORT control statements /* . . .

TOOLMSG DD Statement Defines the ICETOOL message data set for all operations. ICETOOL messages and statements appear in this data set. ICETOOL uses RECFM=FBA, LRECL=121 and the specified BLKSIZE for the TOOLMSG data set. If the BLKSIZE you specify is not a multiple of 121, ICETOOL uses BLKSIZE=121. If you do not specify the BLKSIZE, ICETOOL selects the block size as directed by the SDBMSG installation option (see z/OS DFSORT Installation and Customization). The TOOLMSG DD statement must be present. DFSMSG DD Statement Defines the DFSORT message data set for all operations. The DFSORT messages and control statements from all ICETOOL calls to DFSORT appear in this data set. Refer to the discussion of SYSOUT in System DD Statements on page 64 for details. Either a DFSMSG DD statement or an SSMSG DD statement must be present. If both are present, ICETOOL uses DFSMSG as the

Chapter 6. Using ICETOOL

487

Job Control Language for ICETOOL

DFSORT message data set. If a DFSMSG DD is not present, but an SSMSG DD is present, ICETOOL uses SSMSG as the DFSORT message data set. Note: A SYSOUT data set should be used for the DFSORT message data set (for example, //DFSMSG DD SYSOUT=*). If you define the DFSORT message data set as a temporary or permanent data set, you will only see the DFSORT messages from the last call to DFSORT, unless you allocate a new data set using a disposition of MOD. //SYMNAMES DD Defines the SYMNAMES data set containing statements to be used for symbol processing. See Chapter 7, Using Symbols for Fields and Constants, on page 617 for complete details. //SYMNOUT DD Defines the data set in which SYMNAMES statements and the symbol table are to be listed. See Chapter 7, Using Symbols for Fields and Constants, on page 617 for complete details. TOOLIN DD statement Defines the ICETOOL statement data set that must have the following attributes: RECFM=F or RECFM=FB and LRECL=80. If the TOOLIN Interface is used, the TOOLIN DD statement must be present. If the Parameter List Interface is used, the TOOLIN DD statement is not required and is ignored if present. indd DD Statement Defines the input data set for an operation. Refer to SORTIN DD Statement on page 68 for details. ICETOOL imposes the additional restriction that the LRECL of this data must be at least 4. An indd DD statement must be present for each unique indd name specified in each FROM operand. outdd DD Statement Defines an output data set for a COPY, SELECT, SORT, or SPLICE operation. Refer to SORTOUT and OUTFIL DD Statements on page 74 for details. An outdd DD statement must be present for each unique outdd name specified in each TO operand. savedd DD Statement Defines an output data set for a SELECT operation. Refer to SORTOUT and OUTFIL DD Statements on page 74 for details. A savedd DD statement must be present for each unique savedd name specified in each DISCARD operand. listdd DD Statement Defines the list data set for a DEFAULTS, DISPLAY, or OCCUR operation. For each listdd data set, ICETOOL uses RECFM=FBA, LRECL=121 (for DEFAULTS) or the LRECL specified in the WIDTH operand or calculated as needed if WIDTH is not specified (DISPLAY and OCCUR), and the specified block size. If the BLKSIZE you specify is not a multiple of the LRECL, ICETOOL uses BLKSIZE=LRECL. If you do not specify BLKSIZE, ICETOOL

488

z/OS V1R10.0 DFSORT Application Programming Guide

Job Control Language for ICETOOL

selects the block size as directed by the LISTSDB or LISTNOSDB option if specified, or otherwise as directed by the SDBMSG installation option (see z/OS DFSORT Installation and Customization). A listdd DD statement must be present for each unique listdd name specified in each LIST operand. xxxxCNTL DD Statement Defines the DFSORT control statement data set for a COPY, COUNT, SELECT, SORT, or SPLICE operation. Refer to SORTCNTL DD Statement on page 76 for more details. An xxxxCNTL DD statement must be present for each unique xxxx specified in each USING operand.

JCL Restrictions
You should avoid using ddnames reserved for ICETOOL and DFSORT in ICETOOL operands (FROM, TO, LIST,DISCARD). In general, you should also avoid supplying DD statements with ddnames reserved for DFSORT when using ICETOOL because doing so can cause unpredictable results. Specifically: v SORTCNTL should not be used as a ddname in ICETOOL operators nor should it be supplied as a DD statement. A xxxxCNTL DD statement should only be supplied when you specify a USING(xxxx) operand. xxxx must be four characters that are valid in a ddname of the form xxxxCNTL. xxxx must not be SYSx. v SYSIN, SORTCNTL, SORTIN, SORTOUT, SORTINnn, and xxxxINnn (where xxxx is specified in a USING operand) should not be used as ddnames in ICETOOL operators nor supplied as DD statements. v TOOLMSG, DFSMSG, SSMSG, SYMNAMES, SYMNOUT, TOOLIN, SYSUDUMP, and SYSABEND should not be used as ddnames in ICETOOL operators. v In general, xxxxWKdd ddnames should not be used as ddnames in ICETOOL operators nor supplied as DD statements. However, if you want to override dynamic allocation of work data sets for ICETOOL operators OCCUR and UNIQUE, you can use SORTWKdd DD statements for that purpose. If you want to override dynamic allocation of work data sets for ICETOOL operators SELECT, SORT, and SPLICE, you can use xxxxWKdd DD statements for that purpose in conjunction with the USING operand. v DFSPARM (or the ddname specified for the PARMDDN installation option) should not be used as a ddname in ICETOOL operators. It should only be used as a DD statement to override DFSORT options for all operators, if appropriate. Refer to DFSPARM DD Statement on page 77 for details. v xxxxOFdd (where xxxx is specified in a USING operand) is required as the ddname when an OUTFIL statement in the xxxxCNTL data set specifies FILES=dd. To avoid this requirement, use the FNAMES=ddname operand rather than the FILES=dd operand in OUTFIL statements, and include a DD statement for the specified ddname. See OUTFIL Control Statements on page 221 for details of the FNAMES operand. You should not use different DDs for a data set to be used for output and then input in the same step, if that data set can be extended to a second or subsequent volume, because that will result in incorrect output. See Data Set Notes and Limitations on page 13 for more information.

Chapter 6. Using ICETOOL

489

ICETOOL Statements

ICETOOL Statements
Each operation must be described to ICETOOL using an operator statement. Additionally, ICETOOL allows comment statements and blank statements. An explanation of the general rules for coding ICETOOL statements is given below followed by a detailed discussion of each operator.

General Coding Rules

The general format for all ICETOOL operator statements is: OPERATOR operand ... operand where each operand consists of KEYWORD(parameter, parameter...) or just KEYWORD. Any number of operators can be specified and in any order. The following rules apply for operator statements: The operator and operands must be in uppercase EBCDIC. The operator must be specified first. One blank is required between the operator and the first operand. One blank is required between operands. Any number of blanks can be specified before or after the operator or any operand, but blanks cannot be specified anywhere else except within quoted character strings. v Parentheses must be used where shown. Commas or semicolons must be used where commas are shown. v v v v v v Operands can be in any order. v Columns 1-72 are scanned; columns 73-80 are ignored. v Continuation can be indicated by a hyphen (-) after the operator or after any operand. The next operand must then be specified on the next line. For example:
SORT FROM(INDD) USING(ABCD) TO(OUTPUT1,OUTPUT2,OUTPUT3)

Any characters specified after the hyphen are ignored. Each operand must be completely specified on one line. A statement with an asterisk (*) in column 1 is treated as a comment statement. It is printed with the other ICETOOL statements, but otherwise not processed. A statement with blanks in columns 1 through 72 is treated as a blank statement. It is ignored, because ICETOOL prints blank lines where appropriate.

490

z/OS V1R10.0 DFSORT Application Programming Guide

COPY Operator

COPY Operator

, COPY FROM(indd) TO( outdd USING(xxxx) , TO( outdd ) VSAMTYPE(x)

USING(xxxx)

LOCALE(name) LOCALE(CURRENT) LOCALE(NONE)

SERIAL

Copies an input data set to one or more output data sets. DFSORT is called to copy the indd data set to the outdd data sets; the DFSORT control statements in xxxxCNTL are used if USING(xxxx) is specified. You can use DFSORT control statements and options in the xxxxCNTL data set to copy a subset of the input records (INCLUDE or OMIT statement; SKIPREC and STOPAFT options; OUTFIL INCLUDE, OMIT, SAVE, STARTREC, ENDREC, SAMPLE, SPLIT, SPLITBY, and SPLIT1R operands; user exit routines), reformat records for output (INREC, OUTREC and OUTFIL statements, user exit routines), and so on. If an INCLUDE or OMIT statement or an OUTFIL INCLUDE or OMIT operand is specified in the xxxxCNTL data set, the active locales collating rules affect INCLUDE and OMIT processing, as explained in the Cultural Environment Considerations discussion in INCLUDE Control Statement on page 98.

Operand Descriptions
The operands described below can be specified in any order. FROM(indd) Specifies the ddname of the input data set to be read by DFSORT for this operation. An indd DD statement must be present and must define an input data set that conforms to the rules for DFSORTs SORTIN data set. Refer to JCL Restrictions on page 489 for more information regarding the selection of ddnames. TO(outdd,...) Specifies the ddnames of the output data sets to be written by DFSORT for this operation. From 1 to 10 outdd names can be specified. An outdd DD statement must be present for each outdd name specified. If a single outdd data set is specified, DFSORT is called once to copy the indd data set to the outdd data set, using SORTOUT processing; the outdd data set must conform to the rules for DFSORTs SORTOUT data set. If multiple outdd data sets are specified and SERIAL is not specified, DFSORT is called once to copy the indd data set to the outdd data sets, using OUTFIL processing; the outdd data sets must conform to the rules for DFSORTs OUTFIL data sets.
Chapter 6. Using ICETOOL

491

COPY Operator
TO and USING can both be specified. If USING is not specified, TO must be specified. If TO is not specified, USING must be specified. A ddname specified in the FROM operand must not also be specified in the TO operand. Refer to JCL Restrictions on page 489 for more information regarding the selection of ddnames. USING(xxxx) Specifies the first 4 characters of the ddname for the control statement data set to be used by DFSORT for this operation. xxxx must be four characters that are valid in a ddname of the form xxxxCNTL. xxxx must not be SYSx. If USING is specified, an xxxxCNTL DD statement must be present and the control statements in it must conform to the rules for DFSORTs SORTCNTL data set. TO and USING can both be specified. If USING is not specified, TO must be specified. If TO is not specified, USING must be specified and the xxxxCNTL data set must contain either one or more OUTFIL statements or a MODS statement for an E35 routine that disposes of all records. Other statements are optional. Refer to JCL Restrictions on page 489 for more information regarding the selection of ddnames. VSAMTYPE(x) Specifies the record type for a VSAM input data set. x must be either F for fixed-length record processing or V for variable-length record processing. If VSAMTYPE(x) is specified, ICETOOL will pass a RECORD TYPE=x control statement to DFSORT. (If you specify a RECORD TYPE=x statement in the xxxxCNTL data set, it will override the one passed by ICETOOL.) For complete information on record type processing for VSAM input, see RECORD Control Statement on page 394. LOCALE(name) Specifies that locale processing is to be used and designates the name of the locale to be made active during DFSORT processing. LOCALE(name) can be used to override the LOCALE installation option. For complete details on LOCALE(name), see the discussion of the LOCALE operand in OPTION Control Statement on page 167. LOCALE(CURRENT) Specifies that locale processing is to be used, and the current locale active when DFSORT is entered will remain the active locale during DFSORT processing. LOCALE(CURRENT) can be used to override the LOCALE installation option. For complete details on LOCALE(CURRENT), see the discussion of the LOCALE operand in OPTION Control Statement on page 167. LOCALE(NONE) Specifies that locale processing is not to be used. DFSORT will use the binary encoding of the code page defined for your data for collating and comparing. LOCALE(NONE) can be used to override the LOCALE installation option. For complete details on LOCALE(NONE), see the discussion of the LOCALE operand in OPTION Control Statement on page 167. SERIAL Specifies that OUTFIL processing is not to be used when multiple outdd data

492

z/OS V1R10.0 DFSORT Application Programming Guide

COPY Operator
sets are specified. DFSORT is called multiple times and uses SORTOUT processing; the outdd data sets must conform to the rules for DFSORTs SORTOUT data set. SERIAL is not recommended because the use of serial processing (that is, multiple calls to DFSORT) instead of OUTFIL processing can degrade performance and imposes certain restrictions as detailed below. SERIAL is ignored if a single outdd data set is specified. DFSORT is called to copy the indd data set to the first outdd data set using the DFSORT control statements in the xxxxCNTL data set if USING(xxxx) is specified. If the first copy is successful, DFSORT is called as many times as necessary to copy the first outdd data set to the second and subsequent outdd data sets. Therefore, for maximum efficiency, use a disk data set as the first in a list of outdd data sets on both disk and tape. If more than one outdd data set is specified, DFSORT must be able to read the first outdd data set after it is written in order to copy it to the other outdd data sets. Do not use a SYSOUT or DUMMY data set as the first in a list of outdd data sets because: v if the first data set is SYSOUT, DFSORT abends when it tries to copy the SYSOUT data set to the second outdd data set. v if the first data set is DUMMY, DFSORT copies the empty DUMMY data set to the other outdd data sets, with the result that all outdd data sets are then empty.

COPY Examples
Although the COPY operators in the examples below could all be contained in a single ICETOOL job step, they are shown and discussed separately for clarity.

Example 1
* Method 1 COPY FROM(MASTER) TO(PRINT,TAPE,DISK) * Method 2 COPY FROM(MASTER) TO(DISK,TAPE,PRINT) SERIAL

This example shows two different methods for creating multiple output data sets. Method 1 requires one call to DFSORT, one pass over the input data set, and allows the output data sets to be specified in any order. The COPY operator copies all records from the MASTER data set to the PRINT (SYSOUT), TAPE, and DISK data sets, using OUTFIL processing. Method 2 requires three calls to DFSORT, three passes over the input data set, and imposes the restriction that the SYSOUT data set must not be the first TO data set. The COPY operator copies all records from the MASTER data set to the DISK data set and then copies the resulting DISK data set to the TAPE and PRINT (SYSOUT) data sets. Because the first TO data set is processed three times (written, read, read), placing the DISK data set first is more efficient than placing the TAPE data set first. PRINT must not be the first in the TO list because a SYSOUT data set cannot be read.

Example 2
* Method 1 COPY FROM(IN) TO(DEPT1) USING(DPT1) COPY FROM(IN) TO(DEPT2) USING(DPT2) COPY FROM(IN) TO(DEPT3) USING(DPT3) * Method 2 COPY FROM(IN) USING(ALL3)

Chapter 6. Using ICETOOL

493

COPY Operator
This example shows two different methods for creating subsets of an input data set. Assume that: v The DPT1CNTL data set contains:
INCLUDE COND=(5,3,CH,EQ,CD01)

v The DPT2CNTL data set contains:

INCLUDE COND=(5,3,CH,EQ,CD02)

v The DPT3CNTL data set contains:

INCLUDE COND=(5,3,CH,EQ,CD03)

v The ALL3CNTL data set contains:

OUTFIL FNAMES=DEPT1,INCLUDE=(5,3,CH,EQ,CD01) OUTFIL FNAMES=DEPT2,INCLUDE=(5,3,CH,EQ,CD02) OUTFIL FNAMES=DEPT3,INCLUDE=(5,3,CH,EQ,CD03)

Method 1 requires three calls to DFSORT and three passes over the input data set: v The first COPY operator copies the records from the IN data set that contain D01 in positions 5-7 to the DEPT1 data set. v The second COPY operator copies the records from the IN data set that contain D02 in positions 5-7 to the DEPT2 data set. v The third COPY operator copies the records from the IN data set that contain D03 in positions 5-7 to the DEPT3 data set. Method 2 accomplishes the same result as method 1, but because it uses OUTFIL statements instead of TO operands, requires only one call to DFSORT and one pass over the input data set.

Example 3
COPY FROM(VSAMIN) TO(VSAMOUT) VSAMTYPE(V)

The COPY operator copies all records from the VSAMIN data set to the VSAMOUT data set. The VSAM records are treated as variable-length.

COUNT Operator

COUNT FROM(indd) USING(xxxx) VSAMTYPE(x)

LOCALE(name) LOCALE(CURRENT) LOCALE(NONE)

RC4

EMPTY NOTEMPTY HIGHER(x) LOWER(y) EQUAL(v) NOTEQUAL(w)

Prints a message containing the count of records in a data set. Can also be used to set RC=12, RC=4, or RC=0 based on meeting criteria for the number of records in a data set.

494

z/OS V1R10.0 DFSORT Application Programming Guide

COUNT Operator
DFSORT is called to copy the indd data set to ICETOOLs E35 user exit. The DFSORT control statements in xxxxCNTL are used if USING(xxxx) is specified. You can use a DFSORT INCLUDE or OMIT statement in the xxxxCNTL data set to count a subset of the input records. If an INCLUDE or OMIT statement is specified in the xxxxCNTL data set, the active locales collating rules affect INCLUDE and OMIT processing as explained in the Cultural Environment Considerations discussion in INCLUDE Control Statement on page 98. If EMPTY, NOTEMPTY, HIGHER(x), LOWER(y), EQUAL(v) or NOTEQUAL(w) is not specified, ICETOOL prints a message containing the record count as determined by its E35 user exit. If EMPTY, NOTEMPTY, HIGHER(x), LOWER(y), EQUAL(v) or NOTEQUAL(w) is specified, ICETOOL checks the record count as determined by its E35 user exit against the specified criteria. If the criteria is met (for example, HIGHER(20) is specified and the record count is 21 or more), ICETOOL sets RC=12 for the COUNT operator by default or RC=4 for the COUNT operator, if RC4 is specified. If the criteria is not met (for example, HIGHER(20) is specified and the record count is 20 or less), ICETOOL sets RC=0 for the COUNT operator. ICETOOL uses DFSORTs STOPAFT option to process the minimum number of records required to determine whether or not the criteria is met. Note: Be sure to check the messages in TOOLMSG when you initially set up any COUNT operators with criteria to make sure that RC=12 is not issued because of syntax errors. You must not supply your own DFSORT MODS statement because it would override the MODS statement passed by ICETOOL for this operator. Note: The record count is also printed for the DISPLAY, OCCUR, RANGE, SELECT, STATS, UNIQUE, and VERIFY operators.

Operand Descriptions
The operands described below can be specified in any order. FROM(indd) See the discussion of this operand on the COPY statement in COPY Operator on page 491. USING(xxxx) Specifies the first 4 characters of the ddname for the control statement data set to be used by DFSORT for this operation. xxxx must be four characters that are valid in a ddname of the form xxxxCNTL. xxxx must not be SYSx. If USING is specified, an xxxxCNTL DD statement must be present and the control statements in it: 1. Must conform to the rules for DFSORTs SORTCNTL data set. 2. Should generally be used only for an INCLUDE or OMIT statement or comments statements. Refer to JCL Restrictions on page 489 for more information regarding the selection of ddnames. VSAMTYPE(x) See the discussion of this operand on the COPY statement in COPY Operator on page 491.
Chapter 6. Using ICETOOL

495

COUNT Operator
LOCALE(name) See the discussion of this operand on the COPY statement in COPY Operator on page 491. LOCALE(CURRENT) See the discussion of this operand on the COPY statement in COPY Operator on page 491. LOCALE(NONE) See the discussion of this operand on the COPY statement in COPY Operator on page 491. RC4 Can be used to set RC=4 for this COUNT operator if the record count meets the specified criteria. RC4 can be specified only if EMPTY, NOTEMPTY, HIGHER(x), LOWER(y), EQUAL(v), or NOTEQUAL(w) is specified. RC4 overrides the default of setting RC=12 for this COUNT operator if the record count meets the specified criteria EMPTY Sets RC=12 (or RC=4 if RC4 is specified) for this COUNT operator if the input data set or subset is empty, or sets RC=0 for this COUNT operator if the input data set or subset is not empty. EMPTY is equivalent to EQUAL(0). NOTEMPTY Sets RC=12 (or RC=4 if RC4 is specified) for this COUNT operator if the input data set or subset is not empty, or sets RC=0 for this COUNT operator if the input data set or subset is empty. EMPTY is equivalent to NOTEQUAL(0). HIGHER(x) Sets RC=12 (or RC=4 if RC4 is specified) for this COUNT operator if the record count is higher than x, or sets RC=0 for this COUNT operator if the record count is equal to or lower than x. x must be specified as n or +n where n can be 0 to 562949953421310. LOWER(y) Sets RC=12 (or RC=4 if RC4 is specified) for this COUNT operator if the record count is lower than y, or sets RC=0 for this COUNT operator if the record count is equal to or higher than y. y must be specified as n or +n where n can be 0 to 562949953421310. EQUAL(v) Sets RC=12 (or RC=4 if RC4 is specified) for this COUNT operator if the record count is equal to v, or sets RC=0 for this COUNT operator if the record count is not equal to v. v must be specified as n or +n where n can be 0 to 562949953421310. NOTEQUAL(w) Sets RC=12 (or RC=4 if RC4 is specified) for this COUNT operator if the record count is not equal to w, or sets RC=0 for this COUNT operator if the record count is equal to w. w must be specified as n or +n where n can be 0 to 562949953421310.

496

z/OS V1R10.0 DFSORT Application Programming Guide

COUNT Operator

COUNT Examples
Example 1
For this example, assume that the CTL1CNTL data set contains a DFSORT INCLUDE statement.
COUNT FROM(IN1) COUNT FROM(IN2) USING(CTL1)

The first COUNT operator prints a message containing the count of records in the IN1 data set. The second COUNT operator prints a message containing the count of records included from the IN2 data set.

Example 2
COUNT FROM(INPUT1) EMPTY

Sets RC=12 if INPUT1 is empty (that is, INPUT1 has no records), or sets RC=0 if INPUT1 is not empty (that is, INPUT1 has at least one record).

Example 3
For this example, assume that the CTL2CNTL data set contains a DFSORT INCLUDE statement.
COUNT FROM(INPUT2) HIGHER(50000) RC4 USING(CTL2)

Sets RC=4 if more than 50000 records are included from INPUT2, or sets RC=0 if 50000 or less records are included from INPUT2.

DEFAULTS Operator

DEFAULTS LIST(listdd) LISTSDB LISTNOSDB

| | | | | | | | | | | | |

Prints the DFSORT installation defaults report in a separate list data set. DFSORT enables you to maintain separate sets of installation defaults for eight different installation environments as follows: v JCL (ICEAM1) - batch JCL directly invoked installation environment v INV (ICEAM2) - batch program invoked installation environment v TSO (ICEAM3) - TSO directly invoked installation environment v TSOINV (ICEAM4) - TSO program invoked installation environment v TD1 (ICETD1) - first time-of-day installation environment v TD2 (ICETD2) - second time-of-day installation environment v TD3 (ICETD3) - third time-of-day installation environment v TD4 (ICETD4) - fourth time-of-day installation environment Each installation default has two or more possible values; DFSORT is shipped with a set of IBM-supplied defaults that can be modified using ICEPRMxx members of
Chapter 6. Using ICETOOL

497

DEFAULTS Operator
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | PARMLIB or the ICEMAC macro. The DEFAULTS operator provides an easy way to determine the installation default values to be used at run-time. See z/OS DFSORT Installation and Customization for a complete discussion of ICEPRMxx members in PARMLIB, the ICEMACmacro, the eight installation environments, and the installation default values. DEFAULTS produces a three-part report showing: 1. The merged PARMLIB/ICEMAC installation default values for ICEAM1-4 and ICETD1-4 that will be used at run-time. 2. The specified PARMLIB ICEPRMxx member option values for ICEAM1-4 and ICETD1-4 (for reference). 3. The ICEMAC installation default values for ICEAM1-4 and ICETD1-4 (for reference). The format of the report produced by DEFAULTS varies depending on the defaults selected, but the first part of the report might look like this conceptually:

Z/OS DFSORT V1R10 MERGED PARMLIB/ICEMAC DEFAULTS

- p -

* IBM-SUPPLIED DEFAULT (ONLY SHOWN IF DIFFERENT FROM THE SPECIFIED DEFAULT) ITEM ---------item . . . item item . . . Z/OS DFSORT V1R10 MERGED PARMLIB/ICEMAC DEFAULTS - p JCL (ICEAM1) VALUE -------------------value INV (ICEAM2) VALUE -------------------value TSO (ICEAM3) VALUE -------------------value TSOINV (ICEAM4) VALUE ------------------value

value value

value value * IBM_value

value value

value value

* IBM-SUPPLIED DEFAULT (ONLY SHOWN IF DIFFERENT FROM THE SPECIFIED DEFAULT) ITEM ---------item . . . item item . . . TD1 (ICETD1) VALUE -------------------value TD2 (ICETD2) VALUE -------------------value TD3 (ICETD3) VALUE -------------------value TD4 (ICETD4) VALUE ------------------value

value * IBM_value value

value * IBM_value value

value value

value value

The merged PARMLIB/ICEMAC default value for each item is shown as it is set for each of the eight installation environments. For any value that is different from the IBM-supplied value, the IBM-supplied value is shown below it. The control character occupies the first byte of each record. The title and headings are always printed; p is the page number. The item name column occupies 10 bytes, each of the item value columns occupies 20 bytes, and 5 blanks appear between columns.

Operand Descriptions
LIST(listdd) Specifies the ddname of the list data set to be produced by ICETOOL for this

498

z/OS V1R10.0 DFSORT Application Programming Guide

DEFAULTS Operator
operation. A listdd DD statement must be present. ICETOOL uses RECFM=FBA, LRECL=121 and the specified BLKSIZE for the list data set. If the BLKSIZE you specify is not a multiple of 121, ICETOOL uses BLKSIZE=121. If you do not specify the BLKSIZE, ICETOOL selects the block size as directed by LISTSDB or LISTNOSDB, if specified, or otherwise as directed by installation option SDBMSG from ICEAM2 or ICEAM4 (see z/OS DFSORT Installation and Customization). Refer to JCL Restrictions on page 489 for more information regarding the selection of ddnames. LISTSDB or LISTNOSDB Can be used to override the SDBMSG value for this LIST data set. LISTSDB directs ICETOOL to select the system-determined optimum block size for the LIST data set in the same way as for installation option SDBMSG=YES. LISTNOSDB directs ICETOOL to select the block size for the LIST data set in the same way as for installation option SDBMSG=NO. See the discussion of the LIST(listdd) operand above for more information on how LISTSDB or LISTNOSDB affects the LIST data set block size. Attention: LISTSDB has no effect for SYSOUT data sets (for example, //RPT1 DD SYSOUT=*), because the system-determined optimum block size is not used for spool or dummy data sets.

DEFAULTS Example
DEFAULTS LIST(OPTIONS)

Prints, in the OPTIONS data set, the DFSORT installation defaults report. The OPTIONS output starts on a new page and might look as follows. The first few items are shown with illustrative values for ICEAM1-4 and ICETD1-4 for each of the three parts of the report.
Z/OS DFSORT V1R10 MERGED PARMLIB/ICEMAC DEFAULTS - 1 -

| | | | | | | | | | | | | | | | | | | | |

* IBM-SUPPLIED DEFAULT (ONLY SHOWN IF DIFFERENT FROM THE SPECIFIED DEFAULT) ITEM ---------ENABLE ABCODE ALTSEQ ARESALL ARESINV CFW CHALT CHECK CINV . . . JCL (ICEAM1) VALUE -------------------NONE MSG SEE BELOW 0 NOT APPLICABLE YES YES * NO YES YES INV (ICEAM2) VALUE -------------------TD1 99 * MSG SEE BELOW 0 0 YES YES * NO YES YES TSO (ICEAM3) VALUE -------------------NONE MSG SEE BELOW 0 NOT APPLICABLE YES NO YES YES TSOINV (ICEAM4) VALUE --------------------NONE 99 * MSG SEE BELOW 0 0 YES NO YES YES

Chapter 6. Using ICETOOL

499

DEFAULTS Operator

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Z/OS DFSORT V1R10 MERGED PARMLIB/ICEMAC DEFAULTS

- 4 -

* IBM-SUPPLIED DEFAULT (ONLY SHOWN IF DIFFERENT FROM THE SPECIFIED DEFAULT) ITEM ---------SUN MON TUE WED THU FRI SAT ABCODE ALTSEQ ARESALL ARESINV CFW CHALT TD1 (ICETD1) VALUE -------------------0600-2000 * NONE NONE NONE NONE NONE NONE 0600-2000 * NONE 99 * MSG SEE BELOW 0 0 YES YES * NO YES YES TD2 (ICETD2) VALUE -------------------NONE NONE NONE NONE NONE NONE NONE MSG SEE BELOW 0 0 YES NO TD3 (ICETD3) VALUE -------------------NONE NONE NONE NONE NONE NONE NONE MSG SEE BELOW 0 0 YES NO YES YES TD4 (ICETD4) VALUE -----------------NONE NONE NONE NONE NONE NONE NONE MSG SEE BELOW 0 0 YES NO YES YES

CHECK YES CINV YES . . . Z/OS DFSORT V1R10 PARMLIB ICEPRMXX MEMBER OPTIONS ICEOPT COMMAND IN EFFECT: START ICEOPT,ICEPRM=(03) RELEASE: MODULE: APAR LEVEL: COMPILED: AREA: 1.10 ICEPRML BASE 05/14/07 1

- 7 -

JCL (ICEAM1) OPTIONS ITEM ---------RESALL CHALT VALUE ---------------------------------------40000 YES MEMBER -------ICEPRM03 ICEPRM03

INV (ICEAM2) OPTIONS ITEM ---------RESINV CHALT VALUE ---------------------------------------40000 YES MEMBER -------ICEPRM03 ICEPRM03

TSO (ICEAM3) OPTIONS - NONE TSOINV (ICEAM4) OPTIONS - NONE TD1 (ICETD1) OPTIONS ITEM ---------CHALT VALUE ---------------------------------------YES MEMBER -------ICEPRM03

TD2 (ICETD2) OPTIONS - NONE TD3 (ICETD3) OPTIONS - NONE TD4 (ICETD4) OPTIONS - NONE

500

z/OS V1R10.0 DFSORT Application Programming Guide

DEFAULTS Operator

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Z/OS DFSORT V1R10 ICEMAC DEFAULTS ITEM ---------RELEASE MODULE APAR LEVEL COMPILED ENABLE ABCODE ALTSEQ ARESALL ARESINV CFW CHALT CHECK CINV . . . JCL (ICEAM1) VALUE -------------------1.10 ICEAM1 BASE 05/15/07 NONE MSG SEE BELOW 0 NOT APPLICABLE YES NO YES YES

- 8 INV (ICEAM2) VALUE -------------------1.10 ICEAM2 BASE 05/15/07 TD1 99 SEE BELOW 0 0 YES NO YES YES TSO (ICEAM3) VALUE -------------------1.10 ICEAM3 BASE 05/08/07 NONE MSG SEE BELOW 0 NOT APPLICABLE YES NO YES YES TSOINV (ICEAM4) VALUE --------------------1.10 ICEAM4 BASE 05/15/07 NONE 99 SEE BELOW 0 0 YES NO YES YES

Z/OS DFSORT V1R10 ICEMAC DEFAULTS ITEM ---------RELEASE MODULE APAR LEVEL COMPILED SUN MON TUE WED THU FRI SAT ABCODE ALTSEQ ARESALL ARESINV CFW CHALT CHECK CINV . . . TD1 (ICETD1) VALUE -------------------1.10 ICETD1 BASE 05/15/07 0600-2000 NONE NONE NONE NONE NONE 0600-2000 99 SEE BELOW 0 0 YES NO YES YES

- 11 TD2 (ICETD2) VALUE -------------------1.10 ICETD2 BASE 05/08/07 NONE NONE NONE NONE NONE NONE NONE MSG SEE BELOW 0 0 YES NO YES YES TD3 (ICETD3) VALUE -------------------1.10 ICETD3 BASE 05/08/07 NONE NONE NONE NONE NONE NONE NONE MSG SEE BELOW 0 0 YES NO YES YES TD4 (ICETD4) VALUE --------------------1.10 ICETD4 BASE 05/08/07 NONE NONE NONE NONE NONE NONE NONE MSG SEE BELOW 0 0 YES NO YES YES

The title and appropriate heading lines appear at the top of each page. The specified and IBM-supplied ALTSEQ tables are printed separately after the other items.

Chapter 6. Using ICETOOL

501

DISPLAY Operator

DISPLAY Operator

DISPLAY

FROM(indd)

ON(p,m,f) ON(p,m,f,formatting) ON(p,m,HEX) ON(VLEN) ON(VLEN,formatting) ON(NUM) ON(NUM,formatting)

LIST(listdd)

TITLE(string)

PAGE

DATE DATE(abcd) DATENS(abc) YDDD(abc) YDDDNS(ab)

TIME TIME(abc) TIMENS(ab)

BLANK PLUS

HEADER(string1) HEADER(string1,string2) HEADER(string1,string2,string3) HEADER(NONE) NOHEADER

LINES(n)

INDENT(n)

BETWEEN(n)

TBETWEEN(n)

TOTAL(string)

MAXIMUM(string)

MINIMUM(string)

AVERAGE(string)

LIMIT(n)

VSAMTYPE(x)

WIDTH(n)

BREAK(p,m,f) BREAK(p,m,f,formatting)

BTITLE(string)

BTOTAL(string)

BMAXIMUM(string)

BMINIMUM(string)

BAVERAGE(string)

STATLEFT

UZERO

LISTSDB LISTNOSDB

Prints the values or characters of specified numeric fields (including SMF, TOD, and ETOD date and time) or character fields in a separate list data set. Simple, tailored, and sectioned reports can be produced. From 1 to 20 fields can be

502

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
specified, but the resulting list data set line length must not exceed the limit specified by the WIDTH operand or 2048 bytes if WIDTH is not specified. The record number can be printed as a special field. DFSORT is called to copy the indd data set to ICETOOLs E35 user exit. ICETOOL uses its E35 user exit to print appropriate titles, headings and data in the list data set. You must not supply your own DFSORT MODS, INREC, or OUTREC statement, because they would override the DFSORT statements passed by ICETOOL for this operator. Specifying formatting items or the PLUS or BLANK operand, which can compress the columns of output data, can enable you to include more fields in your report, up to a maximum of 20, if your line length is limited by the character width your printer or display supports.

Simple Report
You can produce a simple report by specifying just the required operands. For example, if you specify FROM and LIST operands, and ON operands for 10-byte character and 7-byte zoned decimal fields, the output in the list data set can be represented as follows:
(p,m,f) characters . . . (p,m,f) sddddddddddddddd . . .

A control character occupies the first byte of each list data set record. Left-justified standard headings are printed at the top of each page to indicate the contents of each column, followed by a line for each record showing the characters and numbers in the fields of that record. The fields are printed in columns in the same order in which they are specified in the DISPLAY statement. All fields are left-justified. For numeric fields, leading zeros are printed, a is used for the minus sign, and a + is used for the plus sign. By default, the first column of data starts immediately after the control character, and three blanks appear between columns. The INDENT operand can be used to change the number of blanks before the first column of data. The BETWEEN operand can be used to change the number of blanks between columns. The standard column widths are as follows: v Character data: the length of the character field, or 20 bytes if the field length is less than 21 bytes v Numeric data: 16 bytes, or 32 bytes if the numeric field is BI or FI with a length greater than 4, PD with a length greater than 8, ZD, CSF, FS, UFF or SFF with a length greater than 15, or FL. v Record number: 15 bytes HEADER operands can be used to change or suppress the headings. Formatting items or the PLUS or BLANK operand can be used to change the appearance of

Chapter 6. Using ICETOOL

503

DISPLAY Operator
numeric fields in the report. PLUS, BLANK, and HEADER operands can be used to change the width of the columns for numeric and character fields and the justification of headings and fields. The NOHEADER operand can be used to create list data sets containing only data records. Data sets created in this way can be processed further by other operators (for example, STATS or UNIQUE) using CH format for character values or FS format for numeric values. TOTAL, MAXIMUM, MINIMUM, and AVERAGE can be used to print statistics for numeric fields after the columns of data. Formatting items can be used to suppress the statistics for selected numeric fields.

Tailored Report
You can tailor the output in the list data set using various operands that control title, date, time, page number, headings, lines per page, field formats, and total, maximum, minimum, and average values for the columns of numeric data. The optional operands can be used in many different combinations to produce a wide variety of report formats. For example, if you specify FROM, LIST, BLANK, TITLE, PAGE, DATE, TIME, HEADER and AVERAGE operands, and ON operands for 10-byte character and 7-byte zoned decimal fields, the output in the list data set can be represented as follows:
title header ---------characters . . . average - p header -------sd . . . sd mm/dd/yy hh:mm:ss

A control character occupies the first byte of each list data set record. The title line is printed at the top of each page of the list data set. It contains the elements you specify (title string, page number, date and time) in the order in which you specify them. By default, eight blanks appear between title elements. The TBETWEEN(n) operand can be used to change the number of blanks between title elements. A blank line is printed after the title line. Your specified headings (underlined) are printed after the title line on each page to indicate the contents of each column, followed by a line for each record showing the characters and numbers in the fields of that record. Your specified headings can be one, two or three lines. Headings for character fields are left-justified and headings for numeric fields are right-justified. Your specified statistical lines (total, maximum, minimum, and average, and their associated strings) are printed for selected numeric fields after the columns of data. The associated strings can be printed in the first column or to the left of it. The fields are printed in columns in the same order in which they are specified in the DISPLAY statement. Character fields are left-justified and numeric fields are right-justified. For numeric fields, leading zeros are suppressed, a is used for the minus sign, and a blank is used for the plus sign (you can specify PLUS rather than BLANK if you want a + to be used for the plus sign).

504

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
Formatting items can be used to change the appearance of individual numeric fields in the report with respect to separators, number of digits, decimal point, decimal places, signs, leading zeros, division by 10, 100, 1000, 10000, 100000, 1000000, 1000000000, 1024, 1048576 (1024*1024), or 1073741824 (1024*1024*1024), leading strings, floating strings, and trailing strings. Formatting items can also be used to insert leading or trailing strings for character fields. The column widths are dynamically adjusted according to the length of the headings and the maximum number of bytes needed for the character or numeric data.

Sectioned Report
You can produce a sectioned report (simple or tailored) by including a BREAK operand to indicate the break field used to divide the report into sections. Each set of sequential input records (which you have previously sorted on the break field and other fields, as appropriate), with the same value for the specified break field, results in a corresponding set of data lines that is treated as a section in the report. The break field is printed at the beginning of each section. Formatting items can be used to change the appearance of numeric break fields, and to insert a string before or after character or numeric break fields. Optional break operands can be used to modify the break title for each section (the break value is always printed as part of the break title) and to print statistics for selected numeric fields in each section. For example, if you add BTITLE, BREAK, BMAXIMUM, and BMINIMUM to the operands for the tailored report discussed above, each section of the output in the list data set starts on a new page and can be represented as follows:
title btitle - p bvalue header -------sd . . . sd sd mm/dd/yy hh:mm:ss

header ---------characters . . . bmaximum bminimum

The final page showing the overall statistics starts on a new page and can be represented as follows:
title header ---------average - p header -------sd mm/dd/yy hh:mm:ss

Operand Descriptions
The operands described below can be specified in any order. FROM(indd) Specifies the ddname of the input data set to be read by DFSORT for this
Chapter 6. Using ICETOOL

505

DISPLAY Operator
operation. An indd DD statement must be present and must define an input data set that conforms to the rules for DFSORTs SORTIN data set. In addition, the LRECL of the data set must be at least 4. ON(p,m,f) Specifies the position, length, and format of a numeric or character field to be used for this operation. (p,m,f) is used for the standard column heading (see HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3), HEADER(NONE) and NOHEADER for alternative heading options). By default, three blanks appear between columns. You can change the space between columns with BETWEEN(n). p specifies the first byte of the field relative to the beginning of the input record. p is 1 for the first data byte of a fixed-length record and 5 for the first data byte of a variable-length record as illustrated below (RRRR represents the 4-byte record descriptor word):
Fixed-length record | Variable-length record | D | A | T | A | ... | | R | R | R | R | D | A | T | A | ... p= 1 2 3 4 | p= 1 2 3 4 5 6 7 8

m specifies the length of the field in bytes. A field must not extend beyond position 32752 or beyond the end of a record. The maximum length for a field depends on its format. f specifies the format of the field as shown below.
Format Code BI FI PD ZD FL Length 1 to 8 bytes 1 to 8 bytes 1 to 16 bytes 1 to 31 bytes 4 or 8 bytes Description Unsigned binary Signed fixed-point Signed packed decimal Signed zoned decimal Signed hexadecimal floating-point converted to signed integer Character Signed numeric with optional leading floating sign Unsigned free form numeric Signed free form numeric SMF date interpreted as Zyyyymmdd SMF date interpreted as Zyyyymm SMF date interpreted as Zyyyyddd TOD date interpreted as Zyyyymmdd TOD date interpreted as Zyyyymm TOD date interpreted as Zyyyyddd

CH CSF or FS UFF SFF DT1 DT2 DT3 DC1 DC2 DC3

1 to 1500 bytes 1 to 32 bytes (31 digit limit) 1 to 44 bytes (31 digit limit) 1 to 44 bytes (31 digit limit) 4 bytes 4 bytes 4 bytes 8 bytes 8 bytes 8 bytes

506

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
Format Code DE1 DE2 DE3 TM1 TM2 TM3 TM4 TC1 TC2 TC3 TC4 TE1 TE2 TE3 TE4 Length 8 bytes 8 bytes 8 bytes 4 bytes 4 bytes 4 bytes 4 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes Description ETOD date interpreted as Zyyyymmdd ETOD date interpreted as Zyyyymm ETOD date interpreted as Zyyyyddd SMF time interpreted as Zhhmmss SMF time interpreted as Zhhmm SMF time interpreted as Zhh SMF time interpreted as Zhhmmssxx TOD time interpreted as Zhhmmss TOD time interpreted as Zhhmm TOD time interpreted as Zhh TOD time interpreted as Zhhmmssxx ETOD time interpreted as Zhhmmss ETOD time interpreted as Zhhmm ETOD time interpreted as Zhh ETOD time interpreted as Zhhmmssxx

Note: See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions.

For a CSF, FS, UFF, or SFF format field: v A maximum of 31 digits is allowed. If a value with more than 31 digits is found, ICETOOL issues an error message and terminates the operation. For a ZD or PD format field: v If a decimal value contains an invalid digit (A-F), ICETOOL identifies the bad value in a message and prints asterisks for that value, and for the total, maximum, minimum and average (if specified) for that field, in the list data set. If the number of bad values reaches the LIMIT for invalid decimal values, ICETOOL terminates the operation. If the LIMIT operand is not specified, a default of 200 is used for the invalid decimal value limit. v A value is treated as positive if its sign is F, E, C, A, 8, 6, 4, 2, or 0. v A value is treated as negative if its sign is D, B, 9, 7, 5, 3, or 1. For an FL format field:

Chapter 6. Using ICETOOL

507

DISPLAY Operator
v The normalized or unnormalized FL (hexadecimal floating-point) value is converted to a signed integer in the range -9223372036854775808 to 9223372036854775807. The fractional part of the FL value is lost, and in some cases the signed integer may be one of a number of possible signed integers for the FL value depending on its precision. Converted values less than -9223372036854775808 are set to -9223372036854775808. Converted values greater than 9223372036854775807 are set to 9223372036854775807. v If you are not running in z/Architecture mode, specifying an FL format field results in an error message and termination. For a DT1, DT2 or DT3 format field: v An invalid SMF date can result in a data exception (0C7 ABEND) or an incorrect ZD date. v SMF date values are always treated as positive. For a DC1, DC2, DC3, DE1, DE2, or DE3 format field: v TOD and ETOD date values are always treated as positive. For a TM1, TM2, TM3 or TM4 format field: v An invalid SMF time can result in an incorrect ZD time. v SMF time values are always treated as positive. For a TC1, TC2, TC3, TC4, TE1, TE2, TE3, or TE4 format field: v TOD and ETOD time values are always treated as positive. ON(p,m,f,formatting) Specifies the position, length, and format of a numeric or character field to be used for this operation and how the data for this field is to be formatted for printing. The BLANK operand is automatically in effect. See ON(p,m,f) for further details. formatting

, mask Epattern Lstring Fstring Tstring LZ NOST Ndd Udd /x

specifies formatting items that indicate how the data for this field is to be formatted for printing. Formatting items can be specified in any order, but each item can only be specified once. Any formatting item can be specified for a numeric field, but only Lstring and Tstring can be specified for a character field.

508

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
The column width is dynamically adjusted to accommodate the maximum bytes to be inserted as a result of all formatting items specified. mask specifies an edit mask to be applied to the numeric data for this field. Thirty-nine pre-defined edit masks are available, encompassing many of the numeric notations throughout the world with respect to separators, decimal point, decimal places, signs, and so forth. ICETOOL edits the data according to the selected mask. If other formatting items are specified but mask is not, the default mask of A0 is applied to the data. Epattern cannot be specified with a mask. The attributes of each group of masks is shown below.
Table 67. Attributes of Edit Masks Masks A0 A1-A5 B1-B6 C1-C6 D1-D6 E1-E4 F1-F5 G1-G6 Separators No Yes Yes Yes Yes Yes Yes Yes Decimal Places 0 0 1 2 3 0 2 4 Positive Sign blank blank blank blank blank blank blank blank Negative Sign () () -

The table below describes the available masks and shows how the values 12345678 and -1234567 would be printed for each mask. In the pattern: v d is used to represent a decimal digit (0-9) v w is used to represent a leading sign that will be blank for a positive value or for a negative value v x is used to represent a trailing sign that will be blank for a positive value or for a negative value v y is used to represent a leading sign that will be blank for a positive value or ( for a negative value v z is used to represent a trailing sign that will be blank for a positive value or ) for a negative value
Table 68. Edit Mask Patterns Mask A0 A1 A2 A3 A4 A5 B1 B2 B3 B4 Pattern wddddddddddddddddddddddddddddddd wd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd wd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd wd ddd ddd ddd ddd ddd ddd ddd ddd ddd ddd wddddddddddddddddddddddddddddddd d ddd ddd ddd ddd ddd ddd ddd ddd ddd dddx wddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd.d wddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd,d wddd ddd ddd ddd ddd ddd ddd ddd ddd ddd,d wdddddddddddddddddddddddddddddd.d 12345678 12345678 12,345,678 12.345.678 12 345 678 12345678 12 345 678 1,234,567.8 1.234.567,8 1 234 567,8 1234567.8 -1234567 -1234567 -1,234,567 -1.234.567 -1 234 567 -1234567 1 234 567-123,456.7 -123.456,7 -123 456,7 -123456.7

Chapter 6. Using ICETOOL

509

DISPLAY Operator
Table 68. Edit Mask Patterns (continued) Mask B5 B6 C1 C2 C3 C4 C5 C6 D1 D2 D3 D4 D5 D6 E1 E2 E3 E4 F1 F2 F3 F4 F5 G1 G2 G3 G4 G5 G6 Pattern wdddddddddddddddddddddddddddddd,d ddd ddd ddd ddd ddd ddd ddd ddd ddd ddd,dx wdd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd.dd wdd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd,dd wdd ddd ddd ddd ddd ddd ddd ddd ddd ddd,dd wddddddddddddddddddddddddddddd.dd wddddddddddddddddddddddddddddd,dd dd ddd ddd ddd ddd d ddd ddd ddd ddd,ddx wd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd.ddd wd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd,ddd wd ddd ddd ddd ddd ddd ddd ddd ddd ddd,ddd wdddddddddddddddddddddddddddd.ddd wdddddddddddddddddddddddddddd,ddd d ddd ddd ddd ddd ddd ddd ddd ddd ddd,dddx yd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,dddz yd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.dddz yd ddd ddd ddd ddd ddd ddd ddd ddd ddd dddz ydddddddddddddddddddddddddddddddz ydd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd.ddz ydd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd,ddz ydd ddd ddd ddd ddd ddd ddd ddd ddd ddd,ddz yddddddddddddddddddddddddddddd.ddz yddddddddddddddddddddddddddddd,ddz wddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd,ddd.dddd wddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd.ddd,dddd wddd ddd ddd ddd ddd ddd ddd ddd ddd,dddd wddddddddddddddddddddddddddd.dddd wddddddddddddddddddddddddddd,dddd ddd ddd ddd ddd ddd ddd ddd ddd ddd,ddddx 12345678 1234567,8 1 234 567,8 123,456.78 123.456,78 123 456,78 123456.78 123456,78 123 456,78 12,345.678 12.345,678 12 345,678 12345.678 12345,678 12 345,678 12,345,678 12.345.678 12 345 678 12345678 123,456.78 123.456,78 123 456,78 123456.78 123456,78 1,234.5678 1.234,5678 1 234,5678 1234.5678 1234,5678 1 234,5678 -1234567 -123456,7 123 456,7-12,345.67 -12.345,67 -12 345,67 -12345.67 -12345,67 12 345,67-1,234.567 -1.234,567 -1 234,567 -1234.567 -1234,567 1 234,567(1,234,567) (1.234.567) (1 234 567) (1234567) (12,345.67) (12.345,67) (12 345,67) (12345.67) (12345,67) -123.4567 -123,4567 -123,4567 -123.4567 -123,4567 123,4567-

If LZ is specified, leading zeros are printed. for example, +1 is shown as 0,000.01 with ON(21,6,FS,C1,LZ). If LZ is not specified, leading zeros are suppressed except when inappropriate. For example, +1 is shown as 1 with ON(21,6,FS,A1) and as 0.01 with ON(21,6,FS,C1). The leading sign (blank for a positive value or for a negative value) appears to the left of the first non-suppressed digit of the formatted value. For example, 1 is shown as 1 with ON(21,6,FS,A2), as 000.001 with ON(21,6,FS,A2,LZ) and as 0.01 with ON(21,6,FS,C2). Epattern specifies an edit pattern to be applied to the numeric data for this field. Epattern is useful for formatting unsigned numeric data such as telephone

510

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
numbers, dates, time-of-day, social security numbers, and so on. For example, 0123456789 is shown as (012)-345-6789 with ON(21,10,ZD,E(999)-999-9999). The pattern (1 to 44 characters) must be enclosed in single apostrophes. Each 9 in the pattern (up to 31) is replaced by a corresponding digit from the numeric value. Characters other than 9 in the pattern appear as specified. To include a single apostrophe () in the pattern, specify two single apostrophes (). Fstring or a mask cannot be specified with Epattern. When Epattern is specified for a field: v Values are shown unsigned. For example, +120622 and 120622 are both shown as 12:06:22 with ON(12,7,FS,E99:99:99). v If the number of significant digits in a value is less than the number of 9s in the pattern, 0s are filled in on the left. For example, 1234 is shown as 0012-34 with ON(12,6,FS,E9999-99). v If the number of significant digits in a value is greater than the number of 9s in the pattern, digits are truncated from the left. For example, 1234567 is shown as *45:67* with ON(9,4,PD,E*99:99*). Lstring specifies a leading string to appear at the beginning of the character or numeric data column for this field. For example, DFSORT is shown as **DFSORT with ON(1,8,CH,L**). The string (1 to 10 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). Fstring specifies a floating string to appear to the left of the first non-blank character of the formatted numeric data for this field. For example, 0001234 is shown as $12.34 with ON(9,7,ZD,C1,F$). The string (1 to 10 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). Epattern cannot be specified with Fstring. Tstring specifies a trailing string to appear at the end of the character or numeric data column for this field. For example, DFSORT is shown as **DFSORT *** with ON(1,8,CH,L**,T***). The string (1 to 10 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). LZ specifies that leading zeros are to be printed when the specified edit mask is applied to the numeric data for this field, overriding the default of suppressing leading zeros. For example, +123 is shown as 123 with ON(21,6,FS,A0), but as 000123 with ON(21,6,FS,A0,LZ). LZ is useful for formatting numeric data, such as account numbers, for which leading zeros must be printed. Leading zeros are always printed for Epattern regardless of whether or not LZ is specified. NOST specifies that requested statistics (TOTAL, MAXIMUM, MINIMUM, AVERAGE, BTOTAL, BMAXIMUM, BMINIMUM, BAVERAGE) are not to be printed for this numeric field.
Chapter 6. Using ICETOOL

511

DISPLAY Operator
Ndd or Udd specifies the number of digits to be used for the numeric field. Ndd or Udd can be used to change the column width for numeric fields, and to prevent overflow for totals. dd specifies the number of digits and must be a two-digit number between 01 and 31. The default number of digits (d) for a numeric field is the maximum number of digits for that field. For example, d is 5 for ON(1,5,ZD). If you know that your numeric field requires less than d digits, you can use a lower number of digits (dd) instead by specifying Udd, thus reducing the column width if it is determined by d. For example, ON(1,5,ZD,U03) reduces d from 5 to 3. If you want your numeric field to be displayed with more than d digits, you can use a higher number of digits (dd) instead by specifying Ndd or Udd, thus increasing the column width if it is determined by d. For example, ON(1,5,ZD,U10) increases d from 5 to 10. The default number of digits (d) for a total is 15 if the numeric field is BI or FI with a length up to 4, PD with a length up to 8, or ZD, CSF, FS, UFF or SFF with a length up to 15. The default number of digits (d) for a total is 31 if the numeric field is BI or FI with a length greater than 4, PD with a length greater than 8, or ZD, CSF, FS, UFF or SFF with a length greater than 15. If you know that your total requires less than d digits, you can use a lower number of digits (dd) instead by specifying Ndd or Udd for the ON field, thus reducing the column width if it is determined by d. For example, ON(1,18,ZD,U18) with TOTAL reduces d from 31 to 18. If you know that your total can overflow d digits, you can use a higher number of digits (dd) instead by specifying Ndd or Udd, thus preventing overflow and increasing the column width if it is determined by d. For example, ON(1,15,ZD,U17) with TOTAL increases d from 15 to 17. Either Ndd or Udd can be used to set d greater than the maximum for a numeric field, but only Udd can be used to set d less than the maximum for a numeric field. For Udd: dd is used for d. For example: If v v v v v v TOTAL and BTOTAL are not used: If ON(1,5,ZD) is specified, 5 digits (default for 5,ZD) are used. If ON(1,5,ZD,U10) is specified, 10 digits (from U10) are used.. If ON(1,5,ZD,U03) is specified, 3 digits (from U03) are used. If ON(1,16,FS) is specified, 16 digits (default for 16,FS) are used. If ON(1,16,FS,U16) is specified, 16 digits (from U16) are used.. If ON(1,16,FS,U15) is specified, 15 digits (from U15) are used.

If TOTAL or BTOTAL is used: v If ON(1,5,ZD) is specified, 15 digits (default for TOTAL or BTOTAL and 5,ZD) are used. v If ON(1,5,ZD,U10) is specified, 10 digits (from U10) are used. v If ON(1,5,ZD,U03) is specified, 3 digits (from U03) are used. v If ON(1,16,FS) is specified, 31 digits (default for TOTAL or BTOTAL and 16,FS) are used. v If ON(1,16,FS,U16) is specified, 16 digits (from U16) are used. v If ON(1,16,FS,U15) is specified, 15 digits (from U15) are used. If you use Udd and a numeric value or total overflows dd digits, ICETOOL prints asterisks for that numeric value or total and terminates the operation.

512

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
You can prevent the overflow by specifying an appropriately higher dd value for Udd. For example, if ON(1,12,ZD,U09) results in overflow, you can use ON(1,12,ZD,U10) instead. If Epattern is specified, Udd is ignored, because d is determined from the pattern. For Ndd: If dd is greater than or equal d, dd is used. If dd is less than d, d is used. For example: If v v v TOTAL and BTOTAL are not used: If ON(1,5,ZD) is specified, 5 digits (default for 5,ZD) are used. If ON(1,5,ZD,N10) is specified, 10 digits (from N10) are used. If ON(1,5,ZD,N03) is specified, 5 digits (from 5,ZD) are used

If TOTAL or BTOTAL is used: v If ON(1,5,ZD) is specified, 15 digits (default for TOTAL or BTOTAL and 5,ZD) are used. v If ON(1,5,ZD,N10) is specified, 10 digits (from N10) are used. v If ON(1,5,ZD,N03) is specified, 5 digits (from 5,ZD) are used. If you use Ndd and a total overflows dd digits, ICETOOL prints asterisks for the total and terminates the operation. You can prevent the overflow by specifying an appropriately higher dd value for Ndd. For example, if ON(1,17,ZD,N17) with TOTAL results in overflow, you can use ON(1,17,ZD,N18) instead If Epattern is specified, Ndd is ignored, because d is determined from the pattern. /x specifies division of the numeric data for this field before formatting. x indicates the division factor to be used as described below. The resulting values are rounded down to the nearest integer. Statistics (TOTAL, MAXIMUM, MINIMUM, AVERAGE, BTOTAL, BMAXIMUM, BMINIMUM, BAVERAGE) and column widths reflect the divided numbers. /D /C /K /DK /CK specifies division by 10 before formatting. For example, 1234 is shown as 123 with ON(11,2,FI,/D). specifies division by 100 before formatting. For example, 12345 is shown as 12.3 with ON(11,2,BI,/C,B1). specifies division by 1000 before formatting. For example, 1234567890 is shown as (1 234 567) with ON(1,11,FS,/K,E3). specifies division by 10000 (10*1000) before formatting. For example, 6213849653 is shown as 0-6213-84 with ON(31,10,FS,/DK,E9-9999-99). specifies division by 100000 (100*1000) before formatting. For example, 1234567890123456789012345 is shown as 1,234,567,890,123,456.7890 with ON(21,25,ZD,G1,/CK). specifies division by 1000000 (1000*1000) before formatting. For example, 123456789 is shown as 1.23 with ON(31,10,FS,/M,C4). specifies division by 1000000000 (1000*1000*1000) before formatting. For example, 1234567898765 is shown as 1234 with ON(15,13,ZD,A4,/G). specifies division by 1024 before formatting. For example, 1234567890 is shown as 1 205 632 with ON(45,10,ZD,/KB,A3).
Chapter 6. Using ICETOOL

/M /G

/KB

513

DISPLAY Operator
/MB /GB specifies division by 1048576 (1024*1024) before formatting. For example, 123456789 is shown as 117 with ON(60,9,FS,/MB). specifies division by 1073741824 (1024*1024*1024) before formatting. For example, 1234567898765 is shown as 1,149 with ON(15,13,ZD,/GB,A1).

ON(p,m,HEX) Specifies the position and length of a character field to be used for this operation and printed in hexadecimal format (00-FF for each byte). (p,m,HEX) is used for the standard column heading. See HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3), HEADER(NONE), and NOHEADER for alternative heading options. See ON(p,m,f) for a discussion of p. m specifies the length of the field in bytes. A field must not extend beyond position 32752 or beyond the end of a record. A field can be 1 to 1000 bytes. ON(VLEN) Equivalent to specifying ON(1,2,BI); a two-byte binary field starting at position 1. For variable-length records, ON(VLEN) represents the record-length for each record. RECORD LENGTH is used for the standard column heading. See HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3), HEADER(NONE), and NOHEADER for alternative heading options. ON(VLEN,formatting) Equivalent to specifying ON(1,2,BI,formatting); a two-byte binary field starting at position 1, and how the data for this field is to be formatted for printing. The BLANK operand is automatically in effect. See ON(VLEN) for further details. formatting

, mask Epattern Lstring Fstring Tstring LZ NOST Ndd Udd /x

specifies formatting items that indicate how the data for this field is to be formatted for printing. Formatting items can be specified in any order, but each item can only be specified once. The column width is dynamically adjusted to accommodate the maximum bytes to be inserted as a result of all formatting items specified. See ON(p,m,f,formatting) for a discussion of formatting.

514

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
ON(NUM) Specifies that the record number is to be printed. The record number starts at 1 and is incremented by 1 for each record printed in the list data set. RECORD NUMBER is used for the standard column heading. See HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3), HEADER(NONE), and NOHEADER for alternative heading options. ON(NUM,formatting) Specifies that the record number is to be printed, and how the record number is to be formatted for printing. The BLANK operand is automatically in effect. See ON(NUM) for further details. formatting

, mask Epattern Lstring Fstring Tstring LZ Ndd Udd

specifies formatting items that indicate how the record number is to be formatted for printing. Formatting items can be specified in any order, but each item can only be specified once. The column width is dynamically adjusted to accommodate the maximum bytes to be inserted as a result of all formatting items specified. mask See ON(p,m,f,formatting) for a discussion of mask.

Epattern specifies an edit pattern to be applied to the record number. The pattern (1 to 24 characters) must be enclosed in single apostrophes. Each 9 in the pattern (up to 15) is replaced by a corresponding digit from the numeric value. Characters other than 9 in the pattern appear as specified. To include a single apostrophe () in the pattern, specify two single apostrophes (). Fstring or a mask cannot be specified with Epattern. When Epattern is specified for the record number: v If the number of significant digits in a record number is less than the number of 9s in the pattern, 0s are filled in on the left. For example, 1234 is shown as 001234 with ON(NUM,E999999). v If the number of significant digits in a record number is greater than the number of 9s in the pattern, digits are truncated from the left. For example, 1234567 is shown as *4567* with ON(NUM,E*9999*). Lstring See ON(p,m,f,formatting) for a discussion of Lstring. Fstring See ON(p,m,f,formatting) for a discussion of Fstring.
Chapter 6. Using ICETOOL

515

DISPLAY Operator
Tstring See ON(p,m,f,formatting) for a discussion of Tstring. LZ See ON(p,m,f,formatting) for a discussion of LZ.

Ndd or Udd Specifies the number of digits to be used for the record number when determining the column width. dd specifies the number of digits and must be a two-digit number between 01 and 15. The default number of digits (d) for the record number is 15. If you know that your record numbers require less than 15 digits, you can use a lower number of digits (dd) instead by specifying Ndd or Udd thus reducing the column width if it is determined by d. For example, if ON(NUM,N09) or ON(NUM,U09) is specified, 9 digits (from N09 or U09) is used instead of 15 (default for record number). If you use Ndd or Udd and the number of records overflows the number of digits used, ICETOOL terminates the operation. You can prevent the overflow by specifying an ppropriately higher dd value for Ndd or Udd. For example, if ON(NUM,N05) results in overflow, you can use ON(NUM,N06) instead. If Epattern is specified, Ndd or Udd is ignored, because d is determined from the pattern. LIST(listdd) Specifies the ddname of the list data set to be produced by ICETOOL for this operation. A listdd DD statement must be present. ICETOOL sets the attributes of the list data set as follows: v RECFM is set to FBA. v LRECL is set to one of the following: If WIDTH(n) is specified, LRECL is set to n. Use WIDTH(n) if your LRECL must be set to a particular value (for example, if you use DISP=MOD to place several reports in the same data set). If WIDTH(n) is not specified, LRECL is set to 121 or to the calculated required line length if it is greater than 121 characters. If your LRECL does not need to be set to a particular value, you can let ICETOOL determine and set the appropriate LRECL value by not specifying WIDTH(n). v BLKSIZE is set to one of the following: The BLKSIZE from the DD statement, DSCB, or label, if it is a multiple of the LRECL used. The LRECL if the BLKSIZE from the DD statement, DSCB, or label is not a multiple of the LRECL used. The block size as directed by LISTSDB or LISTNOSDB if specified, or otherwise as directed by the SDBMSG installation option from ICEAM2 or ICEAM4 (see z/OS DFSORT Installation and Customization), if the BLKSIZE is not available from the DD statement, DSCB, or label. Refer to JCL Restrictions on page 489 for more information regarding the selection of ddnames. TITLE(string) Specifies printing of a title string in the title line. The title line is printed at the top of each page of the list data set. It contains the elements you specify (title string, page number, date and time) in the

516

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
order in which you specify them. By default, eight blanks appear between title elements. You can change the space between title elements with TBETWEEN(n). A blank line is printed after the title line. The string (1 to 50 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). Blanks at the start of the string move the text to the right. Blanks at the end of the string increase the spacing between the string and the next title element. PAGE Specifies printing of the page number in the title line. The page number is printed in the form - p - where p is in decimal with no leading zeros. The page number is 1 for the first page and is incremented by 1 for each subsequent page. The title line is printed at the top of each page of the list data set. It contains the elements you specify (title string, page number, date and time) in the order in which you specify them. By default, eight blanks appear between title elements. You can change the space between title elements with TBETWEEN(n). A blank line is printed after the title line. DATE Specifies printing of the date in the title line. The date is printed in the form mm/dd/yy where mm is the month, dd is the day, and yy is the year. DATE is equivalent to specifying DATE(MDY/). The title line is printed at the top of each page of the list data set. It contains the elements you specify (title string, page number, date and time) in the order in which you specify them. By default, eight blanks appear between title elements. You can change the space between title elements with TBETWEEN(n). A blank line is printed after the title line. DATE(abcd) Specifies printing of the date in the title line. The date is printed in the form adbdc according to the specified values for abc and d. For example, on March 29, 2002, DATE(4MD-) would produce 2002-03-29 and DATE(MDY.) would produce 03.29.02. abc can be any combination of M, D, and Y or 4 (each specified once) where M represents the month (01-12), D represents the day (01-31), Y represents the last two digits of the year (for example, 02), and 4 represents the four digits of the year (for example, 2002). d can be any character and is used to separate the month, day, and year. The title line is printed at the top of each page of the list data set. It contains the elements you specify (title string, page number, date and time) in the order in which you specify them. By default, eight blanks appear between title elements. You can change the space between title elements with TBETWEEN(n). A blank line is printed after the title line. DATENS(abc) Specifies printing of the date in the title line. The date is printed in the form abc according to the specified values for abc. For example, on March 29, 2002, DATENS(4MD) would produce 20020329 and DATENS(MDY) would produce 032902.

Chapter 6. Using ICETOOL

517

DISPLAY Operator
abc can be any combination of M, D, and Y or 4 (each specified once) where M represents the month (01-12), D represents the day (01-31), Y represents the last two digits of the year (for example, 02), and 4 represents the four digits of the year (for example, 2002). The title line is printed at the top of each page of the list data set. It contains the elements you specify (title string, page number, date and time) in the order in which you specify them. By default, eight blanks appear between title elements. You can change the space between title elements with TBETWEEN(n). A blank line is printed after the title line. YDDD(abc) specifies printing of the date in the title line. The date is printed in the form acb according to the specified values for ab and c. For example, on April 7, 2004, YDDD(DY-) would produce 098-04 and YDDD(4D/) would produce 2004/098. ab can be any combination of D, and Y or 4 (each specified once) where D represents the day of the year (001-366), Y represents the last two digits of the year (for example, 04), and 4 represents the four digits of the year (for example, 2004). c can be any character and is used to separate the month, day and year. The title line is printed at the top of each page of the list data set. It contains the elements you specify (title string, page number, date and time) in the order in which you specify them. By default, eight blanks appear between title elements. You can change the space between title elements with TBETWEEN(n). A blank line is printed after the title line. YDDDNS(ab) specifies printing of the date in the title line. The date is printed in the form ab according to the specified values for ab. For example, on April 7, 2004, YDDDNS(DY) would produce 09804 and YDDD(4D) would produce 2004098. ab can be any combination of D, and Y or 4 (each specified once) where D represents the day of the year (001-366), Y represents the last two digits of the year (for example, 04), and 4 represents the four digits of the year (for example, 2004). The title line is printed at the top of each page of the list data set. It contains the elements you specify (title string, page number, date and time) in the order in which you specify them. By default, eight blanks appear between title elements. You can change the space between title elements with TBETWEEN(n). A blank line is printed after the title line. TIME Specifies printing of the time in the title line. The time is printed in the form hh:mm:ss where hh is hours, mm is minutes and ss is seconds. TIME is equivalent to specifying TIME(24:). The title line is printed at the top of each page of the list data set. It contains the elements you specify (title string, page number, date and time) in the order in which you specify them. By default, eight blanks appear between title elements. You can change the space between title elements with TBETWEEN(n). A blank line is printed after the title line.

518

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
TIME(abc) Specifies printing of the time in the title line. The time is printed in the form hhcmmcss xx according to the specified value for ab and c. For example, at 08:25:13 pm, TIME=(24:) would produce 20:25:13 and TIME=(12.) would produce 08.25.13 pm. ab can be: v 12 to indicate 12-hour time. hh (hours) is 01-12, mm (minutes) is 00-59, ss (seconds) is 00-59 and xx is am or pm. v 24 to indicate 24-hour time. hh (hours) is 00-23, mm (minutes) is 00-59, ss (seconds) is 00-59 and xx is not included. c can be any character and is used to separate the hours, minutes, and seconds. The title line is printed at the top of each page of the list data set. It contains the elements you specify (title string, page number, date and time) in the order in which you specify them. By default, eight blanks appear between title elements. You can change the space between title elements with TBETWEEN(n). A blank line is printed after the title line. TIMENS(ab) Specifies printing of the time in the title line. The time is printed in the form hhmmss xx according to the specified value for ab. For example, at 08:25:13 pm, TIMENS=(24) would produce 202513 and TIMENS=(12) would produce 082513 pm. ab can be: v 12 to indicate 12-hour time. hh (hours) is 01-12, mm (minutes) is 00-59, ss (seconds) is 00-59 and xx is am or pm. v 24 to indicate 24-hour time. hh (hours) is 00-23, mm (minutes) is 00-59, ss (seconds) is 00-59 and xx is not included. The title line is printed at the top of each page of the list data set. It contains the elements you specify (title string, page number, date and time) in the order in which you specify them. By default, eight blanks appear between title elements. You can change the space between title elements with TBETWEEN(n). A blank line is printed after the title line. BLANK Specifies an alternate format for printing character and numeric data as follows: v Numeric values for which formatting is not specified are printed with blank for plus sign, for minus sign and no leading zeros (overriding the default of + for plus sign and leading zeros). Numeric values are thus displayed as: d...d for positive values (blank sign immediately to the left of the digits and no leading zeros) d...d for negative values ( sign immediately to the left of the digits and no leading zeros) v Column widths are dynamically adjusted according to the length of the headings and the maximum number of bytes needed for the character or numeric data v Headings and data for numeric fields are right-justified (overriding the default of left-justified headings and data for numeric fields)

Chapter 6. Using ICETOOL

519

DISPLAY Operator
PLUS Specifies an alternate format for printing character and numeric data as follows: v Numeric values for which formatting is not specified are printed with + for plus sign, for minus sign and no leading zeros (overriding the default of leading zeros). Numeric values are thus displayed as: +d...d for positive values ( sign immediately to the left of the digits and no leading zeros) d...d for negative values ( sign immediately to the left of the digits and no leading zeros) v Column widths are dynamically adjusted according to the length of the headings and the maximum number of bytes needed for the character or numeric data v Headings and data for numeric fields are right-justified (overriding the default of left-justified headings and data for numeric fields) For ON(NUM), PLUS is treated as BLANK. HEADER(string1) Specifies a heading to be printed for the corresponding ON field. The specified string is used instead of the standard column heading for the corresponding ON field. (ON fields and HEADER operands correspond one-for-one according to the order in which they are specified; that is, the first HEADER operand corresponds to the first ON field, the second HEADER operand corresponds to the second ON field, and so on.) The string (1 to 50 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). If the string length is greater than the column width for the corresponding ON field, the column width is increased to the string length. The heading is left-justified for character fields or right-justified for numeric fields and is underlined with hyphens for the entire column width (overriding the default of left-justified, non-underlined headings). Character values are left-justified and numeric values are right-justified (overriding the default of left-justified field values). A null string () or blank string ( ) may be used to set string1 to blanks. Blanks at the start or end of a heading string may alter the justification of the heading or the width of the column. If HEADER(string1) is used for any ON field, HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3), or HEADER(NONE) must be used for each ON field. HEADER(string1,string2) Specifies a heading to be printed for the corresponding ON field. A two-line heading is used with string1 on line1 and string2 on line2. A null string () or blank string ( ) may be used to set string1 or string2 to blanks. A comma (,) may also be used to set string1 to blanks. For example, HEADER(,string1) results in blanks for this heading in line1 and string1 for this heading in line2.

520

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
If HEADER(string1,string2) is used for any ON field, HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3) or HEADER(NONE) must be used for each ON field. If a HEADER(string1,string2) operand is specified, a two-line heading is also used for any HEADER(string1) operands you specify, with string1 for that heading on line1 and blanks for that heading on line2. HEADER(,string1) can be used to put blanks for that heading on line1 and string1 for that heading on line2. See HEADER(string1) for more details on the HEADER operand. HEADER(string1,string2,string3) Specifies a heading to be printed for the corresponding ON field. A three-line heading is used with string1 on line1, string2 on line2 and string3 on line3. A null string () or blank string ( ) may be used to set string1, string2 or string3 to blanks. A comma (,) may also be used to set string1 or string2 to blanks. For example, HEADER(,,string1) results in blanks for this heading in line1 and line2 and string1 for this heading in line3. If HEADER(string1,string2,string3) is used for any ON field, HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3) or HEADER(NONE) must be used for each ON field. If a HEADER(string1,string2,string3) operand is specified: v a three-line heading is also used for any HEADER(string1) operands you specify, with string1 for that heading on line1 and blanks for that heading on line2 and line3. HEADER(,,string1) can be used to put blanks for that heading on line1 and line2 and string1 for that heading on line3. v a three-line heading is also used for any HEADER(string1,string2) operands you specify, with string1 for that heading on line1, string2 for that heading on line2 and blanks for that heading on line3. HEADER(,string1,string2) can be used to put blanks for that heading on line1, string1 for that heading on line2 and string2 for that heading on line3. See HEADER(string1) for more details on the HEADER operand. HEADER(NONE) Specifies that a heading is not to be printed for the corresponding ON field. The standard column heading for the corresponding ON field is suppressed. If HEADER(NONE) is used for any ON field, HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3), or HEADER(NONE) must be used for each ON field. Specifying HEADER(NONE) for every ON field is equivalent to specifying NOHEADER. NOHEADER Specifies that headings for ON fields are not to be printed (overriding the default of printing standard headings for ON fields).

Chapter 6. Using ICETOOL

521

DISPLAY Operator
If NOHEADER is used, it must be specified only once and HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3), and HEADER(NONE) must not be used. If NOHEADER is specified without any TITLE, DATE, TIME, or PAGE operands, the resulting list data set contains only data records. Data sets created in this way can be processed further by other operators (for example, STATS or UNIQUE) using CH for character values or FS for numeric values. LINES(n) Specifies the number of lines per page for the list data set (overriding the default of 58). n must be greater than 9, but less than 1000. INDENT(n) Specifies the number of blanks to be used to indent the report (overriding the default of 0). n can be from 0 to 50. For example, if INDENT(n) is not specified, the report starts in column 2 (after the control character), whereas if INDENT(10) is specified, the report starts in column 12 (after the control character and 10 blanks). BETWEEN(n) Specifies the number of blanks to be used between the columns of data (overriding the default of 3). n can be from 0 to 50. For example, if BETWEEN(n) is not specified, three blanks appear between columns, whereas if BETWEEN(7) is specified, seven blanks appear between columns. TBETWEEN(n) Specifies the number of blanks to be used between title elements (overriding the default of 8). n can be from 0 to 50. For example, if TBETWEEN(n) is not specified, eight blanks appear between the TITLE and PAGE, whereas if TBETWEEN(4) is specified, four blanks appear between TITLE and PAGE. TOTAL(string) Specifies an overall TOTAL line is to be printed after the rows of data for the report. The specified string is printed starting at the indent column of the overall TOTAL line, followed by the overall total for each numeric data column. If STATLEFT is specified, the string is printed to the left of the first column of data with the totals on the same line as the string. If STATLEFT is not specified, the string is printed in the first column of data with the totals on the same line as the string, or on the next line, as appropriate. A blank line is printed before the overall TOTAL line. The string (1 to 50 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). To suppress printing of a string, specify TOTAL() using two single apostrophes. The overall total for each numeric ON field is printed in the format (formatting, PLUS, BLANK, or standard) you specify. The total for a specific numeric field is suppressed if the NOST formatting item is specified for that field. Totals are printed for ON(VLEN) fields, but not for ON(NUM) fields. The default number of digits (d) for a total is 15 if the ON field is BI or FI with a length up to 4, PD with a length up to 8, or ZD, CSF, FS,

522

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
UFF or SFF with a length up to 15. The default number of digits (d) for a total is 31 if the ON field is BI or FI with a length greater than 4, PD with a length greater than 8, ZD, CSF, FS, UFF or SFF with a length greater than 15, or FL. By default, column widths are adjusted to allow for a maximum of a sign and d digits for the totals. If the overall total for an ON field overflows d digits, ICETOOL prints asterisks for the overall total for that field and terminates the operation. You can use the Ndd or Udd formatting item to decrease or increase the number of digits used for a total. If you use Ndd or Udd and the overall total for an ON field overflows dd digits, ICETOOL prints asterisks for the overall total for that field and terminates the operation. You can prevent overflow by specifying an appropriate dd value for Ndd or Udd. For example, if ON(1,15,ZD) with TOTAL overflows the default of 15 digits, you can specify ON(1,15,ZD,U16) to prevent overflow. If ON(1,15,ZD,U16) still results in overflow, you can specify ON(1,15,ZD,U17), and so on. Either Ndd or Udd can be used to set the number of digits greater than the maximum for a numeric field, but only Udd can be used to set the number of digits less than the maximum for a numeric field. See the discussion of Ndd or Udd under ON(p,m,f,formatting) for more details on using Ndd or Udd with TOTAL. The TOTAL, MAXIMUM, MINIMUM, and AVERAGE lines are printed in the order in which you specify them. MAXIMUM(string) Specifies an overall MAXIMUM line is to be printed after the rows of data for the report. The specified string is printed starting at the indent column of the overall MAXIMUM line, followed by the overall maximum for each numeric data column. If STATLEFT is specified, the string is printed to the left of the first column of data with the maximums on the same line as the string. If STATLEFT is not specified, the string is printed in the first column of data with the maximums on the same line as the string, or on the next line, as appropriate. A blank line is printed before the overall MAXIMUM line. The string (1 to 50 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). To suppress printing of a string, specify MAXIMUM() using two single apostrophes. The overall maximum for each numeric ON field is printed in the format (formatting, PLUS, BLANK, or standard) you specify. The maximum for a specific numeric field is suppressed if the NOST formatting item is specified for that field. Maximums are printed for ON(VLEN) fields, but not for ON(NUM) fields. The TOTAL, MAXIMUM, MINIMUM, and AVERAGE lines are printed in the order in which you specify them. MINIMUM(string) Specifies an overall MINIMUM line is to be printed after the rows of data for the report. The specified string is printed starting at the indent column of the overall MINIMUM line, followed by the overall minimum for each numeric data column. If STATLEFT is specified, the string is printed to the left of the first column of data with the
Chapter 6. Using ICETOOL

523

DISPLAY Operator
minimums on the same line as the string. If STATLEFT is not specified, the string is printed in the first column of data with the minimums on the same line as the string, or on the next line, as appropriate. A blank line is printed before the overall MINIMUM line. The string (1 to 50 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). To suppress printing of a string, specify MINIMUM() using two single apostrophes. The overall minimum for each numeric ON field is printed in the format (formatting, PLUS, BLANK, or standard) you specify. The minimum for a specific numeric field is suppressed if the NOST formatting item is specified for that field. Minimums are printed for ON(VLEN) fields, but not for ON(NUM) fields. The TOTAL, MAXIMUM, MINIMUM, and AVERAGE lines are printed in the order in which you specify them. AVERAGE(string) Specifies an overall AVERAGE line is to be printed after the rows of data for the report. The specified string is printed starting at the indent column of the overall AVERAGE line, followed by the overall average for each numeric data column. If STATLEFT is specified, the string is printed to the left of the first column of data with the averages on the same line as the string. If STATLEFT is not specified, the string is printed in the first column of data with the averages on the same line as the string, or on the next line, as appropriate. A blank line is printed before the overall AVERAGE line. The overall average (or mean) is calculated by dividing the overall total by the number of values in the report and rounding down to the nearest integer (examples: 23 / 5 = 4, 23 / 5 = 4). The string (1 to 50 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). To suppress printing of a string, specify AVERAGE() using two single apostrophes. The overall average for each numeric ON field is printed in the format (formatting, PLUS, BLANK, or standard) you specify. The average for a specific numeric field is suppressed if the NOST formatting item is specified for that field. Averages are printed for ON(VLEN) fields, but not for ON(NUM) fields. You can use the Ndd or Udd formatting item to decrease or increase the number of digits used for a total. If the overall total for an ON field overflows d digits, ICETOOL prints asterisks for the overall average for that field and terminates the operation. You can prevent overflow by specifying an appropriate dd value for Ndd or Udd. For example, if ON(1,15,ZD) with AVERAGE overflows the default of 15 digits for the total, you can specify ON(1,15,ZD,U16) to prevent overflow. See the discussion of Ndd or Udd under ON(p,m,f,formatting) for more details on using Ndd or Udd. The TOTAL, MAXIMUM, MINIMUM, and AVERAGE lines are printed in the order in which you specify them.

524

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
LIMIT(n) Specifies a limit for the number of invalid decimal values (overriding the default of 200). If n invalid decimal values are found, ICETOOL terminates the operation. n can be 1 to 15 decimal digits, but must be greater than 0. VSAMTYPE(x) See the discussion of this operand on the COPY statement in COPY Operator on page 491. WIDTH(n) Specifies the line length and LRECL you want ICETOOL to use for your list data set. n can be from 121 to 2048. ICETOOL always calculates the line length required to print all titles, headings, data, and statistics and uses it as follows: v If WIDTH(n) is specified and the calculated line length is less than or equal to n, ICETOOL sets the line length and LRECL to n. v If WIDTH(n) is specified and the calculated line length is greater than n, ICETOOL issues an error message and terminates the operation. v If WIDTH(n) is not specified and the calculated line length is less than or equal to 121, ICETOOL sets the line length and LRECL to 121. v If WIDTH(n) is not specified and the calculated line length is between 122 and 2048, ICETOOL sets the line length and LRECL to the calculated line length. v If WIDTH(n) is not specified and the calculated line length is greater than 2048, ICETOOL issues an error message and terminates the operation. Use WIDTH(n) if your LRECL must be set to a particular value (for example, if you use DISP=MOD to place several reports in the same data set) or if you want to ensure that the line length for your report does not exceed a specific maximum (for example, 133 bytes). Otherwise, you can let ICETOOL calculate and set the appropriate line length and LRECL by not specifying WIDTH(n). BREAK(p,m,f) Specifies a numeric or character break field to be used to divide the report into sections. Each set of sequential input records, with the same value for the specified break field, results in a corresponding set of data lines that is treated as a section in the report. The DISPLAY operator should be preceded by a SORT operator (or another application) that sorts the break field and any other appropriate fields in the desired sequence for the report. Each section starts on a new page. Each page of a section includes a break title line showing the break value for the section. Numeric break values are printed with blank for plus sign, for minus sign, and no leading zeros. BTITLE can be used to specify a string to appear in the break title line. The break value and break title string appear in the order in which you specify BREAK and BTITLE. Two blanks appear between break title elements. A blank line is printed after the break title line. BTOTAL, BMAXIMUM, BMINIMUM, and BAVERAGE can be used to produce break statistics for each numeric ON field-for example, the
Chapter 6. Using ICETOOL

525

DISPLAY Operator
maximum of the values in the section for ON(5,3,ZD) and the maximum of the values in the section for ON(22,2,BI). The break statistics for each section are printed at the end of the section (on one or more pages that include the break title). TOTAL, MAXIMUM, MINIMUM, and AVERAGE can be used to produce overall statistics for each numeric ON field-for example, the maximum of the values in the report for ON(5,3,ZD) and the maximum of the values in the report for ON(22,2,BI). The overall statistics for each section are printed at the end of the report (on a separate page that does not include the break title). See ON(p,m,f) for a discussion of p and m. f specifies the format of the field as shown for ON(p,m,f). Note: An FL (hexadecimal floating-point) field can be specified for ON, but not for BREAK. For a CSF, FS, UFF, or SFF format break field: v A maximum of 31 digits is allowed. If a value with more than 31 digits is found, ICETOOL issues an error message and terminates the operation. For a ZD or PD format break field: v If a decimal value with an invalid digit (A-F) is found, ICETOOL issues an error message and terminates the operation. v A value is treated as positive if its sign is F, E, C, A, 8, 6, 4, 2, or 0. v A value is treated as negative if its sign is D, B, 9, 7, 5, 3, or 1. For a DT1, DT2 or DT3 format field: v An invalid SMF date can result in a data exception (0C7 ABEND) or an incorrect ZD date. v SMF date values are always treated as positive. For a DC1, DC2, DC3, DE1, DE2, or DE3 format field: v TOD and ETOD date values are always treated as positive. For a TM1, TM2, TM3 or TM4 format field: v An invalid SMF time can result in an incorrect ZD time. v SMF time values are always treated as positive. For a TC1, TC2, TC3, TC4, TE1, TE2, TE3, or TE4 format field: v TOD and ETOD time values are always treated as positive. BREAK(p,m,f,formatting) Specifies a numeric or character break field to be used to divide the report into sections, and how the data for this field is to be formatted for printing. See BREAK(p,m,f) for further details. formatting

526

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
, mask Epattern Lstring Fstring Tstring LZ Udd

specifies formatting items that indicate how the record number is to be formatted for printing. Formatting items can be specified in any order, but each item can only be specified once. Any formatting item can be specified for a numeric break field, but only Lstring and Tstring can be specified for a character break field. mask See ON(p,m,f,formatting) for a discussion of mask.

Epattern See ON(p,m,f,formatting) for a discussion of Epattern. Lstring See ON(p,m,f,formatting) for a discussion of Lstring. Fstring See ON(p,m,f,formatting) for a discussion of Fstring. Tstring See ON(p,m,f,formatting) for a discussion of Tstring. LZ Udd See ON(p,m,f,formatting) for a discussion of LZ. specifies the number of digits to be used for a numeric break field. Udd can be used to change the column width for numeric break fields. dd specifies the number of digits and must be a two-digit number between 01 and 31. The default number of digits (d) for a numeric break field is the maximum number of digits for that field. For example, d is 8 for BREAK(1,8,ZD). If you know that your break field requires less than d digits, you can use a lower number of digits (dd) instead by specifying Udd, thus reducing the break field width. For example, BREAK(1,8,ZD,U06) reduces d from 8 to 6. If you want your break field to be displayed with more than d digits, you can use a higher number of digits (dd) instead by specifying Udd, thus increasing the field width. For example, BREAK(1,8,ZD,U11) increases d from 8 to 11. BTITLE(string) Specifies a string to appear in the break title line printed for each page of a section. BTITLE can only be specified if BREAK is specified. The break value and break title string appear in the order in which you specify BREAK and BTITLE. Two blanks appear between break title elements. A blank line is printed after the break title line. The string (1 to 50 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). Blanks at the start of the string move the text to the

Chapter 6. Using ICETOOL

527

DISPLAY Operator
right. Blanks at the end of the string increase the spacing between the string and the break value if BTITLE is specified before BREAK. BTOTAL(string) Specifies a break TOTAL (BTOTAL) line is to be printed after the rows of data for each section. BTOTAL can only be specified if BREAK is specified. The specified string is printed starting at the indent column of the break TOTAL line, followed by the break total for each numeric data column.If STATLEFT is specified, the string is printed to the left of the first column of data with the totals on the same line as the string. If STATLEFT is not specified, the string is printed in the first column of data with the totals on the same line as the string, or on the next line, as appropriate. A blank line is printed before the break TOTAL line. The string (1 to 50 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). To suppress printing of a string, specify BTOTAL() using two single apostrophes. The break total for each numeric ON field is printed in the format (formatting, PLUS, BLANK, or standard) you specify. The total for a specific numeric field is suppressed if the NOST formatting item is specified for that field. Totals are printed for ON(VLEN) fields, but not for ON(NUM) fields. The default number of digits (d) for a break total is 15 if the ON field is BI or FI with a length up to 4, PD with a length up to 8, or ZD, CSF, FS, UFF or SFF with a length up to 15. The default number of digits (d) for a break total is 31 if the ON field is BI or FI with a length greater than 4, PD with a length greater than 8, or ZD, CSF, FS, UFF or SFF with a length greater than 15. By default, column widths are adjusted to allow for a maximum of a sign and d digits for the totals. If the break total for an ON field overflows d digits, ICETOOL prints asterisks for the break total for that field and terminates the operation. You can use the Ndd or Udd formatting item to decrease or increase the number of digits used for a break total. If you use Ndd or Udd and the break total for an ON field overflows dd digits, ICETOOL prints asterisks for the break total for that field and terminates the operation. You can prevent overflow by specifying an appropriate dd value for Ndd or Udd. For example, if ON(1,15,ZD) with BTOTAL overflows the default of 15 digits, you can specify ON(1,15,ZD,U16) to prevent overflow. If ON(1,15,ZD,U16) still results in overflow, you can specify ON(1,15,ZD,U17), and so on. Either Ndd or Udd can be used to set the number of digits greater than the maximum for a numeric field, but only Udd can be used to set the number of digits less than the maximum for a numeric field. See the discussion of Ndd or Udd under ON(p,m,f,formatting) for more details on using Ndd or Udd with BTOTAL. The BTOTAL, BMAXIMUM, BMINIMUM, and BAVERAGE lines are printed in the order in which you specify them. BMAXIMUM(string) Specifies a break MAXIMUM line is to be printed after the rows of data for each section. BMAXIMUM can only be specified if BREAK is

528

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
specified. The specified string is printed starting at the indent column of the break MAXIMUM line, followed by the break maximum for each numeric data column. If STATLEFT is specified, the string is printed to the left of the first column of data with the maximums on the same line as the string. If STATLEFT is not specified, the string is printed in the first column of data with the maximums on the same line as the string, or on the next line, as appropriate. A blank line is printed before the break MAXIMUM line. The string (1 to 50 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). To suppress printing of a string, specify BMAXIMUM() using two single apostrophes. The break maximum for each numeric ON field is printed in the format (formatting, PLUS, BLANK, or standard) you specify. The maximum for a specific numeric field is suppressed if the NOST formatting item is specified for that field. Maximums are printed for ON(VLEN) fields, but not for ON(NUM) fields. The BTOTAL, BMAXIMUM, BMINIMUM, and BAVERAGE lines are printed in the order in which you specify them. BMINIMUM(string) Specifies a break MINIMUM line is to be printed after the rows of data for each section. BMINIMUM can only be specified if BREAK is specified. The specified string is printed starting at the indent column of the break MINIMUM line, followed by the break minimum for each numeric data column. If STATLEFT is specified, the string is printed to the left of the first column of data with the minimums on the same line as the string. If STATLEFT is not specified, the string is printed in the first column of data with the minimums on the same line as the string, or on the next line, as appropriate. A blank line is printed before the break MINIMUM line. The string (1 to 50 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). To suppress printing of a string, specify BMINIMUM() using two single apostrophes. The break minimum for each numeric ON field is printed in the format (formatting, PLUS, BLANK, or standard) you specify. The minimum for a specific numeric field is suppressed if the NOST formatting item is specified for that field. Minimums are printed for ON(VLEN) fields, but not for ON(NUM) fields. The BTOTAL, BMAXIMUM, BMINIMUM, and BAVERAGE lines are printed in the order in which you specify them. BAVERAGE(string) Specifies a break AVERAGE line is to be printed after the rows of data for each section. BAVERAGE can only be specified if BREAK is specified. The specified string is printed starting at the indent column of the break AVERAGE line, followed by the break average for each numeric data column. If STATLEFT is specified, the string is printed to the left of the first column of data with the averages on the same line as the string. If STATLEFT is not specified, the string is printed in the first column of data with the averages on the same line as the string, or on the next line, as appropriate. A blank line is printed before the break AVERAGE line.
Chapter 6. Using ICETOOL

529

DISPLAY Operator
The break average (or mean) is calculated by dividing the break total by the number of values in the section and rounding down to the nearest integer (examples: 23 / 5 = 4, 23 / 5 = 4). The string (1 to 50 characters) must be enclosed in single apostrophes. To include a single apostrophe () in the string, specify two single apostrophes (). To suppress printing of a string, specify BAVERAGE() using two single apostrophes. The break average for each numeric ON field is printed in the format (formatting, PLUS, BLANK, or standard) you specify. The average for a specific numeric field is suppressed if the NOST formatting item is specified for that field. Averages are printed for ON(VLEN) fields, but not for ON(NUM) fields. You can use the Ndd or Udd formatting item to decrease or increase the number of digits used for a break total. If the break total for an ON field overflows d digits, ICETOOL prints asterisks for the break average for that field and terminates the operation. You can prevent overflow by specifying an appropriate dd value for Ndd or Udd. For example, if ON(1,15,ZD) with BAVERAGE overflows the default of 15 digits for the total, you can specify ON(1,15,ZD,U16) to prevent overflow. See the discussion of Ndd or Udd under ON(p,m,f,formatting) for more details on using Ndd or Udd. The BTOTAL, BMAXIMUM, BMINIMUM, and BAVERAGE lines are printed in the order in which you specify them. STATLEFT Specifies that the strings for statistics (TOTAL, MAXIMUM, MINIMUM, AVERAGE, BTOTAL, BMAXIMUM, BMINIMUM, BAVERAGE) are to be placed to the left of the first column of data (overriding the default of placing the strings in the first column). STATLEFT ensures that each statistic appears on the same line as its string while making the statistics lines stand out from the columns of data. UZERO Specifies that 0 and +0 are to be treated as unsigned zero values, that is, as the same value. With UZERO, 0 and +0 are treated as positive for ON, MINIMUM, MAXIMUM, BREAK, BMINIMUM and BMAXIMUM processing. UZERO overrides the default of treating 0 and +0 as signed zero values, that is, as different values. Without UZERO, 0 is treated as negative and +0 is treated as positive for ON, MINIMUM, MAXIMUM, BREAK, BMINIMUM and BMAXIMUM processing. LISTSDB OR LISTNOSDB Can be used to override the SDBMSG value for this LIST data set. LISTSDB directs ICETOOL to select the system-determined optimum block size for the LIST data set in the same way as for installation option SDBMSG=YES. LISTNOSDB directs ICETOOL to select the block size for the LIST data set in the same way as for installation option SDBMSG=NO. See the discussion of the LIST(listdd) operand above for more information on how LISTSDB or LISTNOSDB affects the LIST data set block size.

530

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
Attention: LISTSDB has no effect for SYSOUT data sets (for example, //RPT1 DD SYSOUT=*), because the system-determined optimum block size is not used for spool or dummy data sets.

DISPLAY Examples
Although the DISPLAY operators in the examples below could all be contained in a single ICETOOL job step, they are shown and discussed separately for clarity. See OCCUR Operator on page 548 for additional examples of tailoring the report format.

Example 1
DISPLAY FROM(SOURCE) LIST(FIELDS) ON(NUM) ON(40,12,CH) ON(20,8,PD)

Prints, in the FIELDS data set: v A heading line containing the standard headings v Data lines in the standard format containing: The record number in the standard format The characters from positions 40-51 of the SOURCE data set The packed decimal values from positions 20-27 of the SOURCE data set in the standard format The FIELDS output starts on a new page and looks as follows (the first 2 records are shown with illustrative values):
RECORD NUMBER 000000000000001 000000000000002 . . . (40,12,CH) SAN JOSE MORGAN HILL . . . (20,8,PD) 000000000003745 000000000016502 . . .

The heading line appears at the top of each page.

Example 2
DISPLAY FROM(IN) LIST(LIST1) TITLE(National Accounting Report) PAGE DATE TIME HEADER(Division) HEADER(Revenue) HEADER(Profit/Loss) ON(1,25,CH) ON(45,10,ZD) ON(35,10,ZD) BLANK TOTAL(Company Totals) AVERAGE(Company Averages)

Prints, in the LIST1 data set: v A title line containing the specified title, the page number, the date and the time v A heading line containing the specified underlined headings v Data lines in the BLANK format containing: The characters from positions 1-25 of the IN data set The zoned decimal values from positions 45-54 of the IN data set The zoned decimal values from positions 35-44 of the IN data set v A TOTAL line containing the specified string and the total for each of the two zoned decimal fields in the BLANK format

Chapter 6. Using ICETOOL

531

DISPLAY Operator
v An AVERAGE line containing the specified string and the average for each of the two zoned decimal fields in the BLANK format. The LIST1 output starts on a new page and looks as follows (the first 2 records are shown with illustrative values):
National Accounting Report Division ------------------------Research and Development Manufacturing . . . Company Totals Company Averages - 1 Revenue ---------------54323456 159257631 . . . 612867321 76608415 02/21/05 18:52:44

Profit/Loss ----------------823325 1372610 . . . 5277836 659729

The title line and underlined heading line appear at the top of each page.

Example 3
DISPLAY FROM(DATA) LIST(JUSTDATA) NOHEADER ON(17,5,PD) ON(1,2,FI)

Prints, in the JUSTDATA data set: v Data lines in the standard format containing: The packed decimal values from positions 17-21 of the DATA data set in the standard format The fixed-point values from positions 1-2 of the DATA data set in the standard format The JUSTDATA output contains no page ejects or heading lines and looks as follows (the first 2 records are shown with illustrative values):
-0000000000273216 +0000000000993112 . . . +0000000000000027 +0000000000000321 . . .

Example 4
COPY FROM(INPUT) TO(TEMP) USING(TREG) DISPLAY FROM(TEMP) LIST(REGULAR) PAGE TITLE(Report on Regular Tools) TBETWEEN(12)HEADER(NONE) ON(1,18,CH) HEADER(,Item) ON(35,5,CH) HEADER(Percent,Change) ON(28,4,FS,B1) LINES(66) COPY FROM(INPUT) TO(TEMP) USING(TPOW) DISPLAY FROM(TEMP) LIST(POWER) PAGE TITLE(Report on Power Tools ) TBETWEEN(12)HEADER(NONE) ON(1,18,CH) HEADER(,Item) ON(35,5,CH) HEADER(Percent,Change) ON(28,4,FS,B1) LINES(66)

This example shows how reports for different subsets of data can be produced. Assume that:

532

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
v The TREGCNTL data set contains:
INCLUDE COND=(44,8,CH,EQ,CRegular)

v The TPOWCNTL data set contains:

INCLUDE COND=(44,8,CH,EQ,CPower)

The first COPY operator copies the records from the INPUT data set that contain Regular in positions 44-51 to the TEMP (temporary) data set The first DISPLAY operator uses the first subset of records in the TEMP data set to print, in the REGULAR data set: v A title line containing the page number and specified title, with twelve blanks between these report elements. v A two-line heading containing the specified underlined strings (with no heading for the first ON field)). Note the comma in HEADER(,Item) to place Item on line2 of the heading. v Data lines for the first subset of records containing: The characters from positions 1-18 The characters from positions 35-39 The floating sign values from positions 28-31 formatted with one decimal place and a period as the decimal point The second COPY operator copies the records from the INPUT data set that contain Power in positions 44-51 to the TEMP (temporary) data set The second DISPLAY operator uses the second subset of records in the TEMP data set to print, in the POWER data set: v A title line containing the page number and specified title, with twelve blanks between these report elements. v A two-line heading containing the specified underlined strings (with no heading for the first ON field)). Note the comma in HEADER(,Item) to place Item on line2 of the heading. v Data lines for the second subset of records containing: The characters from positions 1-18 The characters from positions 35-39 The floating sign values from positions 28-31 formatted with one decimal place and a period as the decimal point The REGULAR output starts on a new page and looks as follows (the first 2 records are shown with illustrative values):
- 1 Report on Regular Tools Item ----10325 00273 Percent Change -------7.3 15.8

Hammers Wrenches

The title line and underlined heading lines appear at the top of each page. The number of lines per page is 66, overriding the default of 58. The POWER output starts on a new page and looks as follows (the first 2 records are shown with illustrative values):

Chapter 6. Using ICETOOL

533

DISPLAY Operator

- 1 -

Report on Power Tools Item ----10325 00273 Percent Change ------9.8 123.0

Hammers Wrenches

The title line and underlined heading lines appear at the top of each page. The number of lines per page is 66, overriding the default of 58.

Example 5
DISPLAY FROM(INV) LIST(RDWLIST1) TITLE(No Frills RDW Report) ON(NUM) ON(VLEN) ON(1,4,HEX) MINIMUM(Smallest) MAXIMUM(Largest)

Prints, in the RDWLIST1 data set: v A title line containing the specified title v A heading line containing the standard headings v Data lines in the standard format containing: The record number The record length The record descriptor word (RDW) in hexadecimal v A MINIMUM line containing the specified string and the minimum record length in the standard format v A MAXIMUM line containing the specified string and the maximum record length in the standard format. The RDWLIST1 output starts on a new page and looks as follows (the first 2 records are shown with illustrative values):
No Frills RDW Report RECORD NUMBER 000000000000001 000000000000002 . . . Smallest Largest RECORD LENGTH +000000000000075 +000000000000071 . . . +000000000000058 +000000000000078 (1,4,HEX) 004B0000 00470000 . . .

The title line and heading line appear at the top of each page.

Example 6
DISPLAY FROM(INV) LIST(RDWLIST2) DATE(DMY.) TITLE( Fancy RDW Report ) TIME(12:) HEADER(Relative Record) ON(NUM) HEADER( RDW (length)) ON(VLEN) HEADER(RDW (Hex)) ON(1,4,HEX) -

534

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
BLANK MINIMUM(Smallest Record in Variable Data Set:) MAXIMUM(Largest Record in Variable Data Set:)

Prints, in the RDWLIST2 data set: v A title line containing the date, the specified title and the time v A heading line containing the specified underlined headings v Data lines in the BLANK format containing: The record number The record length The record descriptor word (RDW) in hexadecimal v A MINIMUM line containing the specified string and the minimum record length in the BLANK format v A MAXIMUM line containing the specified string and the maximum record length in the BLANK format. RDWLIST2 output starts on a new page and looks as follows (the first 2 records are shown with illustrative values):
21.09.92 Relative Record --------------1 2 . . . Fancy RDW Report RDW (length) ---------------75 71 . . . 01:52:28 pm RDW (Hex) --------004B0000 00470000 . . .

Smallest Record in Variable Data Set: 58 Largest Record in Variable Data Set: 78

The title line and underlined heading line appear at the top of each page.

Example 7
SORT FROM(PARTS) TO(TEMP) USING(SRT1) DISPLAY FROM(TEMP) LIST(USA) TITLE(Parts Completion Report for USA) DATE HEADER(Part) HEADER(Completed) HEADER(Value ($)) ON(15,6,CH) ON(3,4,ZD,A1) ON(38,8,ZD,C1) TOTAL(Total:) DISPLAY FROM(TEMP) LIST(FRANCE) TITLE(Parts Completion Report for France) DATE(DM4/) HEADER(Part) HEADER(Completed) HEADER(Value (F)) ON(15,6,CH) ON(3,4,ZD,A3) ON(38,8,ZD,C3) TOTAL(Total:) DISPLAY FROM(TEMP) LIST(DENMARK) TITLE(Parts Completion Report for Denmark) DATE(DMY-) HEADER(Part) HEADER(Completed) HEADER(Value (kr)) ON(15,6,CH) ON(3,4,ZD,A2) ON(38,8,ZD,C2) TOTAL(Total:)

This example shows how reports for three different countries can be produced. The reports differ only in the way that date and numeric values are displayed. Assume that the SRT1CNTL data set contains:
SORT FIELDS=(15,6,CH,A)
Chapter 6. Using ICETOOL

535

DISPLAY Operator
The SORT operator sorts the PARTS data set to the TEMP data set using the SORT statement in SRT1CNTL. The first DISPLAY operator uses the sorted records in the TEMP data set to print, in the USA data set: v A title line containing the specified title and the date in the format commonly used in the United States v A heading line containing the specified underlined headings v Data lines containing: The characters from positions 15-20 The zoned decimal values from positions 3-6 formatted with the separators commonly used in the United States The zoned decimal values from positions 38-45 formatted with two decimal places and the separators and decimal point commonly used in the United States. v A TOTAL line containing the specified string and the total for each of the two zoned decimal fields formatted in the same way as the data values. The second DISPLAY operator uses the sorted records in the TEMP data set to print, in the FRANCE data set: v A title line containing the specified title and the date in the format commonly used in France v A heading line containing the specified underlined headings v Data lines containing: The characters from positions 15-20 The zoned decimal values from positions 3-6 formatted with the separators commonly used in France The zoned decimal values from positions 38-45 formatted with two decimal places and the separators and decimal point commonly used in France. v A TOTAL line containing the specified string and the total for each of the two zoned decimal fields formatted in the same way as the data values. The third DISPLAY operator uses the sorted records in the TEMP data set to print, in the DENMARK data set: v A title line containing the specified title and the date in the format commonly used in Denmark v A heading line containing the specified underlined headings v Data lines containing: The characters from positions 15-20 The zoned decimal values from positions 3-6 formatted with the separators commonly used in Denmark The zoned decimal values from positions 38-45 formatted with two decimal places and the separators and decimal point commonly used in Denmark. v A TOTAL line containing the specified string and the total for each of the two zoned decimal fields formatted in the same way as the data values. The USA output starts on a new page and looks as follows (several records are shown with illustrative values):

536

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator

Parts Completion Report for USA Part -----000310 001184 029633 192199 821356 Total: Completed -------------------562 1,234 35 3,150 233 5,214

01/14/05 Value ($) --------------------8,317.53 23,456.78 642.10 121,934.65 2,212.34 156,563.40

The title line and underlined heading line appear at the top of each page. The FRANCE output starts on a new page and looks as follows (several record are shown with illustrative values):
Parts Completion Report for France Part -----000310 001184 029633 192199 821356 Total: Completed -------------------562 1 234 35 3 150 233 5 214 14/01/2005

Value (F) --------------------8 317,53 23 456,78 642,10 121 934,65 2 212,34 156 563,40

The title line and underlined heading line appear at the top of each page. The DENMARK output starts on a new page and looks as follows (several records are shown with illustrative values):
Parts Completion Report for Denmark Part -----000310 001184 029633 192199 821356 Total: Completed -------------------562 1.234 35 3.150 233 5.214 14-01-05

Value (kr) --------------------8.317,53 23.456,78 642,10 121.934,65 2.212,34 156.563,40

The title line and underlined heading line appear at the top of each page.

Example 8
SORT FROM(DATA) TO(TEMP) USING(SRTX) DISPLAY FROM(TEMP) LIST(WEST) DATE TITLE(Western Region Profit/Loss Report) PAGE BTITLE(Division:) BREAK(3,10,CH) HEADER(Branch Office) ON(16,13,CH) HEADER(Profit/Loss (K)) ON(41,4,PD,/K,E1) BMINIMUM(Lowest Profit/Loss in this Division:) BMAXIMUM(Highest Profit/Loss in this Division:) BAVERAGE(Average Profit/Loss for this Division:) MINIMUM(Lowest Profit/Loss for all Divisions:) MAXIMUM(Highest Profit/Loss for all Divisions:) AVERAGE(Average Profit/Loss for all Divisions:)

This example shows how a report with sections can be produced.

Chapter 6. Using ICETOOL

537

DISPLAY Operator
Assume that the SRTXCNTL data set contains:
SORT FIELDS=(3,10,A,16,13,A),FORMAT=CH

The SORT operator sorts the DATA data set to the TEMP data set using the SORT statement in SRTXCNTL. The DISPLAY operator uses the sorted records in the TEMP data set to print, in the WEST data set, sections with: v A title line containing the date, the specified title string, and the page number v A break title containing the specified break title string, and the break field characters from positions 3-12 v A heading line containing the specified underlined headings v Data lines containing: The characters from positions 16-28 The packed decimal values from positions 41-44 divided by 1000 and formatted with separators and signs as specified. v Break MINIMUM, MAXIMUM, and AVERAGE lines containing the specified strings and statistics for the packed decimal field values in this section, formatted in the same way as the data values. The last page of the report contains: v A title line containing the date, the specified title string, and the page number v A heading line containing the specified underlined headings v Overall MINIMUM, MAXIMUM, and AVERAGE lines containing the specified strings and statistics for the packed decimal field values in the report, formatted in the same way as the data values. The first section of the WEST output starts on a new page and looks as follows (several records are shown with illustrative values):
01/14/05 Division: Chips Profit/Loss (K) --------------3,293 (141) 213 1,067 (31) 92 1,535 Western Region Profit/Loss Report - 1 -

Branch Office ------------Gilroy Los Angeles Morgan Hill Oakland San Francisco San Jose San Martin

Lowest Profit/Loss in this Division: (141) Highest Profit/Loss in this Division: 3,293 Average Profit/Loss for this Division: 861

The title line, break title line, and underlined heading line appear at the top of each page of the section. The second section of the WEST output starts on a new page and looks as follows (several records are shown with illustrative values):

538

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator

01/14/05 Division:

Western Region Profit/Loss Report Ice Cream Profit/Loss (K) --------------673 95 (321) 2,318 21

- 2 -

Branch Office ------------Marin Napa San Francisco San Jose San Martin

Lowest Profit/Loss in this Division: (321) Highest Profit/Loss in this Division: 2,318 Average Profit/Loss for this Division: 557

The title line, break title line, and underlined heading line appear at the top of each page of the section. The last page of the WEST output starts on a new page and looks as follows:
01/14/05 Branch Office ------------Western Region Profit/Loss Report Profit/Loss (K) --------------- 3 -

Lowest Profit/Loss for all Divisions: (321) Highest Profit/Loss for all Divisions: 3,293 Average Profit/Loss for all Divisions: 734

Example 9
MODE CONTINUE VERIFY FROM(CHECK) ON(2,3,PD) LIMIT(500) DISPLAY FROM(CHECK) LIST(PDREPORT) BLANK LIMIT(500) HEADER(Relative Record) ON(NUM) HEADER(Numeric) ON(2,3,PD) HEADER(Hexadecimal) ON(2,3,HEX) HEADER(Associated Field) ON(21,20,CH)

This example shows how each record containing an invalid decimal value can be identified either by its relative record number or an associated field in the record. The MODE operator ensures that the DISPLAY operator is processed if the VERIFY operator identifies an invalid decimal value. The VERIFY operator checks for invalid digits (A-F) and invalid signs (0-9) in the packed decimal values from positions 2-4 of the CHECK data set. Messages ICE618A and ICE649A are printed in the TOOLMSG data set for each value (if any) that contains an invalid digit or sign. If 500 invalid values are found, the operation is terminated. The DISPLAY operator checks for invalid digits (A-F) in the packed decimal values from positions 2-4 of the CHECK data set. Messages ICE618A and ICE649A are
Chapter 6. Using ICETOOL

539

DISPLAY Operator
printed in the TOOLMSG data set for each value (if any) that contains an invalid digit. If 500 invalid values are found, the operation is terminated. If a check for invalid signs is required, the VERIFY operator must be used, because the DISPLAY operator only checks for invalid digits. The VERIFY operator is not required if signs need not be checked. The DISPLAY operator also prints, in the PDREPORT data set: v A heading line containing the specified underlined headings v Data lines in the BLANK format containing: The relative record number. This number can be matched against the RECORD numbers printed in the ICE618A messages to find the records with invalid signs. The numeric representation of the packed decimal value in positions 2-4. Asterisks are shown for values with invalid digits, making them easy to identify. Asterisks are not shown for values with invalid signs; these must be identified by matching the relative record number against the RECORD number in ICE618A. The hexadecimal representation of the packed decimal value in positions 2-4 (also shown in ICE649A). This makes it easy to find the specific hexadecimal digits or signs that are invalid. The characters in positions 21-40. An associated field such as this can be used to make identification of the records with invalid values easier. The ICE618A and ICE649A messages in TOOLMSG for the VERIFY operator are:
ICE618A ICE649A ICE618A ICE649A ICE618A ICE649A 0 INVALID (2,3,PD) 0 HEX VALUE: 53A54C 0 INVALID (2,3,PD) 0 HEX VALUE: 621540 0 INVALID (2,3,PD) 0 HEX VALUE: 400F3C VALUE - RECORD: 000000000000003 VALUE - RECORD: 000000000000012 VALUE - RECORD: 000000000000019

The ICE618A and ICE649A messages in TOOLMSG for the DISPLAY operator are:
ICE618A ICE649A ICE618A ICE649A 0 INVALID (2,3,PD) 0 HEX VALUE: 53A54C 0 INVALID (2,3,PD) 0 HEX VALUE: 400F3C VALUE - RECORD: 000000000000003 VALUE - RECORD: 000000000000019

The PDREPORT output looks as follows:

540

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator

Relative Record --------------1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

Numeric ------18600 -93 ****** 86399 24215 8351 19003 -31285 88316 1860 -29285 62154 -328 -11010 1363 92132 -48500 -55 ****** 33218 96031

Hexadecimal ----------18600C 00093B 53A54C 86399C 24215F 08351C 19003C 31285D 88316C 01860C 29285D 621540 00328D 11010D 01363F 92132C 48500D 00055D 400F3C 33218C 96031C

Associated Field -------------------Wagar Gellai Giulianelli Mehta Johnson Packer Childers Burg Monkman Vezinaw Mead Wu Madrid Warren Burt Mao Shen Yamamoto-Smith Yaeger Leung Kaspar

PDREPORT can be used in conjunction with the ICE618A and ICE649A messages to identify that: v Record 3 has an invalid digit of A and an associated field of Giulianelli v Record 12 has an invalid sign of 0 and an associated field of Wu v Record 19 has an invalid digit of F and an associated field of Yaeger.

Example 10
COPY FROM(IN) USING(OUTF) DISPLAY FROM(TEMP) LIST(EMPCT) BLANK TITLE(Employees by Function) DATE HEADER(Function) HEADER(Employees) ON(1,25,CH) ON(30,4,ZD)

This example shows how the OUTFIL table lookup feature can be used to substitute meaningful phrases for cryptic values in ICETOOL reports. Assume that: v The OUTFCNTL data set contains:
OUTFIL FNAMES=TEMP, OUTREC=(1:9,2,CHANGE=(25, CMN,CManufacturing, CRD,CResearch and Development, CFN,CFinance, CMR,CMarketing, CIS,CInformation Systems), 30:4,4)

The COPY operator uses the OUTFIL statement in OUTFCNTL to reformat the IN data set records to the TEMP (temporary) data set. Two fields are extracted for use by the DISPLAY operator: v The 2-character department code in positions 9-10 is changed to a 25-character name in positions 1-25 using the table lookup feature. v The zoned decimal value in positions 4-7 is moved to positions 30-33. The DISPLAY operator uses the reformatted fields in the TEMP data set to print, in the EMPCT data set: v A title line containing the specified title and the date
Chapter 6. Using ICETOOL

541

DISPLAY Operator
v A heading line containing the specified underlined headings v Data lines in the BLANK format containing: The names from positions 1-25 that were substituted for the department codes The zoned decimal values from positions 30-33. The EMPCT output starts on a new page and looks as follows:
Employees by Function Function ------------------------Manufacturing Marketing Research and Development Information Systems Finance 02/14/05 Employees --------486 21 55 123 33

Example 11
DISPLAY FROM(ACCTS) LIST(PLAIN) TITLE(Accounts Report for First Quarter) DATE(MD4/) BLANK HEADER(Amount) ON(12,6,ZD) HEADER(Id) ON(NUM) HEADER(Acct#) ON(31,3,PD) HEADER(Date) ON(1,4,ZD) TOTAL(Total for Q1) AVERAGE(Average for Q1) DISPLAY FROM(ACCTS) LIST(FANCY) TITLE(Accounts Report for First Quarter) DATE(MD4/) BLANK HEADER(Amount) ON(12,6,ZD,C1,N08) HEADER(Id) ON(NUM,N02) HEADER(Acct#) ON(31,3,PD,NOST,LZ) HEADER(Date) ON(1,4,ZD,E99/99,NOST) INDENT(2) BETWEEN(5) STATLEFT TOTAL(Total for Q1) AVERAGE(Average for Q1)

This example shows some options you can use to improve the appearance of a DISPLAY report. The first DISPLAY operator produces a plain report, and the second DISPLAY operator uses the options shown in bold to produce a fancy report. The PLAIN output starts on a new page and looks as follows:
Accounts Report for First Quarter Amount --------------93271 137622 83147 183261 76389 920013 Total for Q1 1493703 Average for Q1 248950 Id --------------1 2 3 4 5 6 05/04/2001 Acct# ------------------15932 187 15932 2158 187 15932 50328 8388 Date -------------------106 128 212 217 305 319 1287 214

542

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator
The FANCY output starts on a new page and looks as follows:
Accounts Report for First Quarter Amount -------932.71 1,376.22 831.47 1,832.61 763.89 9,200.13 Total for Q1 Average for Q1 14,937.03 2,489.50 Id --1 2 3 4 5 6 05/04/2001 Acct# -----15932 00187 15932 02158 00187 15932 Date ----01/06 01/28 02/12 02/17 03/05 03/19

Here is an explanation of the extra options used for the fancy report: v First ON field: In the PLAIN report, BLANK causes ICETOOL to print the 6-byte ZD values as unedited digits with leading zeros suppressed. But for this example, we know the digits really represent dollars and cents. So in the FANCY report, we use the C1 formatting item (one of thirty-three available masks) to print the values with a comma (,) as the thousands separator and a period (.) as the decimal point. In the PLAIN report, TOTAL causes ICETOOL to allow 15 digits for the values because it does not know how many digits are needed. But for this example, we know the total amount will not exceed 8 digits. So in the FANCY report, we use the N08 formatting item to set the number of digits to 8. This decreases the column width for the field. v Second ON field: In the PLAIN report, NUM causes ICETOOL to allow 15 digits for the record number because it does not know how many digits are needed. But for this example, we know the number of records will not exceed 99. So in the FANCY report, we use the N02 formatting item to set the number of digits to 2. This decreases the column width for the record number. v Third ON field: In the PLAIN report, TOTAL and AVERAGE cause ICETOOL to print the total and average for this 3-byte PD field. But for this example, we know we do not want statistics for the field because it is an account number. So in the FANCY report, we use the NOST formatting item to suppress the statistics for this field. In the PLAIN report, the default mask of A0 causes ICETOOL to suppress leading zeros for this 3-byte PD field. But for this example, we know that we want to show leading zeros for the field because it is an account number. So in the FANCY report, we use the LZ formatting item to print leading zeros for this field. v Fourth ON field: In the PLAIN report, BLANK causes ICETOOL to print the 4-byte ZD values as unedited digits with leading zeros suppressed. But for this example, we know the digits represent a date (month and day). So in the FANCY report, we use the E99/99 formatting item to print the values with leading zeros and a slash (/) between the month and day. In the PLAIN report, TOTAL and AVERAGE cause ICETOOL to print the total and average for this 4-byte ZD field. But for this example, we know we do not want the total or average for this field because it is a date. So in the FANCY report, we use the NOST formatting item to suppress the statistics for this field. Note: In some applications, we might want the minimum and maximum for a date displayed with Epattern, so we would not specify NOST for the date field.
Chapter 6. Using ICETOOL

543

DISPLAY Operator
v INDENT: In the PLAIN report, ICETOOL starts the report in column 2 (after the control character), by default. But for this example, we want to indent the report a bit. So in the FANCY report, we use the INDENT(2) operand to indent the report by 2 blanks so it starts in column 4. v BETWEEN: In the PLAIN report, ICETOOL uses 3 blanks between the columns of data, by default. But for this example, we want more space between the columns. So in the FANCY report, we use the BETWEEN(5) operand to insert 5 blanks between the columns. v STATLEFT: In the PLAIN report, ICETOOL prints the strings for TOTAL and AVERAGE under the first column of data, by default, and uses two lines for each statistic to avoid having the string overlay the value. But for this example, we would like to have the TOTAL and AVERAGE strings stand out in the report and also have each string on the same line as its value. So in the FANCY report, we use the STATLEFT operand to print the TOTAL and AVERAGE strings to the left of the first column of data.

Example 12
SORT FROM(RAWSMF) TO(SMF14) USING(SMFI) DISPLAY FROM(SMF14) LIST(SMF14RPT) TITLE(SMF Type-14 Records) DATE(4MD/) HEADER(Date) ON(11,4,DT1,E9999/99/99) HEADER(Time) ON(7,4,TM1,E99:99:99) HEADER(Sys) ON(15,4,CH) HEADER(Jobname) ON(19,8,CH) HEADER(Datasetname) ON(69,44,CH)

This example shows how SMF date and time values can be displayed in a meaningful way in a report on SMF type-14 records. The SORT operator selects the type-14 records from the RAWSMF data set and sorts them by date and time to the SMF14 data set. It uses the following control statements in SMFICNTL:
INCLUDE COND=(6,1,BI,EQ,14) SORT FIELDS=(11,4,PD,A,7,4,BI,A)

The DISPLAY operator uses the selected type-14 records in SMF14 to print, in the SMF14RPT data set: v A title line containing the specified title and the date v A heading line containing the specified underlined headings v Data lines containing: The SMF date values in positions 11-14 displayed as Cyyyy/mm/dd The The The The SMF time values in positions 7-10 displayed as Chh:mm:ss character values in positions 15-18 character values in positions 19-26 character values in positions 69-112

The SMF14RPT output starts on a new page and looks as follows:

544

z/OS V1R10.0 DFSORT Application Programming Guide

DISPLAY Operator

SMF Type-14 Records Date ---------2001/04/20 2001/04/20 2001/04/21 2001/04/21 2001/04/24 Time -------06:03:15 10:03:22 14:05:37 22:11:00 00:00:08

2001/04/24 Sys ---ID03 ID02 ID03 ID03 ID03 Jobname -------JOB00003 JOB00002 JOB00004 JOB00005 JOB00006 Datasetname ----------- ... SYS1.QRS SYS1.XYZ SYS1.MNO SYS1.MNO SYS1.MNO

Note: When you use SMF date formats (DTn) or SMF time formats (TMn), the SMF values are treated as numeric. This allows you to use numeric formatting items such as masks and patterns to edit the SMF values. By default, DTn and TMn headings, like other numeric headings, appear right-aligned as shown in the SMF14RPT output example above. If you want to center-align or left-align headings for numeric values, you can add an appropriate number of blanks at the end of HEADER(string1). For example, if you wanted to left-align the SMF date heading, you could use six blanks at the end of the header string like so:
HEADER(Date )

to get the following heading:

Date ----------

If you wanted to center-align the SMF date heading, you could use three blanks at the end of the header string like so:
HEADER(Date )

to get the following heading:

Date ----------

Example 13
SORT FROM(SMFIN) TO(SMF71) USING(TY71) DISPLAY FROM(SMF71) LIST(SMF71RPT) TITLE(Low impact central storage frames) BREAK(15,4,CH,LSystem: ) HEADER(Date) ON(11,4,DT1,E9999-99-99) HEADER(Time) ON(7,4,TM1,E99:99:99) HEADER(Min Frames) ON(925,8,FL,U10) HEADER(Max Frames) ON(933,8,FL,U10) HEADER(Avg Frames) ON(941,8,FL,U10) BLANK PAGE

This example shows how floating point values can be displayed as integers in a report on SMF type-71 records with a section for each system id. The SORT operator selects SMF type-71 records that are at least 19 bytes long and sorts them by system id, date and time to the SMF71 data set. It uses the following control statements in TY71CNTL:
OMIT COND=(6,1,BI,NE,+71,OR,1,2,BI,LE,+18) SORT FIELDS=(15,4,CH,A,11,4,PD,A,7,4,BI,A)

The DISPLAY operator uses the selected type-71 records in SMF71 to print, in the SMF71RPT data set: v A title line containing the specified title and the page number.
Chapter 6. Using ICETOOL

545

DISPLAY Operator
v A break title containing the specified leading string and the SMF71SID system id character values in positions 15-18. v A heading line containing the specified underlined headings. v Data lines containing: The SMF71DTE date value. This SMF date value in positions 11-14 is displayed as a Cyyyy-mm-dd value. The SMF71TME time value. This SMF time value in positions 7-10 is displayed as a Chh:mm:ss value. The SMF71CLM minimum number of low-impact central storage frames value. This floating-point value in positions 925-932 is displayed as a 10 digit integer value. (The U10 formatting item reduces the number of digits for the integer representation of the floating-point value from 20 to 10, decreasing the column width for the field.) The SMF71CLX maximum number of low-impact central storage frames value. This floating-point value in positions 933-940 is displayed as a 10 digit integer value. The SMF71CLA average number of low-impact central storage frames value. This floating-point value in positions 941-948 is displayed as a 10 digit integer value. Each system id value starts on a new page and looks as follows (several sections and records are shown with illustrative values):
Low impact central storage frames System: SYSA Date ---------2005-08-01 2005-08-01 2005-08-01 Time -------11:45:00 12:00:00 12:15:00 Min Frames ----------934215 971599 970192 Max Frames ----------1001596 1004939 982565 - 2 Avg Frames ----------963434 984437 973768 - 1 -

Low impact central storage frames System: SYSB Date ---------2005-08-01 2005-08-01 2005-08-01 Time -------11:45:00 12:00:00 12:15:00 Min Frames ----------947220 980120 980387

Max Frames ----------985444 1018982 1051920

Avg Frames ----------966581 986360 1011873

MODE Operator

MODE

STOP CONTINUE SCAN

Specifies one of three modes to control error checking and actions after error detection. A MODE operator effects the processing (that is, error checking of

546

z/OS V1R10.0 DFSORT Application Programming Guide

MODE Operator
ICETOOL statements and calling DFSORT) of the operators that follow it, up to the next MODE operator (if any). MODE operators allow you to do the following for groups of operators or all operators: 1. Stop or continue processing operators after a return code of 12 or 16. A return code of 12 or 16 can be set as the result of a statement or run-time error detected by ICETOOL or DFSORT. 2. Check for errors in ICETOOL statements, but do not call DFSORT.

Operand Descriptions
The operands described below can be specified in any order. STOP Stops subsequent operations if a return code of 12 or 16 is set. If an error is detected for an operator, SCAN mode is automatically set in effect; DFSORT is not called for subsequent operators, although checking ICETOOL statements for errors continues. STOP mode can be used to group dependent operators (that is, if an operation fails, do not process the remaining operators). STOP MODE is set in effect automatically at the start of the ICETOOL run. CONTINUE Continues with subsequent operations regardless of whether or not a return code of 12 or 16 is set. If an operator results in an error, processing continues for subsequent operators. CONTINUE mode can be used to group independent operators (that is, process each operator regardless of the success or failure of the others). SCAN ICETOOL statements are checked for errors, but DFSORT is not called. SCAN mode can be used to test ICETOOL statements for errors. Note: SCAN mode is set automatically if an error is detected while in STOP mode.

MODE Example
MODE SCAN RANGE ... UNIQUE ... MODE STOP VERIFY ... DISPLAY ... MODE CONTINUE COPY ... SORT ... STATS ...

SCAN mode: RANGE and UNIQUE are checked for statement errors, but DFSORT is not called. STOP mode: DISPLAY is dependent on VERIFY. If the return code for VERIFY is 12 or 16, SCAN mode is entered; DISPLAY is checked for statement errors, but DFSORT is not called.

Chapter 6. Using ICETOOL

547

MODE Operator
CONTINUE mode: COPY, SORT, and STATS are independent of each other. SORT is processed even if the return code for COPY is 12 or 16. STATS is processed even if the return code for COPY or SORT is 12 or 16. Note that the return codes for one group of operators does not affect the other groups of operators.

OCCUR Operator

OCCUR OCCURS

FROM(indd)

ON(p,m,f) ON(p,m,f,formatting) ON(p,m,HEX) ON(VLEN) ON(VLEN,formatting) ON(VALCNT) ON(VALCNT,formatting)

LIST(listdd)

TITLE(string)

PAGE

DATE DATE(abcd) DATENS(abc) YDDD(abc) YDDDNS(ab)

TIME TIME(abc) TIMENS(ab)

BLANK PLUS

HEADER(string1) HEADER(string1,string2) HEADER(string1,string2,string3) HEADER(NONE) NOHEADER

LINES(n)

INDENT(n)

BETWEEN(n)

ALLDUPS NODUPS HIGHER(x) LOWER(y) EQUAL(v)

VSAMTYPE(x)

WIDTH(n)

UZERO

TBETWEEN(n)

LISTSDB LISTNOSDB

Prints each unique value for specified numeric fields (including SMF, TOD, and ETOD date and time) or character fields, and how many times it occurs, in a

548

z/OS V1R10.0 DFSORT Application Programming Guide

OCCUR Operator
separate list data set. Simple or tailored reports can be produced. The values printed can be limited to those for which the value count meets specified criteria. From 1 to 10 fields can be specified, but the resulting list data set line length must not exceed the limit specified by the WIDTH operand or 2048 bytes if WIDTH is not specified. At least one ON(VLEN) or ON(p,m,f) field must be specified; all such ON fields specified are used to determine whether a record contains a unique value. A single list data set record is printed for each unique value. If ON(VALCNT) is specified, the value count (that is, the number of times the ON values occur) is printed in the list data set record along with the other ON values. Specifying formatting items or the PLUS or BLANK operand, which can compress the columns of output data, can enable you to include more fields in your report, up to a maximum of 10, if your line length is limited by the character width your printer or display supports. ALLDUPS, NODUPS, HIGHER(x), LOWER(y) or EQUAL(v) can be specified to limit the ON values printed to those for which the value count meets the specified criteria (for example, ALLDUPS for duplicate values only). The default criteria is HIGHER(0) resulting in the ON values being printed for each unique value. DFSORT is called to sort the indd data set to ICETOOLs E35 user exit. ICETOOL uses its E35 exit to print appropriate titles, headings and data in the list data set. You must not supply your own DFSORT MODS, INREC, OUTREC, SUM, or RECORD statement, because they override the DFSORT statements passed by ICETOOL for this operator. The DYNALLOC option is passed to DFSORT to ensure that work space is available for the sort. If your installation defaults for dynamic allocation are inappropriate for an OCCUR operator, you can take one of the following actions: 1. Override the DYNALLOC option using an OPTION control statement such as:
OPTION DYNALLOC=(,8)

in the DFSPARM data set. 2. Use SORTWKdd DD statements to override the use of dynamic allocation. Refer to SORTWKdd DD Statement on page 72 for details. Attention: Either of these actions affects the work data sets used for a UNIQUE operator, or for a SELECT or SPLICE operator for which USING(xxxx) is not specified. Tape work data sets cannot be used with ICETOOL.

Simple Report
You can produce a simple report by specifying just the required operands. For example, if you specify FROM and LIST operands, and ON operands for 10-byte character and 7-byte zoned decimal fields and the value count, the output in the list data set can be represented as follows:
(p,m,f) characters . . . (p,m,f) sddddddddddddddd . . . VALUE COUNT ddddddddddddddd . . .

Chapter 6. Using ICETOOL

549

OCCUR Operator
A control character occupies the first byte of each list data set record. Left-justified standard headings are printed at the top of each page to indicate the contents of each column, followed by a line for each record showing the characters and numbers in the fields of that record, and the count of occurrences (value count) of the specified values. The fields are printed in columns in the same order in which they are specified in the OCCUR statement. All fields are left-justified. For numeric fields, leading zeros are printed, a is used for the minus sign, and a + is used for the plus sign. For the value count, leading zeros are printed. By default, the first column of data starts immediately after the control character, and three blanks appear between columns. The INDENT operand can be used to change the number of blanks before the first column of data. The BETWEEN operand can be used to change the number of blanks between columns. The standard column widths are as follows: v Character data: the length of the character field or 20 bytes if the field length is less than 21 bytes v Numeric data: 16 bytes, or 32 bytes if the numeric field is BI or FI with a length greater than 4, PD with a length greater than 8, or ZD, CSF, FS, UFF or SFF with a length greater than 15. v Value count: 15 bytes HEADER operands can be used to change or suppress the headings. PLUS or BLANK operands can be used to change the format of numeric fields. PLUS, BLANK and HEADER operands can be used to change the width of the columns for numeric and character fields and the justification of headings and fields. The NOHEADER operand can be used to create list data sets containing only data records. Data sets created in this way can be processed further by other operators (for example, STATS or UNIQUE) using CH format for character values or FS format for numeric values (including the value count).

Tailored Report
You can tailor the output in the list data set using various operands that control title, date, time, page number, headings, lines per page and field formats. The optional operands can be used in many different combinations to produce a wide variety of report formats. For example, if you specify FROM, LIST, BLANK, TITLE, PAGE, DATE, TIME, and HEADER operands, and ON operands for 10-byte character and 7-byte zoned decimal fields and the value count, the output in the list data set looks as follows:
title header ---------characters . . . - p header -------sd . . . mm/dd/yy header -------------d . . . hh:mm:ss

A control character occupies the first byte of each list data set record. The title line is printed at the top of each page of the list data set. It contains the elements you specify (title string, page number, date and time) in the order in which you specify

550

z/OS V1R10.0 DFSORT Application Programming Guide

OCCUR Operator
them. By default, eight blanks appear between title elements. The TBETWEEN(n) operand can be used to change the number of blanks between title elements. A blank line is printed after the title line. Your specified headings (underlined) are printed after the title line on each page to indicate the contents of each column, followed by a line for each record showing the characters and numbers in the fields of that record. Your specified headings can be one, two or three lines. Headings for character fields are left-justified and headings for numeric fields are right-justified. The fields are printed in columns in the same order in which they are specified in the OCCUR statement. Character fields are left-justified and numeric fields are right justified. For numeric fields, leading zeros are suppressed, a - is used for the minus sign, and a blank is used for the plus sign (you can specify PLUS rather than BLANK if you want a + to be used for the plus sign). For the value count, leading zeros are suppressed. Formatting items can be used to change the appearance of individual numeric fields in the report with respect to separators, number of digits, decimal point, decimal places, signs, leading zeros, leading strings, floating strings, and trailing strings. Formatting items can also be used to insert leading or trailing strings for character fields. The column widths are dynamically adjusted according to the length of the headings and the maximum number of bytes needed for the character or numeric data.

Operand Descriptions
The operands described below can be specified in any order. FROM(indd) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. ON(p,m,f) Specifies the position, length, and format of a numeric or character field to be used for this operation. (p,m,f) is used for the standard column heading (see HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3), HEADER(NONE), and NOHEADER for alternative heading options). By default, three blanks appear between columns. You can change the space between columns with BETWEEN(n). p specifies the first byte of the field relative to the beginning of the input record. p is 1 for the first data byte of a fixed-length record and 5 for the first data byte of a variable-length record as illustrated below (RRRR represents the 4-byte record descriptor word):
Fixed-length record | Variable-length record | D | A | T | A | ... | | R | R | R | R | D | A | T | A | ... p= 1 2 3 4 | p= 1 2 3 4 5 6 7 8

m specifies the length of the field in bytes. A field must not extend beyond position 32752 or beyond the end of a record. The maximum length for a field depends on its format.

Chapter 6. Using ICETOOL

551

OCCUR Operator
f specifies the format of the field as follows:
Format Code BI FI PD ZD CH CSF or FS UFF SFF DT1 DT2 DT3 DC1 DC2 DC3 DE1 DE2 DE3 TM1 TM2 TM3 TM4 TC1 TC2 TC3 TC4 TE1 Length 1 to 8 bytes 1 to 8 bytes 1 to 16 bytes 1 to 31 bytes 1 to 1500 bytes 1 to 32 bytes (31 digit limit) 1 to 44 bytes (31 digit limit) 1 to 44 bytes (31 digit limit) 4 bytes 4 bytes 4 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes 4 bytes 4 bytes 4 bytes 4 bytes 8 bytes 8 bytes 8 bytes 8 bytes 8 bytes Description Unsigned binary Signed fixed-point Signed packed decimal Signed zoned decimal Character Signed numeric with optional leading floating sign Unsigned free form numeric Signed free form numeric SMF date interpreted as Zyyyymmdd SMF date interpreted as Zyyyymm SMF date interpreted as Zyyyyddd TOD date interpreted as Zyyyymmdd TOD date interpreted as Zyyyymm TOD date interpreted as Zyyyyddd ETOD date interpreted as Zyyyymmdd ETOD date interpreted as Zyyyymm ETOD date interpreted as Zyyyyddd SMF time interpreted as Zhhmmss SMF time interpreted as Zhhmm SMF time interpreted as Zhh SMF time interpreted as Zhhmmssxx TOD time interpreted as Zhhmmss TOD time interpreted as Zhhmm TOD time interpreted as Zhh TOD time interpreted as Zhhmmssxx ETOD time interpreted as Zhhmmss

552

z/OS V1R10.0 DFSORT Application Programming Guide

OCCUR Operator
Format Code TE2 TE3 TE4 Length 8 bytes 8 bytes 8 bytes Description ETOD time interpreted as Zhhmm ETOD time interpreted as Zhh ETOD time interpreted as Zhhmmssxx

Note: See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions.

For a CSF, FS, UFF, or SFF format field: v A maximum of 31 digits is allowed. If a value with more than 31 digits is found, ICETOOL issues an error message and terminates the operation. For a ZD or PD format field: v If a decimal value contains an invalid digit (A-F), ICETOOL identifies the bad value in a message and terminates the operation. v F, E, C, A, 8, 6, 4, 2, and 0 are treated as equivalent positive signs. Thus the zoned decimal values F2F3C1, F2F3F1 and 020301 are counted as only one unique value. v D, B, 9, 7, 5, 3, and 1 are treated as equivalent negative signs. Thus the zoned decimal values F2F3B0, F2F3D0, and 020310 are counted as only one unique value. The fields of records that do not meet the specified criteria are not checked for invalid digits (PD and ZD) or excessive digits (CSF, FS, UFF, and SFF). For a DT1, DT2 or DT3 format field: v An invalid SMF date can result in a data exception (0C7 ABEND) or an incorrect ZD date. v SMF date values are always treated as positive. For a DC1, DC2, DC3, DE1, DE2, or DE3 format field: v TOD and ETOD date values are always treated as positive. For a TM1, TM2, TM3 or TM4 format field: v An invalid SMF time can result in an incorrect ZD time. v SMF time values are always treated as positive. For a TC1, TC2, TC3, TC4, TE1, TE2, TE3, or TE4 format field: v TOD and ETOD time values are always treated as positive. ON(p,m,f,formatting) Specifies the position, length and format of a numeric or character field to be used for this operation and how the data for this field is to be formatted for printing. The BLANK operand is automatically in effect. See ON(p,m,f) for further details. formatting

Chapter 6. Using ICETOOL

553

OCCUR Operator
, mask Epattern Lstring Fstring Tstring LZ Ndd Udd

specifies formatting items that indicate how the data for this field is to be formatted for printing. Formatting items can be specified in any order, but each item can only be specified once. Any formatting item can be specified for a numeric field, but only Lstring and Tstring can be specified for a character field. The column width is dynamically adjusted to accommodate the maximum bytes to be inserted as a result of all formatting items specified. mask See the discussion of mask under ON(p,m,f,formatting) in DISPLAY Operator on page 502.

Epattern See the discussion of Epattern under ON(p,m,f,formatting) in DISPLAY Operator on page 502. Lstring See the discussion of Lstring under ON(p,m,f,formatting) in DISPLAY Operator on page 502. Fstring See the discussion of Fstring under ON(p,m,f,formatting) in DISPLAY Operator on page 502. Tstring See the discussion of Tstring under ON(p,m,f,formatting) in DISPLAY Operator on page 502. LZ See the discussion of LZ under ON(p,m,f,formatting) in DISPLAY Operator on page 502.

Ndd or Udd specifies the number of digits to be used for the numeric field. Ndd or Udd can be used to change the column width for numeric fields. dd specifies the number of digits and must be a two-digit number between 01 and 31. The default number of digits (d) for a numeric field is the maximum number of digits for that field. For example, d is 5 for ON(1,5,ZD). If you know that your numeric field requires less than d digits, you can use a lower number of digits (dd) instead by specifying Udd, thus reducing the column width if it is determined by d. For example, ON(1,5,ZD,U03) reduces d from 5 to 3. If you want your numeric field to be displayed with more than d digits, you can use a higher number of digits (dd) instead by specifying Ndd or Udd, thus increasing the column width if it is determined by d. For example, ON(1,5,ZD,U10) increases d from 5 to 10.

554

z/OS V1R10.0 DFSORT Application Programming Guide

OCCUR Operator
Either Ndd or Udd can be used to set d greater than the maximum for a numeric field, but only Udd can be used to set d less than the maximum for a numeric field. For Udd: dd is used for d. For example: v If ON(1,5,ZD) is specified, 5 digits (default for 5,ZD) are used. v If ON(1,5,ZD,U10) is specified, 10 digits (from U10) are used. v v v v If If If If ON(1,5,ZD,U03) is specified, 3 digits (from U03) are used. ON(1,16,FS) is specified, 16 digits (default for 16,FS) are used. ON(1,16,FS,U16) is specified, 16 digits (from U16) are used. ON(1,16,FS,U15) is specified, 15 digits (from U15) are used.

If you use Udd and a numeric value overflows dd digits, ICETOOL terminates the operation. You can prevent the overflow by specifying an appropriately higher dd value for Udd. For example, if ON(1,12,ZD,U09) results in overflow, you can use ON(1,12,ZD,U10) instead. If Epattern is specified, Udd is ignored, because the number of digits is determined from the pattern. For Ndd: If dd is greater than or equal to d, dd is used. If dd is less than d, d is used. For example: v If ON(1,5,ZD) is specified, 5 digits (default for 5,ZD) are used. v If ON(1,5,ZD,N10) is specified, 10 digits (from N10) are used. v If ON(1,5,ZD,N03) is specified, 5 digits (from 5,ZD) are used. If Epattern is specified, Ndd is ignored, because d is determined from the pattern. ON(p,m,HEX) Specifies the position and length of a character field to be used for this operation and printed in hexadecimal format (00-FF for each byte). (p,m,HEX) is used for the standard column heading (see HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3), HEADER(NONE), and NOHEADER for alternative heading options). See ON(p,m,f) for a discussion of p. m specifies the length of the field in bytes. A field must not extend beyond position 32752 or beyond the end of a record. A field can be 1 to 1000 bytes. ON(VLEN) Equivalent to specifying ON(1,2,BI); a two-byte binary field starting at position 1. For variable-length records, ON(VLEN) represents the record-length for each record. RECORD LENGTH is used for the standard column heading. See HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3), HEADER(NONE), and NOHEADER for alternative heading options. ON(VLEN,formatting) Equivalent to specifying ON(1,2,BI,formatting); a two-byte binary field starting at position 1, and how the data for this field is to be formatted for printing. The BLANK operand is automatically in effect. See ON(VLEN) for further details.
Chapter 6. Using ICETOOL

555

OCCUR Operator
formatting

, mask Epattern Lstring Fstring Tstring LZ Ndd Udd

specifies formatting items that indicate how the data for this field is to be formatted for printing. Formatting items can be specified in any order, but each item can only be specified once. The column width is dynamically adjusted to accommodate the maximum bytes to be inserted as a result of all formatting items specified. mask See the discussion of mask under ON(p,m,f,formatting) in DISPLAY Operator on page 502.

Epattern See the discussion of Epattern under ON(p,m,f,formatting) in DISPLAY Operator on page 502. Lstring See the discussion of Lstring under ON(p,m,f,formatting) in DISPLAY Operator on page 502. Fstring See the discussion of Fstring under ON(p,m,f,formatting) in DISPLAY Operator on page 502. Tstring See the discussion of Tstring under ON(p,m,f,formatting) in DISPLAY Operator on page 502. LZ See the discussion of LZ under ON(p,m,f,formatting) in DISPLAY Operator on page 502.

Ndd or Udd See the discussion of Ndd or Udd under ON(p,m,f,formatting) in OCCUR Operator on page 548. ON(VALCNT) Specifies that the number of occurrences for each unique value is to be printed. VALUE COUNT is used for the standard column heading (see HEADER(string1), HEADER(string1,string2), HEADER(string1,string2,string3), HEADER(NONE) and NOHEADER for alternative heading options). ON(VALCNT,formatting) Specifies that the number of occurrences for each unique value is to be printed, and how the value count is to be formatted for printing. The BLANK operand is automatically in effect. See ON(VALCNT) for further details.

556

z/OS V1R10.0 DFSORT Application Programming Guide

OCCUR Operator
formatting

, mask Epattern Lstring Fstring Tstring LZ Ndd Udd

specifies formatting items that indicate how the value count is to be formatted for printing. Formatting items can be specified in any order, but each item can only be specified once. The column width is dynamically adjusted to accommodate the maximum bytes to be inserted as a result of all formatting items specified. mask See the discussion of mask under ON(p,m,f,formatting) in DISPLAY Operator on page 502. Epattern specifies an edit pattern to be applied to the value count. The pattern (1 to 24 characters) must be enclosed in single apostrophes. Each 9 in the pattern (up to 15) is replaced by a corresponding digit from the numeric value. Characters other than 9 in the pattern appear as specified. To include a single apostrophe () in the pattern, specify two single apostrophes (). Fstring or a mask cannot be specified with Epattern. When Epattern is specified for the value count: v If the number of significant digits in a value count is less than the number of 9s in the pattern, 0s are filled in on the left. For example, 1234 is shown as 001234 with ON(VALCNT,E999999). v If the number of significant digits in a value count is greater than the number of 9s in the pattern, digits are truncated from the left. For example, 1234567 is shown as *4567* with ON(VALCNT,E*9999*). Lstring See the discussion of Lstring under ON(p,m,f,formatting) in DISPLAY Operator on page 502. Fstring See the discussion of Fstring under ON(p,m,f,formatting) in DISPLAY Operator on page 502. Tstring See the discussion of Tstring under ON(p,m,f,formatting) in DISPLAY Operator on page 502. LZ See the discussion of LZ under ON(p,m,f,formatting) in DISPLAY Operator on page 502.

Chapter 6. Using ICETOOL

557

OCCUR Operator
Ndd or Udd Specifies the number of digits to be used for the value count when determining the column width. dd specifies the number of digits and must be a two-digit number between 01 and 15. The default number of digits (d) for the value count is 15. If you know that your value counts require less than 15 digits, you can use a lower number of digits (dd) instead by specifying Ndd or Udd, thus reducing the column width if it is determined by d. For example, if ON(VALCNT,N06) or ON(VALCNT,U06) is specified, 6 digits (from N06 or U06) is used instead of 15 (default for value count). If you use Ndd or Udd and a value count overflows the number of digits used, ICETOOL terminates the operation. You can prevent the overflow by specifying an appropriately higher dd value for Ndd or Udd. For example, if ON(VALCNT,N05) results in overflow, you can use ON(VALCNT,N06) instead. If Epattern is specified, Ndd or Udd is ignored, because d is determined from the pattern. LIST(listdd) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. TITLE(string) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. PAGE See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. DATE See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. DATE(abcd) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. DATENS(abc) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. YDDD(abc) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. YDDDNS(ab) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. TIME See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. TIME(abc) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502.

558

z/OS V1R10.0 DFSORT Application Programming Guide

OCCUR Operator
TIMENS(ab) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. BLANK See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. PLUS See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. For ON(VALCNT), PLUS is treated as BLANK. HEADER(string1) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. HEADER(string1,string2) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. HEADER(string1,string2,string3) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. HEADER(NONE) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. NOHEADER See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. LINES(n) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. INDENT(n) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. BETWEEN(n) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. TBETWEEN(n) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. ALLDUPS Limits the ON values printed to those that occur more than once (that is, those with duplicate field values). The ON values are printed when value count > 1. ALLDUPS is equivalent to HIGHER(1). NODUPS Limits the ON values printed to those that occur only once (that is, those with no duplicate field values). The ON values are printed when value count = 1. NODUPS is equivalent to EQUAL(1) or LOWER(2).

Chapter 6. Using ICETOOL

559

OCCUR Operator
HIGHER(x) Limits the ON values printed to those that occur more than x times. The ON values are printed when value count > x. x must be specified as n or +n where n can be 1 to 15 decimal digits. LOWER(y) Limits the ON values printed to those that occur less than y times. The ON values are printed when value count < y. y must be specified as n or +n where n can be 1 to 15 decimal digits. EQUAL(v) Limits the ON values printed to those that occur v times. The ON values are printed when value count = v. v must be specified as n or +n where n can be 1 to 15 decimal digits. VSAMTYPE(x) See the discussion of this operand on the COPY statement in COPY Operator on page 491. WIDTH(n) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. UZERO Specifies that 0 and +0 are to be treated as unsigned zero values, that is, as the same value. With UZERO, 0 and +0 are treated as positive for ON processing. UZERO overrides the default of treating 0 and +0 as signed zero values, that is, as different values. Without UZERO, 0 is treated as negative and +0 is treated as positive for ON processing. LISTSDB or LISTNOSDB See the discussion of these operands on the DISPLAY statement in DISPLAY Operator on page 502.

OCCUR Examples
Although the OCCUR operators in the examples below could all be contained in a single ICETOOL job step, they are shown and discussed separately for clarity. See DISPLAY Operator on page 502 for additional examples of tailoring the report format.

Example 1
OCCUR FROM(SOURCE) LIST(VOLSERS) ON(40,6,CH) ON(VALCNT)

Prints, in the VOLSERS data set: v A heading line containing the standard headings v A data line for each unique ON(40,6,CH) value in the standard format containing: The characters from positions 40-45 of the SOURCE data set for the unique value The count of occurrences in the SOURCE data set of the unique value The VOLSERS output starts on a new page and looks as follows (the first 2 records are shown with illustrative values):

560

z/OS V1R10.0 DFSORT Application Programming Guide

OCCUR Operator

(40,6,CH) ABC001 ABC002 . . .

VALUE COUNT 000000000000025 000000000000011 . . .

The heading line appears at the top of each page.

Example 2
OCCUR FROM(IN) LIST(LIST1) TITLE( 3090 Distribution ) PAGE HEADER(Data Centers) ON(VALCNT) HEADER(State) ON(1,16,CH) HEADER(3090s) ON(25,3,PD) BLANK

Prints, in the LIST1 data set: v A title line containing the specified title and the page number v A heading line containing the specified underlined headings v A data line for each unique ON(1,16,CH) and ON(25,3,PD) value in the BLANK format containing: The count of occurrences in the IN data set of the unique value The characters from positions 1-16 of the IN data set for the unique value The packed decimal values from positions 25-27 of the IN data set for the unique value The LIST1 output starts on a new page and looks as follows (the first 2 records are shown with illustrative values):
3090 Distribution Data Centers --------------12 6 . . . - 1 3090s -----1 2 . . .

State ---------------Alabama Alabama . . .

The title line and underlined heading line appear at the top of each page.

Example 3
OCCURS FROM(FAILURES) LIST(CHECKIT) DATE TITLE(Possible System Intruders) PAGE TBETWEEN(3) HEADER(,,Userid) HEADER(Number of,Logon Failures,(More than 4)) ON(23,8,CH) ON(VALCNT) HIGHER(4) BLANK

Prints, in the CHECKIT data set: v A title line containing the date, the specified title, and the page number. Three blanks appear between the title elements as specified by the TBETWEEN(3) operand.

Chapter 6. Using ICETOOL

561

OCCUR Operator
v An underlined three-line heading. The three-line heading for the first ON field has blanks on line1 and line2 and Userid on line3. The heading for the second ON field has Number of on line1, Logon Failures on line2 and (More than 4) on line3. v A data line for each unique ON(23,8,CH) value for which there are more than 4 occurrences, in the BLANK format, containing: The characters from positions 23-30 of the FAILURES data set The count of occurrences of the characters from positions 23-30 of the FAILURES data set The CHECKIT output starts on a new page and looks as follows (the first 2 records are shown with illustrative values):
01/02/06 Possible System Intruders Number of Logon Failures (More than 4) --------------5 11 . . . - 1 -

Userid -------B7234510 D9853267

The title line and underlined three-line heading lines appear at the top of each page.

Example 4
OCCUR FROM(VARIN) LIST(ONCE) TITLE(Record lengths that occur only once) TIME(12:) DATE(DMY.) ON(VLEN) NODUPS BLANK

Prints, in the ONCE data set: v A title line containing the specified title and the time and date v A heading line containing the standard heading v A data line for each record length for which there is only one occurrence, in the BLANK format, containing the record length The ONCE output starts on a new page and looks as follows (the first 2 records are shown with illustrative values):
Record lengths that occur only once RECORD LENGTH 57 61 . . . 09:52:17 am 21.10.92

The title line and heading line appear at the top of each page.

562

z/OS V1R10.0 DFSORT Application Programming Guide

OCCUR Operator

Example 5
OCCUR FROM(BRANCH) LIST(CALLRPT)DATENS(4MD)TITLE(Yearly Branch Phone Call Counts)HEADER(Phone Number) ON(7,10,ZD,E(999)-999-9999)HEADER(Calls) ON(VALCNT,A1,N05)INDENT(5) BETWEEN(10)

Prints, in the CALLRPT data set: v A title line containing the date (without separators) and the specified title. v A heading line containing the specified underlined headings. v A data line for each unique ON(7,10,ZD) value containing: The zoned decimal value from positions 7-16 of the BRANCH data set printed as (ddd)-ddd-dddd according to the Epattern formatting item. The count of occurences of this value printed as dd,ddd according to the A1 and N05 formatting items. The report is indented by five blanks as specified by the INDENT(5) operand, and ten blanks appear between the columns as specified by the BETWEEN(10) operand. The CALLRPT output starts on a new page and looks as follows:
20020316 Phone Number -------------(037)-325-1807 (216)-721-5530 (218)-062-7214 Yearly Branch Phone Call Counts Calls ------3,125 2,087 872

RANGE Operator

RANGE FROM(indd)

ON(p,m,f) ON(VLEN)

HIGHER(x) LOWER(y) HIGHER(x) LOWER(y) EQUAL(v) NOTEQUAL(w)

VSAMTYPE(x)

Prints a message containing the count of values in a specified range for a specific numeric field. DFSORT is called to copy the indd data set to ICETOOLs E35 user exit. ICETOOL prints a message containing the range count as determined by its E35 user exit. The range can be specified as higher than x, lower than y, higher than x and lower than y, equal to v, or not equal to w, where x, y, v, and w are signed or unsigned decimal values. If the range is specified as higher than x and lower than y, it must
Chapter 6. Using ICETOOL

563

RANGE Operator
be a valid range (for example, higher than 5 and lower than 6 is not a valid range, because there is no integer value that satisfies the criteria). You must not supply your own DFSORT MODS, INREC, or OUTREC statement, because they would override the DFSORT statements passed by ICETOOL for this operator.

Operand Descriptions
The operands described below can be specified in any order. FROM(indd) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. ON(p,m,f) Specifies the position, length, and format of the numeric field to be used for this operation. p specifies the first byte of the field relative to the beginning of the input record. p is 1 for the first data byte of a fixed-length record and 5 for the first data byte of a variable-length record as illustrated below (RRRR represents the 4-byte record descriptor word):
Fixed-length record | Variable-length record | D | A | T | A | ... | | R | R | R | R | D | A | T | A | ... p= 1 2 3 4 | p= 1 2 3 4 5 6 7 8

m specifies the length of the field in bytes. A field must not extend beyond position 32752 or beyond the end of a record. The maximum length for a field depends on its format. f specifies the format of the field as follows:
Format Code BI FI PD ZD CSF or FS UFF SFF Length 1 to 8 bytes 1 to 8 bytes 1 to 16 bytes 1 to 31 bytes 1 to 32 bytes (31 digit limit) 1 to 44 bytes (31 digit limit) 1 to 44 bytes (31 digit limit) Description Unsigned binary Signed fixed-point Signed packed decimal Signed zoned decimal Signed numeric with optional leading floating sign Unsigned free form numeric Signed free form numeric

Note: See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions.

For a CSF, FS, UFF, or SFF format field: v A maximum of 31 digits is allowed. If a value with more than 31 digits is found, ICETOOL issues an error message and terminates the operation. For a ZD or PD format field: v If a decimal value contains an invalid digit (A-F), ICETOOL identifies the bad value in a message and terminates the operation. v A value is treated as positive if its sign is F, E, C, A, 8, 6, 4, 2, or 0. v A value is treated as negative if its sign is D, B, 9, 7, 5, 3, or 1. For a ZD, PD, CSF, FS, or SFF format field, a negative zero value is treated as a positive zero value.

564

z/OS V1R10.0 DFSORT Application Programming Guide

RANGE Operator
ON(VLEN) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. HIGHER(x) Values higher than x are counted as contained in the range. If only HIGHER(x) is specified, the range count is incremented when x < value. If LOWER(y) is also specified, the range count is incremented when x < value < y. x must be specified as n, +n, or n where n can be 1 to 31 decimal digits. LOWER(y) Values lower than y are counted as contained in the range. If only LOWER(y) is specified, the range count is incremented when value < y. If HIGHER(x) is also specified, the range count is incremented when x < value < y. y must be specified as n, +n, or n where n can be 1 to 31 decimal digits. EQUAL(v) Values equal to v are counted as contained in the range. The range count is incremented when v = value. v must be specified as n, +n, or n where n can be 1 to 31 decimal digits. NOTEQUAL(w) Values not equal to w are counted as contained in the range. The range count is incremented when w = value. w must be specified as n, +n, or n where n can be 1 to 31 decimal digits. VSAMTYPE(x) See the discussion of this operand on the COPY statement in COPY Operator on page 491.

RANGE Example
RANGE FROM(DATA1) ON(VLEN) HIGHER(10) RANGE FROM(DATA2) ON(31,18,ZD) LOWER(+123456789012345678) RANGE FROM(DATA3) ON(29001,4,FI) HIGHER(-10000) LOWER(27) RANGE FROM(DATA2) ON(45,3,PD) EQUAL(-999) RANGE FROM(DATA3) ON(40,1,BI) NOTEQUAL(199)

The first RANGE operator prints a message containing the count of binary values from positions 1-2 of the DATA1 data set that are higher than 10. The second RANGE operator prints a message containing the count of zoned decimal values from positions 31-48 of the DATA2 data set that are lower than 123456789012345678. The third RANGE operator prints a message containing the count of fixed-point values from positions 29 001-29 004 of the DATA3 data set that are higher than -10 000 but lower than 27. The fourth RANGE operator prints a message containing the count of packed decimal values from positions 45-47 of the DATA2 data set that are equal to -999. The fifth RANGE operator prints a message containing the count of binary values from position 40 of the DATA3 data set that are not equal to 199. This RANGE operator could be used to count the number of records that do not have G in position 40, because 199 (XC7) is the EBCDIC code for G. Alternatively, the COUNT operator could be used with OMIT COND=(40,1,CH,EQ,CG).
Chapter 6. Using ICETOOL

565

SELECT Operator

SELECT Operator

SELECT FROM(indd)

TO(outdd) DISCARD(savedd) TO(outdd) DISCARD(savedd)

ON(p,m,f) ON(VLEN)

ALLDUPS NODUPS HIGHER(x) LOWER(y) EQUAL(v) FIRST LAST FIRSTDUP LASTDUP

VSAMTYPE(x)

UZERO

USING(xxxx)

Selects records from an input data set based on meeting criteria for the number of times specified numeric or character field values occur. This makes it possible to only keep records with duplicate field values, only keep records with no duplicate field values, only keep records with field values that occur more than, less than, or exactly n times, or only keep the first or last record with each unique or duplicate field value. From 1 to 10 fields can be specified. At least one ON(VLEN) or ON(p,m,f) field must be specified; all such ON fields specified will be used to determine the value count (that is, the number of times the ON values occur) to be matched against the criteria. DISCARD(savedd) can be used to save the records that do not meet the criteria (that is, the discarded records), in the savedd data set. DISCARD(savedd) can be used with or without TO(outdd). DFSORT is called to sort the indd data set. ICETOOL uses its E35 exit to determine which records to include in the outdd data set or savedd data set. ICETOOL passes the EQUALS option to DFSORT to ensure that duplicates are kept in their original input order. The DFSORT control statements in xxxxCNTL are used if USING(xxxx) is specified. | Do not supply your own MODS, SUM or OUTREC statement. You can use comment statements. You can use INCLUDE, OMIT, INREC, OPTION, SORT, or OUTFIL statements providing you observe these rules: v You can use an INCLUDE or OMIT statement to remove input records before SELECT processing. v You can use an INREC statement to reformat input records before SELECT processing. You can use INRECs PARSE, BUILD (FIELDS), OVERLAY, IFTHEN, or IFOUTLEN functions. If your INREC statement changes the starting position

566

z/OS V1R10.0 DFSORT Application Programming Guide

SELECT Operator
of an ON field, you must specify the new starting position for that ON field. For example, if your input records have a CH key at positions 1-5 and you use an INREC statement like this:
INREC FIELDS=(25:1,50)

you must specify ON(25,5,CH) instead of ON(1,5,CH). v If you specify a SORT statement, you must specify each ON field as a p,m,f,A sort field and these sort fields must be in the same order as the ON fields. After these sort fields, you can specify additional p,m,f,A or p,m,f,D sort fields. The additional sort fields will be used for sorting, but not for selecting. For example, if you use a SELECT statement like this:
SELECT FROM(IN) TO(OUT) ON(21,5,CH) FIRST USING(CTL1)

you can use a SORT statement in CTL1CNTL like this:

SORT FIELDS=(21,5,CH,A,41,6,CH,D)

The records will be sorted by the 21,5,CH,A field and the 41,6,CH,D field, but only selected by the 21,5,CH field. This would allow you to select the highest 41,6,CH value for each 21,5,CH value. v If you specify TO(outdd) without DISCARD(savedd), you can further process the outdd records after SELECT processing using an OUTFIL statement like this:
OUTFIL FNAMES=outdd,...

or multiple OUTFIL statements like this:

OUTFIL FNAMES=outdd,... OUTFIL FNAMES=outdd1,... ...

v If you specify DISCARD(savedd) without TO(outdd), you can further process the savedd records after SELECT processing using one (and only one) OUTFIL statement like this:
OUTFIL FNAMES=savedd,...

v If you specify TO(outdd) and DISCARD(savedd), you can further process the outdd and savedd records after SELECT processing using two (and only two) OUTFIL statements like this:
OUTFIL FNAMES=outdd,... OUTFIL FNAMES=savedd,...

Both statements must be specified in the order shown with at least the FNAMES parameter. For example, to further modify only the DISCARD data set, you could use statements like this:
OUTFIL FNAMES=OUT OUTFIL FNAMES=SAVE,INCLUDE=(21,3,ZD,GT,+25)

ICETOOL requires extra storage for SELECT processing, over and above what is normally needed by ICETOOL and DFSORT, in order to save your records until it can determine whether or not they meet your specified criteria. In most cases, only a small amount of storage is needed and can be obtained (above 16MB virtual). However, for a FROM data set with a large record length and criteria requiring many saved records, a large amount of storage is needed. For example, with a record length of 32756 and HIGHER(99), over 3 MBs of storage is needed. If ICETOOL cannot get the storage it needs, it issues a message and terminates the SELECT operation. Increasing the REGION by the amount indicated in the message may allow ICETOOL to run successfully.

Chapter 6. Using ICETOOL

567

SELECT Operator
The DYNALLOC option is passed to DFSORT to ensure that work space is available for the sort. If your installation defaults for dynamic allocation are inappropriate for a SELECT operator, you can specify USING(xxxx) and take one of the following actions: 1. Override the DYNALLOC option using an OPTION control statement such as:
OPTION DYNALLOC=(,8)

in the xxxxCNTL data set. 2. Use xxxxWKdd DD statements to override the use of dynamic allocation. Refer to SORTWKdd DD Statement on page 72 for details. Tape work data sets cannot be used with ICETOOL.

Operand Descriptions
The operands described below can be specified in any order. FROM(indd) See the discussion of this operand on the COPY statement in COPY Operator on page 491. TO(outdd) Specifies the ddname of the output data set to which DFSORT will write the records it selects for the operation (that is, the records that meet the specified criteria). Thus, the outdd data set will contain the records selected by ALLDUPS, NODUPS, HIGHER(x), LOWER(y), EQUAL(v), FIRST, LAST, FIRSTDUP or LASTDUP. An outdd DD statement must be present and must define an output data set that conforms to the rules for DFSORTs SORTOUT data set (if the DISCARD operand is not specified) or OUTFIL data set (if the DISCARD operand is specified). TO and DISCARD can both be specified. If DISCARD is not specified, TO must be specified. If TO is not specified, DISCARD must be specified. The ddname specified in the TO operand must not be the same as the ddname specified in the FROM or DISCARD operand. Refer to JCL Restrictions on page 489 for more information. DISCARD(savedd) Specifies the ddname of the output data set to which DFSORT will write the records it does not select for this operation (that is, the records that do not meet the specified criteria). Thus, the savedd data set will contain the records discarded by ALLDUPS, NODUPS, HIGHER(x), LOWER(y), EQUAL(v), FIRST, LAST, FIRSTDUP or LASTDUP. A savedd DD statement must be present and must define an output data set that conforms to the rules for DFSORTs OUTFIL data set. TO and DISCARD can both be specified. If DISCARD is not specified, TO must be specified. If TO is not specified, DISCARD must be specified. The ddname specified in the DISCARD operand must not be the same as the ddname specified in the FROM or TO operand. Refer to JCL Restrictions on page 489 for more information. ON(p,m,f) Specifies the position, length, and format of a numeric or character field to be used for this operation.

568

z/OS V1R10.0 DFSORT Application Programming Guide

SELECT Operator
p specifies the first byte of the field relative to the beginning of the input record. p is 1 for the first data byte of a fixed-length record and 5 for the first data byte of a variable-length record as illustrated below (RRRR represents the 4-byte record descriptor word):
Fixed-length record | Variable-length record | D | A | T | A | ... | | R | R | R | R | D | A | T | A | ... p= 1 2 3 4 | p= 1 2 3 4 5 6 7 8

If INREC is specified, p must refer to the record as reformatted by INREC. m specifies the length of the field in bytes. A field must not extend beyond position 32752, or beyond the end of a record. If INREC is specified, a field must not extend beyond the end of the record as reformatted by INREC. The maximum length for a field depends on its format. f specifies the format of the field as shown below.
Format Code BI FI PD ZD CH CSF or FS UFF SFF Length 1 to 1500 bytes 1 to 256 bytes 1 to 16 bytes 1 to 31 bytes 1 to 1500 bytes 1 to 32 bytes 1 to 44 bytes 1 to 44 bytes Description Unsigned binary Signed fixed-point Signed packed decimal Signed zoned decimal Character Signed numeric with optional leading floating sign Unsigned free form numeric Signed free form numeric

Note: See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions.

For a ZD or PD format field: v F, E, C, A, 8, 6, 4, 2, and 0 are treated as equivalent positive signs. Thus the zoned decimal values F2F3C1, F2F3F1 and 020301 are counted as only one unique value. v D, B, 9, 7, 5, 3, and 1 are treated as equivalent negative signs. Thus the zoned decimal values F2F3B0, F2F3D0, and 020310 are counted as only one unique value. v Digits are not checked for validity. ON(VLEN) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. ALLDUPS Limits the records selected to those with ON values that occur more than once (value count > 1). You can use this operand to keep just those records with duplicate field values. ALLDUPS is equivalent to HIGHER(1). NODUPS Limits the records selected to those with ON values that occur only once (value count = 1). You can use this operand to keep just those records with no duplicate field values. NODUPS is equivalent to EQUAL(1) or LOWER(2).
Chapter 6. Using ICETOOL

569

SELECT Operator
HIGHER(x) Limits the records selected to those with ON values that occur more than x times (value count > x). You can use this operand to keep just those records with field values that occur more than x times. x must be specified as n or +n where n can be 0 to 99. LOWER(y) Limits the records selected to those with ON values that occur less than y times (value count < y). You can use this operand to keep just those records with field values that occur less than y times. y must be specified as n or +n where n can be 0 to 99. EQUAL(v) Limits the records selected to those with ON values that occur v times (value count = v). You can use this operand to keep just those records with field values that occur v times. v must be specified as n or +n where n can be 0 to 99. FIRST Limits the records selected to those with ON values that occur only once (value count = 1) and the first record of those with ON values that occur more than once (value count > 1). You can use this operand to keep just the first record for each unique field value. LAST Limits the records selected to those with ON values that occur only once (value count = 1) and the last record of those with ON values that occur more than once (value count > 1). You can use this operand to keep just the last record for each unique field value. FIRSTDUP Limits the records selected to the first record of those with ON values that occur more than once (value count > 1). You can use this operand to keep just the first record of those records with duplicate field values. LASTDUP Limits the records selected to the last record of those with ON values that occur more than once (value count > 1). You can use this operand to keep just the last record of those records with duplicate field values. VSAMTYPE(x) See the discussion of this operand on the COPY statement in COPY Operator on page 491. UZERO See the discussion of this operand on the OCCUR statement in OCCUR Operator on page 548. USING(xxxx) Specifies the first 4 characters of the ddname for the control statement data set to be used by DFSORT for this operation. xxxx must be four characters that are valid in a ddname of the form xxxxCNTL. xxxx must not be SYSx. If USING is specified, an xxxxCNTL DD statement must be present and the control statements in it: 1. Must conform to the rules for DFSORTs SORTCNTL data set. 2. Should generally be used only for an INCLUDE or OMIT statement, an INREC statement, a SORT statement, comment statements, or OUTFIL statements as described for SELECT Operator on page 566.

570

z/OS V1R10.0 DFSORT Application Programming Guide

SELECT Operator

SELECT Examples
Although the SELECT operators in the examples below could all be contained in a single ICETOOL job step, they are shown and discussed separately for clarity.

Example 1
SELECT FROM(INPUT) TO(DUPS) ON(11,8,CH) ON(30,44,CH) ALLDUPS

Sorts the INPUT data set to the DUPS data set, selecting only the records from INPUT with characters in positions 11-18 and characters in positions 30-73 that occur more than once (that is, only records with duplicate ON field values). The DUPS data set might look as follows (several records are shown for illustrative purposes): | | | | | | | | | |
USR002 DFSRT2 DFSRT5 DFSRT1 SYS003 DFSRT2 USR003 . . . BETTEN BETTEN BOENIG BOENIG BOENIG BOENIG BOENIG . . . 12 5 20 20 20 20 20 . . . DOC.EXAMPLES DOC.EXAMPLES MYDATA MYDATA MYDATA SORTST1.TEST SORTST1.TEST . . .

Example 2
SELECT FROM(INPUT) TO(ONLYONE) ON(23,3,FS) NODUPS

Sorts the INPUT data set to the ONLYONE data set, selecting only the records from INPUT with floating sign values in positions 23-25 that occur just once (that is, only records with no duplicate ON field values). The ONLYONE data set might look as follows (several records are shown for illustrative purposes): | | | | | | | |
DFSRT2 DFSRT1 USR002 SYS003 DFSRT2 . . . BOENIG PACKER BETTEN YAEGER CORNELL . . . 5 8 12 32 108 . . . DOC.EXAMPLES ICETOOL.SMF.RUNS DOC.EXAMPLES ICETOOL.TEST.CASES FS.TEST.CASES . . .

Example 3
SELECT FROM(FAILURES) TO(CHECKOUT) ON(28,8,CH) ON(1,5,CH) HIGHER(3)

Sorts the FAILURES data set to the CHECKOUT data set, selecting only the records from FAILURES with characters in positions 28-35 and characters in positions 1-5 that occur more than three times (that is only records with four or more duplicate ON field values). The CHECKOUT data set might look as follows (several records are shown for illustrative purposes):
03/12/04 03/12/04 03/12/04 03/12/04 03/06/04 03/06/04 08:36:59 09:27:32 09:03:18 08:56:13 15:12:01 14:57:00 A3275647 A3275647 A3275647 A3275647 C3275647 C3275647
Chapter 6. Using ICETOOL

571

SELECT Operator
03/06/04 03/06/04 03/06/04 . . . 15:43:19 16:06:39 15:22:08 . . . C3275647 C3275647 C3275647 . . .

Example 4
SELECT FROM(BOOKS) TO(PUBLISHR) ON(29,10,CH) FIRST

Sorts the BOOKS data set to the PUBLISHR data set, selecting only the records from BOOKS with characters in positions 29-38 that occur only once and the first record of those with characters in positions 29-38 that occur more than once (that is, one record for each unique ON field value). The PUBLISHR data set might look as follows (several records are shown for illustrative purposes):
Banana Slugs I Have Known Toads on Parade Pets Around the World . . . Brent Cooper Davis . . . Animals Animals Animals . . .

Example 5
SELECT FROM(BOOKS) TO(PUBLISHR) ON(29,10,CH) FIRST DISCARD(SAVEREST)

This example creates the same PUBLISHR data set as Example 4. In addition, it creates a SAVEREST data set that contains all of the records not written to the PUBLISHR data set. The SAVEREST data set might look as follows (several records are shown for illustrative purposes):
How to Talk to Your Amoeba Brent What Buzzards Want Davis Birds of Costa Rica Davis . . . Animals Animals Animals

Example 6
SELECT FROM(MASTPULL) TO(MATCH) ON(5,8,CH) FIRSTDUP

This example shows how you can use a list of account numbers in a pull data set to only select records with those account numbers from a master data set. The MASTPULL DD would have the master data set and pull data set concatenated together (in that order). The SELECT operator sorts the concatenated data sets and selects only the first record of those with characters in positions 5-12 that occur more than once (that is, one record for each duplicate ON field value). Because the master data set is first in the concatenation, the selected records will come from the master data set. If the master data set looked like this:
A52 N92 B12 J73 Q28 RB172832 MX328126 LB018725 AB007231 SP973004 2001/03/15 2001/01/27 2000/12/28 2001/02/13 2000/11/19

572

z/OS V1R10.0 DFSORT Application Programming Guide

SELECT Operator
and the pull data set looked like this:
AB007231 RS859276 QN005001 MX328126

the MATCH data set would look like this:

J73 AB007231 2001/02/13 N92 MX328126 2001/01/27

Note: This example assumes that there are not any duplicate account numbers in either the master or pull data sets. If that is not true, you can use SELECT with FIRST or LAST, for the appropriate data set, to make it true. For example, if your master data set has duplicate account numbers and you want to select the first account number from the master data set for each account number in the pull data set, you could use the following statements:
SELECT FROM(MASTER) TO(TEMP) ON(5,8,CH) FIRST SELECT FROM(TEMPPULL) TO(MATCH) ON(5,8,CH) FIRSTDUP

The TEMPPULL DD would have the temporary data set and pull data set concatenated together (in that order).

Example 7
SELECT FROM(INPUT) TO(ONLYONE) ON(23,3,FS) NODUPS USING(CTL1)

This example shows how you can use USING(xxxx) to supply an OUTFIL statement to modify the TO data set. SELECT chooses the same output records as for Example 2 on page 571, but an OUTFIL statement is used to further modify those records for output to the ONLYONE data set. The CTL1CNTL data set contains:
OUTFIL FNAMES=ONLYONE, REMOVECC, INCLUDE=(23,3,FS,LT,100), OUTREC=(1:1,7,8:C|,11:11,7,19:C|,23:23,3,FS,M11, 27:C|,30:30,15), TRAILER1=(/,TOTAL= ,TOT=(23,3,FS,M11,LENGTH=6))

and the ONLYONE data set might look as follows:

DFSRT2 DFSRT1 USR002 SYS003 | | | | EISSLER PACKER EISSLER YAEGER | | | | 005 008 012 032 | | | | DOC.EXAMPLES ICETOOL.SMF.RUN DOC.EXAMPLES ICETOOL.TEST.CA

TOTAL= 000057

Example 8
This example shows how you can use USING(xxxx) to supply an OMIT statement to remove certain input records and an INREC statement to reformat certain input records before SELECT processing begins.
SELECT FROM(INB) TO(OUTB) ON(8,10,CH) FIRSTDUP USING(BIRD)

Lets say the INB data set looks like this:

TYPE1 CROWS TYPE1 PIGEONS TYPE1 HAWKS
Chapter 6. Using ICETOOL

573

SELECT Operator
TYPE1 TYPE1 TYPE1 TYPE1 TYPE2 TYPE2 TYPE2 TYPE2 TYPE3 TYPE3 ROBINS SPARROWS CHICKENS RAVENS PIGEONS ROBINS HAWKS TERNS EAGLES STARLINGS

We want to remove the TYPE3 records and then select one record for each type of bird that appears in both a TYPE1 and a TYPE2 record. We could use the following control statements in BIRDCNTL:
* Remove the TYPE3 records. OMIT COND=(1,5,CH,EQ,CTYPE3) * Reformat the TYPE2 records to place the bird name in * same place as in the TYPE1 records so we can match them. INREC IFTHEN=(WHEN=(1,5,CH,EQ,CTYPE2), BUILD=(8:18,10))

The OUTB data set would look like this:

TYPE1 HAWKS TYPE1 PIGEONS TYPE1 ROBINS

Example 9
This example shows how you can use USING(xxxx) to supply a SORT statement to alter the records that are selected.
SELECT FROM(IN) TO(OUT) ON(1,5,CH) FIRST USING(CTL1)

Lets say the IN data set looks like this:

FRANK FRANK FRANK FRANK VICKY VICKY VICKY VICKY 00015 00012 00018 00005 00022 00028 00002 00015

We want to select the record with each name that has the highest count. If we just used ON(1,5,CH) without any CTL1CNTL statements, wed get the first record without regard to the count. The OUT data set would look like this:
FRANK 00015 VICKY 00022

To get the record with the highest count, we can use the following SORT statement in CTL1CNTL:
SORT FIELDS=(1,5,CH,A,7,5,ZD,D)

The records will be sorted in ascending order on the name field, and in descending order on the count field. By sorting descending on the count, we ensure that the record with the highest count is the first record for each name. Thus, when ON(1,5,CH) selects the first record, it will be the one with the highest count. The OUT data set will look like this:
FRANK 00018 VICKY 00028

574

z/OS V1R10.0 DFSORT Application Programming Guide

SORT Operator

SORT Operator

SORT FROM(indd) USING(xxxx) , TO( outdd ) VSAMTYPE(x)

LOCALE(name) LOCALE(CURRENT) LOCALE(NONE)

SERIAL

Sorts a data set to one or more output data sets. DFSORT is called to sort the indd data set to the outdd data sets using the DFSORT control statements in xxxxCNTL. You must supply a DFSORT SORT statement in the xxxxCNTL data set to indicate the control fields for the sort. You can use additional DFSORT statements in the xxxxCNTL data set to sort a subset of the input records (INCLUDE or OMIT statement; SKIPREC and STOPAFT options; OUTFIL INCLUDE, OMIT, SAVE, STARTREC, ENDREC, SAMPLE, SPLIT, SPLITBY, and SPLIT1R operands; user exit routines), reformat records for output (INREC, OUTREC, and OUTFIL statements, user exit routines), and so on. The active locales collating rules affect SORT processing as explained in SORT Control Statement on page 398. If an INCLUDE or OMIT statement or an OUTFIL INCLUDE or OMIT operand is specified in the xxxxCNTL data set, the active locales collating rules affect INCLUDE and OMIT processing as explained in the Cultural Environment Considerations discussion in INCLUDE Control Statement on page 98. The DYNALLOC option is passed to DFSORT to ensure that work space is available for the sort. If your installation defaults for dynamic allocation are inappropriate for a SORT operator, you can take one of the following actions: 1. Override the DYNALLOC option using an OPTION control statement such as:
OPTION DYNALLOC=(,8)

in the xxxxCNTL data set in conjunction with the USING(xxxx) operand. 2. Use xxxxWKdd DD statements to override the use of dynamic allocation in conjunction with the USING(xxxx) operand. Refer to SORTWKdd DD Statement on page 72 for details. Tape work data sets cannot be used with ICETOOL.

Operand Descriptions
The operands described below can be specified in any order. FROM(indd) See the discussion of this operand on the COPY statement in COPY Operator on page 491. USING(xxxx) Specifies the first 4 characters of the ddname for the control statement data set
Chapter 6. Using ICETOOL

575

SORT Operator
to be used by DFSORT for this operation. xxxx must be four characters that are valid in a ddname of the form xxxxCNTL. xxxx must not be SYSx. An xxxxCNTL DD statement must be present, and the control statements in it must conform to the rules for DFSORTs SORTCNTL data set. The xxxxCNTL data set must contain a SORT statement. If TO is not specified, the xxxxCNTL data set must also contain either one or more OUTFIL statements or a MODS statement for an E35 routine that disposes of all records. Other statements are optional. If you want to override dynamic allocation of work data sets for this operation, you can use xxxxWKdd DD statements for that purpose. Refer to JCL Restrictions on page 489 for more information regarding the selection of ddnames. TO(outdd,...) Specifies the ddnames of the output data sets to be written by DFSORT for this operation. From 1 to 10 outdd names can be specified. An outdd DD statement must be present for each outdd name specified. If a single outdd data set is specified, DFSORT is called once to sort the indd data set to the outdd data set using SORTOUT processing; the outdd data set must conform to the rules for DFSORTs SORTOUT data set. If multiple outdd data sets are specified and SERIAL is not specified, DFSORT is called once to sort the indd data set to the outdd data sets using OUTFIL processing; the outdd data sets must conform to the rules for DFSORTs OUTFIL data sets. A ddname specified in the FROM operand must not also be specified in the TO operand. Refer to JCL Restrictions on page 489 for more information regarding the selection of ddnames. VSAMTYPE(x) See the discussion of this operand on the COPY statement in COPY Operator on page 491. LOCALE(name) See the discussion of this operand on the COPY statement in COPY Operator on page 491. LOCALE(CURRENT) See the discussion of this operand on the COPY statement in COPY Operator on page 491. LOCALE(NONE) See the discussion of this operand on the COPY statement in COPY Operator on page 491. SERIAL Specifies that OUTFIL processing is not to be used when multiple outdd data sets are specified. DFSORT is called multiple times and uses SORTOUT processing; the outdd data sets must conform to the rules for DFSORTs SORTOUT data set. SERIAL is not recommended because the use of serial processing (that is, multiple calls to DFSORT) instead of OUTFIL processing can degrade performance and imposes certain restrictions as detailed below. SERIAL is ignored if a single outdd data set is specified. DFSORT is called to sort the indd data set to the first outdd data set using the DFSORT control statements in the xxxxCNTL data set. If the sort operation is successful, DFSORT is called as many times as necessary to copy the first

576

z/OS V1R10.0 DFSORT Application Programming Guide

SORT Operator
outdd data set to the second and subsequent outdd data sets. Therefore, for maximum efficiency, use a disk data set as the first in a list of outdd data sets on both disk and tape. If more than one outdd data set is specified, DFSORT must be able to read the first outdd data set after it is written in order to copy it to the other outdd data sets. Do not use a SYSOUT or DUMMY data set as the first in a list of outdd data sets because: v If the first data set is SYSOUT, DFSORT abends when it tries to copy the SYSOUT data set to the second outdd data set. v If the first data set is DUMMY, DFSORT copies the empty DUMMY data set to the other outdd data sets (that is, all of the resulting outdd data sets are empty).

SORT Examples
Although the SORT operators in the examples below could all be contained in a single ICETOOL job step, they are shown and discussed separately for clarity.

Example 1
* Method 1 SORT FROM(MASTER) TO(PRINT,TAPE,DISK) USING(ABCD) * Method 2 SORT FROM(MASTER) TO(DISK,TAPE,PRINT) USING(ABCD) SERIAL

This example shows two different methods for creating multiple sorted output data sets. Assume that the ABCDCNTL data set contains:
SORT FIELDS=(15,20,CH,A,1,5,PD,D)

Method 1 requires one call to DFSORT, one pass over the input data set, and allows the output data sets to be specified in any order. The SORT operator sorts all records from the MASTER data set to the PRINT (SYSOUT), TAPE, and DISK data sets, using the SORT statement in the ABCDCNTL data set and OUTFIL processing. Method 2 requires three calls to DFSORT, three passes over the input data set, and imposes the restriction that the SYSOUT data set must not be the first TO data set. The SORT operator sorts all records from the MASTER data set to the DISK data set, using the SORT statement in the ABCDCNTL data set, and then copies the resulting DISK data set to the TAPE and PRINT (SYSOUT) data sets. Because the first TO data set is processed three times (written, read, read), placing the DISK data set first is more efficient than placing the TAPE data set first. PRINT must not be the first in the TO list because a SYSOUT data set cannot be read.

Example 2
* Method 1 SORT FROM(IN) TO(DEPT1) USING(DPT1) SORT FROM(IN) TO(DEPT2) USING(DPT2) SORT FROM(IN) TO(DEPT3) USING(DPT3) * Method 2 SORT FROM(IN) USING(ALL3)

This example shows two different methods for creating sorted subsets of an input data set. Assume that: v The DPT1CNTL data set contains:
SORT FIELDS=(51,2,BI,A,18,5,CH,A,58,4,BI,A) INCLUDE COND=(5,3,CH,EQ,CD01)

v The DPT2CNTL data set contains:

Chapter 6. Using ICETOOL

577

SORT Operator
SORT FIELDS=(51,2,BI,A,18,5,CH,A,58,4,BI,A) INCLUDE COND=(5,3,CH,EQ,CD02)

v The DPT3CNTL data set contains:

SORT FIELDS=(51,2,BI,A,18,5,CH,A,58,4,BI,A) INCLUDE COND=(5,3,CH,EQ,CD03)

v The ALL3CNTL data set contains:

SORT FIELDS=(51,2,BI,A,18,5,CH,A,58,4,BI,A) OUTFIL FNAMES=DEPT1,INCLUDE=(5,3,CH,EQ,CD01) OUTFIL FNAMES=DEPT2,INCLUDE=(5,3,CH,EQ,CD02) OUTFIL FNAMES=DEPT3,INCLUDE=(5,3,CH,EQ,CD03)

Method 1 requires three calls to DFSORT and three passes over the input data set: v The first SORT operator sorts the records from the IN data set that contain D01 in positions 5-7 to the DEPT1 data set v The second COPY operator sorts the records from the IN data set that contain D02 in positions 5-7 to the DEPT2 data set v The third COPY operator sorts the records from the IN data set that contain D03 in positions 5-7 to the DEPT3 data set. Method 2 accomplishes the same result as method 1 but, because it uses OUTFIL statements instead of TO operands, requires only one call to DFSORT and one pass over the input data set.

Example 3
SORT FROM(IN1) TO(FRANCE) USING(SRT1) LOCALE(FR_FR) SORT FROM(IN1) TO(CANADA) USING(SRT1) LOCALE(FR_CA) SORT FROM(IN1) TO(BELGIUM) USING(SRT1) LOCALE(FR_BE)

This example shows how sorted data for three different countries can be produced. Assume that the SRT1CNTL data set contains:
SORT FIELDS=(5,20,CH,A,31,15,CH,A,1,4,FI,D,63,10,CH,D)

The first SORT operator sorts all records from the IN1 data set to the FRANCE data set, using the SORT statement in the SRT1CNTL data set. The character (CH) control fields are sorted according to the collating rules defined in locale FR_FR (French language for France). The second SORT operator sorts all records from the IN1 data set to the CANADA data set, using the SORT statement in the SRT1CNTL data set. The character (CH) control fields are sorted according to the collating rules defined in locale FR_CA (French language for Canada). The third SORT operator sorts all records from the IN1 data set to the BELGIUM data set, using the SORT statement in the SRT1CNTL data set. The character (CH) control fields are sorted according to the collating rules defined in locale FR_BE (French language for Belgium).

578

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator

SPLICE Operator

SPLICE FROM(indd) TO(outdd)

ON(p,m,f)

WITH(p,m)

WITHEACH WITHALL

KEEPNODUPS

KEEPBASE

USING(xxxx)

VSAMTYPE(x)

UZERO

VLENMAX VLENOVLY

Splices together specified fields from records with matching numeric or character field values (that is, duplicate values), but different information. This makes it possible to join fields from different types of input records to create an output record with information from two or more records. Typically, you will want to reformat the records from two or more data sets to temporary data sets, and concatenate those temporary data sets together as input to the SPLICE operator. SPLICE Examples on page 587 shows some techniques for splicing records from different data sets together in a variety of ways to perform various file join and match operations. By default (when WITHALL and WITHEACH are not specified), one spliced record is created for each set of duplicates. The first duplicate is spliced with specified fields from the last duplicate. The first duplicate is treated as a base record. The last duplicate is treated as an overlay record. Specified fields from the overlay record are overlaid on to the base record. Thus, the output record consists of fields from the base (first) record intermixed with specified fields from the overlay (last) record. The records to be spliced can originate from two different input data sets. From 1 to 10 ON fields can be used for the fields to match on. At least one ON(p,m,f) field must be specified; all such ON fields specified will be used to determine the matching records to be spliced together. From 1 to 50 WITH fields can be used to specify the fields to be overlaid on the base record from the overlay record. At least one WITH(p,m) field must be specified; all such WITH fields specified will be overlaid on to the base record. All other fields in the base record will be kept unchanged.

Chapter 6. Using ICETOOL

579

SPLICE Operator
To illustrate the splicing process, if we had the following two input records with the base fields, ON field and WITH fields as shown:
BASE1 ON1 ON1 BASE2 WITHA BASE3 BASE4 GGGGG WITHB

the resulting spliced output record would be:

BASE1 ON1 BASE2 WITHA BASE3 BASE4 WITHB

For variable-length records, by default (without VLENMAX or VLENOVLY), the spliced record has the same length as the base record, and WITH fields from the overlay record that are beyond the end of the base record do not appear in the spliced record. For example, if we had the following two records with the lengths (in the RDW), ON field and WITH fields as shown:
25 | ON1 BASE1 BASE2 35 | ON1 WITH1 WITH2

the resulting spliced output record would be:

25 | ON1 BASE1 WITH1 BASE2

The WITH2 field is beyond the end of the base record, so it is not spliced. However, if you specify VLENMAX, the spliced record is given the larger of the base record length or overlay record length. If we specify VLENOVLY, the spliced record is given the overlay record length. In either case, if the overlay record length is larger, bytes in the extended spliced record that are not overlaid are filled in with blanks. The resulting spliced output record with either VLENMAX or VLENOVLY would be:
35 ON1 BASE1 WITH1 BASE2 WITH2

You can use VLENMAX when you want the spliced record to have the maximum length of the base or overlay record. You can use VLENOVLY when you want the spliced record to have the length of the overlay record, regardless of whether its longer or shorter than the base record. Without VLENMAX or VLENOVLY, the spliced record has the length of the base record regardless of whether its longer or shorter than the overlay record. For fixed-length records, the length of the base, overlay and spliced records are all the same. Thus, VLENOVLY and VLENMAX have no meaning for fixed-length records and are ignored. WITHEACH can be used to create one spliced record for each set of duplicates. The first duplicate is spliced with one specified field from each subsequent duplicate. The first duplicate is treated as a base record. Each subsequent duplicate is treated as an overlay record. The specified field from each overlay record is overlaid on to the base record. Thus, the output record consists of fields from the base record intermixed with a specified field from each overlay record. Note that the specified field from an overlay record can actually consist of multiple fields from the record that have previously been reformatted into one contiguous field. The records to be spliced can originate from multiple input data sets

580

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator
To illustrate the splicing process when WITHEACH is specified, if we had the following four records with the base fields, ON field and WITH fields as shown:
BASE1 ON1 ON1 ON1 ON1 BASE2 WITHA WITHB WITHC

The resulting spliced output record would be:

BASE1 ON1 BASE2 WITHA WITHB WITHC

For variable-length records, by default (without VLENMAX), the spliced record has the same length as the base record. For example, with WITHEACH, if we had the following four records with the lengths (in the RDW), ON field and WITH fields as shown:
30 25 50 40 | BASE1 ON1 | ON1 | ON1 | ON1 BASE2 WITHA WITHB WITHC

the resulting spliced output records would be:

30 | BASE1 ON1 WITHA BASE2

The WITHB and WITHC fields are beyond the end of the base record, so they are not spliced. However, if you specify VLENMAX, the spliced record is given the largest of the base record length or overlay record lengths. If the largest overlay record length is larger than the base record length, bytes in the extended spliced record that are not overlaid are filled in with blanks. The resulting spliced output record with WITHEACH and VLENMAX would be:
50 | BASE1 ON1 WITHA BASE2 WITHC WITHB

VLENOVLY cannot be specified with WITHEACH. WITHALL can be used to create multiple spliced records for each set of duplicates. The first duplicate is spliced with the specified fields from the second duplicate. Then the first duplicate is spliced with the specified fields from the third duplicate, and so on. The first duplicate is treated as a base record. Each subsequent duplicate is treated as an overlay record. The specified fields from each overlay record are overlaid on to the base record. Thus, the output records consist of fields from the base record intermixed with specified fields from the overlay records. The records to be spliced can originate from multiple input data sets. To illustrate the splicing process when WITHALL is specified, if we had the following four records with the base fields, ON field and WITH fields as shown:
BASE1 ON1 ON1 ON1 ON1 BASE2 WITHA WITHC WITHE BASE3 BASE4 GGGGG WITHB WITHF

The resulting three spliced output records would be:

BASE1 ON1 BASE1 ON1 BASE1 ON1 BASE2 BASE2 BASE2 WITHA WITHC WITHE BASE3 BASE4 WITHB BASE3 BASE4 BASE3 BASE4 WITHF
Chapter 6. Using ICETOOL

581

SPLICE Operator
Note that without WITHALL, the resulting single spliced output record would be:
BASE1 ON1 BASE2 WITHE BASE3 BASE4 WITHF

For variable-length records, by default (without VLENMAX or VLENOVLY), the spliced record has the same length as the base record, and WITH fields from the overlay record that are beyond the end of the base record do not appear in the spliced record. For example, with WITHALL, if we had the following four records with the lengths (in the RDW), ON field and WITH fields as shown:
30 25 50 40 | BASE1 ON1 | ON1 | ON1 | ON1 BASE2 WITHA WITHB WITHE WITHC WITHF WITHD

the resulting three spliced output records would be:

30 | BASE1 ON1 WITHA BASE2 30 | BASE1 ON1 WITHB BASE2 30 | BASE1 ON1 WITHE BASE2

The WITHC, WITHD and WITHF fields are beyond the end of the base record, so they are not spliced. However, if you specify VLENMAX, the spliced record is given the larger of the base record length or overlay record length. If we specify VLENOVLY, the spliced record is given the overlay record length. In either case, if the overlay record length is larger, bytes in the extended spliced record that are not overlaid are filled in with blanks. The resulting three spliced output records with WITHALL and VLENMAX would be:
30 | BASE1 ON1 50 | BASE1 ON1 40 | BASE1 ON1 WITHA BASE2 WITHB BASE2 WITHE BASE2 WITHC WITHF WITHD

The resulting three spliced output records with WITHALL and VLENOVLY would be:
25 | BASE1 ON1 50 | BASE1 ON1 40 | BASE1 ON1 WITHA WITHB BASE2 WITHE BASE2 WITHC WITHF WITHD

KEEPNODUPS can be used to keep the non-duplicate records as well as the spliced records. The non-duplicate records will be unchanged. To illustrate the splicing process when KEEPNODUPS is specified, if we had the following six records with the base fields, ON fields and WITH fields as shown:
UNIQA BASEA DUPAA UNIQB BASEB DUPBB ONA ONB ONB ONC OND OND

WITHA WITHB

The two unique records (ONA and OND) would be kept along with the two spliced records (ONB and OND). The resulting four unspliced and spliced output records would be:
UNIQA BASEA UNIQB BASEB ONA ONB ONC OND WITHA WITHB

Note that without KEEPNODUPS, the two unique records (ONA and ONC) would not be kept. The resulting two spliced output records would be:

582

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator
BASEA ONB BASEB OND WITHA WITHB

KEEPBASE can be used to keep the base records (first duplicate) as well as the spliced records. The base records will be unchanged. To illustrate the splicing process when KEEPBASE is specified, if we had the following six records with the base fields, ON fields and WITH fields as shown:
UNIQA BASEA DUPAA UNIQB BASEB DUPBB ONA ONB ONB ONC OND OND

WITHA WITHB

The two base records with duplicates (first ONB record and first OND record) would be kept along with the two spliced records (ONB and OND). The resulting four unspliced and spliced output records would be:
BASEA BASEA BASEB BASEB ONB ONB OND OND WITHA WITHB

Note that without KEEPBASE, the two base records with duplicates (first ONB record and first OND record) would not be kept. The resulting two spliced output records would be:
BASEA ONB BASEB OND WITHA WITHB

If we used KEEPNODUPS and KEEPBASE with the original six records, the resulting six unspliced and spliced output records would be:
UNIQA BASEA BASEA UNIQB BASEB BASEB ONA ONB ONB ONC OND OND

WITHA WITHB

DFSORT is called to sort the indd data set. ICETOOL uses its E35 exit to determine which records to splice and include in the outdd data set. ICETOOL passes the EQUALS option to DFSORT to ensure that duplicates are kept in their original input order. The DFSORT control statements in xxxxCNTL are used if USING(xxxx) is specified. | Do not supply your own MODS, SUM, OUTREC, or SORT statement. You can use comment statements. You can use INCLUDE, OMIT, INREC, OPTION, and OUTFIL statements providing you observe these rules: v You can use an INCLUDE or OMIT statement to remove input records before SPLICE processing. v You can use an INREC statement to reformat input records before SPLICE processing; the base and overlay records are reformatted according to the INREC statement. You can use INRECs PARSE, BUILD (FIELDS), OVERLAY, IFTHEN, or IFOUTLEN functions. If your INREC statement changes the starting position of an ON field or WITH field, you must specify the new starting position for

Chapter 6. Using ICETOOL

583

SPLICE Operator
that ON field or WITH field. For example, if your input records have a CH key at positions 1-5 and a WITH field at 6-8 and you use an INREC statement like this:
INREC FIELDS=(31:1,50)

you must specify ON(31,5,CH) instead of ON(1,5,CH) and WITH(36,3) instead of WITH(6,3). v You can further process the outdd records associated with TO(outdd) after SPLICE processing using an OUTFIL statement like this:
OUTFIL FNAMES=outdd,...

or multiple OUTFIL statements like this:

OUTFIL FNAMES=outdd,... OUTFIL FNAMES=outdd1,... ...

For example, with TO(OUT1) you could further modify the OUT1 records after they have been spliced, with a statement like this:
OUTFIL FNAMES=OUT1,FTOV,VLTRIM=X40

The DYNALLOC option is passed to DFSORT to ensure that work space is available for the sort. If your installation defaults for dynamic allocation are inappropriate for a SPLICE operator, you can specify USING(xxxx) and take one of the following actions: 1. Override the DYNALLOC option using an OPTION control statement such as:
OPTION DYNALLOC=(,8)

in the xxxxCNTL data set. 2. Use xxxxWKdd DD statements to override the use of dynamic allocation. Refer to SORTWKdd DD Statement on page 72 for details. Tape work data sets cannot be used with ICETOOL.

Operand Descriptions
FROM(indd) See the discussion of this operand on the COPY statement in COPY Operator on page 491. TO(outdd) Specifies the ddname of the output data set to which DFSORT will write the records it produces for the operation (that is, the spliced records, the non-duplicate records if KEEPNODUPS is specified, and the base records if KEEPBASE is specified). An outdd DD statement must be present and must define an output data set that conforms to the rules for DFSORTs SORTOUT data set. The ddname specified in the TO operand must not be the same as the ddname specified in the FROM operand. Refer to JCL Restrictions on page 489 for more information. ON(p,m,f) See the discussion of this operand on the SELECT statement in SELECT Operator on page 566.

584

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator
WITH(p,m) Specifies the position and length of a field to be overlaid from the overlay record on to the base record. p specifies the first byte of the field relative to the beginning of the overlay record. p is 1 for the first data byte of a fixed-length record and 5 for the first data byte of a variable-length record as illustrated below (RRRR represents the 4-byte record descriptor word):
Fixed-length record | Variable-length record | D | A | T | A | ... | | R | R | R | R | D | A | T | A | ... p= 1 2 3 4 | p= 1 2 3 4 5 6 7 8

If INREC is specified, p must refer to the record as reformatted by INREC. m specifies the length of the field in bytes. A field must not extend beyond position 32752. A WITH field will not be used to overlay the RDW of a variable-length base record or to overlay bytes from beyond the end of an overlay record on to a base record. When necessary, WITH fields will be adjusted to prevent these situations. For example, if WITH(1,6) is specified for a variable-length record, it will be treated as WITH(5,2) and if WITH(75,10) is specified for an 80-byte overlay record, it will be treated as WITH(75,6). A WITH field will not be used to overlay bytes beyond the end of a base record. When necessary, WITH fields will be adjusted to prevent this situation. For example, if WITH(75,10) is specified for an 80-byte base record, it will be treated as WITH(75,6). However, if you specify VLENMAX or VLENOVLY, a WITH field can be used to overlay bytes beyond the end of a base record provided that WITH field is present in the overlay record. For example, if VLENMAX and WITH(75,10) is specified for an 80-byte base record and a 90-byte overlay record, the spliced record will have a length of 90 bytes and the WITH(75,10) field will be present at positions 75-84 followed by 6 blanks in positions 85-90. WITHEACH Specifies that the first duplicate is spliced with one specified field from each subsequent duplicate. One WITH field from each overlay record is overlaid on to the base record. The first WITH field specifies the bytes to be overlaid from the second duplicate record on to the first duplicate record. The second WITH field specifies the bytes to be overlaid from the third duplicate record on to the first duplicate record, and so on. For any set of duplicates, extra overlay records without matching WITH fields, or extra WITH fields without matching overlay records are ignored. With WITHEACH, a single spliced output record is created using the base record and one field from each overlay record. Note that the specified field from an overlay record can actually consist of multiple fields from the record that have previously been reformatted into one contiguous field. WITHEACH overrides the default of splicing the first duplicate with all of the specified fields from the last duplicate. VLENOVLY cannot be specified with WITHEACH. WITHALL Specifies that the first duplicate is spliced with specified fields from the second duplicate, and then from each subsequent duplicate in turn. All of the WITH fields from each overlay record are overlaid on to the base record.

Chapter 6. Using ICETOOL

585

SPLICE Operator
With WITHALL, a spliced output record is created from each base record and overlay record, resulting in n1 spliced records for each set of n duplicates. WITHALL overrides the default of splicing the first duplicate with all of the specified fields from the last duplicate. KEEPNODUPS Specifies that non-duplicate records are to be kept as well as spliced records. The non-duplicate records will be unchanged. KEEPBASE Specifies that base records (first duplicate) are to be kept as well as spliced records. The base records will be unchanged. VLENMAX Specifies that for variable-length records, the length of the spliced record is set to the maximum length of the base record and overlay record. VLENMAX overrides the default of setting the length of the spliced record to the length of the base record. If VLENMAX is specified with or without WITHALL, the spliced record is given the larger of the base record length or overlay record length. If the overlay record length is larger than the base record length, bytes in the extended spliced record that are not overlaid are filled in with blanks. If VLENMAX is specified with WITHEACH, the spliced record is given the largest of the base record length or overlay record lengths. If the largest overlay record length is larger than the base record length, bytes in the extended spliced record that are not overlaid are filled in with blanks. For fixed-length records, VLENMAX is ignored since the base, overlay and spliced records all have the same length. VLENOVLY Specifies that for variable-length records, the length of the spliced record is set to the length of the overlay record. VLENOVLY overrides the default of setting the length of the spliced record to the length of the base record. If VLENOVLY is specified with or without WITHALL, the spliced record is given the overlay record length. If the overlay record length is larger than the base record length, the spliced record is padded with blanks from the end of the base record to the new length. If the overlay record length is smaller than the base record length, bytes in the extended spliced record that are not overlaid are filled in with blanks. VLENOVLY cannot be specified with WITHEACH. For fixed-length records, VLENOVLY is ignored since the base, overlay and spliced records all have the same length. USING(xxxx) Specifies the first 4 characters of the ddname for the control statement data set to be used by DFSORT for this operation. xxxx must be four characters that are valid in a ddname of the form xxxxCNTL. xxxx must not be SYSx. If USING is specified, an xxxxCNTL DD statement must be present and the control statements in it: 1. Must conform to the rules for DFSORTs SORTCNTL data set. 2. Should generally be used only for an INCLUDE or OMIT statement, an INREC statement, comment statements, or appropriate OUTFIL statements as described for SPLICE Operator on page 579.

586

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator
VSAMTYPE(x) See the discussion of this operand on the COPY statement in COPY Operator on page 491. UZERO See the discussion of this operand on the OCCUR statement in OCCUR Operator on page 548.

SPLICE Examples
SPLICE normally requires reformatting the records of two or more data sets so they can be joined, so complete JCL examples are shown in this section to illustrate the suggested techniques. These techniques and others can be employed with SPLICE to perform a variety of tasks. Because SPLICE overlays the WITH fields from the overlay record to the base record using matching ON fields, its usually necessary to do some initial setup before using SPLICE, to ensure that: v the ON fields are in the same positions in the base and overlay records v the WITH fields in the overlay records are in the positions they will occupy in the base records v the base records and overlay records are the same length. This is always required for fixed-length records, and is required for variable-length records unless VLENMAX or VLENOVLY is specified. For optimum efficiency, it is also a good idea to remove any records that are not needed for the SPLICE operation as part of the initial setup before the SPLICE operation, by using appropriate INCLUDE or OMIT statements.

Example 1 - Create one spliced record for each match in two files
This example shows how you can splice data together for each pair of records with the same ON field in two different input data sets.
//S1 EXEC PGM=ICETOOL //TOOLMSG DD SYSOUT=* //DFSMSG DD SYSOUT=* //IN1 DD * Y12 89503 MKT Y12 57301 MKT Z35 02316 DEV Y12 91073 MKT Z35 18693 DEV /* //IN2 DD * 89503 27M $9,185,354 SAN JOSE CA 72135 08M $317,632 BOSTON MA 18693 10M $8,732,105 BUFFALO NY 57301 50M $30,000 NEWARK NJ /* //TEMP1 DD DSN=&&TEMP1,DISP=(MOD,PASS),SPACE=(TRK,(5,5)),UNIT=SYSDA //COMBINE DD SYSOUT=* //TOOLIN DD * * Reformat the File1 records for splicing COPY FROM(IN1) TO(TEMP1) USING(CTL1) * Reformat the File2 records for splicing COPY FROM(IN2) TO(TEMP1) USING(CTL2) * Splice the needed data from File1 and File2 together SPLICE FROM(TEMP1) TO(COMBINE) ON(5,5,ZD) WITH(15,17) /* //CTL1CNTL DD * OUTREC FIELDS=(1,14, file1 data
Chapter 6. Using ICETOOL

587

SPLICE Operator
31:X) /* //CTL2CNTL DD * OUTREC FIELDS=(5:1,5, 15:7,15, 30:33,2) /* add blanks for spliced file2 data put file2 key in same place as file1 key file2 data file2 data

The base records originate from the IN1 data set and are copied and reformatted to the TEMP1 data set. The reformatted TEMP1 records are 31 bytes long and look like this:
Y12 Y12 Z35 Y12 Z35 89503 57301 02316 91073 18693 MKT MKT DEV MKT DEV

The overlay records originate from the IN2 data set and are copied and reformatted to the end (MOD) of the TEMP1 data set. The reformatted TEMP1 records are 31 bytes long and look like this:
89503 72135 18693 57301 27M $9,185,354 CA 08M $317,632 MA 10M $8,732,105 NY 50M $30,000 NJ

Note that MOD is used for the TEMP1 data set, so the reformatted records from IN1 and IN2 will be output to the TEMP1 data set in that order, ensuring that they are spliced in that order. The base and overlay records from the TEMP1 data set are sorted and spliced to the COMBINE data set. The records look like this after they are sorted on the 5,5,ZD field, but before they are spliced. As a visual aid, the WITH fields in the overlay records are shown in bold.
Z35 02316 DEV Z35 18693 DEV 18693 Y12 57301 MKT 57301 72135 Y12 89503 MKT 89503 Y12 91073 MKT

10M $8,732,105 NY 50M 08M $30,000 NJ $317,632 MA

27M $9,185,354 CA

The spliced COMBINE records are 31 bytes long and look like this:
Z35 18693 DEV 10M $8,732,105 NY Y12 57301 MKT 50M $30,000 NJ Y12 89503 MKT 27M $9,185,354 CA

Note that the base records for 18693, 57301 and 89503 have been spliced together with their respective overlay records. Heres what the various ICETOOL operators do in this job: v The first COPY operator creates reformatted IN1 records in TEMP1. The second COPY operator creates reformatted IN2 records in TEMP1. The reformatted IN1 records have blanks where the reformatted IN2 WITH fields will go. The reformatted IN2 records have the ON field from IN2 in the same place as in the reformatted IN1 records, and have the IN2 data where we want it to go in the

588

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator
reformatted IN1 records. We made the reformatted IN1 and reformatted IN2 records the same size so we can put them all in the TEMP1 data set and use TEMP1 as input to the SPLICE operator. v The SPLICE operator sorts the records from TEMP1 using the ON field. TEMP1 has the reformatted IN1 records before the reformatted IN2 records. The spliced records are created from the base records and the overlay records in TEMP1. Whenever two records are found with the same ON field, the WITH field from the second record (reformatted IN2 overlay record) is overlaid on to the first record (reformatted IN1 base record). The resulting spliced records are written to the COMBINE data set.

Example 2 - Combine complete records from four files

This example shows how you can use the WITHEACH operand to splice complete records from four different data sets together.
//S2 EXEC PGM=ICETOOL //TOOLMSG DD SYSOUT=* //DFSMSG DD SYSOUT=* //FILE1 DD DSN=... input file1 - 300-byte records //FILE2 DD DSN=... input file2 - 400-byte records //FILE3 DD DSN=... input file3 - 150-byte records //FILE4 DD DSN=... input file4 - 20-byte records //** BE SURE TO USE MOD FOR T1 //T1 DD DSN=&&TX,UNIT=SYSDA,SPACE=(CYL,(5,5)), // DISP=(MOD,PASS) //ALLRCDS DD DSN=... output file - 870-byte records //TOOLIN DD * * Reformat the File1 records for splicing on added sequence COPY FROM(FILE1) TO(T1) USING(CTL1) * Reformat the File2 records for splicing on added sequence COPY FROM(FILE2) TO(T1) USING(CTL2) * Reformat the File3 records for splicing on added sequence COPY FROM(FILE3) TO(T1) USING(CTL3) * Reformat the File4 records for splicing on added sequence COPY FROM(FILE4) TO(T1) USING(CTL4) * Splice record-by-record on added sequence number SPLICE FROM(T1) TO(ALLRCDS) ON(871,8,PD) WITHEACH WITH(301,400) WITH(701,150) WITH(851,20) USING(CTL5) /* //CTL1CNTL DD * * Reformat records to: * 1 301 701 851 871 * File1bytes|400 blanks|150 blanks|20 blanks |seqno OUTREC FIELDS=(1,300,871:SEQNUM,8,PD) /* //CTL2CNTL DD * * Reformat records to: * 1 301 701 851 871 * 300 blanks|File2bytes|150 blanks|20 blanks |seqno OUTREC FIELDS=(301:1,400,871:SEQNUM,8,PD) /* //CTL3CNTL DD * * Reformat records to: * 1 301 701 851 871 * 300 blanks|400 blanks|File3bytes|20 blanks |seqno OUTREC FIELDS=(701:1,150,871:SEQNUM,8,PD) /* //CTL4CNTL DD * * Reformat records to: * 1 301 701 851 871 * 300 blanks|400 blanks|150 blanks|File4bytes|seqno OUTREC FIELDS=(851:1,20,871:SEQNUM,8,PD) /* //CTL5CNTL DD *

number number number number

Chapter 6. Using ICETOOL

589

SPLICE Operator
* Remove added sequence number from spliced records to get: * File1bytes|File2bytes|File3bytes|File4bytes OUTFIL FNAMES=ALLRCDS,OUTREC=(1,870) /*

Because the data sets do not have a common key, we add sequence numbers to the records from each data set and use the sequence numbers as the ON field for SPLICE. Using this technique, we can splice together the 300-byte records from FILE1, the 400-byte records from FILE2, the 150-byte records from FILE3 and the 20-byte records from FILE4, to produce 870-byte records in ALLRCDS. Conceptually, the 870-byte records in ALLRCDS would look like this:
File1 Record1 ... File2Record1 ... File3Record1 ... File4Record1 ... File1 Record2 ... File2Record2 ... File3Record2 ... File4Record2 ... ...

The base records originate from the FILE1 data set and the overlay records originate from the FILE2, FILE3 and FILE4 data sets. Heres what the various ICETOOL operators do in this job: The first COPY operator creates reformatted records in the T1 data set with the FILE1 records in positions 1-300, blanks in all other positions up to 870, and a sequence number in positions 871-878. The sequence number will be 1 for the first FILE1 record, 2 for the second FILE1 record, and so on. The second COPY operator creates reformatted records in the T1 data set with the FILE2 records in positions 301-700, blanks in all other positions up to 870, and a sequence number in positions 871-878. The sequence number will be 1 for the first FILE2 record, 2 for the second FILE2 record, and so on. The third COPY operator creates reformatted records in the T1 data set with the FILE3 records in positions 701-850, blanks in all other positions up to 870, and a sequence number in positions 871-878. The sequence number will be 1 for the first FILE3 record, 2 for the second FILE3 record, and so on. The fourth COPY operator creates reformatted records in the T1 data set with the FILE4 records in positions 851-870, blanks in all other positions up to 850, and a sequence number in positions 871-878. The sequence number will be 1 for the first FILE4 record, 2 for the second FILE4 record, and so on. Note that MOD is used for the T1 data set, so the reformatted records from FILE1, FILE2, FILE3 and FILE4 will be output in that order in T1, ensuring that they are sorted and spliced in that order. The SPLICE operator sorts the records from T1 using the sequence number as the ON field. With WITHEACH, the reformatted FILE1 records are treated as the base records, and the reformatted FILE2, FILE3 and FILE4 records are treated as the overlay records; each WITH field is associated with an overlay record in turn. So the first WITH field specifies the bytes to be used from the second duplicate (FILE2 record), the second WITH field specifies the bytes to be used from the third duplicate (FILE3 record) and the third WITH field specifies the bytes to be used from the fourth duplicate (FILE4 record). SPLICE matches each base and overlay record by their sequence numbers, and creates a new combined 878-byte record. The OUTFIL statement in CTL5CNTL is used to remove the sequence number so that the 870-byte spliced record is written to the ALLRCDS data set.

590

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator

Example 3 - Create files with matching and non-matching records

This example shows how you can match records in input data sets 1 and 2 to produce three output data sets with: v ON fields that appear in both input data set 1 and input data set 2 v ON fields that appear only in input data set 1 v ON fields that appear only in input data set 2
//S3 EXEC PGM=ICETOOL //TOOLMSG DD SYSOUT=* //DFSMSG DD SYSOUT=* //IN1 DD * Vicky Frank Carrie Holly Paul /* //IN2 DD * Karen Holly Carrie Vicky Mary /* //OUT12 DD SYSOUT=* //OUT1 DD SYSOUT=* //OUT2 DD SYSOUT=* //T1 DD DSN=&&T1,DISP=(MOD,PASS),UNIT=SYSDA,SPACE=(TRK,(5,5)) //TOOLIN DD * * Add 11 identifier for FILE1 records. COPY FROM(IN1) TO(T1) USING(CTL1) * Add 22 identifier for FILE2 records. COPY FROM(IN2) TO(T1) USING(CTL2) * SPLICE to match up records and write them to their * appropriate output files. SPLICE FROM(T1) TO(OUT12) ON(1,10,CH) WITH(13,1) USING(CTL3) KEEPNODUPS /* //CTL1CNTL DD * * Mark FILE1 records with 11 OUTREC FIELDS=(1,10,12:C11) /* //CTL2CNTL DD * * Mark FILE2 records with 22 OUTREC FIELDS=(1,10,12:C22) /* //CTL3CNTL DD * * Write matching records to OUT12 file. Remove id. OUTFIL FNAMES=OUT12,INCLUDE=(12,2,CH,EQ,C12),OUTREC=(1,10) * Write FILE1 only records to OUT1 file. Remove id. OUTFIL FNAMES=OUT1,INCLUDE=(12,2,CH,EQ,C11),OUTREC=(1,10) * Write FILE2 only records to OUT2 file. Remove id. OUTFIL FNAMES=OUT2,INCLUDE=(12,2,CH,EQ,C22),OUTREC=(1,10) /*

We copy the IN1 records to the T1 data set and add an identifier of 11 to show they come from FILE1. We copy the IN2 records to the end (MOD) of the T1 data set and add an identifier of 22 to show they come from FILE2. We sort the records of T1 on positions 1-3 and splice the second id byte for matching records. We use KEEPNODUPS to keep non-duplicate records.
Chapter 6. Using ICETOOL

591

SPLICE Operator
The records look like this after they are sorted, but before they are spliced:
Carrie Carrie Frank Holly Holly Karen Mary Paul Vicky Vicky 11 22 11 11 22 22 22 11 11 22

The records look like this after they are spliced, but before we do the OUTFIL processing specified by CTL3CNTL with USING(CTL3) for SPLICE:
Carrie Frank Holly Karen Mary Paul Vicky 12 11 12 22 22 11 12

An id of 12 indicates an ON field that appears in IN1 and IN2. An id of 11 indicates an ON field that appears only in IN1. An id of 22 indicates an ON field that appears only in IN2. The OUTFIL statements in CTL3CNTL write the records to their appropriate output data sets (without the ids) as follows: OUT12 contains:
Carrie Holly Vicky

OUT1 contains:
Frank Paul

OUT2 contains:
Karen Mary

Example 4 - Create multiple spliced records for each match in two types of records
This example shows how you can use the WITHALL operand to tell ICETOOL to splice data together for a single record of one type (A records) and multiple records of another type (H records), in the same input data set, that all have the same ON field (duplicate records). It also shows how to ensure that duplicates of the second type without a match of the first type are not written to the output data set. IFTHEN clauses are used in an INREC statement to reformat the two types of records appropriately before they are sorted and spliced
//S4 EXEC PGM=ICETOOL //TOOLMSG DD SYSOUT=* //DFSMSG DD SYSOUT=* //MAST DD * A0000B0000KRSC0000D000000E0000F00G000 A1111B1111FLYC1111D111111E1111F11G111 H02KRSI000002J002K002L02 H03FLYI000003J003K003L03 H04VQXI000004J004K004L04

592

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator
H05FLYI000005J005K005L05 H06KHNI000006J006K006L06 H07KRSI000007J007K007L07 H08FLYI000008J008K008L08 H09KHNI000009J009K009L09 /* //OUT DD SYSOUT=* //TOOLIN DD * * Splice needed base and overlay data together. * Do NOT splice identifier. SPLICE FROM(MAST) TO(OUT) WITH(1,7) WITH(13,4) ON(20,3,CH) WITH(23,3) WITH(26,3) WITHALL USING(CTL1) /* //CTL1CNTL DD * * Before SPLICE: * Set up fields in base (A) records. Add B id in position 33. INREC IFTHEN=(WHEN=(1,1,CH,EQ,CA), BUILD=(8:14,5,17:31,3,20:11,3,29:34,4,33:CB)), * Set up fields in overlay (H) records. Add V id in position 33. IFTHEN=(WHEN=(1,1,CH,EQ,CH), BUILD=(1:7,7,13:18,4,20:4,3,23:1,3,26:22,3,33:CV)) * After SPLICE: * Remove duplicate overlay records without matching base record. * Remove base or overlay indicator. OUTFIL FNAMES=OUT,OMIT=(33,1,CH,EQ,CV),OUTREC=(1,32) /*

The base records are the records in MAST with an A in column 1. They are reformatted by the INREC statement as 33 byte records that look like this:
C0000 C1111 F00KRS F11FLY G000B G111B

We put a B in position 33 to identify these records as base records. The overlay records are the records in MAST with an H in column 1. They are reformatted by the INREC statement as 33 bytes records that look like this:
I000002 I000003 I000004 I000005 I000006 I000007 I000008 I000009 K002 K003 K004 K005 K006 K007 K008 K009 KRSH02L02 FLYH03L03 VQXH04L04 FLYH05L05 KHNH06L06 KRSH07L07 FLYH08L08 KHNH09L09 V V V V V V V V

We put a V in position 33 to identify these records as overlay records. The base and overlay records set up by the INREC statement are sorted and spliced. The records look like this after they are sorted on the 20,3,CH field, but before they are spliced. As a visual aid, the WITH fields in the overlay records are shown in bold.
C1111 F11FLY G111B I000003 K003 FLYH03L03 V I000005 K005 FLYH05L05 V I000008 K008 FLYH08L08 V I000006 K006 KHNH06L06 V I000009 K009 KHNH09L09 V C0000 F00KRS G000B I000002 K002 KRSH02L02 V I000007 K007 KRSH07L07 V I000004 K004 VQXH04L04 V
Chapter 6. Using ICETOOL

593

SPLICE Operator
The spliced output records are 33 bytes long and look like this:
I000003C1111K003F11FLYH03L03G111B I000005C1111K005F11FLYH05L05G111B I000008C1111K008F11FLYH08L08G111B I000009 K009 KHNH09L09 V I000002C0000K002F00KRSH02L02G000B I000007C0000K007F00KRSH07L07G000B

Note that the base record (type A) for FLY has been spliced together with each of the three overlay records (type H) for FLY. Likewise, the base record (type A) for KRS has been spliced together with each of the two overlay records (type H) for KRS. But also note that the overlay records (type H) for KHN have been spliced together. Because KHN does not appear as a base record (type A) we dont want the KHN records to appear in the OUT data set. So we will use the V we put in position 33 for the overlay records to identify and delete spliced overlay records without a matching base record. We only have to do this if we have duplicate overlay records without a matching base record. Single overlay records without a matching base record will be deleted automatically (unless you specify KEEPNODUPS). After we eliminate the spliced overlay records and the position 33 indicator, the OUT records are 32 bytes long and look like this:
I000003C1111K003F11FLYH03L03G111 I000005C1111K005F11FLYH05L05G111 I000008C1111K008F11FLYH08L08G111 I000002C0000K002F00KRSH02L02G000 I000007C0000K007F00KRSH07L07G000

Note that if we had not specified WITHALL, only the first and last records for each set of duplicates would have been spliced, producing the following output:
I000008C1111K008F11FLYH08L08G111 I000007C0000K007F00KRSH07L07G000

Example 5 - Pull records from a master file in sorted order

This example shows how you can use the WITHALL operand to tell ICETOOL to use ON fields in a PULL data set to select one or more records from a MASTER data set. In other words, you can use a PULL list to select records from a MASTER list. In this case, the PULL data set has VB records and the MASTER data set has FB records. The ON field is a City Name that can be 1-20 bytes long, and the selected MASTER records are to be sorted by the City Name. (Example 6 - Pull records from a master file in their original order on page 596 shows how to keep the MASTER records in their original order.)
//S5 EXEC PGM=ICETOOL //TOOLMSG DD SYSOUT=* //DFSMSG DD SYSOUT=* //PULL DD DSN=VAR.PULL.FILE,DISP=SHR //MASTER DD DSN=FIXED.MASTER.FILE,DISP=SHR //TEMP1 DD DSN=&&T1,DISP=(MOD,PASS),SPACE=(TRK,(5,5)),UNIT=SYSDA //OUT DD DSN=FIXED.OUTPUT.FILE,DISP=(NEW,CATLG,DELETE), // SPACE=(TRK,(5,5)),UNIT=SYSDA //TOOLIN DD * * Convert PULL records from VB to FB and add P identifier. COPY FROM(PULL) USING(CTL1) * Add M identifier to MASTER records. COPY FROM(MASTER) TO(TEMP1) USING(CTL2) * Splice PULL and MASTER records (do NOT splice identifier): * Spliced MASTER records with matching PULL records have P id. * Spliced MASTER records without matching PULL records

594

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator
* have M id. * Eliminate records with M id. SPLICE FROM(TEMP1) TO(OUT) ON(1,20,CH) WITHALL WITH(1,40) USING(CTL3) /* //CTL1CNTL DD * * Convert PULL records from VB to FB and add P identifier. OUTFIL FNAMES=TEMP1,VTOF,OUTREC=(5,20,41:CP) /* //CTL2CNTL DD * * Add M identifier to MASTER records. OUTREC FIELDS=(1,40,41:CM) /* //CTL3CNTL DD * * Eliminate MASTER records without matching PULL records. OUTFIL FNAMES=OUT,OMIT=(41,1,CH,EQ,CM),OUTREC=(1,40) /*

The base records originate from the PULL data set (VAR.PULL.FILE). The PULL data set has variable-length (VB) records with the RDW in positions 1-4 and the variable-length City Name starting in position 5 for 1-20 bytes. Conceptually, the PULL records look like this:
Length 12 12 11 15 | | | | | Data SAN JOSE NEW YORK DENVER LOS ANGELES

The overlay records originate from the MASTER data set (FIXED.MASTER.FILE). The MASTER data set has 40-byte fixed-length (FB) records with the City Name in positions 1-20. The PULL records are copied and reformatted to the TEMP1 data set as 41-byte fixed-length (FB) records with the City Name in positions 1-20 (padded on the right with blanks as necessary), and a P in position 41 to identify them as PULL records. The VTOF and OUTREC parameters of DFSORTs OUTFIL statement are used to convert the VB records to FB records with blank padding. The reformatted PULL records in TEMP1 look like this:
SAN JOSE NEW YORK DENVER LOS ANGELES P P P P

The MASTER records are copied and reformatted to the end (MOD) of the TEMP1 data set as 41-byte fixed-length (FB) records with an M added in position 41 to identify them as MASTER records. The reformatted MASTER records in TEMP1 look like this:
SAN JOSE PHOENIX LOS ANGELES SAN JOSE NEW YORK SAN JOSE TUCSON NEW YORK PHOENIX 8630 7993 9203 0052 5218 3896 1056 6385 5831 SUSAN PAUL MICHAEL VICKY CARRIE FRANK LISA MICHAEL HOLLY M M M M M M M M M

The base and overlay records from the TEMP1 data set are sorted and spliced.

Chapter 6. Using ICETOOL

595

SPLICE Operator
The records look like this after they are sorted on the 1,20,CH field, but before they are spliced. As a visual aid, the WITH fields in the overlay records are shown in bold.
DENVER LOS ANGELES LOS ANGELES NEW YORK NEW YORK NEW YORK PHOENIX PHOENIX SAN JOSE SAN JOSE SAN JOSE SAN JOSE TUCSON P P M P M M M M P M M M M

9203 5218 6385 7993 5831

MICHAEL CARRIE MICHAEL PAUL HOLLY

8630 SUSAN 0052 VICKY 3896 FRANK 1056 LISA

The spliced records look like this:

LOS ANGELES NEW YORK NEW YORK PHOENIX SAN JOSE SAN JOSE SAN JOSE 9203 5218 6385 5831 8630 0052 3896 MICHAEL CARRIE MICHAEL HOLLY SUSAN VICKY FRANK P P P M P P P

Finally, we use the OUTFIL statement for SPLICE to remove each spliced record with an M in position 41, because that represents a base record without a matching overlay record. The OUTFIL statement also removes the P indicator in position 41 from each record, because it is not needed in the OUT data set. Thus, for each MASTER record that matches a PULL record, weve overlaid the PULL record with the MASTER record. This effectively selects all of the MASTER records on the PULL list. The resulting OUT data set (FIXED.OUTPUT.FILE) has the following 40-byte fixed-length records:
LOS NEW NEW SAN SAN SAN ANGELES YORK YORK JOSE JOSE JOSE 9203 5218 6385 8630 0052 3896 MICHAEL CARRIE MICHAEL SUSAN VICKY FRANK

Example 6 - Pull records from a master file in their original order

This example is similar to Example 5 - Pull records from a master file in sorted order on page 594, except that we want to keep the resulting MASTER records in their original order instead of sorting them by the City Name field. We use DFSORTs SEQNUM parameter to add a sequence number to each MASTER record before the records are spliced, and we splice that sequence number along with the data. After SPLICE sorts by the City Name, we SORT again by the sequence number to get the resulting MASTER records back in their original order.
//S6 EXEC PGM=ICETOOL //TOOLMSG DD SYSOUT=* //DFSMSG DD SYSOUT=* //PULL DD DSN=VAR.PULL.FILE,DISP=SHR //MASTER DD DSN=FIXED.MASTER.FILE,DISP=SHR //TEMP1 DD DSN=&&TEMP1,DISP=(MOD,PASS),SPACE=(TRK,(5,5)),UNIT=SYSDA //TEMP2 DD DSN=&&TEMP2,DISP=(,PASS),SPACE=(TRK,(5,5)),UNIT=SYSDA //OUT DD DSN=FIXED.OUTPUT.FILE,DISP=(NEW,CATLG,DELETE), // SPACE=(TRK,(5,5)),UNIT=SYSDA //TOOLIN DD * * Convert PULL records from VB to FB and add P identifier.

596

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator
COPY FROM(PULL) USING(CTL1) * Add sequence number and M identifier to MASTER records. COPY FROM(MASTER) TO(TEMP1) USING(CTL2) * Splice PULL and MASTER records (splice sequence number, but * do NOT splice identifier): * Spliced MASTER records with matching PULL records have P id. * Spliced MASTER records without matching PULL records * have M id. * Eliminate records with M id. SPLICE FROM(TEMP1) TO(TEMP2) ON(1,20,CH) WITHALL WITH(1,48) USING(CTL3) * Sort resulting spliced records on original sequence number * to get them back in their original order. * Remove id and sequence number. SORT FROM(TEMP2) TO(OUT) USING(CTL4) /* //CTL1CNTL DD * * Convert PULL records from VB to FB and add P identifier OUTFIL FNAMES=TEMP1,VTOF,OUTREC=(5,20,49:CP) /* //CTL2CNTL DD * * Add sequence number and M identifier to MASTER records. OUTREC FIELDS=(1,40,41:SEQNUM,8,BI,49:CM) /* //CTL3CNTL DD * * Eliminate MASTER records without matching PULL records. OUTFIL FNAMES=TEMP2,OMIT=(49,1,CH,EQ,CM) /* //CTL4CNTL DD * * Sort on sequence number and remove id and sequence number. SORT FIELDS=(41,8,BI,A) OUTREC FIELDS=(1,40) /*

The resulting OUT data set (FIXED.OUTPUT.FILE) has the following 40-byte fixed-length records:
SAN LOS SAN NEW SAN NEW JOSE ANGELES JOSE YORK JOSE YORK 8630 9203 0052 5218 3896 6385 SUSAN MICHAEL VICKY CARRIE FRANK MICHAEL

Example 7 - Create a report showing if needed parts are on-hand

This example shows how you can use the KEEPNODUPS operand to tell ICETOOL to compare the ON fields in a list of needed parts to the ON fields in a list of on-hand parts, and produce a report showing if each needed part is on-hand or not.
//S7 EXEC PGM=ICETOOL //TOOLMSG DD SYSOUT=* //DFSMSG DD SYSOUT=* //ONHAND DD * P62 Blue P62 Red G73 Blue A27 Green L90 Red P63 Blue /* //NEEDED DD * 2003/05/07 A27 Green 2002/12/29 P62 Blue 2003/03/17 A27 Blue 2003/06/14 M92 Yellow 2002/12/18 L90 Red
Chapter 6. Using ICETOOL

597

SPLICE Operator
/* //COMBINED DD DSN=&&T1,UNIT=SYSDA,SPACE=(TRK,(5,5)), // DISP=(MOD,PASS) //RPT DD SYSOUT=* //TOOLIN DD * * Reformat the ONHAND records for splicing. * Add Yes for found in ONHAND data set. * Add O to indicate ONHAND record. COPY FROM(ONHAND) TO(COMBINED) USING(CTL1) * Reformat the NEEDED records for splicing. * Add No for missing from ONHAND data set. * Add N to indicate NEEDED record. COPY FROM(NEEDED) TO(COMBINED) USING(CTL2) * Splice ONHAND and NEEDED records (splice identifier): * NEEDED records found in ONHAND list will have Yes * and N. * NEEDED records not found in ONHAND list will have No * and N. * ONHAND records that are not needed will have Yes * and O. * Eliminate records with O. SPLICE FROM(COMBINED) TO(RPT) ON(1,12,CH) WITH(24,10) WITH(40,1) KEEPNODUPS USING(CTL3) /* //CTL1CNTL DD * * Reformat ONHAND records with part in 1-12, Yes in 15-17 * and O in 40. OUTREC FIELDS=(1:1,12,15:CYes,40:CO) /* //CTL2CNTL DD * * Reformat NEEDED records with part in 1-12, No in 15-17, * date in 24-33 and N in 40. OUTREC FIELDS=(1:15,12,15:CNo,24:2,10,40:CN) /* //CTL3CNTL DD * * Eliminate ONHAND parts that do not appear in NEEDED list. * Create the report showing if needed parts are on-hand. OUTFIL FNAMES=RPT,OMIT=(40,1,CH,EQ,CO),OUTREC=(1,33), HEADER2=(1:Part,15:On-Hand,24:Needed by,/, 1:------------,15:-------,24:----------) /*

The base records originate from the ONHAND data set and are copied and reformatted to the COMBINED data set. We put an O in position 40 to identify these records as ONHAND records. The overlay records originate from the NEEDED data set and are copied and reformatted to the COMBINED data set. We put an N in position 40 to identify these records as NEEDED records. Because MOD is used for the COMBINED data set, it contains the reformatted ONHAND records followed by the reformatted NEEDED records. The COMBINED records are 40 bytes long and look like this:
P62 P62 G73 A27 L90 P63 A27 P62 A27 M92 L90 Blue Red Blue Green Red Blue Green Blue Blue Yellow Red Yes Yes Yes Yes Yes Yes No No No No No O O O O O O N N N N N

2003/05/07 2002/12/29 2003/03/17 2003/06/14 2002/12/18

The base and overlay records from the COMBINED data set are sorted and spliced.

598

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator
The records look like this after they are sorted on the 1,12,CH field, but before they are spliced. As a visual aid, the WITH fields in the overlay records are shown in bold.
A27 A27 A27 G73 L90 L90 M92 P62 P62 P62 P63 Blue Green Green Blue Red Red Yellow Blue Blue Red Blue No Yes No Yes Yes No No Yes No Yes Yes 2003/03/17 2003/05/07 2002/12/18 2003/06/14 2002/12/29 N O N O O N N O N O O

The spliced output records are 40 bytes long and look like this:
A27 A27 G73 L90 M92 P62 P62 P63 Blue Green Blue Red Yellow Blue Red Blue No Yes Yes Yes No Yes Yes Yes 2003/03/17 2003/05/07 2002/12/18 2003/06/14 2002/12/29 N N O N N N O O

We have three types of records above as follows: 1. Records with Yes and N are NEEDED records with an ONHAND match that have been spliced together. We want these for our report. 2. Records with No and N are NEEDED records without an ONHAND match that have been kept because we used KEEPNODUPS. We want these for our report. 3. Records with Yes and O are ONHAND records without a NEEDED match that have been kept because we used KEEPNODUPS. We do not want these for our report. We use the OUTFIL statement for SPLICE to further process the spliced records. It omits the O records, removes the N byte, and sets up the headers for the report. The resulting RPT data set looks like this:
Part -----------A27 Blue A27 Green L90 Red M92 Yellow P62 Blue On-Hand ------No Yes Yes No Yes Needed by ---------2003/03/17 2003/05/07 2002/12/18 2003/06/14 2002/12/29

Example 8 - Create a report showing if needed parts are on-hand - advanced

This example is a more complex variation of Example 7 - Create a report showing if needed parts are on-hand on page 597. It shows how you can use the WITHALL, KEEPBASE, and KEEPNODUPS operands to tell ICETOOL to compare the ON fields in a list of needed parts to the ON fields in a list of on-hand parts, and produce a report showing if each needed part is on-hand or not. However, it also has duplicate parts in the NEEDED data set, and produces a report with more information from the ONHAND and NEEDED records.
//S8 EXEC PGM=ICETOOL //TOOLMSG DD SYSOUT=* //DFSMSG DD SYSOUT=* //ONHAND DD *
Chapter 6. Using ICETOOL

599

SPLICE Operator
P62 Blue Dallas G73 Blue San Jose A27 Green Vancouver /* //NEEDED DD * Rachel A27 Green Phoenix Monica P62 Blue Phoenix Phoebe A27 Blue Toronto Chandler M92 Yellow Los Angeles Joey M92 Yellow Paris Ross A27 Green Paris /* //COMBINED DD DSN=&&C1,UNIT=SYSDA,SPACE=(TRK,(5,5)), // DISP=(MOD,PASS) //TEMP1 DD DSN=&&T1,UNIT=SYSDA,SPACE=(CYL,(5,5)),DISP=(,PASS) //RPT DD SYSOUT=* //TOOLIN DD * * Reformat the ONHAND records for splicing. * Add Yes for found and D for delete record. COPY FROM(ONHAND) TO(COMBINED) USING(CTL1) * Reformat the NEEDED records for splicing. * Add No for missing and K for keep record. COPY FROM(NEEDED) TO(COMBINED) USING(CTL2) * Splice ONHAND and NEEDED records. * Splice in Requested by, Ship to and id fields. * Eliminate spliced records with D. SPLICE FROM(COMBINED) TO(TEMP1) ON(1,12,CH) WITHALL KEEPBASE KEEPNODUPS USING(CTL3) WITH(24,10) WITH(53,13) WITH(66,1) * Print report. DISPLAY FROM(TEMP1) LIST(RPT) INDENT(2) BETWEEN(2) BLANK HEADER(Part) ON(1,12,CH) HEADER(On-Hand) ON(15,3,CH) HEADER(Requested by) ON(24,12,CH) HEADER(Ship from) ON(38,13,CH) HEADER(Ship to) ON(53,13,CH) /* //CTL1CNTL DD * * Reformat ONHAND records with Part in 1-12, Yes for found in * 15-17, From City in 38-50 and D in 66. OUTREC FIELDS=(1:1,12,15:CYes,38:20,13,66:CD) /* //CTL2CNTL DD * * Reformat NEEDED records with Part in 1-12, No for missing in * 15-17, Requester Name in 24-35, n/a for From City in 38-40, * To City in 53-65 and K in 66. OUTREC FIELDS=(1:15,12,15:CNo ,24:2,10,38:Cn/a, 53:31,13,66:CK) /* //CTL3CNTL DD * * Eliminate ONHAND parts that do not appear in NEEDED list. OUTFIL FNAMES=TEMP1,OMIT=(66,1,CH,EQ,CD) /*

The base records originate from the ONHAND data set. They are copied and reformatted to the COMBINED data set. The reformatted records look like this:
P62 Blue G73 Blue A27 Green Yes Yes Yes Dallas San Jose Vancouver D D D

The overlay records originate from the NEEDED data set and are copied and reformatted to the COMBINED data set. The reformatted records look like this

600

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator
A27 P62 A27 M92 M92 A27 Green Blue Blue Yellow Yellow Green No No No No No No Rachel Monica Phoebe Chandler Joey Ross n/a n/a n/a n/a n/a n/a Phoenix Phoenix Toronto Los Angeles Paris Paris K K K K K K

The base and overlay records from the COMBINED data set are sorted and spliced. However, we need to make sure that all parts which appear in more than one NEEDED record, but do not appear in the ONHAND list, will appear in the report. For example, we have two M92 Yellow parts in the NEEDED data set that do not appear in the ONHAND data set. These two records are reformatted and appear in the COMBINED data set as follows:
M92 Yellow M92 Yellow No No Chandler Joey n/a n/a Los Angeles K Paris K

ICETOOL would normally treat the first record as the base record and the second record as the overlay record. As a result, these two records would be spliced together into one record instead of two. To prevent this, and ensure that we keep both M92 Yellow parts, we must specify KEEPBASE. As a result, two records are kept: the unchanged first M92 Yellow record, and the spliced first and second M92 Yellow records (which in this case looks identical to the unspliced second record). The records look like this after they are sorted on the 1,12,CH field, but before they are spliced. As a visual aid, the WITH fields in the overlay records are shown in bold.:
A27 A27 A27 A27 G73 M92 M92 P62 P62 Blue Green Green Green Blue Yellow Yellow Blue Blue No Yes No No Yes No No Yes No Phoebe Rachel Ross Chandler Joey Monica n/a Vancouver n/a n/a San Jose n/a n/a Dallas n/a K D Phoenix K Paris K D Los Angeles K Paris K D Phoenix K Toronto

The spliced records look like this:

A27 A27 A27 A27 G73 M92 M92 P62 P62 Blue Green Green Green Blue Yellow Yellow Blue Blue No Yes Yes Yes Yes No No Yes Yes Phoebe Rachel Ross Chandler Joey Monica n/a Vancouver Vancouver Vancouver San Jose n/a n/a Dallas Dallas Toronto K D Phoenix K Paris K D Los Angeles K Paris K D Phoenix K

Records with D are not needed, so we use the OUTFIL statement for SPLICE to omit them. The TEMP1 records look like this:
A27 A27 A27 M92 M92 P62 Blue Green Green Yellow Yellow Blue No Yes Yes No No Yes Phoebe Rachel Ross Chandler Joey Monica n/a Vancouver Vancouver n/a n/a Dallas Toronto Phoenix Paris Los Angeles Paris Phoenix K K K K K K

Although we could have used the OUTFIL statement for SPLICE to print the report, weve chosen instead to use a separate DISPLAY operator. DISPLAY

Chapter 6. Using ICETOOL

601

SPLICE Operator
requires an extra pass over the spliced records in TEMP1, but is easier to use than OUTFIL for reports. The resulting RPT data set looks like this:
Part -----------A27 Blue A27 Green A27 Green M92 Yellow M92 Yellow P62 Blue On-Hand ------No Yes Yes No No Yes Requested by -----------Phoebe Rachel Ross Chandler Joey Monica Ship from ------------n/a Vancouver Vancouver n/a n/a Dallas Ship to ------------Toronto Phoenix Paris Los Angeles Paris Phoenix

Example 9 - Create spliced variable-length records from two files

This example shows how you can splice data together for each pair of records with the same ON field in two different VB input data sets, even when records are of different lengths.
//S9 EXEC PGM=ICETOOL //TOOLMSG DD SYSOUT=* //DFSMSG DD SYSOUT=* //CON DD DSN=VAR.INPUT1,DISP=SHR // DD DSN=VAR.INPUT2,DISP=SHR //OUT DD DSN=VAR.OUTPUT,DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(5,5)),UNIT=SYSDA //TOOLIN DD * * Splice the needed data from the two VB files together SPLICE FROM(CON) TO(OUT) ON(5,5,CH) WITHALL WITH(12,5) WITH(22,20) VLENMAX /*

VAR.INPUT1 has RECFM=VB and LRECL=25. It contains the base records which look like this:
Length 25 15 25 25 | | | | | Data DIV01 DIV02 DIV03 DIV05 L2 L6 L8

VAR.INPUT2 has RECFM=VB and LRECL=50. It contains the overlay records which look like this:
Length 42 33 39 19 47 43 | | | | | | | Data DIV01 DIV01 DIV02 DIV05 DIV05 DIV06 83201 73268 00589 57003 01381 37982 FERN BROTHERS INTL ROSS INC. ACME PAINT SHOP FLOWERS BY RENEE EVERYTHING FOR PETS

Because some of the overlay records are longer than their corresponding base records, we use VLENMAX to ensure that none of the data from the overlay records is lost. VLENMAX ensures that the larger length between the base record and overlay record is used for the spliced record, and that blanks are added to the end of the spliced record when needed. The base and overlay records from the concatenated data sets are sorted and spliced. VAR.OUTPUT has RECFM=VB and LRECL=50. It contains the spliced records, which look like this:
Length 42 33 39 25 47 | | | | | | Data DIV01 DIV01 DIV02 DIV05 DIV05 83201 73268 00589 57003 01381 L2 L2 L8 L8 FERN BROTHERS INTL ROSS INC. ACME PAINT SHOP FLOWERS BY RENEE

602

z/OS V1R10.0 DFSORT Application Programming Guide

SPLICE Operator
Notice that VLENMAX prevented any data from being lost. Without VLENMAX, data would have been lost; the spliced records would have looked like this:
Length 25 25 15 25 25 | | | | | | Data DIV01 DIV01 DIV02 DIV05 DIV05 83201 73268 0058 57003 01381 L2 L2 L8 L8 FERN ROSS FLOW

STATS Operator

STATS FROM(indd)

ON(p,m,f) ON(VLEN)

VSAMTYPE(x)

LMSG

Prints messages containing the minimum, maximum, average, and total for specified numeric fields. From 1 to 10 fields can be specified. DFSORT is called to copy the indd data set to ICETOOLs E35 user exit. ICETOOL prints messages containing the minimum, maximum, average, and total for each field as determined by its E35 exit. The average (or mean) is calculated by dividing the total by the record count and rounding down to the nearest integer (examples: 23 / 5 = 4, 23 / 5 = 4). You must not supply your own DFSORT MODS, INREC, or OUTREC statement, because they would override the DFSORT statements passed by ICETOOL for this operator.

Operand Descriptions
The operands described below can be specified in any order. FROM(indd) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. ON(p,m,f) Specifies the position, length, and format of a numeric field to be used for this operation. p specifies the first byte of the field relative to the beginning of the input record. p is 1 for the first data byte of a fixed-length record and 5 for the first data byte of a variable-length record as illustrated below (RRRR represents the 4-byte record descriptor word):
Fixed-length record | Variable-length record | D | A | T | A | ... | | R | R | R | R | D | A | T | A | ... p= 1 2 3 4 | p= 1 2 3 4 5 6 7 8

m specifies the length of the field in bytes. A field must not extend beyond position 32752 or beyond the end of a record. The maximum length for a field depends on its format.

Chapter 6. Using ICETOOL

603

STATS Operator
f specifies the format of the field as follows:
Format Code BI FI PD ZD CSF or FS UFF SFF Length 1 to 8 bytes 1 to 8 bytes 1 to 16 bytes 1 to 31 bytes 1 to 32 bytes (31 digit limit) 1 to 44 bytes (31 digit limit) 1 to 44 bytes (31 digit limit) Description Unsigned binary Signed fixed-point Signed packed decimal Signed zoned decimal Signed numeric with optional leading floating sign Unsigned free form numeric Signed free form numeric

Note: See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions.

If the total for a field overflows 31 digits, ICETOOL continues processing, but prints asterisks for the average and total for that field. For a CSF, FS, UFF, or SFF format field: v A maximum of 31 digits is allowed. If a value with more than 31 digits is found, ICETOOL issues an error message and terminates the operation. For a ZD or PD format field: v If a decimal value contains an invalid digit (A-F), ICETOOL identifies the bad value in a message and prints asterisks for the minimum, maximum, average and total for that field. v A value is treated as positive if its sign is F, E, C, A, 8, 6, 4, 2, or 0. v A value is treated as negative if its sign is D, B, 9, 7, 5, 3, or 1. For a ZD, PD, CSF, FS, or SFF format field, a negative zero value is treated as a positive zero value. ON(VLEN) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. VSAMTYPE(x) See the discussion of this operand on the COPY statement in COPY Operator on page 491. LMSG Specifies that the minimum, maximum, average and total for all numeric fields are to be printed using messages that display 31 digits (overriding the default of printing messages that display 15 digits when possible). LMSG ensures that only message ICE648I is used to display the statistics. Without LMSG, a combination of messages ICE608I, ICE609I and ICE648I can be used to display the statistics.

STATS Example
STATS FROM(DATA1) ON(VLEN) ON(15,4,ZD)

Prints messages containing the minimum, maximum, average and total of the binary values in positions 1-2 of the DATA1 data set. For variable-length records, this gives statistics about the length of the records. Prints messages containing the minimum, maximum, average and total of the zoned decimal values in positions 15-18 of the DATA1 data set.

604

z/OS V1R10.0 DFSORT Application Programming Guide

UNIQUE Operator

UNIQUE Operator

UNIQUE FROM(indd)

ON(p,m,f) ON(VLEN)

VSAMTYPE(x)

UZERO

Prints a message containing the count of unique values for a specified numeric or character field. DFSORT is called to sort the indd data set to ICETOOLs E35 user exit. ICETOOL prints a message containing the unique count as determined by its E35 user exit. The DYNALLOC option is passed to DFSORT to ensure that work space is available for the sort. If your installation defaults for dynamic allocation are inappropriate for a UNIQUE operator, you can take one of the following actions: 1. Override the DYNALLOC option using an OPTION control statement such as:
OPTION DYNALLOC=(8)

in the DFSPARM data set. 2. Use SORTWKdd DD statements to override the use of dynamic allocation. Refer to SORTWKdd DD Statement on page 72 for details. Attention: Either of these actions affects the work data sets used for an OCCUR operator, or for a SELECT or SPLICE operator for which USING(xxxx) is not specified. Tape work data sets cannot be used with ICETOOL. You must not supply your own DFSORT MODS, INREC, OUTREC, SUM or RECORD statement, because they override the DFSORT statements passed by ICETOOL for this operator.

Operand Descriptions
The operands described below can be specified in any order. FROM(indd) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. ON(p,m,f) Specifies the position, length, and format of a numeric or character field to be used with this operation. p specifies the first byte of the field relative to the beginning of the input record. p is 1 for the first data byte of a fixed-length record and 5 for the first data byte of a variable-length record as illustrated below (RRRR represents the 4-byte record descriptor word):
Fixed-length record | Variable-length record | D | A | T | A | ... | | R | R | R | R | D | A | T | A | ... p= 1 2 3 4 | p= 1 2 3 4 5 6 7 8

m specifies the length of the field in bytes. A field must not extend beyond position 32752 or beyond the end of a record. The maximum length for a field depends on its format.
Chapter 6. Using ICETOOL

605

UNIQUE Operator
f specifies the format of the field as shown below:
Format Code BI FI PD ZD CH CSF or FS UFF SFF Length 1 to 256 bytes 1 to 256 bytes 1 to 32 bytes 1 to 32 bytes 1 to 1500 bytes 1 to 32 bytes 1 to 44 bytes 1 to 44 bytes Description Unsigned binary Signed fixed-point Signed packed decimal Signed zoned decimal Character Signed numeric with optional leading floating sign Unsigned free form numeric Signed free form numeric

Note: See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions.

For a ZD or PD format field: v F, E, C, A, 8, 6, 4, 2, and 0 are treated as equivalent positive signs. Thus the zoned decimal values F2F3C1, F2F3F1, and 020301 are counted as only one unique value. v D, B, 9, 7, 5, 3, and 1 are treated as equivalent negative signs. Thus the zoned decimal values F2F3B0, F2F3D0, and 020310 are counted as only one unique value. v Digits are not checked for validity. ON(VLEN) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. VSAMTYPE(x) See the discussion of this operand on the COPY statement in COPY Operator on page 491. UZERO See the discussion of this operand on the OCCUR statement on OCCUR Operator on page 548.

UNIQUE Example
UNIQUE FROM(DATAIN) ON(20,40,CH) UNIQUE FROM(DATAIN) ON(5,3,ZD)

The first UNIQUE operator prints a message containing the count of unique character data in positions 20-59 of the DATAIN data set. The second UNIQUE operator prints a message containing the count of unique zoned decimal values in positions 5-7 of the DATAIN data set.

606

z/OS V1R10.0 DFSORT Application Programming Guide

VERIFY Operator

VERIFY Operator

VERIFY FROM(indd)

ON(p,m,f) NOSIGN LIMIT(n)

VSAMTYPE(x)

Examines particular decimal fields in a data set and prints a message identifying each invalid value found for each field. From 1 to 10 fields can be specified. DFSORT is called to copy the indd data set to ICETOOLs E35 user exit. ICETOOL uses its E35 user exit to examine the digits and sign of each value for validity, and for each invalid value found, prints an error message containing the record number and field value (in hexadecimal). You must not supply your own DFSORT MODS, INREC, or OUTREC statement, because they would override the DFSORT statements passed by ICETOOL for this operator. Notes: 1. Values with invalid decimal digits are also identified for the DISPLAY, OCCUR, RANGE, and STATS operators. 2. The DISPLAY operator can be used to print a report identifying the relative record number, hexadecimal value, and associated fields for each invalid (and valid) decimal value, as shown in Example 9 under DISPLAY Operator on page 502.

Operand Descriptions
The operands described below can be specified in any order. FROM(indd) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. ON(p,m,f) Specifies the position, length, and format of a decimal field to be used for this operation. p specifies the first byte of the field relative to the beginning of the input record. p is 1 for the first data byte of a fixed-length record and 5 for the first data byte of a variable-length record as illustrated below (RRRR represents the 4-byte record descriptor word):
Fixed-length record | Variable-length record | D | A | T | A | ... | | R | R | R | R | D | A | T | A | ... p= 1 2 3 4 | p= 1 2 3 4 5 6 7 8

Chapter 6. Using ICETOOL

607

VERIFY Operator
m specifies the length of the field in bytes. A field must not extend beyond position 32752 or beyond the end of a record. The maximum length for a field depends on its format. f specifies the format of the field as shown below:
Format Code PD ZD Length 1 to 16 bytes 1 to 31 bytes Description Signed packed decimal Signed zoned decimal

Note: See Appendix C, Data Format Descriptions, on page 769 for detailed format descriptions.

A value is considered invalid under one of the following circumstances: v it contains A-F as a digit (examples: a PD field of 00AF or a ZD field of F2FB) v it contains 0-9 as a sign and the NOSIGN operand is not specified (examples: a PD field of 3218 or a ZD field of F235). If the number of bad values reaches the LIMIT for invalid decimal values, ICETOOL terminates the operation. If the LIMIT operand is not specified, a default of 200 is used for the invalid decimal value limit. NOSIGN Specifies that the sign of the decimal values is not to be validity checked (overriding the default of checking for 0-9 as invalid signs). LIMIT(n) See the discussion of this operand on the DISPLAY statement in DISPLAY Operator on page 502. VSAMTYPE(x) See the discussion of this operand on the COPY statement in COPY Operator on page 491.

VERIFY Example
VERIFY FROM(NEW) ON(22,16,PD) ON(7,9,ZD) VERIFY FROM(NEW) ON(22,16,PD) ON(7,9,ZD) NOSIGN LIMIT(10)

The first VERIFY operator checks for invalid digits (A-F) and invalid signs (0-9) in the packed decimal values from positions 22-37 and the zoned decimal values from positions 7-15 of the NEW data set. A message is printed identifying each value (if any) that contains an invalid digit or sign. If 200 invalid values are found, the operation is terminated. The second VERIFY operator checks for invalid digits (A-F) in the packed decimal values from positions 22-37 and the zoned decimal values from positions 7-15 of the NEW data set. A message is printed identifying each value (if any) that contains an invalid digit. If 10 invalid values are found, the operation is terminated. Note: The DISPLAY operator can be used to print a report identifying the relative record number, hexadecimal value, and associated fields for each invalid (and valid) decimal value, as shown in Example 9 under DISPLAY Operator on page 502.

608

z/OS V1R10.0 DFSORT Application Programming Guide

Calling ICETOOL from a Program

Calling ICETOOL from a Program

ICETOOL can be called from an assembler program using the LINK, ATTACH, or XCTL system macros. Standard linkage conventions must be used. When ICETOOL finishes processing, it returns to the calling program with register 15 set to the highest operation return code encountered. See ICETOOL Return Codes on page 616 for an explanation of the ICETOOL return codes. When you call ICETOOL from a program, you have a choice of two different interfaces: the TOOLIN Interface and the Parameter List Interface.

TOOLIN Interface
With the TOOLIN Interface, you supply ICETOOL statements in the TOOLIN data set. ICETOOL prints messages in the TOOLMSG data set, but does not return information directly to your program. To use the TOOLIN interface, set a value of 0 in register 1, or place the address of a 4-byte field containing X80000000 in register 1, before calling ICETOOL as shown below:
... SLR R1,R1 LINK EP=ICETOOL ... LA R1,NOPLIST LINK EP=ICETOOL ... NOPLIST DC X80,AL3(0) ...

TOOLIN INTERFACE - METHOD 1 CALL ICETOOL TOOLIN INTERFACE - METHOD 2 CALL ICETOOL TOOLIN INTERFACE INDICATOR

Parameter List Interface

The Parameter List Interface allows you to use the information derived by ICETOOL in your program. With this interface, you supply ICETOOL statements in a parameter list. ICETOOL prints messages in the TOOLMSG data set, and puts an operation status indicator and operation-specific values in the parameter list for use by your calling program. Figure 39 on page 610 shows the format of the parameter list used with the Parameter List Interface. Table 69 on page 611 shows the operation-specific values returned to the calling program.

Chapter 6. Using ICETOOL

609

Calling ICETOOL from a Program

Register 1

Flags Statement Area 1 Address Return Area 1 address

Starement Area n Address Return Area n Address X'FFFFFFFF"

Figure 39. Parameter List for Parameter List Interface

The flags field must be specified. A 4-byte field containing X FFFFFFFF must be used to indicate the end of the parameter list. It can be coded after any pair of statement/return addresses. All addresses in the parameter list must be 31-bit addresses or clean 24-bit addresses (the first 8 bits contain zeros).

Explanation of Fields
Flags Bit 0 = 0: Use the Parameter List Interface. Process ICETOOL statements from this parameter list and return information to this parameter list. Ignore TOOLIN. Bit 0 = 1: Use the TOOLIN Interface. Process ICETOOL statements from TOOLIN. Ignore this parameter list. Bits 1-31: Reserved. Must be set to zero to ensure future extendability. Statement Area Address and Statement Area Each statement area address gives the location of a statement area that describes an ICETOOL operation to be performed. If the statement area address is 0, ICETOOL ignores this statement area/return area pair. Otherwise, the statement area address must point to a statement area in the following format: v A 2-byte length field containing the length of the statement area for this operation. If this field is 0, ICETOOL ignores this statement area/return area pair. v One or more 80-character ICETOOL statement images in the format described in ICETOOL Statements on page 490. Each statement area must have one operator statement. Comment and blank statements before the operator statement are processed. Comment, blank, and additional operator statements after the end of the first operator statement are ignored. Return Area Address and Return Area Each return area address gives the location of a return area in which ICETOOL is to return operation-specific information for the operation described in the corresponding statement area. If the return area address is 0, ICETOOL does

610

z/OS V1R10.0 DFSORT Application Programming Guide

Calling ICETOOL from a Program

not return any information for this operation. Otherwise, the return area address must point to a return area in the following general format: v A 2-byte length field containing the length of the return area for this operation. If this field is 0, ICETOOL does not return any information for this operation. v A 1-byte operation status indicator which is set by ICETOOL as follows: 0= 4= This operation was run and completed with return code 0 or 4. Operation-specific values (see below) were returned.

This operation was not run (for example, scan mode was in effect) or did not complete with return code 0 or 4. Operation-specific values (see below) were not returned. v Operation-specific values. Each count value returned by ICETOOL is an 8-byte packed decimal value with a C for a positive sign or a D for a negative sign. For a STATS operator, each minimum, maximum, average and total value returned by ICETOOL is a 16-byte packed decimal value with a C for a positive sign or a D for a negative sign. If ICETOOL set the operation status to 4, it did not return any values for this operation. Note: Programs in LPALIB that call ICETOOL must provide return areas that ICETOOL can store into. The required return area length and the operation-specific values returned for each operator are shown in Table 69. If the return area length is less than the length required, ICETOOL issues a message and terminates the operation.
Table 69. Return Area Lengths/Operation-Specific Values Operator COPY COUNT DEFAULTS DISPLAY MODE OCCUR Return Area Length (Bytes) 1 9 1 9 1 17 Operation-Specific Values Returned None Count of records processed, or 0 if any criteria specified None Count of records processed None Count of records processed, count of records resulting from criteria Count of records processed, count of values in range Count of records processed, count of records resulting from criteria None Count of records processed, count of records resulting from criteria

RANGE SELECT

17 17

SORT SPLICE

1 17

Chapter 6. Using ICETOOL

611

Calling ICETOOL from a Program

Table 69. Return Area Lengths/Operation-Specific Values (continued) Operator STATS Return Area Length (Bytes) 64*n+9 Operation-Specific Values Returned Count of records processed, minimum for ON field 1, maximum for ON field 1, average for ON field 1, total for ON field 1, ... minimum for ON field n, maximum for ON field n, average for ON field n, total for ON field n Count of records processed, count of unique values Count of records processed

UNIQUE VERIFY

17 9

Parameter List Interface Example

The example in Figure 40 on page 613 shows a portion of an assembler language program that uses the Parameter List Interface. Figure 41 on page 615 shows the JCL you might use to run the program in Figure 40 on page 613.

612

z/OS V1R10.0 DFSORT Application Programming Guide

Calling ICETOOL from a Program

DEPTVIEW CSECT ... * SET UP PARAMETER LIST AND CALL ICETOOL LA R1,PARLST LOAD ADDRESS OF PARAMETER LIST LINK EP=ICETOOL CALL ICETOOL LTR R15,R15 IF ANY OPERATIONS WERE NOT SUCCESSFUL, BNZ CKSTAT1 DETERMINE WHICH ONE FAILED * ALL OPERATIONS WERE SUCCESSFUL * CHECK EMPLOYEES PER DEPARTMENT AGAINST ACCEPTABLE LEVEL CP RT2AVG1,EMAVGCK IF AVERAGE IS ACCEPTABLE, BNH CKQUAL NO MESSAGE IS NEEDED * ISSUE A MESSAGE SHOWING AVERAGE, MINIMUM, MAXIMUM, AND * TOTAL NUMBER OF EMPLOYEES PER DEPARTMENT. ... * CHECK EXPENSES PER DEPARTMENT AGAINST ACCEPTABLE LEVEL CKQUAL CP RT2AVG2,TLAVGCK IF AVERAGE IS ACCEPTABLE, BNH PCTCALC NO MESSAGE IS NEEDED * ISSUE A MESSAGE SHOWING AVERAGE, MINIMUM, MAXIMUM, AND * TOTAL EXPENSES PER DEPARTMENT. ... * CALCULATE THE PERCENTAGE OF DEPARTMENTS OVER/UNDER EMPLOYEE LIMIT PCTCALC MVC WORK+2(4),RT3RCDS+4 COPY NUMBER OF DEPARTMENTS SP WORK+2(4),RT3RNG+4(4) SUBTRACT NUMBER WITHIN LIMITS TO * GET NUMBER OVER/UNDER LIMIT CP WORK+2(4),P0 IF NONE OVER/UNDER LIMIT, BE PCTPRT PERCENTAGE IS ZERO MP WORK+2(4),P100 MULTIPLY NUMBER OVER/UNDER BY 100 DP WORK(6),RT3RCDS+4(4) DIVIDE BY NUMBER OF DEPARTMENTS * ISSUE A MESSAGE SHOWING THE PERCENTAGE OF DEPARTMENTS THAT ARE * OVER/UNDER EMPLOYEE LIMIT PCTPRT UNPK PCTVAL,WORK(2) CONVERT AVERAGE TO PRINTABLE EBCDIC OI PCTVAL+2,XF0 ENSURE LAST DIGIT IS PRINTABLE ... * ONE OR MORE OPERATIONS FAILED CKSTAT1 CLI RT1STAT,0 IF OPERATION 1 WORKED, BNE CKSTAT2 CHECK OPERATION 2 * ISSUE MESSAGE: OPERATION 1 FAILED - CHECK TOOLMSG ... * PARAMETER LIST PARLST DC A(0) USE PARAMETER LIST INTERFACE DC A(ST1A) STATEMENT AREA 1 ADDRESS DC A(RT1A) RETURN AREA 1 ADDRESS DC A(ST2A) STATEMENT AREA 2 ADDRESS DC A(RT2A) RETURN AREA 2 ADDRESS DC A(ST3A) STATEMENT AREA 3 ADDRESS DC A(RT3A) RETURN AREA 3 ADDRESS DC F.*-1 END OF PARAMETER LIST* OPERATOR STATEMENT AREAS

Figure 40. ICETOOL Parameter List Interface Example (Part 1 of 2)

Chapter 6. Using ICETOOL

613

Calling ICETOOL from a Program

* COPY OPERATION ST1A DC AL2(ST1E-ST1) LENGTH OF STATEMENT AREA 1 ST1 DC CL80* CREATE TWO COPIES OF THE DENVER SITE DC CL80* DEPARTMENT RECORDS DC CL80COPY FROM(IN) TO(OUT1,OUT2) USING(CTL1) ST1E EQU * * STATS OPERATION ST2A DC AL2(ST2E-ST2) LENGTH OF STATEMENT AREA 2 ST2 DC CL80* GET STATISTICS FOR NUMBER OF EMPLOYEES DC CL80* AND TRAVEL EXPENSES PER DEPARTMENT DC CL80STATS FROM(OUT1) ON(15,2,PD) ON(28,8,ZD) ST2E EQU * * RANGE OPERATION ST3A DC AL2(ST3E-ST3) LENGTH OF STATEMENT AREA 3 ST3 DC CL80* DETERMINE THE NUMBER OF DEPARTMENTS THAT ARE DC CL80* WITHIN THE LIMIT FOR NUMBER OF EMPLOYEES DC CL80RANGE FROM(OUT1) ON(15,2,PD) - DC CL80 HIGHER(10) LOWER(21) ST3E EQU * * RETURN AREAS COPY OPERATION RT1A DC AL2(RT1E-RT1STAT) LENGTH OF RETURN AREA 1 RT1STAT DS C OPERATION STATUS RT1E EQU * * STATS OPERATION RT2A DC AL2(RT2E-RT2STAT) LENGTH OF RETURN AREA 2 RT2STAT DS C OPERATION STATUS RT2RCDS DS PL8 COUNT OF RECORDS PROCESSED RT2MIN1 DS PL16 FIELD 1 - MINIMUM VALUE RT2MAX1 DS PL16 FIELD 1 - MAXIMUM VALUE RT2AVG1 DS PL16 FIELD 1 - AVERAGE VALUE RT2TOT1 DS PL16 FIELD 1 - TOTAL VALUE RT2MIN2 DS PL16 FIELD 2 - MINIMUM VALUE RT2MAX2 DS PL16 FIELD 2 - MAXIMUM VALUE RT2AVG2 DS PL16 FIELD 2 - AVERAGE VALUE RT2TOT2 DS PL16 FIELD 2 - TOTAL VALUE RT2E EQU * * RANGE OPERATION RT3A DC AL2(RT3E-RT3STAT) LENGTH OF RETURN AREA 3 RT3STAT DS C OPERATION STATUS RT3RCDS DS PL8 COUNT OF RECORDS PROCESSED RT3RNG DS PL8 COUNT OF VALUES IN RANGE RT3E EQU * * VARIABLES/CONSTANTS WORK DS PL6 WORKING VARIABLE P100 DC P100 CONSTANT 100 P0 DC P0 CONSTANT 0 EMAVGCK DC P17 ACCEPTABLE AVERAGE EMPLOYEE COUNT TLAVGCK DC P5000 ACCEPTABLE AVERAGE TRAVEL EXPENSES PCTVAL DS PL3 PERCENTAGE OF DEPARTMENTS THAT ARE * OVER/UNDER EMPLOYEE LIMIT ...

Figure 40. ICETOOL Parameter List Interface Example (Part 2 of 2)

614

z/OS V1R10.0 DFSORT Application Programming Guide

ICETOOL Notes and Restrictions

//EXAMP JOB A402,PROGRAMMER //INVOKE EXEC PGM=DEPTVIEW,REGION=1024K //STEPLIB DD DSN=... Link library containing DEPTVIEW //TOOLMSG DD SYSOUT=A //DFSMSG DD SYSOUT=A //IN DD DSN=ALL.DEPTS,DISP=SHR //OUT1 DD DSN=ALL.DEPTS.BACKUP1,DISP=OLD //OUT2 DD DSN=ALL.DEPTS.BACKUP2,DISP=OLD //CTL1CNTL DD * * SELECT ONLY THE DENVER SITE DEPARTMENT RECORDS INCLUDE COND=(1,12,CH,EQ,CDENVER) /*

Figure 41. JCL for Parameter List Interface Program Example

ICETOOL Notes and Restrictions

v Small REGION values can cause storage problems when ICETOOL calls DFSORT. Large REGION values give DFSORT the flexibility to use the storage it needs for best performance. We recommend that you use a REGION value of at least 1024K for ICETOOL. v Each ICETOOL operation results in a set of ICETOOL messages in the TOOLMSG data set, and a corresponding set of DFSORT messages in the DFSMSG data set. For a particular call to DFSORT, you can relate the sets of messages in the TOOLMSG and DFSMSG data sets by using the unique identifier for that call. Just match the identifier printed in ICETOOL message ICE606I or ICE627I to the same identifier printed in DFSORT message ICE200I. This is particularly important if an ICETOOL operation fails due to an error detected by DFSORT (return code 16). | | | | | | | | v Because ICETOOL calls DFSORT, the installation defaults used for DFSORT are those in effect for the appropriate program-invoked environment, that is, the ICEAM2 or ICEAM4 defaults, or the ICETDx defaults activated for ICEAM2 or ICEAM4. The DFSORT installation defaults apply only to DFSORT, not to ICETOOL. For example, installation option MSGCON=ALL causes DFSORT, but not ICETOOL, to write messages to the master console. The one exception is the SDBMSG installation option; the value in effect from ICEAM2 or ICEAM4 is used for ICETOOLs TOOLMSG data set. v When ICETOOL calls DFSORT, it passes control statements and options appropriate to the specific operations being performed. You should not override the DFSORT control statements or options passed by ICETOOL unless you understand the ramifications of doing so. For example, ICETOOL passes the NOABEND option to DFSORT to ensure that ICETOOL will regain control if DFSORT issues an error message. If you specify:
//DFSPARM DD * DEBUG ABEND

you cause DFSORT to abend when it issues an error message, thus preventing ICETOOL from performing subsequent operators. v Tape work data sets cannot be used with ICETOOL. v An ON field must not include bytes beyond the fixed part of variable length input records. The entire field specified must be present in every input record, otherwise, DFSORT issues message ICE015A, ICE218A, or ICE027A and terminates.

Chapter 6. Using ICETOOL

615

ICETOOL Return Codes

ICETOOL Return Codes

ICETOOL sets a return code for each operation it performs in STOP or CONTINUE mode and passes back the highest return code it encounters to the operating system or the invoking program. For successful completion of all operations, ICETOOL passes back a return code of 0 or 4 to the operating system or the invoking program. For unsuccessful completion due to an unsupported operating system, ICETOOL passes back a return code of 24 to the operating system or invoking program. For unsuccessful completion of one or more operations, ICETOOL passes back a return code of 12, 16, or 20 to the operating system or the invoking program. The meanings of the return codes that ICETOOL passes back (in register 15) are: 0 4 Successful completion. All operations completed successfully. Successful completion. All operations completed successfully. Either: v RC4 was specified for an ICETOOL COUNT operator and the record count met the specified criteria, or v DFSORT passed back a return code of 4 for one or more operations. See DFSORT Messages and Return Codes on page 22 for details. Unsuccessful completion. ICETOOL detected one or more errors that prevented it from completing successfully. Messages for these errors were printed in the TOOLMSG data set. Unsuccessful completion. DFSORT detected one or more errors that prevented ICETOOL from completing successfully. Messages for these errors were printed in the DFSMSG data set. Message data set error. The TOOLMSG DD statement was not present or the TOOLMSG data set was not opened. Unsupported operating system. This operating system is not supported by this release of DFSORT.

12

16

20 24

616

z/OS V1R10.0 DFSORT Application Programming Guide

Chapter 7. Using Symbols for Fields and Constants

Field and Constant Symbols Overview . . . . DFSORT Example . . . . . . . . . . SYMNAMES DD Statement . . . . . . . SYMNOUT DD Statement . . . . . . . . SYMNAMES Statements . . . . . . . . . Comment and Blank Statements . . . . . Symbol Statements . . . . . . . . . Keyword Statements . . . . . . . . . Using SYMNOUT to Check Your SYMNAMES Statements . . . . . . . . . . . . Using Symbols in DFSORT Statements . . . . SORT and MERGE . . . . . . . . . SUM . . . . . . . . . . . . . . . . . . . . . . . . . . 617 618 620 620 620 620 621 630 633 633 634 635 INCLUDE and OMIT . . . . . . INREC and OUTREC . . . . . . OUTFIL . . . . . . . . . . Using Symbols in ICETOOL Operators . COUNT . . . . . . . . . . DISPLAY . . . . . . . . . . OCCUR . . . . . . . . . . RANGE . . . . . . . . . . SELECT . . . . . . . . . . SPLICE . . . . . . . . . . STATS, UNIQUE and VERIFY . . . ICETOOL Example . . . . . . Notes for Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635 636 638 641 641 641 642 642 642 642 642 642 644

Field and Constant Symbols Overview

This chapter describes DFSORTs simple and flexible method for using symbols in DFSORT and ICETOOL statements. You can define and use a symbol for any field, constant, or output column that is recognized in a DFSORT control statement or ICETOOL operator. This makes it easy to create and reuse collections of symbols (that is, mappings) representing information associated with various record layouts. In addition, you can obtain and use collections of DFSORT symbols created specifically for records produced by other products (for example, RACF, DFSMSrmm and DCOLLECT) or by your site. Visit the DFSORT home page at the following URL to obtain information about downloading DFSORT symbol mappings for records produced by other products, and examples that use these symbols:
http://www.ibm.com/storage/dfsort

Symbols can increase your productivity by automatically providing the positions, lengths and formats of the fields, the values of the constants, and the positions of the output columns associated with the particular records you are processing with DFSORT or ICETOOL. You can even use system symbols (for example, &JOBNAME.) in your symbol constants. To use symbols for DFSORT or ICETOOL, you just: 1. Create or obtain the DFSORT symbol data sets you need. Symbol data sets contain symbols that map the fields in your records, and constants used for comparisons, titles, headings and so on. The symbols are specified in DFSORTs simple but flexible SYMNAMES statement format. Symbols can be easily added or modified using an editor, such as ISPF EDIT. 2. Include a SYMNAMES DD statement in your job. SYMNAMES specifies one or more symbol data sets (sequential, partitioned member, DD *) to be used for your DFSORT or ICETOOL application. SYMNAMES can be used to concatenate as many symbol data sets as you like.

Copyright IBM Corp. 1973, 2006

617

Using Symbols for Fields and Constants

3. Use the symbols from SYMNAMES where appropriate in DFSORT control statements or ICETOOL operators. You can mix symbols (for example, Last_Name) with regular fields (for example, p,m,f) and constants (for example, Cstring). DFSORT or ICETOOL will read SYMNAMES and use the symbols it contains to transform your statements by performing symbol substitution. DFSORT or ICETOOL will then use the transformed statements as if you had specified them directly. If your record layout changes, just make a corresponding change to your DFSORT symbol data set. DFSORT will use the new mapping to transform your symbols correctly, even if positions change, so you wont have to change your statements. Be sure that your symbol definitions match your record layout before you attempt to use them.

DFSORT Example
The example below shows the JCL and control statements for a simple DFSORT job that uses symbols. Lets say you created a symbols data set named MY.SYMBOLS that contains the following SYMNAMES statements:
* Fields First_Name,6,20,CH Last_Name,*,=,= Account_Number,53,3,PD SKIP,2 Balance,*,6,ZD Type,*,8,CH * Constants Loan,LOAN Check,CHECKING Level1,50000 Level2,-100

Heres the JCL and control statements for the example:

//EXAMP JOB A402,PROGRAMMER //RUNIT EXEC PGM=ICEMAN //SYMNAMES DD DSN=MY.SYMBOLS,DISP=SHR //SYMNOUT DD SYSOUT=* //SYSOUT DD SYSOUT=* //SORTIN DD ... //SORTOUT DD ... //SYSIN DD * INCLUDE COND=((Type,EQ,Loan,AND,Balance,GT,Level1),OR, (Type,EQ,Check,AND,Balance,LE,Level2)) SORT FIELDS=(Last_Name,A,First_Name,A, Type,A,Account_Number,D) /*

This example is only meant to give you a quick overview of how symbols can be used. The rest of this chapter will explain all of the details, but here are a few important things to take note of: v The SYMNAMES DD indicates you want DFSORT or ICETOOL to do symbol processing. The SYMNAMES data set contains the symbols for fields and constants. v DFSORT or ICETOOL will print your original symbols and the symbol table constructed from them in the SYMNOUT data set, if you specify it. You might

618

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

want to use SYMNOUT while debugging a set of symbols and then remove it, or you might want to keep SYMNOUT permanently so you can always see your original symbols and the symbol table. v The simple, yet flexible, format for SYMNAMES statements is:
symbol,value remark

where value can represent a field (p,m,f or p,m or p), a parsed field (%nn), or a constant (Cstring, cstring, string, Sstring, sstring, Xstring, xstring, Bstring, bstring, n, +n or n). Leading blanks are allowed before symbol so indentation can be used. For example, the following SYMNAMES statements could be specified:
Div1_Department,8,1,BI Research,B0001.... Marketing,B0010.... Development,B0100.... Division 1 Department Research Departments Marketing Departments Development Departments

v Symbols are case-sensitive: Frank, FRANK and frank are three different symbols. v An asterisk (*) can be used to assign the next position to p. For example:
Symbola,6,20,CH Symbolb,*,5,BI Symbolc,*,12,ZD

is the same as specifying:

Symbola,6,20,CH Symbolb,26,5,BI Symbolc,31,12,ZD

By using * for p, you can map consecutive fields in your records without having to compute their actual positions. v SKIP,n can be used to advance the next position by n bytes so it can be used for *. For example:
Symbola,6,20,CH SKIP,2 Symbolb,*,5,BI

is the same as specifying:

Symbola,6,20,CH Symbolb,28,5,BI

SKIP,n gives you an easy way to skip unused bytes. Other mapping aids allow you to reset the next position (POSITION,q or POSITION,symbol), or align the next position on a halfword (ALIGN,H), fullword (ALIGN,F) or doubleword (ALIGN,D). v An equal sign (=) can be used for p, m or f to assign the previous position, length or format to p, m, or f, respectively. For example:
Symbola,6,20,CH Symbola1,=,8,= Symbola2,*,12,= Symbold,*,=,ZD

is the same as specifying:

Symbola,6,20,CH Symbola1,6,8,CH Symbola2,14,12,CH Symbold,26,12,ZD

By using = and *, you can easily map fields onto other fields.

Chapter 7. Using Symbols for Fields and Constants

619

Using Symbols for Fields and Constants

v Symbols for fields and constants can be specified in any order. However, the use of * and = imposes order dependencies on symbols for fields. v Comment statements and blank statements are allowed in SYMNAMES.

SYMNAMES DD Statement
A SYMNAMES DD statement indicates you want DFSORT or ICETOOL to do symbol processing. It specifies the SYMNAMES data set (SYMNAMES for short), which can consist of one DFSORT symbol data set or many concatenated symbol data sets. A symbol data set can be a sequential data set, a partitioned member or a DD * data set; all three types can be concatenated together for the SYMNAMES DD. Each symbol data set must contain SYMNAMES statements describing the symbols for fields and constants to be used for the DFSORT or ICETOOL application. Each symbol data set must have the following attributes: RECFM=F or RECFM=FB and LRECL=80. For best performance, use a large block size, such as the system determined optimum block size, for all DFSORT symbol data sets. If a SYMNAMES DD statement is not present, or SYMNAMES is empty, symbol processing is not performed.

SYMNOUT DD Statement
A SYMNOUT DD statement specifies a data set in which you want DFSORT or ICETOOL to print your original SYMNAMES statements and the symbol table constructed from them. DFSORT or ICETOOL uses RECFM=FBA, LRECL=121 and the specified BLKSIZE for the SYMNOUT data set (SYMNOUT for short). If the BLKSIZE you specify is not a multiple of 121, or you do not specify the BLKSIZE: v the system determined optimum block size is used, if supported v otherwise, BLKSIZE=121 is used. For best performance, use a large block size, such as the system determined optimum block size, for the SYMNOUT data set.

SYMNAMES Statements
Each symbol in SYMNAMES must be described using a SYMNAMES statement. A SYMNAMES statement can be a symbol statement, keyword statement, comment statement or blank statement.

Comment and Blank Statements

A statement with an asterisk (*) in column 1 is treated as a comment statement. It is printed in SYMNOUT (if specified), but otherwise not processed. A statement with blanks in columns 1 through 80 is treated as a blank statement. It is printed in SYMNOUT (if specified), but otherwise not processed.

620

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

Symbol Statements
The general format for a symbol statement is:
symbol,value remark

The general coding rules are as follows: v Columns 1 through 80 are scanned. v The symbol can start in column 1 or in any column after 1. v A remark is optional, but if specified, must be separated from the value by at least one blank. A remark is printed in SYMNOUT (if specified), but otherwise not processed. v A semicolon (;) can be used instead of a comma (,) between the symbol and the value. v Continuation is not allowed. Each symbol and value must be completely specified on one line. The specific syntax for symbol statements is:

symbol,

constant field parsed field

Symbol: A symbol can be 1 to 50 EBCDIC characters consisting of uppercase letters (A-Z), lowercase letters (a-z), numbers (0-9), the number sign (#), the dollar sign ($), the commercial at sign (@), the underscore(_) and the hyphen(-). The first character of a symbol must not be a number or a hyphen. Symbols are treated as case-sensitive: Frank, FRANK and frank are three different symbols. The following DFSORT/ICETOOL reserved words (uppercase only as shown) are not allowed as symbols: A, AC, ADD, ALL, AND, AQ, ASL, AST, BI, CH, CLO, COPY, COUNT, COUNT15, CSF, CSL, CST, CTO, D, DATE, DATE1, DATE1..., DATE2, DATE2..., DATE3, DATE3..., DATE4, DC1, DC2, DC3, DC4, DE1, DE2, DE3, DE4, DIV, DT1, DT2, DT3, D1, D2, E, F, FI, FL, FS, H, HEX, LS, MAX, MIN, MOD, MUL, Mn, Mnn, NONE, NUM, OL, OR, OT, PAGE, PAGEHEAD, PD, PDC, PDF, PD0, SEQNUM, SFF, SS, SUB, SUBCOUNT, SUBCOUNT15, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TIME, TIME1, TIME1P, TIME2, TIME2P, TIME3, TIME3P, TM1, TM2, TM3, TM4, TS, UFF, VALCNT, VLEN, X, Y2x, Y2xx, Z, ZD, ZDC, and ZDF, where n is 0-9 and x is any character. Lower case and mixed case forms of these words, such as None and page, can be used as symbols. POSITION, SKIP and ALIGN (uppercase only) are treated as keywords as discussed in Keyword Statements on page 630 and thus are not recognized as symbols. However, lowercase and mixed case forms of these words, such as Position and skip, can be used as symbols. Some examples of valid symbols are: Account_Number, CON12, PHONE#, count, SORT-KEY, and _Invalid.

Chapter 7. Using Symbols for Fields and Constants

621

Using Symbols for Fields and Constants

Some examples of invalid symbols are: 123_Account (starts with a number), COUNT (reserved word), DATE1-20 (reserved word), and -Invalid (starts with a hyphen). Constant: A constant can be a character string, system symbol string, hexadecimal string, bit string, decimal number, or two-digit year date string. A symbol for a constant value must be used only where such a constant is allowed and has the desired result. Otherwise, substitution of the constant for the symbol will result in an error message or unintended processing. For example, if the following SYMNAMES statement is specified:
SYMB,B10110001

SYMB can be used in this INCLUDE statement:

INCLUDE COND=(12,1,BI,EQ,SYMB)

because a bit string can be compared to a binary field. However, SYMB will result in an error message if used in this INCLUDE statement:
INCLUDE COND=(12,1,CH,EQ,SYMB)

because a bit string cannot be compared to a character field. Make sure the constants that will be substituted for your symbols are appropriate. If in doubt, check the rules for constants given in the description of the relevant operand. A symbol can represent one of the following types of constants: v A character string in the format xx...x, Cxx...x or cxx...x. The value x may be any EBCDIC character. You can specify up to 64 characters for the string. cxx...x will be treated like Cxx...x. Note: If you want to use system symbols (for example, &JOBNAME.) in your character strings, use a system symbol string (Sstring or sstring) as described below instead of a character string. If you want to include a single apostrophe in the character string, you must specify it as two single apostrophes (each pair of apostrophes counts as two characters towards the 64 character limit for the string). Thus:
Required: ONeill Specify: CONeill

Double-byte data may be used in a character string (each pair of shift-in/shift-out characters and each double-byte character counts as two characters towards the 64 character limit for the string). See INCLUDE Control Statement on page 98 for details on double-byte data. Some examples of valid character strings are: +0.193, cTitle, CONeil, CJ62,J82,M72 and . Some examples of invalid character strings are: CAB (apostrophes not paired), ctitle (ending apostrophe missing) and CONEIL (one apostrophe after O instead of two). You can use Cxx...x and xx...x interchangeably. xx...x will be substituted for symbols where appropriate even if Cxx...x is specified in SYMNAMES. Likewise, Cxx...x will be substituted for symbols where appropriate even if xx...x is specified in SYMNAMES. For example, if these SYMNAMES statements are specified:

622

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

My_Title,cMy Report My_Heading,CJanuary DEPT1,J82 DEPT2,cM72

the ICETOOL operator:

DISPLAY TITLE(My_Title) HEADER(My_Heading) ...

will be transformed to:

DISPLAY TITLE(My Report) HEADER(January) ...

and the INCLUDE statement:

INCLUDE COND=(5,3,EQ,DEPT1,OR,5,3,EQ,DEPT2),FORMAT=CH

will be transformed to:

INCLUDE COND=(5,3,EQ,CJ82,OR,5,3,EQ,CM72),FORMAT=CH

Although the rules for character strings used as symbols generally follow the rules for INCLUDE/OMIT character strings, keep in mind that the same rules do not apply for character strings in all DFSORT and ICETOOL operands, so use symbols representing character strings appropriately. For example, ICETOOL only allows up to 50 characters for a TITLE string, so TITLE(MYCON) would result in an error message if MYCON is a 64-character string, even though MYCON could be used without error in an INCLUDE statement. As another example, double-byte characters would be recognized in a character string substituted for a symbol in an INCLUDE statement, but would not be recognized in a character string substituted in an OUTREC statement. v A system symbol string in the format Soriginal_string or soriginal_string The original_string can contain any combination of EBCDIC characters and system symbols (&SYMBOL or &SYMBOL.) you want to use to form a character string. DFSORT will replace each system symbol in the system symbol string with its substitution text to create a character string in the format Cresult_string. For example, you could specify the following symbol statement in SYMNAMES:
Rpt_hdr,S Job &JOBNAME. was run on Sysplex &SYSPLEX. on &LWDAY

If you used this symbol statement in a job named TEST2 that you ran on sysplex MAS3 on a Thursday, DFSORT would transform it into the following symbol statement:
Rpt_hdr,C Job TEST2 was run on Sysplex MAS3 on THU

&JOBNAME. was replaced with TEST2, &SYSPLEX. was replaced with MAS3 and &LWDAY was replaced with THU. If you used this same symbol statement in a job named BIGTEST that you ran on sysplex MAS2 on a Monday, DFSORT would transform it into the following symbol statement:
Rpt_hdr,C Job BIGTEST was run on Sysplex MAS2 on MON

This time &JOBNAME. was replaced with BIGTEST, &SYSPLEX. was replaced with MAS2 and &LWDAY was replaced with MON. You could use the Rpt_hdr symbol in an OUTFIL statement like this:
OUTFIL HEADER2=(Rpt_hdr,5X,Page ,PAGE=(EDIT=(TTT)),/)

and get the heading you needed based on the setting of the system symbol values where and when the job was run.
Chapter 7. Using Symbols for Fields and Constants

623

Using Symbols for Fields and Constants

The types of system symbols you can use in a system symbol string are: Dynamic system symbols like &YYMMDD, &LYYMMDD, &HHMMSS, &LHHMMSS, &DAY, &LDAY, &HR, &LHR, &JDAY, &LJDAY, &JOBNAME, &MIN, &LMIN, &MON, &LMON, &SEC, &LSEC, &WDAY, &LWDAY, &YR2, &LYR2, &YR4, and &LYR4. System-defined static system symbols like &SYSCLONE, &SYSNAME, &SYSPLEX, &SYSR1, and &SYSALVL. Installation-defined static system symbols specified by your installation in an IEASYMxx member of SYS1.PARMLIB. Note: System symbols must be specified using all uppercase characters. Lowercase characters are not recognized as system symbols. For example, &JOBNAME is recognized as a system symbol, but &jobname and &Jobname are not. You can use all three types of system symbols separately or in combination within a system symbol string. You can also use all of the system symbol string building facilities such as substring notation, concatenation, embedded blanks, and so on, in a system symbol string. Thus, system symbol strings can be very simple like this one:
Sysname,s&SYSNAME

Or more complex like this one:

Dsn1,sACCT.&SYSNAME(3:2)..D&LJDAY

For more information on system symbols, see z/OS MVS Initialization and Tuning Reference, SA22-7592. Note: JCL symbols and IPCS symbols are not system symbols and will not be recognized or replaced in a system symbol string. soriginal_string will be treated like Soriginal_string. If you want to include a single apostrophe in the system symbol string, you must specify it as two single apostrophes. DFSORT uses the ASASYMBM service to transform Soriginal_string into Cresult_string. If your system symbol string has errors involving symbol names, substring notation, and so on, ASASYMBM transforms the symbol system string to a character string according to its rules for substitution. For example, if you specify these symbol statements:
Ok,S&YR4(1:2).&SYSNAME. Bad,S&YR4(1.2).&SYSNAM.

where the valid substring notation 1:2 and the known system symbol &SYSNAME. (for example, ED53) are used for Ok, but the invalid substring notation 1.2 and the unknown system symbol &SYSNAM. are used for Bad, the resulting symbol statements are:
Ok,C20EDS3 Bad,C2006(1.2).&SYSNAM.

See z/OS MVS Programming: Assembler Services Reference ABE-HSP, SA22-7606 for complete details on the ASASYMBM service. After a symbol statement containing a system symbol string (Soriginal_string) is transformed into a symbol statement containing the resulting character string (Cresult_string), it will be error checked and processed like any other symbol statement containing a character string. See the description of character string above for details.

624

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

If a SYMNOUT data set is specified, it will show the symbol statement containing the original system symbol string as well as the transformed symbol statement containing the resulting character string. This can be helpful for debugging errors or unexpected results in your system symbol strings. v A hexadecimal string in the format Xyy...yy or xyy...yy. The value yy represents any pair of hexadecimal digits. Each hexadecimal digit must be 0-9, A-F or a-f. You can specify up to 32 pairs of hexadecimal digits. xyy...yy will be treated like Xyy...yy. a-f will be treated like A-F. Some examples of valid hexadecimal strings are: XF2C3, x2fa71e, and X07. Some examples of invalid hexadecimal strings are: XF2G301 (G is not a valid hexadecimal digit), xbf3 (unpaired hexadecimal digits) and X (no hexadecimal digits). v A bit string in the format Bbbbbbbbb...bbbbbbbb or bbbbbbbbb...bbbbbbbb. The value bbbbbbbb represents 8 bits that constitute a byte. Each bit must be 1, 0 or . (period). You can specify up to 8 groups of 8 bits. bbbbbbbbb...bbbbbbbb will be treated like Bbbbbbbbb...bbbbbbbb. Some examples of valid bit strings are: B01100100, b11..00..000..111 and B11....... Some examples of invalid bit strings are: B0101 (not a multiple of eight bits), b00..11.... (not a multiple of eight bits), b00000002 (2 is not a valid bit) and B (no bits). v A decimal number in the format n, +n or n. You can specify from 1 to 31 significant digits. Some examples of valid decimal numbers are: +270, 270, 000036, +0 and 2000000. Some examples of invalid decimal numbers are: ++15 (too many plus signs), 280 (sign in wrong place) and 2.8 (period is not allowed). v A two-digit year date string in the format Ystring or ystring. string can be: yy, yyx,yyxx, yyxxx or yyxxxx where y is a hexadecimal year digit (0-9) and x is a hexadecimal non-year digit (0-9). Uppercase, lowercase or mixed case forms of LOW, BLANKS, or HIGH. A two-digit year date string in the format Ydatex, Ydatex+n or Ydatex-n. - datex can be uppercase, lowercase or mixed case forms of DATE1, DATE2 or DATE3. - n is a decimal number representing the number of days for DATE1 and DATE3, or the number of months for DATE2. Some examples of valid two-digit year date strings are: Y99, y00123, ydate2, YDATE1+20, yDate3-1, and YBlanks. Some examples of invalid two-digit year date strings are: Y9, yAB123, YDATE2-3, and Yblank. Field: A field can be specified as p,m,f (position, length and format), p,m (position and length) or p (position only). A symbol for a field value must be used only where such a field is allowed and has the desired result. Otherwise, substitution of the field for the symbol will result in an error message or unintended processing. For example, if the following SYMNAMES statement is specified:
Field1,15,2,CH

Chapter 7. Using Symbols for Fields and Constants

625

Using Symbols for Fields and Constants

Field1 can be used in a SORT statement such as:
SORT FIELDS=(Field1,A)

because a character field is allowed in a SORT statement. However, Field1 will result in an error message if used in a SUM statement such as:
SUM FIELDS=(Field1)

because a character field is not allowed in a SUM statement. As another example, Field1: can be used in an INREC statement such as:
OUTFIL OVERLAY=(Field1:CAB)

to set the output column to 15, because column notation is allowed in the BUILD or OVERLAY operand of an INREC or OUTREC statement and in the BUILD, OVERLAY, HEADERx, or TRAILERx operand of an OUTFIL statement. However, Field1: will result in an error message if used in any other operand, such as WHEN. Make sure the fields that will be substituted for your symbols are appropriate. If in doubt, check the rules for p, m, f, and c: given in the description of the relevant operand. You can specify p,m,f for your field symbols and then use them where p,m is required because DFSORT or ICETOOL will substitute just p,m when appropriate. You can specify p,m,f or p,m for your field symbols and then use them where c: is required because DFSORT will substitute just p: when appropriate. For example, if you specify the following in SYMNAMES:
First_Field,12,2,BI Second_Field,18,6,CH Third_Field,28,5,PD Fourth_Field,36,3 Fifth_Field,52,4,PD Max,200000 Outcol2,16

These DFSORT control statements:

OMIT COND=(Fifth_Field,GT,Max) SORT FIELDS=(First_Field,A,Fourth_Field,A),FORMAT=CH SUM FIELDS=(Second_Field,ZD) OUTFIL OUTREC=(First_Field:First_Field, Outcol2:Third_Field,M11, Fourth_Field)

will be transformed to:

OMIT COND=(52,4,PD,GT,200000) SORT FIELDS=(12,2,A,36,3,A),FORMAT=CH SUM FIELDS=(18,6,ZD) OUTFIL BUILD=(12:12,2,16:28,5,PD,M11,36,3)

Note that DFSORT did the following substitutions: v OMIT statement: p,m,f for Fifth_Field as required by COND without FORMAT. v SORT statement: p,m for First_Field and Fourth_Field as required by FIELDS with FORMAT. v SUM statement: p,m for Second_Field as required for symbol,f (that is, Second_Field,ZD).

626

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

v OUTFIL statement: p: for First_Field: and Outcol2: as required by the OUTREC operand for an output column. p,m for First_Field and Fourth_Field as required by the OUTREC operand for an unedited field. p,m,f for Third_Field as required by the OUTREC operand for an edited field (that is, Third_Field,M11). The general rules for using p, m and f in symbol statements are as follows: v p can be a number, an asterisk (*) or an equal sign (=). A number from 1 to 32752 is allowed in p,m or p,m,f. Because p (position only) cannot be distinguished from the constant n, 1 to 15 significant digits are allowed for p (position only). An asterisk (*) can be used to assign the next position to p. Each time a symbol for p,m,f or p,m is read, the next position is set to p+m. Additionally, the next position can be modified by keyword statements (see Keyword Statements on page 630). When * is specified for p, the next position is assigned to p. If the next position has not been set when * is used for p (for example, * is used in the first symbol), p is set to 1. The symbol table printed in the SYMNOUT data set (if specified) will show you the actual positions assigned when you specify * for p. As an example of how * can be used, if you specify the following SYMNAMES statements:
Sym1,*,5,ZD Con1,27 Sym2,*,2,BI Field1,8,13,CH Field2,*,5,PD Field3,*,2,FI

SYMNOUT will show the following symbol table:

Sym1,1,5,ZD Con1,27 Sym2,6,2,BI Field1,8,13,CH Field2,21,5,PD Field3,26,2,FI

By using * for p, you can map consecutive fields in your records without having to compute their actual positions. You can also map fields added between other fields without having to change the p values for the original or inserted fields. * is also useful for creating mappings of contiguous fields using concatenated symbol data sets. As a simple example, if you specify:
//SYMNAMES DD DSN=MY.SYMPDS(RDW),DISP=SHR // DD DSN=MY.SYMPDS(SECTION1),DISP=SHR // DD DSN=MY.SYMPDS(SECTION2),DISP=SHR

and the RDW member contains:

RDW,1,4,BI

the SECTION1 member contains:

Flag_Byte,*,1,BI Error1,X80 Error2,X40 Count_of_Parts,*,5,ZD

and the SECTION2 member contains:

New_Parts,*,5,ZD Old_Parts,*,5,ZD Variable_Fields,*
Chapter 7. Using Symbols for Fields and Constants

627

Using Symbols for Fields and Constants

SYMNOUT will show the following symbol table:
RDW,1,4,BI Flag_Byte,5,1,BI Error1,X80 Error2,X40 Count_of_Parts,6,5,ZD New_Parts,11,5,ZD Old_Parts,16,5,ZD Variable_Fields,21

You might use these symbols in the following statements:

OPTION COPY OUTFIL FNAMES=ERR1,INCLUDE=(Flag_Byte,EQ,Error1), OUTREC=(RDW,Count_of_Parts,Variable_Fields) OUTFIL FNAMES=ERR2,INCLUDE=(Flag_Byte,EQ,Error2), OUTREC=(RDW,New_Parts,Old_Parts,Variable_Fields)

An equal sign (=) can be used to assign the previous position to p. Each time a symbol for p,m,f or p,m is read, the previous position is set to p. Additionally, the previous position can be modified by a POSITION keyword statement (see below). When = is specified for p, the previous position is assigned to p. If the previous position has not been set when = is used for p, an error message is issued. The symbol table printed in the SYMNOUT data set (if specified) will show you the actual positions assigned when you specify = for p. As an example of how = can be used for p, if you specify the following SYMNAMES statements:
Sym1,5,4,CH Sym2,=,2,CH Sym3,*,2,CH

SYMNOUT will show the following symbol table:

Sym1,5,4,CH Sym2,5,2,CH Sym3,7,2,CH

By using = and * for p, you can easily map fields onto other fields. Whenever you use = for p, you must ensure that the previous position is the one you want. In particular, if you insert a new field symbol with the wrong position before a symbol that uses = for p, you will need to change = to the actual position you want. v m can be an equal sign (=) or a number from 1 to 32752. An equal sign (=) can be used to assign the previous length to m. Each time a symbol for p,m,f or p,m is read, the previous length is set to m. When = is specified for m, the previous length is assigned to m. If the previous length has not been set when = is used for m, an error message is issued. The symbol table printed in the SYMNOUT data set (if specified) will show you the actual lengths assigned when you specify = for m. As an example of how = can be used for m, if you specify the following SYMNAMES statements:
Flags1,5,1,BI Error1,X08 Flags2,15,=,BI Error2,X04 Flags3,22,=,BI Error3,X23

SYMNOUT will show the following symbol table:

628

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

Flags1,5,1,BI Error1,X08 Flags2,15,1,BI Error2,X04 Flags3,22,1,BI Error3,X23

Whenever you use = for m, you must ensure that the previous length is the one you want. In particular, if you insert a new field symbol with the wrong length before a symbol that uses = for m, you will need to change = to the actual length you want. v f can be an equal sign (=) or one of the following formats: AC, AQ, ASL, AST, BI, CH, CLO, CSF, CSL, CST, CTO, DC1, DC2, DC3, DE1, DE2, DE3, DT1, DT2, DT3, D1, D2, FI, FL, FS, LS, OL, OT, PD, PD0, SFF, SS, TC1, TC2, TC3, TC4, TE1, TE2, TE3, TE4, TM1, TM2, TM3, TM4, TS, UFF, Y2B, Y2C, Y2D, Y2DP, Y2P, Y2PP, Y2S, Y2T, Y2TP, Y2U, Y2UP, Y2V, Y2VP, Y2W, Y2WP, Y2X, Y2XP, Y2Y, Y2YP, Y2Z or ZD. You can specify f using uppercase letters (for example, CH), lowercase letters (for example, ch) or mixed case letters (for example, Ch). f specified in any case will be treated like uppercase. An equal sign (=) can be used to assign the previous format to f. Each time a symbol for p,m,f is read, the previous format is set to f. When = is specified for f, the previous format is assigned to f. If the previous format has not been set when = is used for f, an error message is issued. The symbol table printed in the SYMNOUT data set (if specified) will show you the actual formats assigned when you specify = for f. As an example of how = can be used for f, if you specify the following SYMNAMES statements:
Field1,5,8,CH Field1a,=,3 Field2,*,12,= Field3,*,20,=

SYMNOUT will show the following symbol table:

Field1,5,8,CH Field1a,5,3 Field2,8,12,CH Field3,20,20,CH

Whenever you use = for f, you must ensure that the previous format is the one you want. In particular, if you insert a new field symbol with the wrong format before a symbol that uses = for f, you will need to change = to the actual format you want. Parsed field: A parsed field can be specified as %nn with nn as 00-99 or as %n with n as 0-9. %0n will be substituted for %n. A symbol for a parsed field must be used only where such a field is allowed and has the desired result. Otherwise, substitution of %nn for the symbol will result in an error message. For example, if the following SYMNAMES statement is specified:
Revenue,%03

Revenue can be used in an OUTREC statement such as:

OUTREC PARSE=(Revenue=(STARTAT=C+,FIXLEN=9)), OVERLAY=(31:Revenue,UFF,EDIT=(III,IIT,TTT))

because a parsed field is allowed in the PARSE operand and the OVERLAY operand. However, Revenue will result in an error message if used in a SORT statement such as:
Chapter 7. Using Symbols for Fields and Constants

629

Using Symbols for Fields and Constants

SORT FIELDS=(Revenue,UFF,A)

because a parsed field is not allowed in a SORT statement. Make sure the parsed fields that will be substituted for your symbols are appropriate. If in doubt, check the rules for %nn given in the the description of the relevant operand. As an example of how parsed fields can be used, if you specify the following SYMNAMES statements:
branch,1,7 tab,X05 comma,, first_name,%00 last_name,%1 date,%02 company,%03 city,%04 state,%05

SYMNOUT will show the following symbol table:

branch,1,7 tab,X05 comma,C, first_name,%00 last_name,%01 date,%02 company,%03 city,%04 state,%05

This DFSORT control statement:

INREC PARSE=(first_name=(ABSPOS=9,FIXLEN=12,ENDBEFR=comma), last_name=(FIXLEN=15,ENDBEFR=comma), %=(ENDBEFR=tab), date=(FIXLEN=10,ENDBEFR=tab), company=(FIXLEN=31,ENDBEFR=tab), city=(FIXLEN=14,ENDBEFR=tab), state=(FIXLEN=12)), BUILD=(branch,9:first_name,22:last_name, 38:date,JFY=(SHIFT=RIGHT), 49:company,83:city,98:state)

will be transformed to:

INREC PARSE=(%00=(ABSPOS=9,FIXLEN=12,ENDBEFR=C,),%01=(FIXLEN=15,ENDB* EFR=C,),%=(ENDBEFR=X05),%02=(FIXLEN=10,ENDBEFR=X05* ),%03=(FIXLEN=31,ENDBEFR=X05),%04=(FIXLEN=14,ENDBEFR=X* 05),%05=(FIXLEN=12)),BUILD=(1,7,9:%00,22:%01,38:%02,JF* Y=(SHIFT=RIGHT),49:%03,83:%04,98:%05)

Keyword Statements
The general format for a keyword statement is:
keyword,value remark

The general coding rules are as follows: v Columns 1 through 80 are scanned. v The keyword can start in column 1 or in any column after 1. v The keyword must be specified in all uppercase letters. Otherwise, it will be treated as a symbol.

630

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

v A remark is optional, but if specified, must be separated from the value by at least one blank. A remark is printed in SYMNOUT (if specified), but otherwise not processed. v A semicolon (;) can be used instead of a comma (,) between the keyword and the value. v Continuation is not allowed. Each keyword and value must be completely specified on one line. The specific syntax for keyword statements is:

POSITION,q POSITION,symbol SKIP,n ALIGN,H ALIGN,F ALIGN,D

Keyword statements can help you map the fields in your records by letting you set a starting position, skip unused bytes and align fields on specific boundaries. v POSITION,q can be used to set the next position and the previous position to q. As discussed under p above, the next position is used when an asterisk (*) is specified for p in a symbol statement, and the previous position is used when an equal sign (=) is specified for p in a symbol statement. q can be a number from 1 to 32752. When you use POSITION,q you can use either * or = interchangably for p of the next symbol. As an example of how POSITION,q can be used, if you specify the following SYMNAMES statements:
POSITION,27 Account_Balance,*,5,PD Account_Id,*,8,CH POSITION,84 New_Balance,=,20

SYMNOUT will show the following symbol table:

Account_Balance,27,5,PD Account_Id,32,8,CH New_Balance,84,20

v POSITION,symbol can be used to set the next position and the previous position to the position established for the indicated symbol. As discussed under p above, the next position is used when an asterisk (*) is specified for p in a symbol statement, and the previous position is used when an equal sign (=) is specified for p in a symbol statement. When you use POSITION,symbol you can use either * or = interchangeably for p of the next symbol. symbol can be any previously defined field symbol. Thus, POSITION,symbol can be used like the Assembler ORG instruction to map different fields onto the same area. As an example of how POSITION,symbol can be used, if you specify the following SYMNAMES statements:

Chapter 7. Using Symbols for Fields and Constants

631

Using Symbols for Fields and Constants

Workarea,21,100 volser1,=,6,CH volser2,*,6,CH POSITION,Workarea status,=,1,BI dsname,*,44,CH Use workarea for volsers Reuse workarea for status and dsname

SYMNOUT will show the following symbol table:

Workarea,21,100 volser1,21,6,CH volser2,27,6,CH status,21,1,BI dsname,22,44,CH

v SKIP,n can be used to add n bytes to the next position. As discussed under p above, the next position is used when an asterisk (*) is specified for p in a symbol statement. n can be a number from 1 to 32752. As an example of how SKIP,n can be used, if you specify the following SYMNAMES statements:
Field#1,15,6,FS SKIP,4 Unused bytes Field#2,*,5,= SKIP,2 Unused bytes Field#3,*,8,CH

SYMNOUT will show the following symbol table:

Field#1,15,6,FS Field#2,25,5,FS Field#3,32,8,CH

v ALIGN,H can be used to align the next position on a halfword boundary, that is, 1, 3, 5 and so on. As discussed under p above, the next position is used when an asterisk (*) is specified for p in a symbol statement. ALIGN,h will be treated like ALIGN,H. As an example of how ALIGN,H can be used, if you specify the following SYMNAMES statements:
A1,7,3,CH ALIGN,H A2,*,2,BI

SYMNOUT will show the following symbol table:

A1,7,3,CH A2,11,2,BI

v ALIGN,F can be used to align the next position on a fullword boundary, that is, 1, 5, 9 and so on. As discussed under p above, the next position is used when an asterisk (*) is specified for p in a symbol statement. ALIGN,f will be treated like ALIGN,F. As an example of how ALIGN,F can be used, if you specify the following SYMNAMES statements:
B1,7,3,CH ALIGN,f B2,*,4,BI

SYMNOUT will show the following symbol table:

B1,7,3,CH B2,13,4,BI

632

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

v ALIGN,D can be used to align the next position on a doubleword boundary, that is, 1, 9, 17 and so on. As discussed under p above, the next position is used when an asterisk (*) is specified for p in a symbol statement. ALIGN,d will be treated like ALIGN,D. As an example of how ALIGN,D can be used, if you specify the following SYMNAMES statements:
C1,7,3,CH ALIGN,D C2,*,8,BI

SYMNOUT will show the following symbol table:

C1,7,3,CH C2,17,8,BI

Using SYMNOUT to Check Your SYMNAMES Statements

To avoid surprises, its a good idea to check for errors and incorrect positions, lengths and formats in any SYMNAMES statements you create before you use them in DFSORT or ICETOOL statements. The following simple job will cause DFSORT to issue messages in SYSOUT for any errors it detects in your SYMNAMES statements, allowing you to correct these errors before proceeding. Once your SYMNAMES statements are free of errors, the job will cause DFSORT to show the Symbol Table in SYMNOUT, allowing you to correct any incorrect positions, lengths or formats for your symbols (for example, those caused by incorrect use of *, =, SKIP, and so on).
//CHECK JOB A402,PROGRAMMER //DOIT EXEC PGM=ICEMAN //SYMNAMES DD ... SYMNAMES statements to be checked //SYMNOUT DD SYSOUT=* //SORTIN DD * //SORTOUT DD DUMMY //SYSIN DD * OPTION COPY /*

Once youve debugged your SYMNAMES statements, you can use them in DFSORT and ICETOOL statements.

Using Symbols in DFSORT Statements

You can use symbols in the following DFSORT control statements: INCLUDE, INREC, MERGE, OMIT, OUTFIL, OUTREC, SORT and SUM. In general, you can use symbols in these DFSORT statements where you can use constants (string, Cstring, Xstring, Bstring, n, +n or n), fields (p,m,f or p,m or p), parsed fields (%nn), and output columns (c:). See the discussion of each control statement in Chapter 3, Using DFSORT Program Control Statements, on page 81 for a description of its syntax. You can use symbols in these control statements in any source (that is, DFSPARM, SYSIN, SORTCNTL, and parameter lists). When DFSORT transforms these control statements, it removes labels and remarks, and continues statements by placing an asterisk in column 72 and beginning the next line in column 16. DFSORT will list the original control statements as specified (with labels, remarks, comment statements and blank statements) by source, as well as the transformed statements.
Chapter 7. Using Symbols for Fields and Constants

633

Using Symbols for Fields and Constants

Details and examples of the use of symbols for each applicable DFSORT control statement is given below. The examples are meant to illustrate variations in how symbols can be used and how they will be transformed. Therefore, the examples do not necessarily correspond to how symbols would be used in real applications. The examples use these SYMNAMES statements:
C_Field1,6,5,CH Any_Format,12,3 Z_Field1,22,8,ZD P_Field1,30,4,PD C_Field2,4,2,ch SubString,16,3,SS Start_col,11 Dept_col,55 LIMIT,+12500 Sysplex,S&SYSPLEX. Depts,J82,L92,M72 Code_1,c86A4Z QCON,CCarries Constant Stopper,XFFFFFF Flags,35,1,BI Error,B11010000 Empty,B......01 Full,XFF Lookup,52,1,BI Entry1,X05 Value1,Read Entry2,X20 Value2,Update RDW,1,4 Record Descriptor Word Variable_Fields,451 Variable fields at end of variable-length record * Constants for report Div_Title,Division: BO_Title,Branch Office BO_Hyphens,------------- BO_Equals,============= PL_Title, Profit/(Loss) PL_Hyphens,-------------------- PL_Equals,==================== Total,Total Lowest,Lowest * Fields for report Division,3,10,CH Branch_Office,16,13,CH Profit_or_Loss,31,10,ZD Class_value,%00 Students_value,%01 Class_constant,CLASS=( Students_constant,STUDENTS=( End_constant,)

SORT and MERGE

FIELDS operand: You can use symbols where you can use fields (p,m,f and p,m). A symbol for p,m,f results in substitution of p,m if FORMAT=f or symbol,f is specified. Example 1
SORT FIELDS=(C_Field1,A,Z_Field1,D, C_Field2,ZD,A),EQUALS

will be transformed to:

SORT FIELDS=(6,5,CH,A,22,8,ZD,D,4,2,ZD,A),EQUALS

634

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

Example 2
MERGE FIELDS=(Any_Format,A,C_Field1,A),FORMAT=CH

will be transformed to:

MERGE FIELDS=(12,3,A,6,5,A),FORMAT=CH

SUM
FIELDS operand: You can use symbols where you can use fields (p,m,f and p,m). A symbol for p,m,f results in substitution of p,m if FORMAT=f or symbol,f is specified. Example 1
SUM FIELDS=(Z_Field1,C_Field1,ZD)

will be transformed to:

SUM FIELDS=(22,8,ZD,6,5,ZD)

Example 2
SUM FORMAT=ZD,FIELDS=(C_Field1,Any_Format)

will be transformed to:

SUM FORMAT=ZD,FIELDS=(6,5,12,3)

INCLUDE and OMIT

COND operand: You can use symbols where you can use fields (p1,m1,f1 and p1,m1 and p2,m2,f2 and p2,m2) and constants (n, +n, n, Cxx...x, Xyy...yy, Yyyx...x and Bbbbbbbbb...bbbbbbbb). A symbol for p,m,f results in substitution of p,m if FORMAT=f or symbol,f is specified. A symbol for string always results in substitution of Cstring. Example 1
INCLUDE COND=((Z_Field1,GT,LIMIT,AND,Any_Format,CH,EQ,C_Field2),OR, (SubString,NE,Depts),OR, (Flags,ALL,Error,AND,Flags,NE,Empty))

will be transformed to:

INCLUDE COND=((22,8,ZD,GT,+12500,AND,12,3,CH,EQ,4,2,CH),OR,(16,3,SS,NE* ,CJ82,L92,M72),OR,(35,1,BI,ALL,B11010000,AND,35,1,BI* ,NE,B......01))

Example 2
OMIT FORMAT=BI,COND=(C_Field1,EQ,Code_1,OR, Any_Format,EQ,Stopper,OR, Flags,EQ,Full)

will be transformed to:

OMIT FORMAT=BI,COND=(6,5,EQ,C86A4Z,OR,12,3,EQ,XFFFFFF,OR,35,1,EQ,X* FF)

Example 3
INCLUDE COND=(25,8,CH,EQ,Sysplex)

If the value for the system symbol &SYSPLEX. is MAS3, the INCLUDE statement will be transformed to:
Chapter 7. Using Symbols for Fields and Constants

635

Using Symbols for Fields and Constants

INCLUDE COND=(25,8,CH,EQ,CMAS3)

Note: You can use a symbol for YDATEx, YDATEx+n or YDATEx-n (where x is 1, 2 or 3) in the COND operand, but you cannot use symbol+n or symbol-n to substitute YDATEn+n or YDATEn-n in the COND operand. For example, if you have the symbols:
YD1,YDATE1 YD1P5,YDATE1+5

The INCLUDE statement:

INCLUDE COND=(1,6,Y2T,EQ,YD1)

will be transformed to:

INCLUDE COND=(1,6,Y2T,EQ,YDATE1)

The INCLUDE statement:

INCLUDE COND=(1,6,Y2T,EQ,YD1P5)

will be transformed to:

INCLUDE COND=(1,6,Y2T,EQ,YDATE1+5)

The INCLUDE statement:

INCLUDE COND=(1,6,Y2T,EQ,YD1+5)

will not be transformed because YD1+5 is not valid.

INREC and OUTREC

PARSE operand: You can use symbols where you can use parsed fields (%nn) and constants (Cxx...x and Xyy...yy). FIELDS, BUILD, OVERLAY, IFTHEN BUILD, and IFTHEN OVERLAY operands: You can use symbols where you can use output columns (c:), fields (p,m,f and p,m and p), parsed fields (%nn), non-repeated constants (Cxx...x and Xyy...yy, but not nCxx...x or nXyy...yy), and decimal constants (+n and n, but not n). You cannot use symbols for edit patterns (pattern). In the JFY and SQZ suboperands, you can use symbols where you can use constants (Cxx...x and Xyy...yy). In the CHANGE and NOMATCH suboperands, you can use symbols where you can use fields (q,n), parsed fields (%nn), and constants (Cxx...x, Xyy...yy and Bbbbbbbbb). In the RESTART suboperand for SEQNUM, you can use a symbol where you can use a field (p,m) or parsed field (%nn). A symbol for p or p,m or p,m,f or p,m,Y2x or p,m,Y2xP results in substitution of p: for symbol: (output column). A symbol for p,m,f results in substitution of p,m,f if (symbol),fo or symbol,TO=fo or symbol,ZDF or symbol,ZDC or symbol,PDC or symbol,PDF is specified, but results in substitution of p,m if symbol,fo is specified (when fo is not ZDF, ZDC, PDC, or PDF) because fo cannot be distinguished from f (except for ZDF, ZDC, PDC, or PDF). For example, if SYM1 is defined as 5,4,ZD, (SYM1),PD is transformed to (5,4,ZD),PD and SYM1,TO=PD is transformed to 5,4,ZD,TO=PD,

636

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

whereas SYM1,PD is transformed to 5,4,PD. Thus, you should always use (symbol),fo or symbol,TO=fo rather than symbol,fo A symbol for p,m,f results in substitution of p,m unless symbol,edit or symbol,to or (symbol) is specified or the symbol is part of an arithmetic expression. For example, if SYM1 is defined as 5,4,ZD, SYM1,X is transformed to 5,4,X, whereas SYM1,M12 is transformed to 5,4,ZD,M12 and SYM1,ADD,+1 is transformed to 5,4,ZD,ADD,+1. A symbol for p,m,Y2x results in substitution of p,m,Y2x if symbol,TO=fo or symbol,ZDF or symbol,ZDC or symbol,PDC or symbol, PDF is specified, but results in substitution of p,m if symbol,fo is specified (when fo is not ZDF, ZDC, PDC, or PDF) because fo cannot be distinguished from f (except for ZDF, ZDC, PDC, or PDF). For example, if SYM1 is defined as 5,4,Y2T, SYM1,TO=PD is transformed to 5,4,Y2T,TO=PD, whereas SYM1,PD is transformed to 5,4,PD. Thus, you should always use symbol,TO=fo rather than symbol,fo when dealing with symbols for p,m,Y2x fields A symbol for p,m,Y2x results in substitution of p,m,Y2x unless symbol,f or symbol,HEX is specified. A symbol for p,m,Y2xP results in substitution of p,m,Y2xP unless symbol,f or symbol,HEX is specified. A symbol for string always results in substitution of Cstring. Example 1
INREC FIELDS=(Start_col:C_Field2,2X,C_Field1,F,Stopper,5C*, Z_Field1,Dept_col:Depts,X,P_Field1,TO=FS,X,Z_Field1,M10, Z_Field1,MUL,(P_Field1,SUB,LIMIT),EDIT=(SIIIIIT.TT),SIGNS=(+,-))

will be transformed to:

INREC FIELDS=(11:4,2,2X,6,5,F,XFFFFFF,5C*,22,8,55:CJ82,L92,M72,X* ,30,4,PD,TO=FS,X,22,8,ZD,M10,22,8,ZD,MUL,(30,4,PD,SUB,+1* 2500),EDIT=(SIIIIIT.TT),SIGNS=(+,-))

Example 2
OUTREC FIELDS=(RDW, ** Record Descriptor Word ** Z_Field1,2Z, 3CSymbol cannot be used for a repeated constant, Code_1,Flags, Variable_Fields) ** Variable part of input record

will be transformed to:

OUTREC FIELDS=(1,4,22,8,2Z,3CSymbol cannot be used for a repeated con* stant,C86A4Z,35,1,451)

Example 3
INREC PARSE=(Class_value=(STARTAFT=Class_constant, ENDBEFR=End_constant,FIXLEN=8), Students_value=(STARTAFT=Students_constant, ENDBEFR=End_constant,FIXLEN=5)), BUILD=(Class_value,3X,Students_value,UFF,M11,LENGTH=5)

will be transformed to:

INREC PARSE=(%00=(STARTAFT=CCLASS=(,ENDBEFR=C),FIXLEN=8),%01=(STAR* TAFT=CSTUDENTS=(,ENDBEFR=C),FIXLEN=5)),BUILD=(%00,3X* ,%01,UFF,M11,LENGTH=5)

Chapter 7. Using Symbols for Fields and Constants

637

Using Symbols for Fields and Constants

IFTHEN WHEN=(logexp) operand: You can use symbols where you can use fields (p1,m1,f1 and p1,m1 and p2,m2,f2 and p2,m2) and constants (n, +n, -n, Cxx...x, Xyy...yy, Yyyx...x and Bbbbbbbbb...bbbbbbbb). A symbol for p,m,f results in substitution of p,m if symbol,f is specified. A symbol for string always results in substitution of Cstring. Example 1
INREC IFTHEN=(WHEN=(Lookup,EQ,Entry1),OVERLAY=(75:Value1)), IFTHEN=(WHEN=(Lookup,EQ,Entry2),OVERLAY=(75:Value2))

will be transformed to:

INREC IFTHEN=(WHEN=(52,1,BI,EQ,X05),OVERLAY=(75:CRead)),IFTHEN=(WH* EN=(52,1,BI,EQ,X20),OVERLAY=(75:CUpdate))

Note: You can use a symbol for YDATEx, YDATEx+n or YDATEx-n (where x is 1, 2 or 3) in the WHEN operand, but you cannot use symbol+n or symbol-n to substitute YDATEn+n or YDATEn-n in the WHEN operand. See the discussion of INCLUDE and OMIT for further details.

OUTFIL
INCLUDE, OMIT, and IFTHEN WHEN=(logexp) operands: You can use symbols where you can use fields (p1,m1,f1 and p1,m1 and p2,m2,f2 and p2,m2) and constants (n, +n, n, Cxx...x, Xyy...yy, Yyyx...x and Bbbbbbbbb...bbbbbbbb). A symbol for p,m,f results in substitution of p,m if symbol,f is specified. A symbol for string always results in substitution of Cstring. Note: You can use a symbol for YDATEx, YDATEx+n or YDATEx-n (where x is 1, 2 or 3) in the INCLUDE, OMIT or WHEN operand, but you cannot use symbol+n or symbol-n to substitute YDATEn+n or YDATEn-n in the INCLUDE, OMIT or WHEN operand. See the discussion of INCLUDE and OMIT for further details. PARSE operand: You can use symbols where you can use parsed fields (%nn) and constants (Cxx...x and Xyy...yy). OUTREC, BUILD, OVERLAY, IFTHEN BUILD, and IFTHEN OVERLAY operands: You can use symbols where you can use output columns (c:), fields (p,m,f and p,m and p), parsed fields (%nn), non-repeated constants (Cxx...x and Xyy...yy, but not nCxx...x or nXyy...yy), and decimal constants (+n and n, but not n). You cannot use symbols for edit patterns (pattern). In the JFY and SQZ suboperands, you can use symbols where you can use constants (Cxx...x and Xyy...yy). In the CHANGE and NOMATCH suboperands, you can use symbols where you can use fields (q,n), parsed fields (%nn), and constants (Cxx...x, Xyy...yy and Bbbbbbbbb). In the RESTART suboperand for SEQNUM, you can use a symbol where you can use a field (p,m) or a parsed field (%nn). A symbol for p or p,m or p,m,f or p,m,Y2x or p,m,Y2xP results in substitution of p: for symbol: (output column).

638

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

A symbol for p,m,f results in substitution of p,m,f if (symbol),fo or symbol,TO=fo or symbol,ZDF or symbol,ZDC or symbol,PDC or symbol,PDF is specified, but results in substitution of p,m if symbol,fo is specified (when fo is not ZDF or ZDC ZDF, ZDC, PDC, or PDF) because fo cannot be distinguished from f (except for ZDF, ZDC, PDC, and PDF). For example, if SYM1 is defined as 5,4,ZD, (SYM1),PD is transformed to (5,4,ZD),PD and SYM1,TO=PD is transformed to 5,4,ZD,TO=PD, whereas SYM1,PD is transformed to 5,4,PD. Thus, you should always use (symbol),fo or symbol,TO=fo rather than symbol,fo. A symbol for p,m,f results in substitution of p,m unless symbol,edit or symbol,to or (symbol) is specified or the symbol is part of an arithmetic expression. For example, if SYM1 is defined as 5,4,ZD, SYM1,X is transformed to 5,4,X, whereas SYM1,M12 is transformed to 5,4,ZD,M12 and SYM1,ADD,+1 is transformed to 5,4,ZD,ADD,+1. A symbol for p,m,Y2x results in substitution of p,m,Y2x if symbol,TO=fo or symbol,ZDF or symbol,ZDC or symbol,PDC or symbol,PDF is specified, but results in substitution of p,m if symbol,fo is specified (when fo is not ZDF, ZDC, PDC, or PDF) because fo cannot be distinguished from f (except for ZDF, ZDC, PDC, and PDF). For example, if SYM1 is defined as 5,4,Y2T, SYM1,TO=PD is transformed to 5,4,Y2T,TO=PD, whereas SYM1,PD is transformed to 5,4,PD. Thus, you should always use symbol,TO=fo rather than symbol,fo when dealing with symbols for p,m,Y2x fields A symbol for p,m,Y2x results in substitution of p,m,Y2x unless symbol,f or symbol,HEX is specified. A symbol for p,m,Y2xP results in substitution of p,m,Y2xP unless symbol,f or symbol,HEX is specified. A symbol for string always results in substitution of Cstring. VLFILL operand: You can use symbols where you can use constants (Cx and Xyy). A symbol for string always results in substitution of Cstring. VLTRIM operand: You can use symbols where you can use constants (Cx and Xyy). A symbol for string always results in substitution of Cstring. HEADER1 and HEADER2 operands: You can use symbols where you can use output columns (c:), fields (p,m) and non-repeated constants (xx...x, Cxx...x, and Xyy...yy, but not nxx...x, nCxx...x, or nXyy...yy). A symbol for p or p,m or p,m,f results in substitution of p: for symbol: (output column).A symbol for p,m,f always results in substitution of p,m. A symbol for string always results in substitution of Cstring. TRAILER1 and TRAILER2 operands: Outside of the suboperands TOTAL, TOT, MIN, MAX, AVG, SUBTOTAL, SUBTOT, SUB, SUBMIN, SUBMAX and SUBAVG: You can use symbols where you can use output columns (c:), fields (p,m) and non-repeated constants (xx...x, Cxx...x and Xyy...yy, but not nxx...x, nCxx...x or nXyy...yy). A symbol for p or p,m or p,m,f results in substitution of p: for symbol: (output column). A symbol for p,m,f always results in substitution of p,m. A symbol for string always results in substitution of Cstring. Inside of the suboperands TOTAL, TOT, MIN, MAX, AVG, SUBTOTAL, SUBTOT, SUB, SUBMIN, SUBMAX and SUBAVG: You can use symbols where you can use fields (p,m,f). A symbol for p,m,f results in substitution of p,m,f if symbol,TO=fo or symbol,ZDF or symbol,ZDC or symbol,PDC or symbol,PDF is specified, but results in substitution of p,m if symbol,fo is specified (when fo is not ZDF, ZDC, PDC, or
Chapter 7. Using Symbols for Fields and Constants

639

Using Symbols for Fields and Constants

PDF) because fo cannot be distinguished from f (except for ZDF, ZDC, PDC, and PDF). For example, if SYM1 is defined as 5,4,ZD, MIN=(SYM1,TO=PD) is transformed to MIN=(5,4,ZD,TO=PD) whereas MIN=(SYM1,PD) is transformed to MIN=(5,4,PD). Thus, you should always use symbol,TO=fo rather than symbol,fo. SECTIONS operand: The HEADER1 and HEADER2 operands discussion above also applies to the HEADER3 suboperand of SECTIONS. The TRAILER1 and TRAILER2 operands discussion above also applies to the TRAILER3 suboperand of SECTIONS. Outside of the HEADER3 and TRAILER3 suboperands, you can use symbols where you can use fields (p,m). A symbol for p,m,f always results in substitution of p,m. Example 1
OUTFIL FNAMES=OUT1, INCLUDE=(Z_Field1,GT,LIMIT,AND,Any_Format,CH,EQ,C_Field2), OUTREC=(Any_Format:P_Field1,M0,2X,Any_Format,BI,LENGTH=3,2X, QCON,2X, C_Field2,HEX,2X,Z_Field1,EDIT=(I III IIT.T),2X, * Lookup Table Lookup,CHANGE=(6,Entry1,Value1,Entry2,Value2), NOMATCH=(Lookup))

will be transformed to:

OUTFIL FNAMES=OUT1,INCLUDE=(22,8,ZD,GT,+12500,AND,12,3,CH,EQ,4,2,CH),O* UTREC=(12:30,4,PD,M0,2X,12,3,BI,LENGTH=3,2X,CCarries * Constant,2X,4,2,HEX,2X,22,8,ZD,EDIT=(I III IIT.T),2X,* 52,1,CHANGE=(6,X05,CRead,X20,CUpdate),NOMATCH=(5* 2,1))

Example 2
OUTFIL FNAMES=REPORT, OUTREC=(6:Branch_Office,24:Profit_or_Loss,M5,LENGTH=20,75:X), SECTIONS=(Division,SKIP=P, HEADER3=(2:Div_Title,Division,5X,Page:,&PAGE,2/, 6:BO_Title,24:PL_Title,/, 6:BO_Hyphens,24:PL_Hyphens), TRAILER3=(6:BO_Equals,24:PL_Equals,/, 6:Total,24:TOTAL=(Profit_or_Loss,M5,LENGTH=20),/, 6:Lowest,24:MIN=(Profit_or_Loss,M5,LENGTH=20)))

will be transformed to: |

OUTFIL FNAMES=REPORT,OUTREC=(6:16,13,24:31,10,ZD,M5,LENGTH=20,75:X),SE* CTIONS=(3,10,SKIP=P,HEADER3=(2:CDivision: ,3,10,5X,P* age:,&PAGE,2/,6:CBranch Office,24:C Profit/(Lo* ss),/,6:C-------------,24:C--------------------),TR* AILER3=(6:C=============,24:C====================,/,* 6:CTotal,24:TOTAL=(31,10,ZD,M5,LENGTH=20),/,6:CLowest* ,24:MIN=(31,10,ZD,M5,LENGTH=20)))

Example 3
OUTFIL IFTHEN=(WHEN=INIT, PARSE=(Class_value=(STARTAFT=Class_constant, ENDBEFR=End_constant,FIXLEN=8), Students_value=(STARTAFT=Students_constant, ENDBEFR=End_constant,FIXLEN=5)), BUILD=(1:Class_value)), IFTHEN=(WHEN=(1,8,SS,EQ,CBiology ,Algebra ,Geometry),

640

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

BUILD=(CThere are ,Students_value,UFF,M10,X, Class_value,C Students)), IFTHEN=(WHEN=NONE, BUILD=(C*Not relevant*))

will be transformed to:

OUTFIL IFTHEN=(WHEN=INIT,PARSE=(%00=(STARTAFT=CCLASS=(,ENDBEFR=C),* FIXLEN=8),%01=(STARTAFT=CSTUDENTS=(,ENDBEFR=C),FIXLE* N=5)),BUILD=(1:%00)),IFTHEN=(WHEN=(1,8,SS,EQ,CBiology ,* Algebra ,Geometry),BUILD=(CThere are ,%01,UFF,M10,X,%* 00,C Students)),IFTHEN=(WHEN=NONE,BUILD=(C*Not releva* nt*))

Using Symbols in ICETOOL Operators

You can use symbols in the following ICETOOL operators: COUNT, DISPLAY, OCCUR, RANGE, SELECT, SPLICE, STATS, UNIQUE, and VERIFY. In general, you can use symbols in these ICETOOL operators where you can use constants (string, n, +n or n) and fields (p,m,f or p,m). See the discussion of each operator in Chapter 6, Using ICETOOL, on page 479 for a description of its syntax. ICETOOL reads the SYMNAMES data set once and uses it for all operators and DFSORT control statements for the run. You can use symbols in operators from the TOOLIN data set or your parameter list. You can also use symbols in DFSORT control statements in xxxxCNTL data sets or in the DFSPARM data set (see Using Symbols in DFSORT Statements on page 633 for details). ICETOOL will list the original operator statements as well as the transformed operator statements. Details of the use of symbols for each applicable ICETOOL operator is given below followed by a complete ICETOOL example. The example is meant to illustrate variations in how symbols can be used and how they will be transformed. Therefore, the example does not necessarily correspond to how symbols would be used in real applications.

COUNT
HIGHER, LOWER, EQUAL and NOTEQUAL operands: You can use symbols where you can use constants (x, y, v, and w).

DISPLAY
ON operand: You can use symbols where you can use fields (p,m,f and p,m). A symbol for p,m,f results in substitution of p,m if symbol,f or symbol,HEX is specified. BREAK operand: You can use symbols where you can use fields (p,m,f and p,m). A symbol for p,m,f results in substitution of p,m if symbol,f is specified. TITLE, HEADER, TOTAL, MAXIMUM, MINIMUM, AVERAGE, BTITLE, BTOTAL, BMAXIMUM, BMINIMUM and BAVERAGE operands: You can use symbols where you can use constants (string). A symbol for Cstring always results in substitution of string.

Chapter 7. Using Symbols for Fields and Constants

641

Using Symbols for Fields and Constants

OCCUR
ON operand: You can use symbols where you can use fields (p,m,f and p,m). A symbol for p,m,f results in substitution of p,m if symbol,f or symbol,HEX is specified. TITLE and HEADER operands: You can use symbols where you can use constants (string). A symbol for Cstring always results in substitution of string. HIGHER, LOWER and EQUAL operands: You can use symbols where you can use constants (x, y and v).

RANGE
ON operand: You can use symbols where you can use fields (p,m,f and p,m). A symbol for p,m,f results in substitution of p,m if symbol,f is specified. HIGHER, LOWER, EQUAL and NOTEQUAL operands: You can use symbols where you can use constants (x, y, v and w).

SELECT
ON operand: You can use symbols where you can use fields (p,m,f and p,m). A symbol for p,m,f results in substitution of p,m if symbol,f is specified. HIGHER, LOWER and EQUAL operands: You can use symbols where you can use constants (x, y and v).

SPLICE
ON operand: You can use symbols where you can use fields (p,m,f and p,m). A symbol for p,m,f results in substitution of p,m if symbol,f is specified. WITH operand: You can use symbols where you can use fields (p,m). A symbol for p,m,f results in substitution of p,m.

STATS, UNIQUE and VERIFY

ON operand: You can use symbols where you can use fields (p,m,f and p,m). A symbol for p,m,f results in substitution of p,m if symbol,f is specified.

ICETOOL Example
//TOOLSYM JOB A402,PROGRAMMER //DOIT EXEC PGM=ICETOOL //TOOLMSG DD SYSOUT=* //DFSMSG DD SYSOUT=* //SYMNOUT DD SYSOUT=* //SYMNAMES DD * Rdw,1,4,BI Account_Code,12,1,CH Dept_Code,*,=,= Customer_Name,*,20,CH SKIP,2 Customer_Balance,*,10,ZD Customer_Flags,*,1,BI * Department Codes Research,R Marketing,M * Balance Cutoffs Cancel,+10000 100.00 Gift,+1000000 10,000.00

642

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

Stop_Check,-500 -5.00 * Headings and Titles Title,SCustomer Report for &LWDAY. Head1,Customer Name Head2,Customer Balance Head3,Customer Flags /* //IN DD DSN=MY.CUSTOMER.INPUT,DISP=SHR //OUT DD DSN=&&O,UNIT=SYSDA,SPACE=(CYL,(5,5),RLSE), // DISP=(,PASS) //LIST1 DD SYSOUT=* //TOOLIN DD * RANGE FROM(IN) ON(Customer_Balance) LOWER(Stop_Check) SORT FROM(IN) TO(OUT) USING(CTL1) DISPLAY FROM(OUT) LIST(LIST1) BLANK WIDTH(133) TITLE(Title) DATE(4MD/) PAGE HEADER(Head1) ON(Customer_Name) HEADER(Head2) ON(Customer_Balance,C1) HEADER(Head3) ON(Customer_Flags,HEX) /* //CTL1CNTL DD * SORT FIELDS=(Customer_Balance,D,Customer_Name,A) INCLUDE COND=((Dept_Code,EQ,Research,OR,Dept_Code,EQ,Marketing), AND,Customer_Balance,GT,Gift) /*

If the value for the system symbol &LWDAY. is FRI, SYMNOUT will show the following:
------- ORIGINAL STATEMENTS FROM SYMNAMES ------Rdw,1,4,BI Account_Code,12,1,CH Dept_Code,*,=,= Customer_Name,*,20,CH SKIP,2 Customer_Balance,*,10,ZD Customer_Flags,*,1,BI * Department Codes Research,R Marketing,M * Balance Cutoffs Cancel,+10000 100.00 Gift,+1000000 10,000.00 Stop_Check,-500 -5.00 * Headings and Titles Title,SCustomer Report for &LWDAY. Head1,Customer Name Head2,Customer Balance Head3,Customer Flags ------------------ SYMBOL TABLE ----------------Rdw,1,4,BI Account_Code,12,1,CH Dept_Code,13,1,CH Customer_Name,14,20,CH Customer_Balance,36,10,ZD Customer_Flags,46,1,BI Research,CR Marketing,CM Cancel,+10000 Gift,+1000000 Stop_Check,-500 Title,CCustomer Report for FRI Head1,CCustomer Name Head2,CCustomer Balance Head3,CCustomer Flags

Chapter 7. Using Symbols for Fields and Constants

643

Using Symbols for Fields and Constants

The ICETOOL operators will be transformed to:
RANGE FROM(IN) ON(36,10,ZD) LOWER(-500) SORT FROM(IN) TO(OUT) USING(CTL1) DISPLAY FROM(OUT) LIST(LIST1) BLANK WIDTH(133)TITLE(Customer Report for FRI) DATE(4MD/) PAGEHEADER(Customer Name) ON(14,20,CH)HEADER(Customer Balance) ON(36,10,ZD,C1)HEADER(Customer Flags) ON(46,1,HEX)

The DFSORT control statements in CTL1CNTL will be transformed to:

SORT FIELDS=(36,10,ZD,D,14,20,CH,A) INCLUDE COND=((13,1,CH,EQ,CR,OR,13,1,CH,EQ,CM),AND,36,10,ZD,GT,+10* 00000)

Notes for Symbols

v EFS programs cannot be used with symbol processing. v DFSORT or ICETOOL scans each SYMNAMES statement for errors, and prints an error message for the first error detected. A marker ($) is printed directly below the SYMNAMES statement near the error, if appropriate. Scanning stops at the first error, and then continues with the next SYMNAMES statement. However, once an error is detected, positions generated by using an asterisk (*) for p or POSITION,symbol in subsequent statements will not be checked for errors. DFSORT and ICETOOL terminate after all SYMNAMES statements are scanned if an error is detected in any statement. v If DFSORT or ICETOOL detects an error in a control statement or operator statement during the substitution phase (that is, while attempting to substitute values for symbols), it may either: print the original statement in error followed by a $ marker (if appropriate) and an error message, continue the substitution phase with the next statement and terminate when the substitution phase is complete, or stop performing substitution for the statement in error, continue with the next statement and let processing after the substitution phase handle the error. It is possible in this case for a symbol, rather than a substituted value, to appear in a transformed statement. v If the substitution phase is successful, DFSORT and ICETOOL will substitute values for symbols wherever symbols are allowed. Substituted values which are invalid for a particular statement or operand will be detected after the substitution phase. This makes it easier to determine the cause of the error. For example, if SYMNAMES contains:
Sym1,5,4,ZD Con1,1234 Con2,1234

the statement:
INCLUDE COND=(Sym1,EQ,Con1)

will be transformed to the following during the substitution phase:

INCLUDE COND=(5,4,ZD,EQ,C1234)

An ICE114A message with a $ marker under C1234 will then be issued for the statement because a ZD field cannot be compared to a character constant. In this example, the error could be fixed by using Con2 (a decimal constant) in the statement instead of Con1 or by redefining Con1 as a decimal constant.

644

z/OS V1R10.0 DFSORT Application Programming Guide

Using Symbols for Fields and Constants

v If you use a temporary or permanent message data set, it is best to specify a disposition of MOD to ensure you see all messages and control statements in the message data set. In particular, if you use symbols processing and do not use MOD, you will not see the original control statements unless Blockset is selected. v If you rearrange your records in any way (for example, using E15, E35, INREC, OUTREC or OUTFIL) and want to use symbols for the rearranged records, be sure to use symbols that map to the new positions of your fields. For example, if you use a SYMNAMES data set with the following statements:
Field1,1,5,ZD Field2,*,6,ZD Field3,*,3,ZD Field4,*,4,ZD

for this INREC statement:

INREC FIELDS=(Field2,Field4)

the resulting records will only contain Field2 and Field4. If you want to use symbols for the rearranged records (for example, in a SORT statement), you will need to use a SYMNAMES data set with symbols that map to the rearranged records, such as:
New_Field2,1,6,ZD New_Field4,*,4,ZD

If you use unique symbols for the rearranged fields, as in the example above, you can concatenate the old and new symbol data sets together and use the old and new symbols where appropriate, as in this example:
INREC FIELDS=(Field2,Field4) SORT FIELDS=(New_Field2,A,New_Field4,A)

Chapter 7. Using Symbols for Fields and Constants

645

Using Symbols for Fields and Constants

646

z/OS V1R10.0 DFSORT Application Programming Guide

Chapter 8. Using Extended Function Support

Using EFS . . . . . . . . . . . . . . Addressing and Residence Mode of the EFS Program . . . . . . . . . . . . . . . How EFS Works . . . . . . . . . . . . DFSORT Program Phases . . . . . . . . DFSORT Calls to Your EFS Program . . . . . Initialization Phase . . . . . . . . . Input Phase . . . . . . . . . . . . Termination Phase . . . . . . . . . . What You Can Do with EFS . . . . . . . . Opening and Initializing Data Sets . . . . . Examining, Altering, or Ignoring Control Statements . . . . . . . . . . . . . Processing User-Defined Data Types with EFS Program User Exit Routines . . . . . . . Supplying Messages for Printing to the Message Data Set . . . . . . . . . . . . . . Terminating DFSORT . . . . . . . . . . Closing Data Sets and Housekeeping . . . . Structure of the EFS Interface Parameter List . . . Action Codes . . . . . . . . . . . . Control Statement Request List . . . . . . Control Statement String Sent to the EFS program . . . . . . . . . . . . . . Special Handling of OPTION and DEBUG Control Statements . . . . . . . . . Control Statement String Returned by the EFS Program . . . . . . . . . . . . . . Rules for Parsing . . . . . . . . . . EFS Formats for SORT, MERGE, INCLUDE, and OMIT Control Statements . . . . . . . . 647 648 648 649 649 651 653 653 654 655 655 657 657 657 657 657 659 660 660 661 662 662 663 D1 Format on FIELDS Operand . . . . D2 Format on COND Operand . . . . Length of Original Control Statement . . Length of the Altered Control Statement . EFS Program Context Area . . . . . . Extract Buffer Offsets List . . . . . . Record Lengths List . . . . . . . . Information Flags . . . . . . . . . Message List . . . . . . . . . . EFS Program Exit Routines . . . . . . . EFS01 and EFS02 Function Description . . EFS01 User Exit Routine . . . . . . . EFS01 Parameter List . . . . . . . EFS02 User Exit Routine . . . . . . . EFS02 Parameter List . . . . . . . Addressing and Residence Mode of EFS Program User Exit Routines . . . . . EFS Program Return Codes You Must Supply Record Processing Order . . . . . . . How to Request a SNAP Dump . . . . . EFS Program Example . . . . . . . . DFSORT Initialization Phase: . . . . . Major Call 1 . . . . . . . . . . Major Call 2 . . . . . . . . . . Major Call 3 . . . . . . . . . . DFSORT Termination Phase . . . . . Major Call 4 . . . . . . . . . . Major Call 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663 664 666 666 666 666 666 667 668 669 669 670 671 671 672 673 674 674 676 677 677 677 677 678 679 679 679

Using EFS
Like the user exits described in Chapter 4, Using Your Own User Exit Routines, the DFSORT Extended Function Support (EFS) interface is a means by which you can pass run-time control to an EFS program you write yourself. An EFS program is essential if you want to process double-byte character sets (such as Japanese characters) with DFSORT. To process Japanese data types with DFSORT, you can use the IBM Double Byte Character Set Ordering Support Program (DBCS Ordering), Licensed Program 5665-360, Release 2.0, or you can use locale processing with the appropriate locale. Using an EFS program and EFS program exit routines, you can: v Sort or merge user-defined data types (such as double-byte character sets) with user-defined collating sequences v Include or omit records based on the user-defined data types v Provide user-written messages to DFSORT for printing to the message data set v Examine, alter, or ignore control statements or EXEC PARM options prior to processing by DFSORT. The EFS program can also perform routine tasks, such as opening and initializing data sets, terminating DFSORT, and closing data sets.
Copyright IBM Corp. 1973, 2006

647

Using EFS
You can write your EFS program in any language that uses standard register and linkage conventions, and can: v Pass a parameter list and a record (if you provide the EFS01 and EFS02 exit routines in the EFS program) in register 1 v Pass a return code in general register 15. Notes: 1. DFSORT does not support EFS programs for Conventional merge or tape work data set sort applications. 2. VLSHRT is not allowed if EFS processing is in effect and an EFS01 or EFS02 exit routine is provided by the EFS program. 3. If you use locale processing for SORT, MERGE, INCLUDE, or OMIT fields, you must not use an EFS program. DFSORTs locale processing may eliminate the need for an EFS program. See OPTION Control Statement on page 167 for information related to locale processing. 4. If you use symbol processing, you must not use an EFS program. The DFSORT target library, SICEUSER, contains a mapping macro called ICEDEFS, which provides a separate Assembler DSECT for the EFS parameter list.

Addressing and Residence Mode of the EFS Program

You can design the EFS program to reside and run above or below 16MB virtual. Residency and addressing mode can be any valid combination of 24-bit, 31-bit, or ANY. If your EFS program is designed to reside and run below 16MB virtual, the EFS program must determine the proper return mode.

How EFS Works

The EFS interface consists of a variable-length parameter list used to communicate between DFSORT and your EFS program. DFSORT activates the EFS program you write at specific points during run-time, and communicates information back and forth across the interface as your EFS program runs. | | You can activate your EFS program with the installation or run-time option EFS=name (name is the name of your EFS program): See Appendix B, Specification/Override of DFSORT Options, on page 741 for override information. Figure 42 on page 649 illustrates the role of the EFS interface in linking DFSORTs processing capabilities to the EFS program you write.

648

z/OS V1R10.0 DFSORT Application Programming Guide

How EFS Works

DFSORT and Non-DFSORT Control Statements and EXEC PARM Options

DFSORT EFS Interface Processing

EFS Program EFS Interface Processing

EFS Interface

Input Data Set

Output Data Set

Figure 42. Relationship Between DFSORT and an EFS Program

DFSORT Program Phases

A DFSORT program phase is a large DFSORT component designed to perform a specific task such as writing the output file. An EFS program is called at various points during run-time of DFSORT program phases in performing the variety of tasks capable with an EFS program. When the termination phase is completed, DFSORT returns control to the operating system or invoking program. EFS processing can be invoked during the initialization, input, and termination phases of DFSORT. DFSORT always calls the EFS program during the initialization phase. During the input phase, DFSORT reads input records, and performs any INCLUDE or OMIT statement logic on the records. If the EFS program generates exit routines (EFS01 and EFS02), DFSORT calls them during the input phase. During the termination phase, DFSORT closes data sets, releases storage, and returns control to the calling program or system. DFSORT always calls the EFS program from the termination phase.

DFSORT Calls to Your EFS Program

DFSORT makes five functional calls (Major Calls 1 through 5) at various phases to transfer information across the EFS interface, between DFSORT and your EFS program. DFSORT can make multiple calls at Major Calls 2 and 3. Refer to Figure 43 on page 650 and Figure 44 on page 651 as you read this section for illustrations of the relationships between program phases and calls during run-time.

Chapter 8. Using Extended Function Support

649

How EFS Works

Initialization Phase

DFSORT Major Call 1 EFS Processing Major Call 2 EFS Program

Major Call 3

DFSORT

Input Phase
EFS01 and EFS02 Parameter List Processing

Call for each Input Record

EFS01

One or more calls for each EFS02 Input Record

DFSORT

Termination Phase
EFS Processing

Major Call 4 EFS Program

Major Call 5

Figure 43. EFS Program Calls for a Sort. The figure also shows the calls to the EFS program EFS01 and EFS02 exit routines.

650

z/OS V1R10.0 DFSORT Application Programming Guide

How EFS Works

Initialization Phase

DFSORT Major Call 1 EFS Processing Major Call 2 EFS Program

Major Call 3

DFSORT

Input and Output Phase

EFS01 and EFS02 Parameter List Processing

Call for each Input Record

EFS01 (Merge Only)

One or more calls for each EFS02 Input Record

DFSORT

Termination Phase
EFS Processing

Major Call 4 EFS Program

Major Call 5

Figure 44. EFS Program Calls for a Merge or Copy. The figure also shows the calls to the EFS program EFS01 and EFS02 exit routines.

Initialization Phase
DFSORT runs Major Calls 1 through 3 during the initialization phase. Major Call 1: The EFS program can perform initialization processing such as opening data sets and obtaining storage. Information is passed in both directions between DFSORT and the EFS program across the EFS interface. At Major Call 1, DFSORT supplies your EFS program with fields in the EFS interface containing: v An action code indicating that Major Call 1 is in effect v Informational flags that describe current processing.

Chapter 8. Using Extended Function Support

651

How EFS Works

When the EFS program returns control to DFSORT, it can supply fields in the EFS interface containing: v A control statement request list, with a list of DFSORT and non-DFSORT control statement operation definers, or EXEC PARM options Note: OUTFIL statements cannot be requested by an EFS program. v An EFS Program Context area (a private communication area for the EFS program) v A list containing messages for printing to the message data set v A return code (in general register 15). Major Call 2: At this call, your EFS program can examine, alter, or ignore control statements before DFSORT processes them, and provide user-written messages to the message data set. DFSORT calls your EFS program once for each control statement or EXEC PARM you request. At Major Call 2, DFSORT supplies your EFS program with fields in the EFS interface containing: v An action code indicating that Major Call 2 is in effect v The original control statement or EXEC PARM option requested by the EFS program v The length of the original control statement or EXEC PARM option v Informational flags that describe current processing v An EFS Program Context area (a private communication area for the EFS program). When the EFS program returns control to DFSORT, it can supply fields in the EFS interface containing: v A modified version of the control statement or EXEC PARM option sent by DFSORT to the EFS program. If you plan to sort or merge user-defined data types, or include or omit user-defined data types, your EFS program must return new formats for the SORT/MERGE or INCLUDE/OMIT control statements. These new formats (D1 and D2) signal DFSORT to call the EFS01 and EFS02 exit routines you included with your EFS program. Note: OUTFIL statements cannot be passed to an EFS program or returned from an EFS program to be parsed. v The length of the altered control statement or EXEC PARM option. v Informational flags signaling DFSORT whether to parse or ignore the control statement or EXEC PARM option. v A list of messages for DFSORT to print to the message data set. v A return code (in general register 15). Major Call 3: At Major Call 3, your EFS program can provide DFSORT with user-written messages to print to the message data set. DFSORT can call the EFS program once for the Blockset technique and once for the Peerage/Vale techniques. DFSORT obtains more information at this call from the EFS program to process the EFS01 and EFS02 exit routines. At Major Call 3, DFSORT supplies your EFS program with fields in the EFS interface containing: v An action code indicating that Major Call 3 is in effect

652

z/OS V1R10.0 DFSORT Application Programming Guide

How EFS Works

v v v v An extract buffer offsets list needed by the EFS01 exit routine A record lengths list of input and output records Informational flags that describe current processing An EFS Program Context area (a private communication area for the EFS program).

When the EFS program returns control to DFSORT, it can supply fields in the EFS interface containing: v An EFS01 exit routine address v An EFS02 exit routine address v A list of messages for printing to the message data set v A return code in general register 15.

Input Phase
DFSORT runs the two exit routines, EFS01 and EFS02, during the input phase. The EFS01 routine supports sorting or merging user-defined data types with user-defined collating sequences and is called once for each record. The EFS02 routine provides logic to include or omit records on user-defined data types and is called one or more times for each record, according to the logic. Information is passed in both directions between DFSORT and the exit routines across the EFS01 and EFS02 parameter lists. DFSORT supplies the EFS01 routine with fields in the parameter list containing: v An Extract Buffer Area to which the EFS01 routine must move all EFS control fields. See EFS01 User Exit Routine on page 670 for more information. v The input data record. v An EFS Program Context Area (a private communication area for the EFS program). When the EFS01 routine returns control to DFSORT, it must return a return code in general register 15. DFSORT supplies the EFS02 routine with fields in the parameter list containing: v A Correlator Identifier, which identifies a relational condition containing EFS fields. See EFS02 User Exit Routine on page 671 for more information. v The input data record. When the EFS02 routine returns control to DFSORT, it must return a return code in general register 15.

Termination Phase
DFSORT runs Major Calls 4 and 5 during the termination phase. Only one call is made at each of these Major Calls. Note: If a system abend occurs while DFSORTs ESTAE recovery routine is in effect, and Major Calls 4 and 5 have not already been run, the ESTAE routine runs them. If an EFS abend occurs during Major Call 1, the ESTAE routine does not run Major Calls 4 and 5. See Appendix E, DFSORT Abend Processing, on page 787 for more information about ESTAE. Major Call 4: The EFS program provides any final user-written messages for printing to the message data set.

Chapter 8. Using Extended Function Support

653

How EFS Works

At Major Call 4, DFSORT supplies your EFS program with fields in the EFS interface containing: v An action code indicating that Major Call 4 is in effect. v An EFS Program Context Area (a private communication area for the EFS program). When the EFS program returns control to DFSORT, it can supply fields in the EFS interface containing: v A message list containing messages for printing to the message data set. v A return code (in general register 15). Major Call 5: The EFS program performs any termination processing, such as closing data sets and releasing storage. At Major Call 5, DFSORT supplies your EFS program with fields in the EFS interface containing: v An action code indicating that Major Call 5 is in effect. v An EFS Program Context Area (a private communication area for the EFS program). When the EFS program returns control to DFSORT, it must supply a return code in general register 15.

What You Can Do with EFS

You can design your EFS program to perform seven basic tasks at the initialization, input, and termination phases of DFSORT. Some of the tasks require using the EFS program-generated user exit routines EFS01 and EFS02.
Table 70. Functions of an Extended Function Support (EFS) Program EFS Program Functions Opening and initializing Initialization Phase EFS Program Input Phase Termination Phase

Examining, altering, EFS Program or ignoring DFSORT and non-DFSORT control statements prior to processing by DFSORT Sorting or merging user-defined data types with user-defined collating sequences Providing the logic to include or omit records based on user-defined data types Supplying messages to DFSORT for printing to the message data set EFS Program EFS01

EFS02

EFS Program

654

z/OS V1R10.0 DFSORT Application Programming Guide

What You Can Do with EFS

Table 70. Functions of an Extended Function Support (EFS) Program (continued) EFS Program Functions Terminating DFSORT Closing data sets and housekeeping Initialization Phase EFS Program Input Phase EFS01, EFS02 Termination Phase EFS Program EFS Program

Opening and Initializing Data Sets

Your EFS program can open data sets, obtain necessary storage, and perform other forms of initialization needed during a run.

Examining, Altering, or Ignoring Control Statements

At Major Call 1, your EFS program can send a control statement request list to indicate the control statements and EXEC PARM options you want DFSORT to send to your EFS program at Major Call 2. OUTFIL statements cannot be requested by an EFS program. At Major Call 2, your EFS program can examine, alter, or ignore control statements and EXEC PARM options that DFSORT reads from the EXEC statement, SYSIN, SORTCNTL, DFSPARM, or a parameter list passed from an invoking program. OUTFIL statements cannot be passed to an EFS program or returned from an EFS program to be parsed. Refer to Figure 45 on page 656 for an illustration of the control statement processing sequence used when an EFS program is activated. The same override rules apply to control statements and parameters returned from an EFS program as apply to the original control statements and parameters. For example, a STOPAFT parameter added to the SORT statement by an EFS program is overridden by a STOPAFT parameter in an OPTION statement in the same way as if the SORT statement originally contained the STOPAFT parameter. See Appendix B, Specification/Override of DFSORT Options, on page 741 for full override details.

Chapter 8. Using Extended Function Support

655

What You Can Do with EFS

Direct Invocation of DFSORT

DFSPARM

Product Invocation of DFSORT

DFSORT processing of DFSPARM parameters not requested by the EFS program

EFS program processing of requested DFSPARM parameters at Major Call 2

DFSORT processing of DFSPARM parameters returned by the EFS program

JCL EXEC statement PARM options

SYSIN

SORTCNTL

DFSORT processing of SYSIN control statements and JCL EXEC statement PARM options not requested by the EFS program

Same processing as for DFSPARM

EFS program processing of requested SYSIN control statements and EXEC PARM options at Major Call 2

Invokers parameter list

DFSORT processing of SYSIN control statements and JCL EXEC statement PARM options returned by the EFS program

Same processing as for DFSPARM

SYSOUT

Figure 45. Control Statement Processing Sequence

656

z/OS V1R10.0 DFSORT Application Programming Guide

What You Can Do with EFS

Processing User-Defined Data Types with EFS Program User Exit Routines
You can write your EFS program to provide two user exit routines to perform various tasks during run-time. Your EFS program user exit routines can: v Process user-defined data types. Your EFS program can provide an EFS01 routine to alter any control field of an input record. v Include or omit records based on user-defined data types. Your EFS program can provide an exit routine to examine any input field of an input record to determine whether or not to include that record for processing.

Supplying Messages for Printing to the Message Data Set

You can use an EFS program to tailor messages for several purposes: v To describe new types of operations v To describe extended field parameters v To customize the message data set to your site v To display statistical information about control statements or EXEC PARM options. You can control whether to print the control statements returned by an EFS program to the message data set with: v The LISTX installation option (see Installation Defaults on page 16) v The LISTX or NOLISTX operators in the PARM field of the JCL EXEC statement (see Specifying EXEC/DFSPARM PARM Options on page 29) v The LIST or NOLIST operators of the OPTION program control statement.

Terminating DFSORT
Your EFS program can terminate DFSORT at any of the five Major Calls and also from either of the two EFS program exit routines during the input phase.

Closing Data Sets and Housekeeping

At Major Call 5, your EFS program can close data sets, free storage and perform any other necessary housekeeping.

Structure of the EFS Interface Parameter List

The EFS interface consists of a variable-length parameter list and is used to communicate between DFSORT and your EFS program. DFSORT initializes the parameter list to zeros during the initialization phase, except that the list end indicator is set to X'FFFFFFFF'. The parameter list resides below 16MB virtual, and remains accessible while the EFS program is active, although DFSORT might change its storage location during run-time to optimize use of storage. The actual address in register 1 (used to pass the interface parameter list address) can therefore change while DFSORT is running. Figure 46 on page 658 illustrates the structure of the EFS interface parameter list. The illustrated portions of the list are explained in order in the following pages. EXEC PARMs are not described in the figure, but are included in processing.

Chapter 8. Using Extended Function Support

657

Structure of the EFS Interface Parameter List

R1

Action code 4 bytes Address of Control Statement list 4 bytes Address of original Control Statement including all keywords and corresponding subparameters 4 bytes Address of modified Control Statement including all keywords and corresponding subparameters 4 bytes Length of original Control Statement including all keywords and corresponding subparameters 4 bytes Length of modified Control Statement including all keywords and corresponding subparameters 4 bytes Address of EFS context area 4 bytes

Control statement request list ** bytes Original control statement string * bytes

Modified control statement string * bytes

Figure 46. EFS Interface Parameter List (Part 1 of 2)

658

z/OS V1R10.0 DFSORT Application Programming Guide

Structure of the EFS Interface Parameter List

Address of Extract buffer offsets (zeros if no EFS fields exist) 4 bytes Address of Record lengths list 4 bytes RESERVED 4 bytes RESERVED 4 bytes RESERVED 4 bytes Information flags 4 bytes Address of message list (zeros if none) 4 bytes RESERVED 4 bytes RESERVED 4 bytes RESERVED 4 bytes Address of f EFS01 extract routine (zeros if none) 4 bytes Address of EFS02 INCLUDE/OMIT f routine (zeros if none) 4 bytes List end indicator (X'FFFFFFFF') 4 bytes

Record lengths list 8 bytes

** - Length determined by length fields in the list * - Length determined by corresponding length field
Figure 46. EFS Interface Parameter List (Part 2 of 2)

Action Codes
DFSORT sets one of five action codes before a call to the EFS program: 0 4 Indicates Major Call 1 to the EFS program. DFSORT sends this action code once. Indicates Major Call 2 to the EFS program. DFSORT might send this action code several times at Major Call 2 depending on how many control statements are requested and found. For example, if the SORT, MERGE, and INCLUDE control statements are all supplied in SYSIN and are requested, the EFS program is called twice: once for the SORT control statement (because SORT and MERGE are mutually exclusive, and assuming the SORT statement is specified first, only the SORT statement is taken) and once for the INCLUDE control statement.

Chapter 8. Using Extended Function Support

659

Structure of the EFS Interface Parameter List

8 Indicates Major Call 3 to the EFS program. DFSORT can send this action code once for the Blockset technique and once for the Peerage/Vale technique. Indicates Major Call 4 to the EFS program. DFSORT sends this action code once. Indicates Major Call 5 to the EFS program. DFSORT sends this action code once.

12 16

Control Statement Request List

The control statement request list describes the control statements and the PARM options to be sent to the EFS program by DFSORT. The control statement request list consists of control statement operation definers and PARM option names. The maximum length allowed for an operation definer or PARM option name is eight bytes. If the operation definer or PARM option name is longer, DFSORT will use only the first eight bytes. Length field values must not include their own length. OUTFIL statements cannot be requested by an EFS program. Non-DFSORT operation definers and PARM options must be in EBCDIC format, and the first character must be non-numeric. The format of the control statement request list is:
Chain pointer to next operation definer or EXEC PARM option name, or zero for end of list 4 bytes Length of operation definer or EXEC PARM option name 2 bytes Operation definer or EXEC PARM option name (variable-length) * bytes

The asterisk (*) indicates that the length is determined by the corresponding length field (maximum of 8 bytes).

Control Statement String Sent to the EFS program

DFSORT scans for the requested control statement from SYSIN, SORTCNTL, DFSPARM, or the invokers parameter list to create a contiguous control statement string; DFSORT will handle any necessary continuation requirements for control statements from SYSIN, SORTCNTL, or DFSPARM. DFSORT scans for the requested PARM option to create a contiguous PARM option string. DFSORT places a copy of the requested control statement or PARM option string in a contiguous storage area for the EFS program. No labels are supplied with the control statement; the address of the string always points to the first byte of the appropriate operation definer or PARM option. DFSORT will send the requested control statement(s) or PARM option(s) to the EFS program as found by DFSORT; DFSORT will provide limited syntax checking of control statements or PARM option(s) before sending them to the EFS program. In addition to following the rules in General Coding Rules on page 84, you must observe the following rules for non-DFSORT control statements: v DFSORT will recognize a control statement with no operand(s) provided the operation definer (1) is supplied in SYSIN, SORTCNTL, or DFSPARM and (2) is the only operation definer contained on a line.

660

z/OS V1R10.0 DFSORT Application Programming Guide

Structure of the EFS Interface Parameter List

v Operation definers supplied through SYSIN, SORTCNTL, DFSPARM, or the extended parameter list and requested by the EFS program will not be recognized if they are longer than eight bytes. In addition to observing the rules in z/OS MVS JCL Users Guide and z/OS MVS JCL Reference you must observe the following rule for non-DFSORT PARM options: v PARM options requested by the EFS program will not be recognized if they are longer than eight bytes. DFSORT will send the requested DFSORT or non-DFSORT control statements or PARM options that remain after DFSORT override rules have been applied. If duplicate DFSORT or non-DFSORT control statements or PARM options are supplied through the same source (such as SYSIN), then DFSORT will send the first occurrence of the control statement. The second occurrence of the DFSORT or non-DFSORT control statement or PARM option will be ignored by DFSORT. If duplicate DFSORT or non-DFSORT control statements are supplied through different sources (such as extended parameter list, SORTCNTL, and DFSPARM), then DFSORT will send the control statement remaining after different source override rules have been applied, except for the DFSORT OPTION and DEBUG control statements (see Special Handling of OPTION and DEBUG Control Statements). If mutually exclusive DFSORT control statements (such as SORT/MERGE) are supplied through the same source (such as SYSIN), then DFSORT will send the first occurrence of the control statement. The second occurrence of the DFSORT control statement will be ignored by DFSORT. If mutually exclusive DFSORT control statements (such as SORT/MERGE) are supplied through different sources (such as extended parameter list, SORTCNTL, and DFSPARM), then DFSORT will send the control statement remaining after different source override rules have been applied. The DFSORT control statement not sent will be ignored by DFSORT. Thus the EFS program will not be sent duplicate DFSORT or non-DFSORT control statements (except for the DFSORT OPTION and DEBUG control statements as explained in Special Handling of OPTION and DEBUG Control Statements), or duplicate PARM options. If the EFS program supplies non-DFSORT operands on the DFSORT OPTION control statement and the OPTION control statement is supplied in the extended parameter list, the EFS program must specify the non-DFSORT operands after all DFSORT operands. DFSORT will free any storage it acquired for the control statement or PARM string. Note: Blanks and quotes are very important to DFSORT in determining the control statement to send to an EFS program. Do not supply unpaired quotes in the INCLUDE/OMIT control statements, because DFSORT treats data within quotes as a constant, and treats blanks outside of quotes as the major delimiter.

Special Handling of OPTION and DEBUG Control Statements

The override features of both the DFSORT OPTION and DEBUG control statements, when supplied through different sources, require special handling when EFS processing is in effect and either or both control statements are requested by the EFS program.
Chapter 8. Using Extended Function Support

661

Structure of the EFS Interface Parameter List

For example, DFSORT handles override for the OPTION and DEBUG control statements as follows: v The OPTION control statement supplied in SORTCNTL will selectively override corresponding options on the OPTION control statement supplied in the extended parameter list. v The DEBUG control statement supplied in SORTCNTL will selectively override corresponding options on the DEBUG control statement supplied in the 24-bit parameter list or the extended parameter list. Because of these override features, DFSORT cannot simply send the OPTION control statement supplied in SORTCNTL and not send the OPTION control statement supplied in the extended parameter list. For the EFS program to process all possible operands on the OPTION control statements, DFSORT must send the OPTION control statements supplied in both SORTCNTL and the extended parameter list. DFSORT will send both the OPTION and DEBUG control statements supplied through different sources. If duplicate OPTION or DEBUG control statements are supplied in the same source and the OPTION or DEBUG control statements are also supplied in different sources, DFSORT will send the first occurrence of both the OPTION and DEBUG control statements supplied through different sources.

Control Statement String Returned by the EFS Program

Your EFS program can alter the control statement or PARM option string and replace it in the original contiguous storage area. If the area is too small, your program must allocate a new contiguous area. If the string is returned in a new storage area, your EFS program will be responsible for freeing the acquired storage. Your EFS program must set an Informational flag to indicate whether the control statement or PARM option in the string should be parsed or ignored by DFSORT (see Information Flags on page 667 for further details). OUTFIL statements cannot be returned from an EFS program to be parsed.

Rules for Parsing

The content and format of the altered control statement to be parsed must correspond to valid DFSORT values as described in Chapter 3, Using DFSORT Program Control Statements, on page 81, except when using the FIELDS operand with SORT or MERGE, or the COND operand with INCLUDE or OMIT (see EFS Formats for SORT, MERGE, INCLUDE, and OMIT Control Statements on page 663). You must observe the following rules for control statements to be returned to DFSORT for parsing: v The operation definer and corresponding operands must be in uppercase EBCDIC format. v At least one blank must follow the operation definer (SORT, MERGE, RECORD, and so on). A control statement can start with one or more blanks and can end with one or more blanks. No other blanks are allowed unless the blanks are part of a constant. v Labels are not allowed; a leading blank, or blanks, before the control statement name is optional. v No continuation character is allowed. v Comment statements, blank statements, and remarks are not allowed.

662

z/OS V1R10.0 DFSORT Application Programming Guide

Structure of the EFS Interface Parameter List

The content and format of the altered EXEC PARM option to be parsed must correspond to valid DFSORT values as described in Specifying EXEC/DFSPARM PARM Options on page 29. The following operands will be ignored by DFSORT if returned by an EFS program on the OPTION control statement: EFS LIST NOLIST LISTX NOLISTX LOCALE MSGDDN MSGDD MSGPRT SMF SORTDD SORTIN SORTOUT USEWKDD The following EXEC PARM options will be ignored by DFSORT if returned by an EFS program: EFS LIST NOLIST LISTX NOLISTX LOCALE MSGDDN MSGDD MSGPRT

EFS Formats for SORT, MERGE, INCLUDE, and OMIT Control Statements
In addition to using the SORT, MERGE, INCLUDE, and OMIT control statements as explained in Program Control Statements, you can also use two additional formats on the FIELDS and COND parameters. The formats are termed D1 and D2 and apply as follows: v D1 with the FIELDS parameter of the SORT or MERGE statement v D2 with the COND parameter of the INCLUDE or OMIT statement. Use D1 and D2 to reflect data types that require special processing by EFS program exit routines EFS01 and EFS02, respectively. You cannot specify D2 format with the INCLUDE or OMIT parameters of the OUTFIL statement.

D1 Format on FIELDS Operand

The syntax for the SORT and MERGE statements using the D1 format on the FIELDS operand is as follows.

Chapter 8. Using Extended Function Support

663

Structure of the EFS Interface Parameter List

, SORT MERGE FIELDS= ( mp,mm,mf,ms )

Where Represents mp mm mf ms field position within the input record field length the D1 format that designates this field as an EFS control field must be either ascending (A) or descending (D); modification by an E61 exit (E) is not allowed.

Table 71 gives an example of using the D1 format for a SORT control statement returned to DFSORT by the EFS program. You must adhere to the following requirements for the D1 format: v The mp, mm, and ms values returned must be valid SORT or MERGE control statement values, except: The combined value of mp and mm may exceed the record length. CHALT will have no effect on EFS fields and will not limit the length to 256. Value E for ms will not be allowed; EFS fields may not be altered by an E61. FORMAT=D1 will not be allowed.
Table 71. D1 Format Returned by an EFS Program Original SORT control statement sent to EFSPGM SORT FIELDS=(15,4,FF,A,20,4,CH,A,40,7,FF,D) Altered SORT control statement returned by EFSPGM SORT FIELDS=(15,4,D1,A,20,4,CH,A,40,7,D1,D) where: FF is a user-defined format that is modified to D1 by the EFS program before returning to DFSORT

D2 Format on COND Operand

Following is the syntax for the INCLUDE or OMIT statements using the D2 format on the COND operand.

, , ( INCLUDE COND= ( OMIT

AND , OR AND , OR

mc,mm,mf, operator , mc, mm, mf, constant mask

664

z/OS V1R10.0 DFSORT Application Programming Guide

Structure of the EFS Interface Parameter List

Where Represents mc mm mf the correlator identifier, a numeric value used to identify each relational condition field length the D2 format designating an EFS field within the relational condition

operator a valid DFSORT comparison or bit logic operator constant a valid DFSORT decimal, character, hexadecimal or bit constant. mask a valid DFSORT hexadecimal or bit string

Table 72 gives an example of using a correlator identifier and the D2 format for an INCLUDE control statement returned to DFSORT by the EFS program. Note: The values for the correlator identifiers assigned to each relational condition by the EFS program can be in any chosen order. The example in Table 72 shows a sequential ordering for the correlator identifiers. You must adhere to the following requirements for the D2 format: v The mc, mm, or constant values returned must be valid INCLUDE or OMIT control statement values, except: The combined value of mc and mm might exceed the record length. Any valid DFSORT constant or mask is allowed. If COND=(mc1,mm1,mf1,operator,mc2,mm2,mf2) is used, both mf1 and mf2 must be D2. CHALT has no effect on EFS fields. FORMAT=D2 is not allowed.
Table 72. Correlator Identifier and D2 Format Returned by an EFS Program Original INCLUDE control statement sent to EFSPGM INCLUDE COND=(15,4,FF,EQ,20,4,FF,AND,40,7,FF,NE,50,7,FF,OR, 30,2,FF,NE,35,2,FF) Altered INCLUDE control statement returned by EFSPGM INCLUDE COND=(1,4,D2,EQ,1,4,D2,AND,2,7,D2,NE,2,7,D2,OR,3,2,D2,NE,3,2,D2) Where: v FF is a user-defined format and modified to D2 by the EFS program before returning to DFSORT. v The first relational condition specified, (1,4,D2,EQ,1,4,D2), uses correlator identifier value 1 to identify this relational condition. v The second relational condition specified, (2,7,D2,NE,2,7,D2), uses correlator identifier value 2 to identify this relational condition. v The third relational condition specified, (3,2,D2,NE,3,2,D2), uses correlator identifier value 3 to identify this relational condition.

Chapter 8. Using Extended Function Support

665

Structure of the EFS Interface Parameter List

Length of Original Control Statement

The control statement includes the first byte of the control statement through the last operand of the control statement or, if only an operation definer is supplied, the length of the operation definer. DFSORT does not send labels supplied with the control statement.

Length of the Altered Control Statement

The length includes the first byte of the control statement through the last operand of the control statement. If leading blanks are provided, the length includes the first leading blank.

EFS Program Context Area

The EFS program context area is a private communication area that can be set up and used by the EFS program as appropriate. DFSORT sends the context area address to the EFS program at each Major Call and at each call to EFS01 and EFS02. The EFS program is responsible for obtaining (at Major Call 1) and releasing (at Major Call 5) the necessary storage for the EFS program context area.

Extract Buffer Offsets List

A linked list of offsets into the extract buffer will be passed to your EFS program. The offsets show the starting positions into the buffer area of any EFS control fields specified on the SORT or MERGE FIELDS operand. The offsets are sent only for EFS control fields and are sent in the same order as specified on the FIELDS operand. If no EFS control fields exist, the address to the offsets is zero. DFSORT frees any storage it acquired for the extract buffer offsets list. The format of the extract buffer offsets list is:
Chain pointer to the next offset or zero for end of list 4 bytes Offset n

4 bytes

Record Lengths List

The record lengths list is a linked list containing the input and output record lengths. You must be aware of the possible change in record size during run-time (for example, with an E15 user exit). The input and output record lengths are sent to the EFS program for informational use only. DFSORT ignores any changes to the values made to the record lengths list returned by the EFS program. DFSORT frees any storage it acquired for the record lengths list. The format of the record lengths list is:

666

z/OS V1R10.0 DFSORT Application Programming Guide

Structure of the EFS Interface Parameter List

Input record length

Output record length

4 bytes

4 bytes

Information Flags
The information flags are defined in the figure that follows:

bit

0 1 2 3 45 6 7 0 0 000 0 0 0

8 0 0000000 00000000 00000000 Reserved 0 = Inform DFSORT to ignore parsing the verb the EFS program returns to DFSORT 1 = Inform DFSORT to parse the verb the EFS program returns to DFSORT

0 = Fixed-length records 1 = Variable-length records 0 = PARM option/Control statement not from DFSPARM 1 = PARM option/Control statement from DFSPARM 0 0 = No application in effect 0 1 = SORT application in effect 1 0 = MERGE application in effect 1 1 = COPY application in effect 0 = SORTDIAG not being used 1 = SORTDIAG being used 0 = Directly invoked 1 = Program invoked 0 0 = Option from EXEC PARM 0 1 = Control statement from SYSIN 1 0 = Control statement from SORTCNTL 1 1 = Control statement from invoking parameter list

Figure 47. Information Flags

Bit Bits 0 and 1

Description Indicate the source of the control statement being processed. Information flags 0 and 1 are set by DFSORT before a call to the EFS program at Major Call 2 (multiple calls are possible at Major Call 2). Indicates how DFSORT was invoked. Information flag 2 is set by DFSORT before Major Call 1 to the EFS program. Indicates whether diagnostic messages are to be printed. Information flag 3 is set by DFSORT before Major Call 1 to the EFS program.

Bit 2

Bit 3

Chapter 8. Using Extended Function Support

667

Structure of the EFS Interface Parameter List

Bits 4 and 5 Indicate the DFSORT function being run. Information flags 4 and 5 are set by DFSORT before each call at Major Call 2 and Major Call 3 to the EFS program (multiple calls are possible at Major Call 2 and Major Call 3). Indicates the source of PARM options and control statements from DFSPARM. Information flag 6 is set by DFSORT before each call at Major Call 2 to the EFS program (multiple calls are possible at Major Call 2). Indicates whether fixed-length records or variable-length records are to be processed. Information flag 7 is set by DFSORT before each call at Major Call 3 to the EFS program (multiple calls are possible at Major Call 3). Set by the EFS program to inform DFSORT whether to parse or ignore the control statement returned by the EFS program. Printing of the control statement is managed by the LISTX/NOLISTX parameters (see OPTION Control Statement on page 167 for further details). Information flag 8 is set by the EFS program before returning to DFSORT from each call at Major Call 2 (multiple calls are possible at Major Call 2).

Bit 6

Bit 7

Bit 8

Message List
Your EFS program can return informational or critical messages. A return code of 0 in general register 15 indicates an informational message while a return code of 16 indicates a critical message. If the EFS program has no messages to send after a Major Call, it must zero the message list address in the EFS interface parameter list. At Major Call 2, if the EFS program finds a syntax error in a control statement, it can return an offset relative to the start of the string to indicate the location of the error. DFSORT first prints the control statement in error and then prints another line containing a dollar symbol ($) at the location indicated by the offset. Because DFSORT associates the relative offset with a critical message, the EFS program must return with a return code of 16 in general register 15. If a relative offset is returned for an EXEC PARM, the relative offset will be ignored. The EFS program must free any storage it acquired for its messages. The length field values must not include their own length. The message list format follows:
Pointer to next message or zero for list end 4 bytes Relative offset (to syntax error) or zero 2 bytes Length of the message text 2 bytes Message text (variable length) * bytes

668

z/OS V1R10.0 DFSORT Application Programming Guide

Structure of the EFS Interface Parameter List

An asterisk (*) indicates that the length is determined by the corresponding length field. DFSORT imposes no restrictions on the format of the messages returned by an EFS program. If you wish, you can use the DFSORT message format so that messages in the message data set are consistent in appearance. For a description of the message format used by DFSORT, see z/OS DFSORT Messages, Codes and Diagnosis Guide

EFS Program Exit Routines

If you specify EFS control fields (D1 format) or EFS fields (D2 format), DFSORT calls the EFS01 or EFS02 exit routines, respectively, to process those fields. The routines are generated by your EFS program, which can return the following information about them at Major Call 3: v The address of an extract routine, EFS01, which is used to extract the control fields of an input record to a buffer area before a sort or merge takes place; EFS01 is not applicable to a copy application. v The address of an INCLUDE or OMIT routine, EFS02, which is used to process comparison logic for including or omitting records. During the termination phase, the EFS program must free any storage used by these routines.

EFS01 and EFS02 Function Description

Each DFSORT control statement describes to DFSORT the type of operation to be performed on input data. Through the EFS interface, DFSORT enables an EFS program to provide user exit routines to perform functions beyond the capabilities of DFSORT control statements. The EFS program can provide user exit routine EFS01 to supplement the function of the DFSORT SORT/MERGE control statements and can provide user exit routine EFS02 to perform the function of the DFSORT INCLUDE/OMIT control statements. When preparing your EFS program exit routines, remember: v The routines must follow standard linkage conventions. v The general registers used by DFSORT for linkage and communication of parameters follow operating system conventions (see Figure 48 on page 670). v The routines must use the described interfaces (see EFS01 Parameter List on page 671 and EFS02 Parameter List on page 672).

Chapter 8. Using Extended Function Support

669

EFS Program Exit Routines

Register 1 13

Use DFSORT places the address of a parameter list in this register. DFSORT places the address of a standard save area in this register. The area can be used to save contents of registers used by the EFS program exit routine. The first word of the area contains the characters SM1 in its three low-order bytes. Contains the address of DFSORT return point. Contains the address of the EFS program exit routine. This register can be used as the base register for EFS program exit routine. This register is also used by the EFS program exit routine to pass return codes to DFSORT.

14 15

Figure 48. DFSORT Register Convention

EFS01 User Exit Routine

Processing of user-defined data types with the EFS01 exit routine requires using the function that alters control statements. EFS program requirements at Major Calls 1 and 2 are: v At Major Call 1, the EFS program must provide the control statement request list with the SORT or MERGE operation definer. See Control Statement Request List on page 660 or further details. v At Major Call 2, the EFS program must return a new format, D1, on the SORT or MERGE control statement that informs DFSORT to call the EFS01 routine, (the control fields defined with the D1 format are also known as EFS control fields). See EFS Formats for SORT, MERGE, INCLUDE, and OMIT Control Statements on page 663 for further details. The EFS program must also return the final position, length, and sequence order. DFSORT uses the final position and length to create a list of offsets. At Major Call 3, DFSORT sends the EFS program a list of offsets into a buffer. These offsets indicate where in the buffer the EFS program must have the EFS01 routine move the data indicated by the EFS control fields. See Extract Buffer Offsets List on page 666 for further details. At Major Call 3, the EFS program must return the address of the EFS01 routine to DFSORT. During the input phase, DFSORT calls the EFS01 routine for each input record. The EFS01 exit routine must move all data indicated by the EFS control fields, specified in the SORT or MERGE FIELDS operand, from the input record to the extract buffer area as specified by the offsets in the extract buffer offsets list. For each EFS control field, the total number of bytes moved by EFS01 into the buffer area is equal to the total number of bytes specified in the mm parameter of the altered SORT or MERGE operand. Records are ordered according to the altered ms parameter. The EFS01 routine is called to extract all EFS control fields to the extract buffer area each time a new record is brought into the input phase.

670

z/OS V1R10.0 DFSORT Application Programming Guide

EFS Program Exit Routines

DFSORT will do sort or merge processing using the data in the extract buffer, and will treat the data as binary data.

EFS01 Parameter List

DFSORT sends three words to the EFS01 user exit routine each time it is entered: v The address of the extract buffer area v The address of the input record v The address of the EFS program context area. DFSORT places the address of a parameter list in register 1. The list begins on a fullword boundary and is three fullwords long. The format of the parameter list is:
Bytes 1 through 4 Address of the extract buffer area Address of the input record Address of the EFS program context area

The EFS01 routine must return one of the following return codes in general register 15: 0 16 The extraction of the EFS control field was successful. The extraction of the EFS control field was unsuccessful; terminate DFSORT.

EFS02 User Exit Routine

Including or omitting records based on user-defined data types with the EFS02 user exit routine requires using the function of altering control statements. EFS program requirements at Major Calls 1 and 2 are: v At Major Call 1, the EFS program must provide the control statement request list with the INCLUDE or OMIT operation definer. See Control Statement Request List on page 660 for further details. v At Major Call 2, the EFS program must return a new format, D2, on the INCLUDE or OMIT control statement that informs DFSORT to call the EFS02 routine (the fields defined with the D2 format are also known as EFS compare fields). See EFS Formats for SORT, MERGE, INCLUDE, and OMIT Control Statements on page 663 for further details. The EFS program must also return the final length and, in place of the position value, must send an identifier (known as a correlator identifier) that identifies a specific relational condition. For each relational condition containing EFS fields, there must be a unique correlator identifier to identify the particular relational condition. See EFS Formats for SORT, MERGE, INCLUDE, and OMIT Control Statements on page 663 for further details. At Major Call 3, the EFS program must return the address of the EFS02 routine to DFSORT. The EFS02 routine is called to perform the INCLUDE or OMIT comparison logic for each relational condition containing an EFS field. During the input phase, DFSORT will call the EFS02 exit routine one or more times for each input record according to the evaluation defined by the AND, OR, or parentheses. The EFS02 exit routine must use the correlator identifier to determine the current relational condition being performed. EFS02 must perform the comparison logic for the current relational condition as identified by the correlator identifier. Figure 49 on page 672
Chapter 8. Using Extended Function Support

671

EFS Program Exit Routines

page 672 repeats Table 72 on page 665 to illustrate an example of the calling sequences to an EFS02 by DFSORT.
Original INCLUDE control statement sent to EFSPGM INCLUDE COND=(15,4,FF,EQ,20,4,FF,AND,40,7,FF,NE,50,7,FF,OR, 30,2,FF,NE,35,2,FF) Altered INCLUDE control statement returned by EFSPGM INCLUDE COND=(1,4,D2,EQ,1,4,D2,AND,2,7,D2,NE,2,7,D2,OR, 3,2,D2,NE,3,2,D2) Where: the calling sequence to EFS02 may be summarized with the following tables:

Relational condition with Correlator Identifier 1

EFS02 returns a return code of 0=True or 4=False True False

DFSORT action when the next logical operator is: AND Call EFS02 with Correlator Id 2 Call EFS02 with Correlator Id 3

Relational condition with Correlator Identifier 2

EFS02 returns a return code of 0=True or 4=False True False

DFSORT action when the next logical operator is: OR Include the record Call EFS02 with Correlator Id 3

Relational condition with Correlator Identifier 3

EFS02 returns a return code of 0=True or 4=False True False

DFSORT action when the next logical operator is: None Include the record Omit the record

Figure 49. Calling Sequence to EFS02 by DFSORT

EFS02 Parameter List

DFSORT sends three words to the EFS02 exit routine each time it is entered: v The address of the correlator identifier v The address of the input record v The address of the EFS program context area. DFSORT places the address of a parameter list in register 1. The list begins on a fullword boundary and is three fullwords long. The format of the parameter list is:
Byte 1 00 Address of the input record Byte 2 00 Byte 3 00 Byte 4 Correlator identifier

672

z/OS V1R10.0 DFSORT Application Programming Guide

EFS Program Exit Routines

Byte 1 Byte 2 Byte 3 Byte 4

Address of the EFS program context area

The EFS02 exit routine must return one of the following return codes in general register 15: 0 True The record passed the INCLUDE or OMIT test for the relational condition of an EFS field. If applicable, processing continues with the next relational condition. Otherwise, DFSORT accepts the record if INCLUDE is specified or omits the record if OMIT is specified. 4 False The record did not pass the INCLUDE or OMIT test for the relational condition of an EFS field. If applicable, processing continues with the next relational condition. Otherwise, DFSORT omits the record if INCLUDE is specified or includes the record if OMIT is specified. 16 Terminate An error occurred in processing the INCLUDE or OMIT logic; terminate DFSORT.

Addressing and Residence Mode of EFS Program User Exit Routines

DFSORT supplies the following features to allow residence above or below 16MB virtual and use of either 24-bit or 31-bit addressing: f (bit 0 of EFS program exit routine address) 0 1 Enter the EFS program exit routine with 24-bit addressing in effect. Enter the EFS program exit routine with 31-bit addressing in effect.

The EFS program user exit routine can return to DFSORT with either 24-bit or 31-bit addressing in effect. The return address that DFSORT placed in register 14 must be used. Except for the EFS program context area address (which DFSORT sends to the EFS program user exit routine unchanged), DFSORT handles the EFS program exit routine parameter list addresses (that is, the pointer to the EFS program exit routine parameter list and the addresses in the parameter list) as follows: v If the EFS program exit routine is entered with 24-bit addressing in effect, DFSORT can pass clean (zeros in the first 8 bits) 24-bit addresses or 31-bit addresses to the EFS program exit routine. The EFS program exit routine must return clean 24-bit addresses if the EFS program exit routine returns to DFSORT with 31-bit addressing in effect. v If the EFS program exit routine is entered with 31-bit addressing in effect, DFSORT can pass clean 24-bit addresses or 31-bit addresses to the EFS program exit routine. The EFS program exit routine must return 31-bit addresses or clean 24-bit addresses.

Chapter 8. Using Extended Function Support

673

EFS Program Return Codes

EFS Program Return Codes You Must Supply

Your EFS program must pass one of two return codes to DFSORT: 0 Continue Processing If you want DFSORT to continue processing for this Major Call, return with a return code of zero in general register 15. 16 Terminate DFSORT If you want DFSORT to terminate processing for this Major Call, return with a return code of 16 in general register 15. If the EFS program returns a return code of 16 from a Major Call prior to Major Call 4 or one of its generated user exit routines returns a return code of 16, DFSORT will skip interim Major Calls, where applicable, to the EFS program or user exit routine, and will call the EFS program at Major Call 4 and at Major Call 5. Multiple calls are possible at Major Call 2 and Major Call 3. If the EFS program returns with a return code of 16 from one of the multiple calls at Major Call 2, subsequent calls at Major Call 2, if applicable, will be completed. If the EFS program returns with a return code of 16 from one of the multiple calls at Major Call 3, subsequent calls at Major Call 3, if applicable, will not be completed. If the EFS program returns a return code of 16 at Major Call 4, DFSORT will still call the EFS program at Major Call 5.

Record Processing Order

The order of record processing when using EFS is similar to processing without it. Figure 50 on page 675 illustrates the record processing sequence for a sort or merge and Figure 51 on page 676 illustrates the record processing sequence for a copy when EFS processing is in effect. The figures illustrate the same points as described in Figure 2 on page 9 with the following exceptions: v When record processing is done for an INCLUDE or OMIT control statement, an EFS02 user exit routine is called to perform the comparison logic for the relational conditions with EFS fields. v When record processing is done for a SORT or MERGE control statement, an EFS01 user exit routine is called to perform the extraction process for EFS control fields.

674

z/OS V1R10.0 DFSORT Application Programming Guide

Record Processing Order

Sort Application
SORTIN

Merge Application
SORTINnn

SKIPREC

E15 or COBOL E15

E15 or COBOL E15

E32

INCLUDE OMIT

EFS02

INCLUDE OMIT

EFS02

STOPAFT

INREC

INREC

SORT SUM

EFS01

MERGE SUM

EFS01

OUTREC

OUTREC

E35 or COBOL E35

E35 or COBOL E35

E35 or COBOL E35

E35 or COBOL E35

SORTOUT

OUTFIL

SORTOUT

OUTFIL

Figure 50. EFS Record Processing Sequence for a Sort or Merge

Chapter 8. Using Extended Function Support

675

How to Request a SNAP Dump

Copy Application
SORTIN

SKIPREC

E15 or COBOL E15

E15 or COBOL E15

INCLUDE OMIT

EFS02

STOPAFT

INREC

COPY

OUTREC

E35 or COBOL E35

E35 or COBOL E35

SORTOUT

OUTFIL

Figure 51. EFS Record Processing Sequence for a Copy

How to Request a SNAP Dump

You can request a SNAP dump for diagnostic purposes before or after any Major Call except Major Call 1. Use either the EFSDPBFR parameter or the EFSDPAFT parameter on the DEBUG statement. See DEBUG Control Statement on page 92 for the correct syntax.

676

z/OS V1R10.0 DFSORT Application Programming Guide

EFS Program Example

EFS Program Example

The following example shows how an EFS program can be used to change control statements at run-time. The following information is assumed for this example DFSORT run: v The EFS program EFSPGM resides in the same library as the DFSORT modules. v The JCL statements for the application are:
//EXAMPLE1 JOB A12345,J. SMITH //S1 EXEC PGM=SORT,PARM=EFS=EFSPGM //SYSOUT DD SYSOUT=A //SORTIN DD DSNAME=SMITH.INPUT,DISP=SHR, // UNIT=3380,SPACE=(TRK,(15,2)),VOL=SER=XYZ003, // DCB=(LRECL=80,BLKSIZE=80,RECFM=F) //SORTOUT DD DSNAME=SMITH.OUTPUT,DISP=(NEW,KEEP), // UNIT=3380,SPACE=(TRK,(15,2)),VOL=SER=XYZ003 //SYSIN DD * SORT FIELDS=(5,20,CH,A,13,5,BI,D) OPTION STOPAFT=30,DYNALLOC=3390 /*

DFSORT Initialization Phase:

Major Call 1
Prior to Major Call 1, DFSORT sets the following fields in the EFS interface parameter list: v Action code=0 Major Call 1 is in effect. v Informational bit flag 2=0 The DFSORT run is JCL-invoked. v Informational bit flag 3=0 SORTDIAG is not in effect. DFSORT calls EFS program EFSPGM at Major Call 1, and EFSPGM sets the following fields in the EFS interface parameter list: v Control statement request list Contains the OPTION operation definer, which indicates to DFSORT that the OPTION control statement is requested by EFSPGM. v EFSPGM program context area EFSPGM will be using the context area. v Message list=0 EFSPGM has no messages for DFSORT to print to the message data set. General register 15 is set to zero.

Major Call 2
Prior to Major Call 2, DFSORT sets the following fields in the EFS interface parameter list: v Action code=4 Major Call 2 is in effect. v Informational bit flag 4=0 and informational bit flag 5=0 No application is in effect.

Chapter 8. Using Extended Function Support

677

EFS Program Example

EFSPGM requested the OPTION control statement. DFSORT makes a call to EFS program EFSPGM for each control statement requested; in this case, one. DFSORT also sets the following fields in the EFS interface parameter list: v Informational bit flag 0=0 and informational bit flag 1=1 The requested control statement came from SYSIN. v The original OPTION control statement, including all operands and corresponding subparameters OPTION STOPAFT=30,DYNALLOC=3390 v The length of the original OPTION control statement, including all operands and corresponding subparameters The original control statement string is 31 bytes long. DFSORT calls EFS program EFSPGM at Major Call 2, and EFSPGM sets the following fields in the EFS interface parameter list: v Informational bit flag 8=1 DFSORT must parse the control statement returned by EFSPGM. v The altered OPTION control statement, including all operands and subparameters OPTION STOPAFT=30,DYNALLOC=3380,EQUALS v The length of the altered OPTION control statement, including all operands and subparameters The altered control statement string is 38 bytes long. v Message list=0 EFSPGM has no messages for DFSORT to print to the message data set. General register 15 is set to zero. Table 73 shows the original control statement sent to EFS program EFSPGM and the altered control statement returned by EFS program EFSPGM.
Table 73. Original and Altered Control Statements Original OPTION control statement sent to EFSPGM OPTION STOPAFT=30,DYNALLOC=3390 Altered OPTION control statement returned by EFSPGM OPTION STOPAFT=30,DYNALLOC=3380,EQUALS Where: STOPAFT=30 is the original operand and value DYNALLOC=3380 is the original operand with a new value EQUALS option has been added

Major Call 3
Prior to Major Call 3, DFSORT sets the following fields in the EFS interface parameter list: v Action code=8 Major Call 3 is in effect. v Informational bit flag 4=0 and informational bit flag 5=1 A sort application is in effect.

678

z/OS V1R10.0 DFSORT Application Programming Guide

EFS Program Example

v Informational bit flag 7=0 Fixed-length records are being processed. v Record lengths list values=80 The LRECL of the input and output data sets is 80. Because the SORTOUT LRECL was not specified, DFSORT defaulted to the SORTIN LRECL for the SORTOUT LRECL. v Extract buffer offsets list=0 No EFS control fields were specified on the SORT control statement. DFSORT calls EFS program EFSPGM at Major Call 3, and EFSPGM sets the following fields in the EFS interface parameter list: v EFS01 address=0 Because the SORT control statement has no EFS control fields, the EFS01 user exit routine is not used. Because no INCLUDE control statement was supplied (with EFS fields), the EFS02 user exit routine is not used. v Message list=0 EFSPGM has no messages for DFSORT to print to the message data set. General register 15 is set to zero.

DFSORT Termination Phase

Major Call 4
Prior to Major Call 4, DFSORT sets the following fields in the EFS interface parameter list: v Action code=12 Major Call 4 is in effect. DFSORT calls EFS program EFSPGM at Major Call 4, and EFSPGM sets the following fields in the EFS interface parameter list: v Message list=0 EFSPGM has no messages for DFSORT to print to the message data set. And general register 15 is set to zero.

Major Call 5
Prior to Major Call 5, DFSORT sets the following fields in the EFS interface parameter list: v Action Code=16 Major Call 5 is in effect. DFSORT calls EFS program EFSPGM at Major Call 5, and EFSPGM does not set any fields in the EFS interface parameter list but sets general register 15 to zero.

Chapter 8. Using Extended Function Support

679

680

z/OS V1R10.0 DFSORT Application Programming Guide

Chapter 9. Improving Efficiency

Improving Performance . . . . . . . . . . Design Your Applications to Maximize Performance . . . . . . . . . . . . . . Directly Invoke DFSORT Processing . . . . . Plan Ahead When Designing New Applications Efficient Blocking . . . . . . . . . . Specify Efficient Sort/Merge Techniques . . . Sorting Techniques . . . . . . . . . Merging Techniques . . . . . . . . . Specify Input/Output Data Set Characteristics Accurately . . . . . . . . . . . . . Input File Size . . . . . . . . . . . Variable-Length Records . . . . . . . . Disk Devices . . . . . . . . . . . Use Extended Format Data Sets . . . . . . Use DFSMSrmm-Managed Tapes, or ICETPEX Specify Devices that Improve Elapsed Time . . Use Options that Enhance Performance . . . . CFW . . . . . . . . . . . . . . DSA . . . . . . . . . . . . . . DSPSIZE . . . . . . . . . . . . . FASTSRT . . . . . . . . . . . . . SDB . . . . . . . . . . . . . . HIPRMAX . . . . . . . . . . . . MOSIZE . . . . . . . . . . . . . Use DFSORTs Fast, Efficient Productivity Features . . . . . . . . . . . . . . INCLUDE or OMIT, STOPAFT, and SKIPREC OUTFIL . . . . . . . . . . . . . LOCALE . . . . . . . . . . . . . 681 682 682 682 682 683 683 683 683 684 684 684 684 685 685 685 685 685 685 686 686 687 687 687 687 687 687 SUM . . . . . . . . . . . . . ICETOOL . . . . . . . . . . . Avoid Options that Degrade Performance . . CKPT . . . . . . . . . . . . . EQUALS . . . . . . . . . . . . EQUCOUNT . . . . . . . . . . LOCALE . . . . . . . . . . . . NOCINV . . . . . . . . . . . . NOBLKSET . . . . . . . . . . . VERIFY . . . . . . . . . . . . Tape Work Data Sets . . . . . . . . User Exit Routines. . . . . . . . . Dynamic Link-Editing . . . . . . . EFS Programs . . . . . . . . . . Use Main Storage Efficiently . . . . . . Tuning Main Storage . . . . . . . . Releasing Main Storage . . . . . . . Allocate Temporary Work Space Efficiently . Disk Work Storage Devices . . . . . . Virtual I/O for Work Data Sets . . . . Tape Work Storage Devices . . . . . . Use Hipersorting . . . . . . . . . . Sort with Data Space . . . . . . . . . Use Memory Object Sorting . . . . . . Use ICEGENER Instead of IEBGENER . . . ICEGENER Return Codes . . . . . . . Use DFSORTs Performance Booster for The SAS System . . . . . . . . . . . . . . Use DFSORTs BLDINDEX Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688 688 688 688 688 688 688 688 689 689 689 689 689 689 689 689 691 692 692 693 693 694 694 695 696 699

. 699 . 699

Improving Performance
DFSORT is designed to optimize performance automatically. It sets optimization variables (such as buffer sizes) and selects the most efficient of several sorting and merging techniques. You can improve DFSORT performance in several ways: v Design your applications to maximize performance: Directly invoke DFSORT processing Plan ahead when designing new applications Specify efficient sort/merge techniques Specify input/output data set characteristics accurately Use extended format data sets Use DFSMSrmm-managed tapes, or ICETPEX Specify devices that improve elapsed time Use options that enhance performance Use DFSORTs fast, efficient productivity features Avoid options that degrade performance. v Use main storage efficiently v Allocate temporary work space efficiently v Use Hipersorting v Sort with data space
Copyright IBM Corp. 1973, 2006

681

Improving Performance
v v v v Use Use Use Use memory object sorting ICEGENER instead of IEBGENER DFSORTs Performance Booster for The SAS System DFSORTs BLDINDEX support.

The DFSORT z/OS DFSORT Tuning Guide provides additional information related to many of the topics covered in this chapter.

Design Your Applications to Maximize Performance

Even though DFSORT automatically optimizes performance when your application is run, you can still improve efficiency by using specifications and options that permit DFSORT to make the best possible use of available resources.

Directly Invoke DFSORT Processing

You can enhance performance by invoking DFSORT with JCL instead of invoking it from a COBOL or a PL/I program. Generally, COBOL or PL/I is used for convenience. However, the trade-off can be degraded performance. You can improve efficiency by taking advantage of the way DFSORT installation defaults and run-time options can be fine-tuned for optimum performance, especially to make use of control statements that work together, such as INCLUDE/OMIT, INREC/OUTREC, SUM, and OUTFIL. You can eliminate records from input files, reformat records to eliminate unwanted fields, combine records arithmetically, and create reports, without requiring routines from other programs.

Plan Ahead When Designing New Applications

You should consider several factors when designing new applications. Some of these factors are discussed below. Whenever possible: v Use either EBCDIC character or binary control fields v Place binary control fields so they start and end on byte boundaries v Avoid using the alternative collating sequence character translation v If you know that a fixed-point control field always contains positive values, specify it as a binary field. v If you know that a packed decimal or zoned decimal control field always contains positive values with the same sign (for example, X'C'), specify it as a binary field. v Use packed decimal format rather than zoned decimal v If several contiguous character or binary control fields in the correct order of significance are to be sorted or merged in the same order (ascending or descending), specify them as one control field v Avoid overlapping control fields. v Avoid using locale processing if your SORT, MERGE, INCLUDE, or OMIT character fields can be processed using the binary encoding of the data.

Efficient Blocking
You can improve the performance of DFSORT significantly by blocking your input and output records efficiently. Whenever possible, use system-determined optimum block sizes for your data sets.

682

z/OS V1R10.0 DFSORT Application Programming Guide

Design Your Applications to Maximize Performance

For more information about letting DFSORT select system-determined optimum block sizes for your output data sets, see the discussion of the SDB option in OPTION Control Statement on page 167.

Specify Efficient Sort/Merge Techniques

Depending on various conditions, DFSORT selects different techniques for sorting and merging. Message ICE143I informs you which technique has been selected. For copy applications, Blockset is the only technique used. If your program cannot use Blockset, DFSORT issues error message ICE160A and stops processing.

Sorting Techniques
One condition that affects which sorting technique DFSORT selects is the type of device used for intermediate storage. If you use a tape device, the Conventional technique is used, which is less efficient. For more information on using tape devices for intermediate storage, see Tape Work Storage Devices on page 693. The Blockset and Peerage/Vale techniques can be used only with disk work data sets. These techniques are discussed below. Blockset Sorting Techniques: DFSORTs most efficient techniques, FLR-Blockset (for fixed-length records) and VLR-Blockset (for variable-length records), will be used for most sorting applications. Notes: v The Blockset technique might require more intermediate work space than Peerage/Vale. For more information, see Allocate Temporary Work Space Efficiently on page 692. v If Blockset is not selected, you can use a SORTDIAG DD statement to force message ICE800I, which gives a code indicating why Blockset cannot be used. Peerage/Vale Sorting Techniques: When the conditions for use of the Blockset sorting technique are not met, DFSORT uses Peerage/Vale.

Merging Techniques
| For merging applications, DFSORT uses the Blockset and Conventional techniques. Blockset Merging Techniques: DFSORTs most efficient techniques, FLR-Blockset (for fixed-length records) and VLR-Blockset (for variable-length records), will be used for most merging applications. Note: If Blockset is not selected, you can use a SORTDIAG DD statement to force message ICE800I, which gives a code indicating why Blockset cannot be used. Conventional Merging Technique: When the conditions for use of the Blockset merging technique are not met, DFSORT uses the Conventional merge technique, which is less efficient.

Specify Input/Output Data Set Characteristics Accurately

DFSORT uses the information given it (about the operation it is to perform) to optimize for highest efficiency. When you supply incorrect information or do not supply information such as data set size and record format, the program makes assumptions that, if incorrect, can lead to inefficiency or program termination.

Chapter 9. Improving Efficiency

683

Design Your Applications to Maximize Performance

Input File Size

When DFSORT has accurate information about the input file size, it can make the most efficient use of both main storage and intermediate work storage. See File Size and Dynamic Allocation on page 734 for information about when and how to specify the input file size.

Variable-Length Records
When the input data set consists of variable-length records and dynamic allocation of intermediate data sets is used, specify the average record length as accurately as possible using AVGRLEN=n in the OPTION statement.

Disk Devices
System performance is improved if storage is specified in cylinders rather than tracks or blocks. Storage on sort work data sets will be readjusted to cylinders if possible. The number of tracks per cylinder for disk devices is shown in Table 74.
Table 74. Number of Tracks per Cylinder for Disk Devices Device 3380 3390 9345 Tracks per Cylinder 15 15 15

If WRKSEC is in effect and the work data set is not allocated to virtual I/O, DFSORT allocates secondary extents as required, even if not requested in the JCL. Allocating twice the space used by the input data sets is usually adequate for the work data sets. Certain conditions can cause additional space requirements. These include: v Long control words (more than 150 bytes) v Using different device types or work data sets v Using an alternative collating sequence v Low ratio of available storage to input file size. Care should be taken to ensure that the LRECL parameter of the DCB corresponds to the actual maximum record length contained in your data set.

Use Extended Format Data Sets

Extended format data sets have features that can: v significantly reduce the elapsed time DFSORT spends reading and writing data v assist in managing the space requirements of very large data sets. The Sequential Data Striping feature can reduce the time required to read and write your DFSORT input and output data sets. We recommend using sequential data striping for your very large DFSORT input and output data sets as a way to improve elapsed time. Features such as compression, extended addressability (for VSAM), increased extent and volume support, and space constraint relief options assist in managing the space requirements of very large data sets.

684

z/OS V1R10.0 DFSORT Application Programming Guide

Design Your Applications to Maximize Performance

If you decide to use compression, realize that there is a CPU cost which could outweigh the I/O performance benefits. Although compression can be used to improve disk storage capacity, the impact to CPU usage and elapsed time should be evaluated in your environment. Consult with your storage administrator to learn how these features can be exploited in your environment.

Use DFSMSrmm-Managed Tapes, or ICETPEX

The use of tapes managed by DFSMSrmm, or a tape management system that uses ICETPEX, allows DFSORT to obtain accurate information about input file size and data set characteristics. This can result in improved performance and more efficient use of both main storage and intermediate work storage.

Specify Devices that Improve Elapsed Time

To get the best elapsed time improvement when using disk with DFSORT, you should use high speed devices, such as IBMs Enterprise Storage Server (ESS) and TotalStorage RS8000 Series subsystems for SORTIN, SORTOUT, SORTWKdd, SORTOUT, and OUTFIL data sets. Throughput can be further improved by leveraging high speed channels, such as IBMs FICON connectivity solutions.

Use Options that Enhance Performance

| | To obtain optimum performance, you can fine-tune your installation and run-time options. Several options that can enhance performance are described below.

CFW
Blockset sorting performance may be improved by using the Cache Fast Write (CFW) capability of IBMs storage controllers. Because IBMs latest storage subsystems have large cache sizes and high speed disk arrays, the use of CFW may not produce a significant performance gain. The CFW parameter specifies whether DFSORT can use CFW when processing SORTWKdd data sets. The default is CFW=YES. If you use the Hyperswap function in an environment that has a high availability configuration, you should specify CFW=NO to prevent DFSORT from abending when a Hyperswap is initiated.

DSA
Performance can be improved for Blockset sort applications by using Dynamic Storage Adjustment (DSA). The DSA parameter sets the maximum amount of storage available to DFSORT for dynamic storage adjustment of a Blockset sort application when SIZE/MAINSIZE=MAX is in effect. If you specify a DSA value greater than the TMAXLIM value, you allow DFSORT to use more storage than the TMAXLIM value if doing so should improve performance. DFSORT only tries to obtain as much storage as needed to improve performance up to the DSA value.

DSPSIZE
Performance can be improved for sort applications that use the Blockset technique by using dataspace sorting. The DSPSIZE parameter sets the maximum size of a data space to be used during a run. Specifying DSPSIZE=MAX allows DFSORT to optimize the maximum size of
Chapter 9. Improving Efficiency

685

Design Your Applications to Maximize Performance

a data space to be used during a run, subject to other system and concurrent Hipersorting, memory object sorting and dataspace sorting activity throughout the run. Total dataspace sorting activity on a system can be further limited by the EXPMAX, EXPOLD, and EXPRES installation options. See the description of DSPSIZE in OPTION Control Statement on page 167 for more information.

FASTSRT
By specifying the COBOL FASTSRT compiler option, you can significantly reduce DFSORT processor time, EXCPs, and elapsed time. With FASTSRT, DFSORT input/output operations are more efficient because DFSORT rather than COBOL does the input/output (see Figure 52 on page 686). For more details, see the COBOL publications. The FASTSRT option does not take effect for input and output if input and output procedures are used in the SORT statement. Many of the functions usually performed in an input or output procedure are the same as those done by DFSORT INREC, OUTFIL, OUTREC, INCLUDE or OMIT, STOPAFT, SKIPREC, and SUM functions. You might be able to eliminate your input and output procedures by coding the appropriate DFSORT program control statements and placing them in either the DFSPARM (DFSORT), SORTCNTL (DFSORT), or IGZSRTCD (COBOL) data set, thereby allowing your SORT statement to qualify for FASTSRT.

Figure 52. Faster Sorting with COBOL

SDB
| To improve Blockset elapsed time, and disk and tape utilization, specify installation option SDB=LARGE as your sites installation (SDB=INPUT is the IBM-supplied default). SDB=LARGE allows DFSORT to select the system-determined optimum block size for your disk and tape output data sets, when appropriate.

686

z/OS V1R10.0 DFSORT Application Programming Guide

Design Your Applications to Maximize Performance

HIPRMAX
Blockset sorting performance can be improved by using Hiperspace along with disk for temporary storage. | | | | | | | The HIPRMAX parameter sets the maximum amount of Hiperspace to be used during a run. Specifying HIPRMAX=OPTIMAL allows DFSORT to optimize the maximum amount of Hiperspace to be used during a run, subject to other system and concurrent Hipersorting, memory object sorting and dataspace sorting activity throughout the run. Total Hipersorting activity on a system can be further limited by the EXPMAX, EXPOLD, and EXPRES installation options. See the description of HIPRMAX in OPTION Control Statement on page 167 for more information.

MOSIZE
Blockset sorting performance can be improved by using memory object sorting. The MOSIZE parameter sets the maximum size of a memory object to be used during a run. Specifying MOSIZE=MAX allows DFSORT to optimize the maximum size of a memory object to be used during a run, subject to other system and concurrent Hipersorting, memory object sorting and dataspace sorting activity throughout the run. Total memory object sorting activity on a system can be further limited by the EXPMAX, EXPOLD, and EXPRES installation options. See the description of MOSIZE in OPTION Control Statement on page 167 for more information.

| |

Use DFSORTs Fast, Efficient Productivity Features

DFSORT offers a rich set of fast, efficient productivity features. These features can eliminate the up-front costs of writing and debugging your own code to perform various tasks, and will perform those tasks more efficiently. The functional capabilities of each of the features listed below is described in detail elsewhere in this document. This section highlights the performance aspects of these features.

INCLUDE or OMIT, STOPAFT, and SKIPREC

You can use the INCLUDE or OMIT statement and the STOPAFT and SKIPREC options to reduce the number of records to be processed, which can reduce processor and data transfer time. v The INCLUDE and OMIT statements allow you to select records by comparing fields with constants or other fields. v The STOPAFT option allows you to specify the maximum number of records to be accepted for sorting or copying. v The SKIPREC option allows you to skip records at the beginning of the input file and sort or copy only the remaining records.

OUTFIL
If you need to create multiple output data sets from the same input data set, you can use OUTFIL to read the input data set only once, thus improving performance. OUTFIL can be used for sort, merge, and copy applications to provide sophisticated filtering, editing, conversion, lookup and replace, and report features. If you are creating only a single output data set and do not need the features of OUTFIL, use SORTOUT rather than OUTFIL for best performance.

LOCALE
You can use the LOCALE option to sort, merge, and compare character data based on collating rules in an active locale; this enables you to obtain results with

Chapter 9. Improving Efficiency

687

Design Your Applications to Maximize Performance

DFSORT that were previously possible only through pre-processing or post-processing of your data. By eliminating such costly processing, you can save time and processing resources.

SUM
You can improve performance by using SUM to add the contents of fields. The SUM statement adds the contents of specified SUM fields in records with identical control fields. The result is placed in one record while the other record is deleted, thus reducing the number of records to be output by DFSORT. | You can use installation option ZDPRINT=YES or run-time option ZDPRINT to specify that positive zoned decimal fields that result from summing are to be printable. That is, you can tell DFSORT to change the last digit of the zone from hex C to hex F. Eliminating Duplicate Records: You can eliminate records with duplicate keys by specifying
SUM FIELDS=NONE

when using the SUM control statement. For a diagram of the processing sequence for record handling statements, user exits, and options, see Figure 2 on page 9.

ICETOOL
ICETOOL is a multi-purpose utility that allows you to use DFSORTs highly efficient I/O and processing to perform multiple operations on one or more data sets in a single job step. ICETOOLs twelve operators allow you to perform sort, copy, statistical, and report operations quickly and efficiently.

Avoid Options that Degrade Performance

Certain options can adversely affect performance, and should be used only when necessary. For example, the CKPT option, which activates checkpoint/restart, prevents use of the efficient Blockset techniques.

CKPT
The CKPT option might preclude the use of the more efficient Blockset technique. | | Note: If installation option IGNCKPT=YES has been selected, DFSORT ignores the checkpoint/restart request and selects the Blockset technique.

EQUALS
The EQUALS option increases the time needed for comparison of records and for data transfer.

EQUCOUNT
The EQUCOUNT option takes additional time to count the number of records with equal keys.

LOCALE
The LOCALE option may increase the time required to run an application.

NOCINV
The NOCINV option precludes the use of control interval access for more efficient VSAM processing.

688

z/OS V1R10.0 DFSORT Application Programming Guide

Design Your Applications to Maximize Performance

NOBLKSET
The NOBLKSET option precludes the use of the more efficient Blockset technique.

VERIFY
The VERIFY option degrades performance, because it involves extra processing.

Tape Work Data Sets

Use of tape work data for intermediate storage precludes the use of the much more efficient disk techniques.

User Exit Routines

When user exit routines are included in an application, the time required to run the application is usually increased. The run time required by most user exit routines is generally small, but the routines at user exits E15, E32, and E35 are entered for each record of the data sets. For large input data sets, the total run time of these routines can be relatively large.

Dynamic Link-Editing
Dynamic link-editing of user exit routines degrades performance.

EFS Programs
When EFS programs are included in an application, the time required to run the application might increase.

Use Main Storage Efficiently

In general, the more main storage you make available to DFSORT, the better the performance for large applications. To prevent excessive paging, ensure that sufficient real storage is available to back up the amount of main storage used. This is especially important with main storage sizes greater than 32MB. The default amount of main storage that will be made available to DFSORT is defined when it is installed. Although it is possible to run a very minimal sort application in 88KB of storage, the actual minimum amount of storage required is generally 128KB to 440KB depending on the application. However, 4MB or more of storage is recommended for better performance. Improved performance will be most noticeable with large input files. With MAINSIZE=MAX, the DSA value can be used to automatically increase the amount of storage DFSORT uses for a sort application when doing so should improve performance. Note: When Blockset is selected, DFSORT can place selected buffers above 16MB virtual. This frees more storage for DFSORT without having to increase the REGION size. A REGION size of at least 440KB must be available to allow DFSORT to use storage effectively.

Tuning Main Storage

Either the REGION value or the MAINSIZE/SIZE value can determine how much storage is available to DFSORT. See z/OS DFSORT Installation and Customization for details. Generally, the most efficient way to allocate (virtual) main storage is to use MAINSIZE/SIZE=MAX explicitly or by default. However, problems can arise if the

Chapter 9. Improving Efficiency

689

Use Main Storage Efficiently

values for the TMAXLIM or MAXLIM installation options have been set excessively high (or low). Guidelines for setting these values are given in z/OS DFSORT Installation and Customization. Note: Do not use SIZE/MAINSIZE=MAX with password-protected data sets if passwords are to be entered through a routine at a user exit, because DFSORT cannot then open the data sets during the initialization phase to make the necessary calculations. If you specify MAINSIZE/SIZE=n and give n a value less than that specified for the MINLIM installation option, MINLIM is used. When SIZE/MAINSIZE=MAX is in effect, DFSORT will use its Dynamic Storage Adjustment (DSA) feature, when appropriate, to improve performance. If the MINLIM value is greater than that specified for REGION on the EXEC statement, DFSORT attempts to use the value specified for MINLIM; if it fails to get the amount specified by MINLIM, DFSORT still tries to run, provided at least 88KB (below 16MB virtual) are available to DFSORT. Storage used for OUTFIL processing will be adjusted automatically, depending upon several factors, including: v Total available storage v Non-OUTFIL processing storage requirements v Number of OUTFIL data sets and their attributes (for example, block size). OUTFIL processing is subject to the ODMAXBF limit and your system storage limits (for example, IEFUSI) but not to DFSORT storage limits, that is, SIZE/MAINSIZE, MAXLIM, and TMAXLIM. DFSORT attempts to use storage above 16MB virtual for OUTFIL processing whenever possible. Notes: 1. In some cases, this release of DFSORT may use more storage than prior releases for comparable applications. This might affect the operation of some applications. For example, some applications that run as in-storage sorts (with no SORTWKdd data sets) in previous releases might not run in-storage when using this release. The amount of storage allocated is normally controlled by TMAXLIM. A REGION size of at least 440KB must be available if DFSORT is to achieve acceptable performance. The allocation of storage can be adversely affected if you have a smaller region value or if DFSORT needs to allocate buffers below 16MB virtual. 2. For extremely large sorts (for example, 2GB or more of data), make sure that Hipersorting, memory object sorting and dataspace sorting are enabled, and that 32MB or more of main storage is available to DFSORT. The relationship between TMAXLIM, MAXLIM, MINLIM, and REGION might be described as a series of checks and balances. Your system programmer has set the default storage values according to your sites major sorting requirements. If you have an overnight or batch time window that must be met, increasing storage (using REGION or SIZE/MAINSIZE=n) can give you some relief from the time constraint. If you are concerned with processor time, decreasing storage (using REGION or SIZE/MAINSIZE=n) can reduce the processor time associated with sorting small files.

| | |

690

z/OS V1R10.0 DFSORT Application Programming Guide

Use Main Storage Efficiently

In general, when you vary the amount of storage available to DFSORT, several things occur: 1. If you increase the amount of storage: v EXCPs are reduced. v For larger files, processor time generally decreases; that is, overhead in managing the extra storage is offset by DFSORT having to make fewer passes over the data. v For a very heavily loaded system, elapsed time might increase because DFSORT can be swapped out more often. v For very small sorts, processor time might remain stable or increase because of the overhead in managing the extra storage. For larger files, processor time will usually decrease because the overhead in managing the extra storage would be less than the benefit gained by DFSORT making fewer passes over the data. 2. If you decrease the amount of storage: v EXCPs increase. v Elapsed time increases for most sorts. v Processor time decreases for very small files, but increases for larger files. Changing the main storage allocation can affect system efficiency. By reducing the amount of main storage allocated, you impair performance of DFSORT to allow other programs to have the storage they need to operate simultaneously; by increasing the allocation, you can run large DFSORT applications efficiently at the risk of decreasing the efficiency of other applications sharing the multiprogramming environment.

Releasing Main Storage

Under some circumstances, DFSORT uses all the available storage in your REGION. This normally will not occur for storage above 16MB virtual (if it does, use the ARESINV or ARESALL options or lower your SIZE/MAINSIZE value). This section explains how to release storage within your REGION. When SIZE/MAINSIZE=n is in effect and n is greater than the REGION parameter or the default REGION value, or when SIZE/MAINSIZE=MAX and TMAXLIM is greater than your REGION, specify the storage you need released in the following way: v For applications with user exits: For directly invoked DFSORT, you can choose one of the following: - Use the m parameter of the MODS control statement. - If SIZE=MAX is in effect, you can use the RESALL option. - Change your REGION so that REGION is greater than SIZE/MAINSIZE (the difference is available). - If the OVERRGN installation option is smaller than your system IEFUSI value, this difference is available. (OVERRGN is an installation option that can be modified only by your system programmer.) For program invoked DFSORT, you can choose one of the following: - If the user exit address is not passed in the parameter list (that is, it is specified with a MODS statement), use the m parameter on the MODS statement. - If the user exit address is passed in the parameter list,and SIZE/MAINSIZE=MAX is in effect, use the RESINV option.
Chapter 9. Improving Efficiency

| | |

691

Use Main Storage Efficiently

- If the user exit address is passed in the parameter list, and SIZE/MAINSIZE=n is in effect, change your REGION so that the REGION is greater than SIZE/MAINSIZE (the difference is available). - If many of your DFSORT applications pass the user exit address in the parameter list and SIZE/MAINSIZE=n is in effect, then consider having the OVERRGN value changed by your system programmer to less than your IEFUSI value. v For applications without user exits: For directly invoked DFSORT, you can choose one of the following: - If SIZE/MAINSIZE=MAX is in effect, use the RESALL option. - If SIZE/MAINSIZE=n is in effect, change your REGION so that REGION is greater than SIZE/MAINSIZE (the difference is available). - Have the OVERRGN value changed by your system programmer to less than your IEFUSI value. For program invoked DFSORT, you can choose one of the following: - If SIZE/MAINSIZE=MAX is in effect, use the RESINV option. - If SIZE/MAINSIZE=n is in effect, change your REGION so that REGION is greater than SIZE/MAINSIZE (the difference is available). - Have the OVERRGN value changed by your system programmer to less than your IEFUSI value. When SIZE/MAINSIZE is less than REGION, make sure the difference between SIZE/MAINSIZE and your REGION specification value or default provides sufficient storage for system or user exit routine use.

Allocate Temporary Work Space Efficiently

Performance is enhanced when multiple channels are available. Performance is also improved if the device is connected so that two channel paths exist between each device and the processor that is running the program.

Disk Work Storage Devices

Program performance is improved if you use devices, storage areas, and channels efficiently. If you specify a particular device type with the UNIT parameter on the DD statements that define intermediate storage data sets (for example, UNIT=3390), DFSORT assigns areas, and some optimization occurs automatically. You can get the best performance using disk intermediate storage devices when you: v Use two or more work data sets. v Select the storage device with the fastest data transfer rate. v Assign one work data set per volume if Parallel Access Volumes (PAV) are not used. This will help minimize I/O queue time on the SORTWKdd data sets. v Use devices that are of the same type. v Use two channel paths to devices. v Make all work data sets the same size, or as nearly the same size as possible. v Make sure the SORTWKdd data sets do not share devices or channels with the SORTIN, SORTOUT, or OUTFIL data sets. v Specify contiguous space for work data sets, and make sure there is enough primary space so that the automatic secondary allocation is not needed. v Provide adequate virtual storage when work data sets are allocated on non-synchronous devices, as explained in Non-Synchronous Storage Subsystems on page 732.

692

z/OS V1R10.0 DFSORT Application Programming Guide

Allocate Temporary Work Space Efficiently

Elapsed time is decreased when DFSORT can both read input while writing to SORTWKdd and write output while reading from SORTWKdd. If, for example, you have two channels, the best allocation of them is to have SORTIN, SORTOUT, and OUTFIL data sets on one and the SORTWKdd data sets on the other. Storage requirements for different disk techniques can be estimated by using the guidelines found in Appendix A, Using Work Space, on page 731.

Virtual I/O for Work Data Sets

Although VIO data sets can provide performance improvements in many applications, these work data sets are generally not as effective as disk work data sets for DFSORT. DFSORT temporary work data sets allocated to virtual devices (VIO) can provide reduced elapsed time at the cost of increased CPU time for DFSORT applications. In general, this is not a good trade-off and VIO should not be used for DFSORT work data sets. If work data sets are allocated to VIO, the VIO installation option tells DFSORT how to handle allocation to VIOs: v VIO=YES causes DFSORT to accept the use of VIOs for work data sets. v VIO=NO causes DFSORT to reallocate work data sets from virtual devices to real devices. Note that in order for re-allocation to be successful, a real device with the same device type as the virtual device must be available. Re-allocation of VIO data sets (VIO=NO) is recommended over no re-allocation (VIO=YES). However, it is better to avoid using VIO work data sets in the first place, since re-allocation wastes time and resources.

Tape Work Storage Devices

The use of tape work storage devices prevents the use of the more efficient Blockset technique. Best performance, using tape intermediate storage, is usually obtained when you use six or more tape drives of the fastest type. As a general rule, you should use as many tapes as you have available for intermediate storage. A larger number of tapes increases the number of strings that can be merged in one pass, and, therefore, decreases the number of passes required in the intermediate merge phase. This then reduces elapsed time and, often, the number of I/O operations. Increasing the number of work units, however, also reduces the block size used for intermediate storage; this can become a critical factor if you have relatively little main storage available for buffers. For example, if DFSORT has only 88KB in which to operate, you probably achieve no improvement (and might find deterioration) if you use more than four tape work units. Therefore, apply the general rule of using as many tapes as possible only when DFSORT has more than 100KB available. For information on how to determine storage requirements when using different tape techniques, see Appendix A, Using Work Space, on page 731. Notes: 1. The frequency with which the tape direction changes during DFSORT work file operations has more of an impact on the effective data rate of the IBM 3480/3490/3590 Magnetic Tape Subsystems than on IBM 3420 Magnetic Tape

Chapter 9. Improving Efficiency

693

Allocate Temporary Work Space Efficiently

Units. Because of this characteristic, performance comparisons between these tape units for intermediate storage cannot be reliably predicted and can vary widely. 2. Devices using the Improved Data Recording Capability (IDRC) feature are not recommended as intermediate storage devices, as they do not perform well with the read backward command.

Use Hipersorting
Hipersorting uses Hiperspace to improve the performance of sort applications that use DFSORTs Blockset Technique. A Hiperspace is a high-performance data space that resides in central storage and is backed by auxiliary storage when necessary. With Hipersorting, Hiperspace is used in place of and along with disk for temporary storage of records during a Blockset sort. Hipersorting reduces I/O processing, which in turn reduces elapsed time, EXCPs, and channel usage. Hipersorting is recommended when the input or output is a compressed sequential or VSAM data set. You can control the maximum amount of Hiperspace for a Hipersorting application with the HIPRMAX parameter. HIPRMAX can direct DFSORT to dynamically determine the maximum amount of Hiperspace, subject to the available storage at the start of the run. You can also use HIPRMAX to suppress Hipersorting when optimizing CPU time is your major concern because Hipersorting can slightly degrade CPU time. | | | | | | | | | | | The actual amount of Hiperspace a Hipersorting application uses depends upon several factors. See the HIPRMAX description in OPTION Control Statement on page 167 for more details. Most important, throughout the run, DFSORT determines the amount of available storage as well as the amount of storage needed by other concurrent Hipersorting, memory object sorting, and datapace sorting applications. Based on this information, DFSORT switches dynamically from using Hiperspace to using disk work data sets when either a storage shortage is predicted or the total Hipersorting, memory object sorting and dataspace sorting activity on the system reaches the limits set by the EXPMAX, EXPOLD, and EXPRES installation options. See z/OS DFSORT Installation and Customization for a complete description of these installation options.

Sort with Data Space

Dataspace sorting uses data space to improve the performance of sort applications that use DFSORTs Blockset Technique. Dataspace sorting allows DFSORT to sort large pieces of data at a time. This helps to reduce CPU time and elapsed time. | | | | | | | | You can control the maximum size of a data space for a dataspace sorting application with the DSPSIZE parameter. DSPSIZE can direct DFSORT to dynamically determine the maximum size of a data space, subject to the available central storage at the start of the run. DSPSIZE=0 means that DFSORT will not use dataspace sorting. The actual size of a data space that a dataspace sorting application uses depends upon several factors. See the DSPSIZE description in OPTION Control Statement on page 167 for more details. The following functions and types of data sets are not supported for dataspace sorting:

694

z/OS V1R10.0 DFSORT Application Programming Guide

Sort with Data Space

v v v v Spool, dummy, or pipe data set, or HFS file, as input. User exits INREC, OUTFIL, OUTREC, and SUM EQUCOUNT

Dataspace sorting is seldom used for very small data sets of a few MB or so because it is more efficient to sort small amounts of data entirely in main storage. The following are actions you can take that might increase the use of dataspace sorting: v Specify sufficient main storage. The default is 6MB, the recommended minimum for dataspace sorting. If you increase the amount of main storage specified, more dataspace sorting is possible, especially when sorting large amounts of data (multiple hundred MBs). Specifying more than 12MB or so will have no significant impact on DFSORTs decision to use dataspace sorting; it will, however, improve the performance of large non-dataspace sorting applications. v Specify generous extent sizes for work data sets, especially for secondary extents. Dataspace sorting is frequently used in conjunction with disk work space but never with Hiperspace or with tape work data sets. v Specify DSPSIZE=MAX. v Verify that IEFUSI does not place any restrictions on the size of the data spaces a single address space can create. v Ensure that DFSORT has accurate information about the input file size. DFSORT can automatically estimate the file size for disk input data sets and tape data sets managed by DFSMSrmm or a tape management system that uses ICETPEX. See File Size and Dynamic Allocation on page 734 for information on situations where DFSORT cannot determine the file size accurately, and what to do about it.

Use Memory Object Sorting

| Memory object sorting uses a memory object in 64-bit virtual storage to improve the performance of sort applications that use DFSORTs Blockset Technique. A memory object is a data area in virtual storage that is allocated above the bar and backed by central storage. With memory object sorting, a memory object is used in place of and along with disk for temporary storage of records during a sort. Memory object sorting reduces I/O processing, which in turn reduces elapsed time, EXCPs, and channel usage. Memory object sorting is recommended for large input data sets when a sufficient amount of central storage is available. You can control the maximum size of a memory object for a memory object sorting application with the MOSIZE parameter. MOSIZE can direct DFSORT to dynamically determine the maximum size of a memory object, subject to the available central storage at the start of the run. MOSIZE=0 means that DFSORT will not use memory object sorting. The actual size of a memory object that a memory object sorting application uses depends upon several factors. See the MOSIZE description in OPTION Control Statement on page 167 for more details. The following are actions you can take that might increase the use of memory object sorting: v Verify that a sufficient size for memory objects is defined by the MEMLIMIT parameter on the JOB or EXEC JCL statement.
Chapter 9. Improving Efficiency

695

Sort with Data Space

v Specify MOSIZE=MAX. v Specify generous extent sizes for work data sets, especially for secondary extents. v Verify that IEFUSI does not place any restrictions on the size of the memory objects a single address space can create. v Ensure that DFSORT has accurate information about the input file size. DFSORT can automatically estimate the file size for disk input data sets and tape data sets managed by DFSMSrmm or a tape management system that uses ICETPEX. See File Size and Dynamic Allocation on page 734 for information on situations where DFSORT cannot determine the file size accurately, and what to do about it.

Use ICEGENER Instead of IEBGENER

You can achieve more efficient processing for applications set up to use the IEBGENER system utility by using DFSORTs ICEGENER facility. Qualifying IEBGENER jobs are processed by the equivalent (though not identical), but more efficient, DFSORT copy function. If, for any reason, the DFSORT copy function cannot be used (for example, if IEBGENER control statements are specified), control is automatically transferred to the IEBGENER system utility. ICEGENER, like IEBGENER, will use an SDB=value parameter you supply using PARM=SDB=value, when appropriate. The valid SDB=value parameters are SDB=LARGE, SDB=YES, SDB=SMALL, SDB=INPUT and SDB=NO, as explained in OPTION Control Statement on page 167. If you supply an invalid SDB=value parameter, ICEGENER will transfer control to IEBGENER, which will terminate due to the invalid parameter. If you do not supply an SDB=value parameter, ICEGENER will use your sites DFSORT installation default for SDB, when appropriate (the IBM-supplied default is SDB=INPUT). If ICEGENER transfers control to IEBGENER, IEBGENER will use the SDB=value parameter you supply, if any, or its normal default for SDB. ICEGENER will also recognize DFSORT parameters other than SDB=value you supply using PARM=parameter that are valid on DFSORTs OPTION statement as explained in OPTION Control Statement on page 167. However, IEBGENER does not recognize any parameters other than the valid SDB=value forms, so if DFSORT must transfer control to IEBGENER, IEBGENER will not recognize DFSORTs parameters and will terminate. Likewise, if you supply a DFSORT parameter using PARM=parameter that is not valid on DFSORTs OPTION statement, DFSORT will transfer control to IEBGENER and IEBGENER will terminate due to the invalid parameter. For example, if you specify:
//S1 EXEC PGM=ICEGENER,PARM=SIZE=2000,MAINSIZE=2000K

ICEGENER will accept SIZE=2000 and MAINSIZE=2000K as valid DFSORT OPTION parameters that specify an exact file size of 2000 records and a limit of 2000K bytes of storage, respectively. If DFSORT copy can be used, these parameters will be used. But if DFSORT must transfer control to IEBGENER, IEBGENER will terminate because it treats SIZE=2000 and MAINSIZE=2000K as invalid parameters. As another example, if you specify:
//S2 EXEC PGM=ICEGENER,PARM=SIZE=2000K

696

z/OS V1R10.0 DFSORT Application Programming Guide

Use ICEGENER Instead of IEBGENER

ICEGENER will treat SIZE=2000K as an invalid DFSORT OPTION parameter and will transfer control to IEBGENER, which will terminate because it treats SIZE=2000K as an invalid parameter. Thus, you can pass PARM parameters to ICEGENER that are valid as DFSORT OPTION parameters, but you must be aware that if ICEGENER transfers control to IEBGENER, those parameters will cause IEBGENER to terminate. PARM parameters that are not valid as DFSORT OPTION parameters (even if they are valid as DFSORT PARM parameters) will cause ICEGENER to transfer control to IEBGENER, which will terminate. ICEGENER can transfer control to IEBGENER due to DFSPARM or SORTCNTL statement errors or other errors detected by DFSORT. Therefore, we recommend that ICEGENER not be used for any application for which IEBGENER cannot be used, to avoid unwanted IEBGENER processing. For example, if ICEGENER is used with an INCLUDE statement in DFSPARM, IEBGENER could be used and complete successfully, but the INCLUDE statement would be ignored. Instead, DFSORT copy should be used directly so that IEBGENER cannot be called. However, if you know that ICEGENER will use DFSORT copy, you can use a DFSPARM data set with ICEGENER to pass control statements and parameters to DFSORT. For example, if you specify:
//DFSPARM DD * OPTION SPANINC=RC0 /*

and ICEGENER uses DFSORT copy, any incomplete spanned records DFSORT detects in a variable spanned input data set are eliminated. If your site has installed ICEGENER to be invoked by the name IEBGENER, you need not make any changes to your applications to use ICEGENER. If your site has not chosen automatic use of ICEGENER, you can use ICEGENER by substituting the name ICEGENER for IEBGENER on the EXEC statement (when DFSORT is directly invoked) or LINK macro (when DFSORT is program-invoked) in any applications you choose. Program-invoked applications must be recompiled. Following is an example of how an IEBGENER application can be changed to use ICEGENER by substituting the name ICEGENER for the name IEBGENER in the EXEC statement.
//GENER JOB... // EXEC PGM=ICEGENER //SYSPRINT DD SYSOUT=* //SYSUT1 DD DSN=CONTROL.MASTER,DISP=OLD,UNIT=3380,VOL=SER=MASTER //SYSUT2 DD DSN=CONTROL.BACKUP,DISP=OLD,UNIT=3380,VOL=SER=BACKUP //SYSIN DD DUMMY

The IEBGENER DD statements SYSUT1 (input), SYSUT2 (output), and SYSPRINT (messages) are used by DFSORT for SORTIN, SORTOUT, and SYSOUT, respectively. These DD statement names will be translated by using an extended parameter list to invoke the copy function. If DFSORT cannot be used (for example, because IEBGENER control statements are specified), control will be transferred to IEBGENER. Notes: 1. The SYSUT2 data set should not be the same as the SYSUT1 data set because this can cause lost or incorrect data or unpredictable results.

Chapter 9. Improving Efficiency

697

Use ICEGENER Instead of IEBGENER

| | | | | | | | | | 2. Whether ICEGENER is invoked from a program or not, DFSORT will be invoked from ICEGENER using an extended parameter list. Therefore, the installation defaults for the ICEAM2 or ICEAM4 environment, or for an ICETDx environment if activated for ICEAM2 or ICEAM4, apply and SORTCNTL or DFSPARM can be used to provide additional control statements for the copy application; for example, OPTION. However, ICEGENER can transfer control to IEBGENER due to DFSPARM or SORTCNTL statement errors or other errors detected by DFSORT. Therefore, DFSORT copy should be used directly rather than ICEGENER if DFSORT processing statements such as INCLUDE, OUTREC, SUM and so on are required. 3. For most error conditions that prevent the use of DFSORT copy, control will be transferred to the IEBGENER system utility. DFSORT messages will not be printed unless a SORTDIAG DD statement is supplied. Use of the SORTDIAG DD statement will allow you to determine why DFSORT copy could not be used. 4. If DFSORT copy is used, its operation and messages will be equivalent to a directly called DFSORT copy application. If an unrecoverable error is encountered (for example, an I/O error), DFSORTs return code of 16 will be changed by ICEGENER to a return code of 12 to emulate the return code from a failing IEBGENER application. 5. DFSORT copy can perform some functions not provided by IEBGENER, such as certain padding and truncation operations. ICEGENER processing is not identical to IEBGENER processing in all cases, since DFSORT copy uses methods to enhance performance (EXCP, for example) that are not used by IEBGENER. 6. In some cases, IEBGENER terminates when the SYSUT2 LRECL is different from the SYSUT1 LRECL. ICEGENER takes one of three actions depending on the GNPAD (LRECL padding) or GNTRUNC (LRECL truncation) installation option, as appropriate. If you want ICEGENER to transfer control to IEBGENER when the SYSUT2 LRECL is larger than the SYSUT1 LRECL, use installation option GNPAD=IEB. If you want ICEGENER to handle LRECL padding, use GNPAD=RC0 (the supplied default) or GNPAD=RC4. If you want ICEGENER to transfer control to IEBGENER when the SYSUT2 LRECL is smaller than the SYSUT1 LRECL, use installation option GNTRUNC=IEB. If you want ICEGENER to handle LRECL truncation, use GNTRUNC=RC0 (the supplied default) or GNTRUNC=RC4. 7. For a call to ICEGENER, or to IEBGENER as an alias for ICEGENER, register 1 must point to a valid parameter list consisting of three addresses as follows: v Address1: The address of the Option List. v Address2: The address of the Alternate DDname List. v Address3: The address of the Page Number List. Methods of calling ICEGENER that generate a valid parameter list will allow ICEGENER to use DFSORTs copy feature, whereas methods of calling ICEGENER that generate an invalid parameter list will cause ICEGENER to transfer control to IEBGENER. For example:
call *(icegener)

| | |

on the TSO command line generates a valid parameter list, whereas:

icegener

on the TSO command line generates an invalid parameter list.

698

z/OS V1R10.0 DFSORT Application Programming Guide

Use ICEGENER Instead of IEBGENER

ICEGENER Return Codes

ICEGENER can use either IEBGENER or the DFSORT copy function. However, for unsuccessful completion due to an unsupported operating system, ICEGENER passes back a return code of 24 to the operating system or the invoking program, without using either IEBGENER or DFSORT copy. If ICEGENER transfers control to IEBGENER, IEBGENER passes back its return code to the operating system or the invoking program. If ICEGENER uses the DFSORT copy function: v For successful completion, ICEGENER passes back a return code of 0 or 4 to the operating system or the invoking program. v For unsuccessful completion with NOABEND in effect, ICEGENER passes back a return code of 12 (changed from 16) to the operating system or the invoking program. v For unsuccessful completion with ABEND in effect, DFSORT issues a user abend with the appropriate code as specified by the ABCODE installation option (either the error message number or a number between 1 and 99). The meanings of the return codes that ICEGENER passes back (in register 15) are: 0 4 Successful completion. ICEGENER completed successfully. Successful completion. ICEGENER completed successfully, and: v Installation option GNPAD=RC4 was specified and the SYSUT2 LRECL was larger than the SYSUT1 LRECL (LRECL padding) or v Installation option GNTRUNC=RC4 was specified and the SYSUT2 LRECL was smaller than the SYSUT1 LRECL (LRECL truncation), or v SPANINC=RC4 was in effect and one or more incomplete spanned records was detected, or v NULLOUT=RC4 was in effect and there were no records for the SYSUT2 data set, or v NULLOFL=RC4 was in effect and there were no data records for an OUTFIL data set. 12 24 Unsuccessful completion. DFSORT detected an error that prevented ICEGENER from completing successfully. Unsupported operating system. This operating system is not supported by this release of DFSORT.

Use DFSORTs Performance Booster for The SAS System

DFSORT provides significant CPU time improvements for SAS applications. To take advantage of this feature, contact SAS Institute Inc. for details of the support they provide to enable this enhancement.

Use DFSORTs BLDINDEX Support

DFSORT provides support that enables IDCAMS BLDINDEX to automatically use DFSORT to improve the performance of most BLDINDEX jobs that require BLDINDEX external sorting.

Chapter 9. Improving Efficiency

699

700

z/OS V1R10.0 DFSORT Application Programming Guide

Chapter 10. Examples of DFSORT Job Streams

Summary of Examples . . . . . . . . . . Storage Administrator Examples . . . . . . . REXX Examples . . . . . . . . . . . . CLIST Examples . . . . . . . . . . . . Sort Examples . . . . . . . . . . . . . Example 1. Sort with ALTSEQ . . . . . . . Example 2. Sort with OMIT, SUM, OUTREC, DYNALLOC and ZDPRINT . . . . . . . Example 3. Sort with ISCII/ASCII Tapes . . . Example 4. Sort with E15, E35, FILSZ, AVGRLEN and DYNALLOC . . . . . . . Example 5. Called sort with SORTCNTL, CHALT, DYNALLOC and FILSZ . . . . . . Example 6. Sort with VSAM Input/Output, DFSPARM and Option Override . . . . . . Example 7. Sort with COBOL E15, EXEC PARM and MSGDDN . . . . . . . . . . . . Example 8. Sort with Dynamic Link-Editing of Exits . . . . . . . . . . . . . . . 701 702 702 703 703 703 704 705 706 707 709 710 712 Example 9. Sort with the Extended Parameter List Interface . . . . . . . . . . . . Example 10. Sort with OUTFIL . . . . . . Example 11. Sort with Pipes and OUTFIL SPLIT Example 12. Sort with INCLUDE and LOCALE Example 13: Sort with HFS Files . . . . . . Example 14. Sort with IFTHEN . . . . . . Merge Examples . . . . . . . . . . . . Example 1. Merge with EQUALS . . . . . . Example 2. Merge with LOCALE and OUTFIL Copy Examples . . . . . . . . . . . . . Example 1. Copy with EXEC PARMs, SKIPREC, MSGPRT and ABEND . . . . . . . . . Example 2. Copy with INCLUDE and VLSHRT Example 3. Copy with OUTREC, PARSE and BUILD . . . . . . . . . . . . . . ICEGENER Example . . . . . . . . . . . ICETOOL Example . . . . . . . . . . . 713 716 718 718 719 720 722 722 723 724 725 726 726 728 729

Summary of Examples
The table below summarizes the examples provided in this chapter.
Application Sort Sort Sort Sort Sort Sort Sort Sort Sort Sort Sort Sort Sort Sort Merge Merge Copy Copy Copy No. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 1 2 1 2 3 Input Disk Disk Tape Tape Disk Disk Disk Disk E15 Disk Pipe Disk HFS files Disk Disk Disk Tape Disk Disk Output Tape Disk Tape Disk Disk Disk Disk Disk Disk Disk and SYSOUT Pipes Disk HFS file Disk Disk Disk Disk Disk Disk IFTHEN EQUALS LOCALE, OUTFIL EXEC PARMs, SKIPREC, MSGPRT, ABEND INCLUDE, VLSHRT OUTREC, PARSE, BUILD Functions/Options ALTSEQ OMIT, SUM, OUTREC, DYNALLOC, ZDPRINT ISCII/ASCII Tapes E15, E35, FILSZ, AVGRLEN, DYNALLOC Program-invoked, SORTCNTL, CHALT, DYNALLOC, FILSZ VSAM Input/Output, DFSPARM, Option Override COBOL E15, EXEC PARM, MSGDDN Dynamic Link-editing of Exits Extended Parameter List Interface OUTFIL Pipes, OUTFIL SPLIT, FILSZ, DYNALLOC INCLUDE, LOCALE

Copyright IBM Corp. 1973, 2006

701

Summary of Examples
Application ICEGENER ICETOOL No. 1 1 Input Disk Disk Output Disk Disk OCCUR, COPY, SORT, MODE, VERIFY, STATS, DISPLAY Functions/Options

Storage Administrator Examples

DFSORT provides a set of sample jobs that demonstrate techniques of interest to Storage Administrators and others who analyze data collected from DFSMShsm, DFSMSrmm, DCOLLECT and SMF. These sample jobs can be found in the ICESTGEX member of the SICESAMP library (contact your System Programmer for details). You can also download these sample jobs from the DFSORT FTP site. These sample jobs show some of the many ways DFSORT features such as ICETOOL and OUTFIL can be used to analyze data and generate reports: DCOLEX1 DCOLLECT Example 1: VSAM report DCOLEX2 DCOLLECT Example 2: Conversion reports DCOLEX3 DCOLLECT Example 3: Capacity planning analysis and reports DFHSMEX1 DFHSM Example 1: Deciphering Activity Logs DFHSMEX2 DFHSM Example 2: Recover a DFHSM CDS with a broken index RMMEX1 DFSMSrmm Example 1: SMF audit report RMMEX2 DFSMSrmm Example 2: Create ADDVOLUME commands

REXX Examples
Both DFSORT and ICETOOL can be called from REXX. The key is to specify ALLOCATE statements for the data sets you need and then use an ADDRESS statement like this:
ADDRESS LINKMVS name

which says to fetch the named program using the standard system search list. Here is an example of a REXX CLIST to call DFSORT:
/* Simple REXX CLIST to call DFSORT */ "FREE FI(SYSOUT SORTIN SORTOUT SYSIN)" "ALLOC FI(SYSOUT) DA(*)" "ALLOC FI(SORTIN) DA(Y897797.INS1) REUSE" "ALLOC FI(SORTOUT) DA(Y897797.OUTS1) REUSE" "ALLOC FI(SYSIN) DA(Y897797.SORT.STMTS) SHR REUSE" ADDRESS LINKMVS ICEMAN

Here are the DFSORT control statements that might appear in the Y897797.SORT.STMTS data set:
SORT FIELDS=(5,4,CH,A) INCLUDE COND=(21,3,SS,EQ,CL92,J82,M72)

Here is an example of a REXX CLIST to call ICETOOL:

/* Simple REXX CLIST to call ICETOOL */ "FREE FI(TOOLMSG DFSMSG VLR LENDIST TOOLIN)" "ALLOC FI(TOOLMSG) DA(*)" "ALLOC FI(DFSMSG) DUMMY" "ALLOC FI(VLR) DA(Y897797.VARIN) REUSE" "ALLOC FI(LENDIST) DA(*)" "ALLOC FI(TOOLIN) DA(Y897797.TOOLIN.STMTS) SHR REUSE" ADDRESS LINKMVS ICETOOL

702

z/OS V1R10.0 DFSORT Application Programming Guide

Summary of Examples
Here are the ICETOOL statements that might appear in the Y897797.TOOLIN.STMTS data set:
OCCURS FROM(VLR) LIST(LENDIST) TITLE(LENGTH DISTRIBUTION REPORT) BLANK HEADER(LENGTH) HEADER(NUMBER OF RECORDS) ON(VLEN) ON(VALCNT)

CLIST Examples
Both DFSORT and ICETOOL can be called from a CLIST. They key is to specify ALLOCATE statements for the data sets you need and then use a CALL statement like this:
CALL *(name)

Here is an example of a CLIST to call DFSORT:

FREE FI(SYSOUT SORTIN SORTOUT SYSIN) ALLOC FI(SYSOUT) DA(*) ALLOC FI(SORTIN) DA(Y897797.INS1) REUSE ALLOC FI(SORTOUT) DA(Y897797.OUTS1) REUSE ALLOC FI(SYSIN) DA(Y897797.SORT.STMTS) SHR REUSE CALL *(ICEMAN)

Here are the DFSORT control statements that might appear in the Y897797.SORT.STMTS data set:
SORT FIELDS=(5,4,CH,A) INCLUDE COND=(21,3,SS,EQ,CL92,J82,M72)

Here is an example of a CLIST to call ICETOOL:

FREE FI(TOOLMSG DFSMSG VLR LENDIST TOOLIN) ALLOC FI(TOOLMSG) DA(*) ALLOC FI(DFSMSG) DUMMY ALLOC FI(VLR) DA(Y897797.VARIN) REUSE ALLOC FI(LENDIST) DA(*) ALLOC FI(TOOLIN) DA(Y897797.TOOLIN.STMTS) SHR REUSE CALL *(ICETOOL)

Here are the ICETOOL statements that might appear in the Y897797.TOOLIN.STMTS data set:
OCCURS FROM(VLR) LIST(LENDIST) TITLE(LENGTH DISTRIBUTION REPORT) BLANK HEADER(LENGTH) HEADER(NUMBER OF RECORDS) ON(VLEN) ON(VALCNT)

Sort Examples
This section includes 14 sort examples.

Example 1. Sort with ALTSEQ

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS
//EXAMP //S1 //SYSOUT //SORTIN //SORTOUT

Blocked variable-length records on disk Blocked variable-length records on 3490 Two 3390 data sets None ALTSEQ
01 02 03 04 05

JOB A400,PROGRAMMER EXEC PGM=SORT DD SYSOUT=A DD DSN=A123456.IN5,DISP=SHR DD DSN=OUT1,UNIT=3490,DISP=(,KEEP),VOL=SER=VOL001

Chapter 10. Examples of DFSORT Job Streams

703

Sort Examples
//SORTWK01 DD UNIT=3390,SPACE=(CYL,(10,10)) //SORTWK02 DD UNIT=3390,SPACE=(CYL,(10,10)) //SYSIN DD * * COLLATE $, # and @ AFTER Z SORT FIELDS=(7,5,AQ,A) ALTSEQ CODE=(5BEA,7BEB,7CEC) 06 07 08 09 10 11

Line 01 02 03 04

Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly by its alias SORT. SYSOUT DD statement. Directs DFSORT messages and control statements to system output class A. SORTIN DD statement. The input data set is named A123456.IN5 and is cataloged. DFSORT determines from the data set label that the RECFM is VB, the maximum LRECL is 120, and the BLKSIZE is 2200. SORTOUT DD statement. The output data set is named OUT1 and is to be allocated on 3490 volume VOL001 and kept. DFSORT sets the RECFM and LRECL from SORTIN and selects an appropriate BLKSIZE for this standard labeled tape. SORTWK01 DD statement. The first work data set is allocated on 3390. SORTWK02 DD statement. The second work data set is allocated on 3390. SYSIN DD statement. DFSORT control statements follow. Comment statement. Printed but otherwise ignored. SORT statement. FIELDS specifies an ascending 5-byte character control field starting at position 7 (the third data byte, because the RDW occupies the first 4 bytes). The control field is to be collated according to the modified sequence described in the ALTSEQ statement. ALTSEQ statement. CODE specifies that the three characters $, # and @ are to collate in that order after Z.

05

06 07 08 09 10

11

Example 2. Sort with OMIT, SUM, OUTREC, DYNALLOC and ZDPRINT

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Blocked fixed-length records on 3380 and 3390 Blocked fixed-length records on 3390 Dynamically allocated None OMIT, OUTREC, SUM, DYNALLOC, ZDPRINT
01 02 03 04 05 06 07 08 09 10 11 12 13

//EXAMP JOB A400,PROGRAMMER //STEP1 EXEC PGM=SORT //SYSOUT DD SYSOUT=H //SORTIN DD DSN=INP1,DISP=SHR,UNIT=3380,VOL=SER=SCR001 // DD DSN=INP2,DISP=SHR,UNIT=3390,VOL=SER=SYS351 //SORTOUT DD DSN=&&OUTPUT,DISP=(,PASS),UNIT=3390, // SPACE=(CYL,(5,1)),DCB=(LRECL=22) //SYSIN DD * OMIT COND=(5,1,CH,EQ,CM) SORT FIELDS=(20,8,CH,A,10,3,FI,D) SUM FIELDS=(16,4,ZD) OPTION DYNALLOC,ZDPRINT OUTREC FIELDS=(10,3,20,8,16,4,2Z,5,1,C SUM)

Line 01

Explanation JOB statement. Introduces this job to the operating system.

704

z/OS V1R10.0 DFSORT Application Programming Guide

Sort Examples
02 03 04-05 EXEC statement. Calls DFSORT directly by its alias SORT. SYSOUT DD statement. Directs DFSORT messages and control statements to system output class H. SORTIN DD statement. Consists of a concatenation of two data sets. The first input data set is named INP1 and resides on 3380 volume SCR001. The second input data set is named INP2 and resides on 3390 volume SYS351. DFSORT determines from the data set labels that the record format is FB, the LRECL is 80 and the largest BLKSIZE is 27920. SORTOUT DD statement. The output data set is temporary and is to be allocated on a 3390. Because the OUTREC statement results in a reformatted output record length of 22 bytes, LRECL=22 must be specified. DFSORT sets the RECFM from SORTIN and selects an appropriate BLKSIZE. SYSIN DD statement. DFSORT control statements follow. OMIT statement. COND specifies that input records with a character M in position 5 are to be omitted from the output data set. SORT statement. FIELDS specifies an ascending 8-byte character control field starting at position 20 and a descending 3-byte fixed-point control field starting at position 10. SUM statement. FIELDS specifies a 4-byte zoned-decimal summary field starting at position 16. Whenever two records with the same control fields (specified in the SORT statement) are found, their summary fields (specified in the SUM statement) are to be added and placed in one of the records, and the other record is to be deleted. OPTION statement. DYNALLOC specifies that work data sets are to be dynamically allocated using the installation defaults for the type of device and number of devices. ZDPRINT specifies that positive ZD SUM fields are to be printable. OUTREC statement. FIELDS specifies how the records are to be reformatted for output. The reformatted records are 22 bytes long and look as follows: Position 1-3 4-11 12-15 16-17 18 19-22 Content Input positions 10 through 12 Input positions 20 through 27 Input positions 16 through 19 Zeros Input position 5 The character string SUM

06-07

08 09 10

11

12

13

Example 3. Sort with ISCII/ASCII Tapes

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS
//EXAMP //RUNIT //SORTIN

Variable-length ISCII/ASCII records on 3590 Variable-length ISCII/ASCII records on 3590 One SYSDA data set None None
01 02 03

JOB A400,PROGRAMMER EXEC SORTD DD DSN=SRTFIL,DISP=(OLD,DELETE),UNIT=3590,

Chapter 10. Examples of DFSORT Job Streams

705

Sort Examples
// DCB=(RECFM=D,LRECL=400,BLKSIZE=404,OPTCD=Q,BUFOFF=L), // VOL=SER=311500,LABEL=(1,AL) //SORTOUT DD DSN=OUTFIL,UNIT=3590,LABEL=(,AL),DISP=(,KEEP), // DCB=(BLKSIZE=404,OPTCD=Q,BUFOFF=L),VOL=SER=311501 //SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,(4)) //SYSIN DD * SORT FIELDS=(10,8,AC,D) RECORD TYPE=D,LENGTH=(,,,20,80) 04 05 06 07 08 09 10 11

Line 01 02 03-05

Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Uses the SORTD cataloged procedure to call DFSORT directly. SORTIN DD statement. The input data set is named SRTFIL and resides on 3590 volume 311500. It is to be deleted after this job step. It has a RECFM of D (variable-length ISCII/ASCII records), a maximum LRECL of 400, a BLKSIZE of 404 and an ISCII/ASCII label. For this job, the buffer offset is the block length indicator. The records are to be translated from ISCII/ASCII to EBCDIC. SORTOUT DD statement. The output data set is named OUTFIL and is to be allocated on 3590 volume 311501 and kept. It is to be written with an ISCII/ASCII label. DFSORT sets the RECFM and LRECL from SORTIN and sets the BLKSIZE to 404 as indicated in the DD statement. For this job, the buffer offset is the block length indicator. The records are to be translated from EBCDIC to ISCII/ASCII. SORTWK01 DD statement. The work data set is allocated on SYSDA. SYSIN DD statement. DFSORT control statements follow. SORT statement. FIELDS specifies a descending 8-byte ISCII/ASCII control field starting at position 10. RECORD statement. TYPE specifies ISCII/ASCII variable-length records. LENGTH specifies that the minimum record length is 20 and the average record length is 80.

06-07

08 09 10 11

Example 4. Sort with E15, E35, FILSZ, AVGRLEN and DYNALLOC

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Variable-length records on 3490 Blocked variable-length records on SYSDA Dynamically allocated E15 and E35 FILSZ, AVGRLEN, DYNALLOC
01 02 03 04 05 06 07 08 09 10 11 12 13

//EXAMP JOB A400,PROGRAMMER //STEP1 EXEC PGM=ICEMAN //SYSOUT DD SYSOUT=A //SORTIN DD DSN=INPUT,VOL=SER=FLY123, // UNIT=3490,DISP=OLD //SORTOUT DD DSN=&&OUT,DISP=(,PASS),SPACE=(CYL,(10,12)), // UNIT=SYSDA,DCB=(RECFM=VB) //MODLIB DD DSN=EXIT1.RTNS,DISP=SHR // DD DSN=EXIT2.RTNS,DISP=SHR //SYSIN DD * SORT FIELDS=(23,4,PD,A,10,6,FS,A) OPTION DYNALLOC=(3390,3),AVGRLEN=75,FILSZ=E50000 MODS E15=(MODREC,1024,MODLIB),E35=(ADDREC,1200,MODLIB)

Line

Explanation

706

z/OS V1R10.0 DFSORT Application Programming Guide

Sort Examples
01 02 03 04-05 JOB statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly. SYSOUT DD statement. Directs DFSORT messages and control statements to system output class A. SORTIN DD statement. The input data set is named INPUT and resides on 3490 volume FLY123. DFSORT determines from the data set label of this standard labeled tape that the RECFM is V, the LRECL is 120 and the BLKSIZE is 124. SORTOUT DD statement. The output data set is temporary and is to be allocated on SYSDA. Because the input is unblocked and the output is to be blocked, RECFM=VB must be specified. DFSORT sets the LRECL from SORTIN and selects an appropriate BLKSIZE. MODLIB DD statement. Specifies the load libraries that contain the exit routines. When exit routines reside in more than one library, the libraries must be concatenated using a single DD statement. SYSIN DD statement. DFSORT control statements follow. SORT statement. FIELDS specifies an ascending 4-byte packed-decimal control field starting at position 23 and an ascending 6-byte floating-sign control field starting at position 10. OPTION statement. DYNALLOC=(3390,3) specifies that three 3390 work data sets are to be allocated. AVGRLEN=75 specifies an average record length of 75. AVGRLEN helps DFSORT optimize work space for variable-length record input. FILSZ=E50000 specifies an estimate of 50000 records. Because the 3490 input data set is compacted, DFSORT might not be able to determine the file size accurately unless the data set is managed by DFSMSrmm or a tape management system that uses ICETPEX. Specification of FILSZ can make a significant difference in work space optimization when tape input data sets are not managed. MODS statement. E15 specifies a user exit routine named MODREC. Approximately 1024 bytes are required for MODREC and the system services (for example, GETMAIN and OPEN) it performs. E35 specifies a user exit routine named ADDREC. Approximately 1200 bytes are required for ADDREC and the system services it performs. MODREC and ADDREC reside in the libraries defined by the MODLIB DD statement.

06-07

08-09

10 11

12

13

Example 5. Called sort with SORTCNTL, CHALT, DYNALLOC and FILSZ

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS
//EXAMP //RUNSORT //STEPLIB //SYSOUT //SYSPRINT //SORTIN //SORTOUT //SORTCNTL OPTION

Blocked fixed-length records on disk Blocked fixed-length records on disk Dynamically allocated None CHALT, DYNALLOC, FILSZ
01 02 03 04 05 06 07 08 09

JOB A400,PROGRAMMER EXEC PGM=MYPGM DD DSN=M999999.LOAD,DISP=SHR DD SYSOUT=A DD SYSOUT=A DD DSN=M999999.INPUT(MASTER),DISP=OLD DD DSN=M999999.OUTPUT.FILE,DISP=OLD DD * CHALT,DYNALLOC=(,3),FILSZ=U25000

Chapter 10. Examples of DFSORT Job Streams

707

Sort Examples
Line 01 02 03 04 05 06 Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls a program named MYPGM that in turn calls DFSORT. STEPLIB DD statement. Specifies the load library that contains MYPGM. SYSOUT DD statement. Directs DFSORT messages and control statements to system output class A. SYSPRINT DD statement. Directs MYPGM output to system output class A. SORTIN DD statement. The input data set is member MASTER in the cataloged partitioned data set M999999.INPUT. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. SORTOUT DD statement. The output data set is named M999999.OUTPUT.FILE and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. SORTCNTL DD statement. DFSORT control statements follow. Statements in SORTCNTL override or supplement statements passed by MYPGM in the DFSORT parameter list it uses. OPTION statement. CHALT specifies that character format control fields (specified in the SORT statement passed by MYPGM) are to be sorted using the ALTSEQ installation option. DYNALLOC=(,3) specifies that three work data sets are to be dynamically allocated using the installation default for the type of device. FILSZ=U25000 specifies a file size of 25000 records is to be used by DFSORT to determine the amount of work space needed. Because the input data set is a member of a PDS, specifying FILSZ helps DFSORT optimize work data set space.

07

08

09 |

708

z/OS V1R10.0 DFSORT Application Programming Guide

Sort Examples

Example 6. Sort with VSAM Input/Output, DFSPARM and Option Override

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS VSAM TYPE=V records VSAM TYPE=V records Dynamically allocated None Override of Various Options
01 02 03 04 05 06 07 08 09 10

//EXAMP JOB A400,PROGRAMMER //S1 EXEC PGM=SORT //SYSOUT DD SYSOUT=A //SORTIN DD DSN=TEST.SORTIN.FILE,DISP=SHR //SORTOUT DD DSN=TEST.SORTOUT.FILE,DISP=SHR //DFSPARM DD * RECORD TYPE=V SORT FIELDS=(30,4,BI,A) OPTION HIPRMAX=10,DYNALLOC=3390,MAINSIZE=3M, MSGPRT=CRITICAL,NOLIST

For purposes of illustration, assume that none of the standard installation defaults for batch direct invocation of DFSORT have been changed by the site. Line 01 02 03 04 Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly by its alias SORT. SYSOUT DD statement. Directs DFSORT messages and control statements to system output class A. SORTIN DD statement. The input data set is TEST.SORTIN.FILE. DFSORT determines that it is a VSAM data set and obtains its attributes from the catalog. SORTOUT DD statement. The output data set is TEST.SORTOUT.FILE. DFSORT determines that it is a VSAM data set and obtains its attributes from the catalog. DFSPARM DD statement. DFSORT control statements follow. DFSPARM can be used for both direct-invocation and program-invocation of DFSORT and overrides options and statements from all other sources. Certain operands, such as MSGPRT and LIST/NOLIST, are used if supplied in DFSPARM, the EXEC PARM or the invocation parameter list, but not used if supplied in SYSIN or SORTCNTL. RECORD statement. TYPE=V specifies that DFSORT is to treat the VSAM records as variable-length. In this case, the RECORD statement could be omitted, because DFSORT would automatically set a record type of V due to the use of VSAM data sets for SORTIN and SORTOUT. SORT statement. FIELDS specifies an ascending 4-byte binary control field starting at position 30. This position corresponds to a specification of KEYS(4 25) for the VSAM CLUSTER (4 bytes at offset 25, which is equivalent to position 26 with 4 bytes added for the RDW that DFSORT supplies at input and removes at output for VSAM TYPE=V records). OPTION statement. HIPRMAX=10 specifies that up to 10 MBs of Hiperspace can be used for Hipersorting, overriding the standard installation default of HIPRMAX=OPTIMAL. DYNALLOC=3390 specifies that work data sets are to be allocated on 3390s, overriding the standard installation default of SYSDA. The standard installation default of four work data sets is not overridden. MAINSIZE=3M specifies that up to 3
Chapter 10. Examples of DFSORT Job Streams

05

06

07

08

09-10

709

Sort Examples
MBs of storage can be used, overriding the standard installation default of MAINSIZE=MAX. MSGPRT=CRITICAL specifies that only error messages are to be printed, overriding the standard installation default of MSGPRT=ALL. NOLIST specifies that control statements are not to be printed, overriding the standard installation default of LIST=YES.

Example 7. Sort with COBOL E15, EXEC PARM and MSGDDN

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Fixed-length records on disk Fixed-length records on SYSDA None COBOL E15 MSGDDN
01 02 03 04 05 06 07 08 09 10 11 12 13

//EXAMP JOB A400,PROGRAMMER //STEP1 EXEC PGM=SORT,PARM=MSGDDN=DFSOUT //STEPLIB DD DSN=SYS1.SCEERUN,DISP=SHR //SYSOUT DD SYSOUT=A //DFSOUT DD SYSOUT=A //EXITC DD DSN=COBEXITS.LOADLIB,DISP=SHR //SORTIN DD DSN=SORT1.IN,DISP=SHR //SORTOUT DD DSN=&&OUT,DISP=(,PASS),SPACE=(CYL,(5,5)), // UNIT=SYSDA,DCB=(LRECL=120) //SYSIN DD * SORT FIELDS=(5,4,A,22,2,A),FORMAT=BI MODS E15=(COBOLE15,37000,EXITC,C) RECORD LENGTH=(,120)

Line 01 02

Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly by its alias name SORT. MSGDDN=DFSOUT specifies an alternate message data set for DFSORT messages and control statements to prevent the COBOL messages in SYSOUT from being interleaved with the DFSORT messages and control statements. STEPLIB statement. Specifies the Language Environment library. SYSOUT statement. Directs COBOL messages to system output class A. DFSOUT statement. Directs DFSORT messages and control statements to system output class A (this is the alternate message data set specified by MSGDDN in the PARM field of the EXEC statement). EXITC statement. Specifies the load library that contains the exit routine. SORTIN DD statement. The input data set is named SORT1.IN and is cataloged. DFSORT determines from the data set label that the RECFM is F, the LRECL is 100 and the BLKSIZE is 100. SORTOUT DD statement. The output data set is temporary and is to be allocated on SYSDA. Because the E15 exit changes the length of the records from 100 bytes to 120 bytes, LRECL=120 must be specified. DFSORT sets the RECFM from SORTIN and sets the BLKSIZE to the LRECL (unblocked records). SYSIN DD statement. DFSORT control statements follow. SORT statement. FIELDS specifies an ascending 4-byte control field starting at position 5 and an ascending 2-byte control field starting at position 22. FORMAT specifies that the control fields are binary. MODS statement. E15 specifies a user exit routine named COBOLE15

03 04 05

06 07

08-09

10 11

12

710

z/OS V1R10.0 DFSORT Application Programming Guide

Sort Examples
written in COBOL. Approximately 37000 bytes are required for the exit, the system services (for example, GETMAIN and OPEN) it performs, and the COBOL library subroutines. COBOLE15 resides in the library defined by the EXITC DD statement. 13 RECORD statement. LENGTH specifies that the COBOL E15 routine changes the length of the records to 120 bytes.

Chapter 10. Examples of DFSORT Job Streams

711

Sort Examples

Example 8. Sort with Dynamic Link-Editing of Exits

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Blocked fixed-length records on disk Blocked fixed-length records on 3380 One SYSDA data set E11, E15, E17, E18, E19, E31, E35, E38, E39 None
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

//EXAMP JOB A400,PROGRAMMER //STEPA EXEC SORT //SORTIN DD DSN=SMITH.INPUT,DISP=SHR //SORTOUT DD DSN=SMITH.OUTPUT,DISP=(NEW,CATLG), // UNIT=3380,SPACE=(TRK,(10,2)),VOL=SER=XYZ003 //SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //EXIT DD DSN=SMITH.EXIT.OBJ,DISP=SHR //EXIT2 DD DSN=SMITH.EXIT2.OBJ,DISP=SHR //SORTMODS DD UNIT=SYSDA,SPACE=(TRK,(10,,3)) //SYSIN DD * SORT FIELDS=(1,8,CH,A,20,4,BI,D) MODS E11=(EXIT11,1024,EXIT,S), E15=(E15,1024,SYSIN,T), E17=(EXIT17,1024,EXIT2,T), E18=(EXIT18,1024,EXIT,T), E19=(E19,1024,SYSIN,T), E31=(PH3EXIT,1024,EXIT,T), E35=(PH3EXIT,1024,EXIT,T), E38=(PH3EXIT,1024,EXIT,T), E39=(E39,1024,SYSIN,T) END <object deck for E15 exit here> <object deck for E19 exit here> <object deck for E39 exit here>

Line 01 02

Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Uses the SORT cataloged procedure to call DFSORT directly and supply the DD statements (not shown) required by the linkage editor. SORTIN DD statement. The input data set is named SMITH.INPUT and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. SORTOUT DD statement. The output data set is named SMITH.OUTPUT and is to be allocated on 3380 volume XYZ003 and cataloged. DFSORT sets the RECFM and LRECL from SORTIN and selects an appropriate BLKSIZE. SORTWK01 DD statement. The work data set is allocated on SYSDA. EXIT DD statement. Specifies the partitioned data set containing the object decks for the E11, E18, E31, E35 and E38 exit routines. EXIT2 DD statement. Specifies the partitioned data set containing the object deck for the E17 exit routine. SORTMODS DD statement. The partitioned data set to hold exit routine object decks from SYSIN for input to the linkage editor is to be allocated on SYSDA. SYSIN DD statement. DFSORT control statements, and object decks to be used by the linkage editor, follow. SORT statement. FIELDS specifies an ascending 8-byte character control field starting at position 1 and a descending 4-byte binary control field starting at position 20.

03

04-05

06 07 08 09

10 11

712

z/OS V1R10.0 DFSORT Application Programming Guide

Sort Examples
12-20 MODS statement. Specifies the exit routines to be used, the approximate number of bytes required for each exit and that: v The EXIT11 routine in the EXIT library is to be link-edited separately from other input phase exit routines and associated with user exit E11. v The E15 and E19 routines in SYSIN, the EXIT17 routine in EXIT2, and the EXIT18 routine in EXIT are to be link-edited together and associated with user exits E15, E19, E17, and E18, respectively. v The E31, E35, and E38 routines in the PH3EXIT object deck and the E39 routine in SYSIN are to be link-edited together and associated with user exits E31, E35, E38, and E39, respectively. END statement. Marks the end of the DFSORT control statements and the beginning of the exit routine object decks. Object decks. The three object decks for the E15, E19, and E39 exit routines follow the END statement.

21 22-24

Example 9. Sort with the Extended Parameter List Interface

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Fixed-length records from E15 Blocked fixed-length records on SYSDA Dynamically allocated E15 OMIT, FILSZ, RESINV, DYNALLOC

//EXAMP JOB A400,PROGRAMMER 01 //STEP1 EXEC PGM=MYSORT 02 //SYSOUT DD SYSOUT=C 03 //MSGOUT DD SYSOUT=C 04 //STEPLIB DD DSN=A123456.LOAD,DISP=SHR 05 //SORTOUT DD DSN=&&OUTPUT,DISP=(,PASS),UNIT=SYSDA, 06 // SPACE=(CYL,(8,4)) 07 //SORTCNTL DD * 08 * Update file size estimate 09 OPTION FILSZ=E30000 10 --------------------------------------------------------------------------------------------------------------------------------------------MYSORT CSECT 11 . . . LA R1,PL1 SET ADDRESS OF PARAMETER LIST 12 * TO BE PASSED TO DFSORT 13 ST R2,PL4 SET ADDRESS OF GETMAINED AREA 14 * TO BE PASSED TO E15 15 LINK EP=SORT INVOKE DFSORT 16 . . . PL1 DC A(CTLST) ADDRESS OF CONTROL STATEMENTS 17 PL2 DC A(E15) ADDRESS OF E15 ROUTINE 18 PL3 DC A(0) NO E35 ROUTINE 19 PL4 DS A USER EXIT ADDRESS CONSTANT 20 PL5 DC F-1 INDICATE END OF LIST 21 CTLST DS 0H CONTROL STATEMENTS AREA 22 DC AL2(CTL2-CTL1) LENGTH OF CHARACTER STRING 23 CTL1 DC C SORT FIELDS=(5,8,CSF,A) 24 DC C RECORD TYPE=F,LENGTH=80 25 DC C OPTION FILSZ=E25000,DYNALLOC, 26 DC CRESINV=8000 27 DC C OMIT FORMAT=CSF,COND=(5,8,EQ,13,8) 28 CTL2 EQU * 29 OUT DCB DDNAME=MSGOUT,... 30
Chapter 10. Examples of DFSORT Job Streams

713

Sort Examples
E15 DS . . . L . . . BR . . . 0H E15 ROUTINE 31

R2,4(,R1)

GET ADDRESS OF GETMAINED AREA

32

R14

RETURN TO DFSORT

33

The JCL for running program MYSORT, and highlights of the code used by MYSORT to invoke DFSORT with the extended parameter list, are shown below. For purposes of illustration, assume that none of the standard installation defaults for batch program invocation of DFSORT have been changed by the site. Line 01 02 03 04 05 06-07 Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls a program named MYSORT that in turn calls DFSORT. SYSOUT DD statement. Directs DFSORT messages and control statements to SYSOUT class C. MSGOUT DD statement. Directs MYSORT messages to SYSOUT class C. STEPLIB DD statement. Specifies the load library that contains MYSORT. SORTOUT DD statement. The output data set is temporary and is to be allocated on SYSDA. Because SORTIN is not used, DFSORT sets the RECFM and LRECL from the RECORD statement and sets the BLKSIZE to the LRECL (unblocked records). SORTCNTL DD statement. DFSORT control statements follow. Statements in SORTCNTL override or supplement statements passed by MYSORT in the extended parameter list it uses. Comment statement. Printed but otherwise ignored. OPTION statement. FILSZ=E30000 specifies an estimate of 30000 records, overriding FILSZ=E25000 in the OPTION statement of the extended parameter list. Because the E15 routine supplies all of the input records, DFSORT will not be able to determine the file size accurately; therefore, specifying FILSZ can make a significant difference in work space optimization when an E15 routine supplies all of the input records. Its important to change the FILSZ value whenever the number of input records increases significantly. This is the start of program MYSORT. Assume that it GETMAINs a work area, saves its address in register 2, and initializes it with information to be used by the E15 routine. MYSORT places the address of the extended parameter list to be passed to DFSORT in register 1. MYSORT places the address of the GETMAINed work area in the user exit address constant field in the extended parameter list.

08

09 10

11

12-13 14-15

714

z/OS V1R10.0 DFSORT Application Programming Guide

Sort Examples
DFSORT will pass this address to the E15 routine (in the second word of the E15 parameter list) when it is entered. 16 17-21 MYSORT calls DFSORT by its alias SORT. The extended parameter list specifies: the address of the control statements area, the address of the E15 routine, that no E35 routine is present, and the address of the GETMAINed work area. F-1 indicates the end of the extended parameter list. Subsequent parameter list fields, such as the address of an ALTSEQ table, are not used in this application. Because the address of the E15 routine is passed in the parameter list, SORTIN cannot be used; if a SORTIN DD statement were present, it would be ignored. 22-23 24 25 This is the start of the control statements area. The total length of the control statements is specified. SORT statement. FIELDS specifies an ascending 8-byte floating-sign control field starting at position 5. RECORD statement. TYPE=F and LENGTH=80 specify that the E15 inserts fixed-length records of 80 bytes. In this case, TYPE=F could be omitted, because DFSORT would automatically set a record type of F. However, LENGTH must be specified when an E15 supplies all of the input records. OPTION statement. FILSZ=E25000 specifies an estimate of 25000 records, which is overridden by FILSZ=E30000 in SORTCNTLs OPTION statement. DYNALLOC specifies that work data sets are to be dynamically allocated using the installation defaults for the type of device and number of devices. RESINV=8000 specifies that approximately 8000 bytes are required for the system services (for example, GETMAIN and OPEN) that MYSORTs E15 exit routine performs. OMIT statement. FORMAT specifies that the compare fields are floating-sign. COND specifies that input records with equal 8-byte floating-sign compare fields starting in position 5 (also the control field) and position 13 are to be omitted from the output data set. This is the end of the control statements area. This is the DCB for MYSORTs MSGOUT output. This is MYSORTs E15 routine. The E15 routine loads the address of the GETMAINed work area from the second word of the E15 parameter list. The E15 routine must supply each input record by placing its address in register 1 and placing a 12 (insert) in register 15. When all the records have been passed, the E15 routine must place an 8 (do not return) in register 15.

26-27

28

29 30 31-33

Chapter 10. Examples of DFSORT Job Streams

715

Sort Examples

Example 10. Sort with OUTFIL

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Fixed-length record data set Multiple fixed-length record data sets Dynamically allocated (by default) None OUTFIL
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

//EXAMP JOB A400,PROGRAMMER //OUTFIL EXEC PGM=SORT //SYSOUT DD SYSOUT=A //SORTIN DD DSN=GRP.RECORDS,DISP=SHR //ALLGPS DD DSN=GRP.ALLGRPS,DISP=OLD //ALLBU DD DSN=GRP.BU,DISP=(NEW,CATLG,DELETE), // UNIT=3390,SPACE=(TRK,(10,10)) //G1STATS DD SYSOUT=A //G2STATS DD SYSOUT=A //SYSIN DD * SORT FIELDS=(6,5,CH,A) OUTFIL FNAMES=(ALLGPS,ALLBU) OUTFIL FNAMES=G1STATS, INCLUDE=(1,3,CH,EQ,CG01), HEADER2=(1:GROUP 1 STATUS REPORT FOR ,&DATE, - PAGE ,&PAGE,2/, 6:ITEM ,16:STATUS ,31:PARTS,/, 6:-----,16:------------,31:-----), OUTREC=(6:6,5, 16:14,1,CHANGE=(12, C1,CSHIP, C2,CHOLD, C3,CTRANSFER), NOMATCH=(C*CHECK CODE*), 31:39,1,BI,M10,LENGTH=5, 120:X) OUTFIL FNAMES=G2STATS, INCLUDE=(1,3,CH,EQ,CG02), HEADER2=(1:GROUP 2 STATUS REPORT FOR ,&DATE, - PAGE ,&PAGE,2/, 6:ITEM ,16:STATUS ,31:PARTS,/, 6:-----,16:------------,31:-----), OUTREC=(6:6,5, 16:14,1,CHANGE=(12, C1,CSHIP, C2,CHOLD, C3,CTRANSFER), NOMATCH=(C*CHECK CODE*), 31:39,1,BI,M10,LENGTH=5, 120:X)

Line 01 02 03 04

Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly by its alias name SORT. SYSOUT DD statement. Directs DFSORT messages and control statements to sysout class A. SORTIN DD statement. The input data set is named GRP.RECORDS and is cataloged. DFSORT determines from the data set label that the RECFM is FB, the LRECL is 80 and the BLKSIZE is 23440.

716

z/OS V1R10.0 DFSORT Application Programming Guide

Sort Examples
05 ALLGPS DD statement. The first OUTFIL output data set is named GRP.ALLGRPS and is catalogued. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. ALLBU DD statement. The second OUTFIL output data set is named GRP.BU and is to be allocated on a 3390 and catalogued. DFSORT sets the RECFM and LRECL from SORTIN and selects an appropriate BLKSIZE. G1STATS DD statement. The third OUTFIL output data set is directed to sysout class A. Because this is an OUTFIL report data set, DFSORT sets the RECFM to FBA (FB from SORTIN and A for ANSI control characters) and the LRECL to 121 (1 byte for the ANSI control character and 120 bytes for the data). DFSORT sets an appropriate BLKSIZE. G2STATS DD statement. The fourth OUTFIL output data set is directed to sysout class A. Because this is an OUTFIL report data set, DFSORT sets the RECFM to FBA (FB from SORTIN and A for ANSI control characters) and the LRECL to 121 (1 byte for the ANSI control character and 120 bytes for the data). DFSORT sets an appropriate BLKSIZE. SYSIN DD statement. DFSORT control statements follow. SORT statement. FIELDS specifies an ascending 5-byte character control field starting at position 6. OUTFIL statement. The sorted input records are written to the ALLGPS and ALLBU data sets. OUTFIL statement. The subset of sorted input records containing G01 in positions 1 through 3 are used to produce a report, which is written to the G1STATS data set. OUTFIL statement. The subset of sorted input records containing G02 in positions 1 through 3 are used to produce a report, which is written to the G2STATS data set.

06-07

08

09

10 11 12 13-26

27-40

Chapter 10. Examples of DFSORT Job Streams

717

Sort Examples

Example 11. Sort with Pipes and OUTFIL SPLIT

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Pipes Pipes Dynamically allocated None FILSZ, OUTFIL, DYNALLOC
01 02 03 04 05 06 07 08 09 10 11 12 13

//EXAMP JOB A400,PROGRAMMER //RUNSORT EXEC PGM=ICEMAN //SYSOUT DD SYSOUT=H //SORTIN DD DSN=INPUT.PIPE,SUBSYS=PIPE, // DCB=(LRECL=60,RECFM=FB,BLKSIZE=32760) //OUT1 DD DSN=OUTPUT.PIPE1,SUBSYS=PIPE, // DCB=(LRECL=60,RECFM=FB,BLKSIZE=32760) //OUT2 DD DSN=OUTPUT.PIPE2,SUBSYS=PIPE, // DCB=(LRECL=60,RECFM=FB,BLKSIZE=32760) //SYSIN DD * OPTION DYNALLOC,FILSZ=U1000000 SORT FIELDS=(1,20,CH,A,25,4,BI,A) OUTFIL FNAMES=(OUT1,OUT2),SPLIT

Line 01 02 03 04-05

Explanation Job statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly. SYSOUT DD statement. Directs DFSORT messages and control statements to system output class H. SORTIN DD statement. The SUBSYS=PIPE parameter directs the allocation to the PIPE subsystem for the pipe named INPUT.PIPE. The DCB statement describes the data set characteristics to subsystem PIPE. OUT1 DD statement. The SUBSYS=PIPE parameter directs the allocation to the PIPE subsystem for the pipe named OUTPUT.PIPE1. The DCB statement describes the data set characteristics to subsystem PIPE. OUT2 DD statement. The SUBSYS=PIPE parameter directs the allocation to the PIPE subsystem for the pipe named OUTPUT.PIPE2. The DCB statement describes the data set characteristics to subsystem PIPE. SYSIN DD statement. DFSORT control statements follow. OPTION statement. DYNALLOC specifies that work data sets are to be dynamically allocated using the installation defaults for type of device and number of devices. FILSZ=U1000000 specifies an estimate of one million input records. SORT statement. FIELDS specifies an ascending 20-byte character control field starting at position 1 and an ascending 4 byte binary control field starting at position 25. OUTFIL statement. The records from the SORTIN pipe are sorted and written alternatively to the OUT1 and OUT2 pipes (that is, the sorted records are split evenly between the two output pipes).

06-07

08-09

10 11

12

13

Example 12. Sort with INCLUDE and LOCALE

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Fixed-length record data set Fixed-length record data set Dynamically allocated (by default) None INCLUDE, LOCALE

718

z/OS V1R10.0 DFSORT Application Programming Guide

Sort Examples
//EXAMP JOB A400,PROGRAMMER //STEP1 EXEC PGM=SORT,PARM=LOCALE=FR_CA //STEPLIB DD DSN=SYS1.SCEERUN,DISP=SHR //SYSOUT DD SYSOUT=A //SORTIN DD DSN=INPUT.FRENCH.CANADA,DISP=SHR //SORTOUT DD DSN=OUTPUT.FRENCH.CANADA,DISP=OLD //SYSIN DD * SORT FIELDS=(1,20,CH,A,25,1,BI,D,30,10,CH,A) INCLUDE COND=(40,6,CH,EQ,50,6,CH) 01 02 03 04 05 06 07 08 09

Line 01 02 |

Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly by its alias name SORT. LOCALE specified in EXEC PARM overrides the installation default for LOCALE. The locale for the French language and the cultural conventions of Canada will be active. STEPLIB DD statement. Specifies the Language Environment run-time library containing the dynamically loadable locales. SYSOUT statement. Directs DFSORT messages and control statements to sysout class A. SORTIN DD statement. The input data set is named INPUT.FRENCH.CANADA and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. SORTOUT DD statement. The output data set is named OUTPUT.FRENCH.CANADA and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. SYSIN DD statement. DFSORT control statements follow. SORT statement. FIELDS specifies an ascending 20-byte character control field starting at position 1, a one-byte descending binary control field starting at position 25, and a 10-byte ascending character control field starting at position 30. The character (CH) control fields will be sorted according to the collating rules defined in locale FR_CA. INCLUDE statement. COND specifies that only input records with equal 6-byte character compare fields starting in position 40 and position 50 are to be included in the output data set. The character (CH) compare fields will be compared according to the collating rules defined in locale FR_CA.

03 04 05

06

07 08

09

Example 13: Sort with HFS Files

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Concatenated HFS Files HFS File Dynamically allocated (by default) None None
01 02 03 04 05 06 07 08 09 10 11

//EXAMP JOB A400,PROGRAMMER //S1 EXEC PGM=SORT //SYSOUT DD SYSOUT=A //SORTIN DD PATH=/user/hfs.inp1.txt,PATHOPTS=ORDONLY, // LRECL=80,BLKSIZE=240,RECFM=FB,FILEDATA=TEXT // DD PATH=/user/hfs.inp2.txt,PATHOPTS=ORDONLY, // LRECL=80,BLKSIZE=80,RECFM=F,FILEDATA=TEXT //SORTOUT DD PATH=/user/hfs.ut.txt,PATHOPTS=OWRONLY, // LRECL=80,BLKSIZE=80,RECFM=F,FILEDATA=TEXT //SYSIN DD * SORT FIELDS=(10,8,CH,A)

Chapter 10. Examples of DFSORT Job Streams

719

Sort Examples
Line 01 02 03 04-05 Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly by its alias name SORT. SYSOUT DD statement. Directs DFSORT messages and control statements to system output class A. SORTIN DD statement. The first input file is an HFS file named /user/hfs.inp1.txt. Only read access is allowed. The file is defined as a text file. It has fixed-length records with a record size of 80 and a block size of 240. The second input file is an HFS file named /user/hfs.inp2.txt. Only read access is allowed. The file is defined as a text file. It has fixed-length records with a record size of 80 and a block size of 80. SORTOUT DD statement. The output file is an HFS file named /user/hfs.ut.txt. Only write access is allowed. The file is defined as a text file. It has fixed-length records with a record size of 80 and a block size of 80. SYSIN DD statement. DFSORT control statements follow. SORT statement. FIELDS specifies an ascending 8-byte character control field starting at position 10.

06-07

08-09

10 11

Example 14. Sort with IFTHEN

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Three fixed-length record data sets Fixed-length record data set Dynamically allocated (by default) None IFTHEN 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19

//EXAMP JOB A400,PROGRAMMER //S1 EXEC PGM=SORT //SYSOUT DD SYSOUT=A //SORTIN DD DSN=INPUT.FILE1,DISP=SHR // DD DSN=INPUT.FILE2,DISP=SHR // DD DSN=INPUT.FILE3,DISP=SHR //SORTOUT DD DSN=OUTPUT.FILE,DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(5,5)),UNIT=SYSDA //SYSIN DD * INREC IFTHEN=(WHEN=(1,3,CH,EQ,CHDR), OVERLAY=(6:YDDD=(D4/),81:C0,82:SEQNUM,2,ZD)), IFTHEN=(WHEN=(1,3,CH,EQ,CTRL), OVERLAY=(11:YDDD=(D4/),81:C9,82:SEQNUM,2,ZD)), IFTHEN=(WHEN=NONE, OVERLAY=(81:C1)) SORT FIELDS=(81,1,CH,A,8,5,CH,A) OUTFIL REMOVECC, OMIT=(81,1,SS,EQ,C0,9,AND,82,2,ZD,GT,+1), OUTREC=(1,80)

This example shows how you can use three input files, each with a header record (HDR), detail records (DTL) and a trailer record (TRL), and create an output file with one header record with the current date, the sorted detail records, and one trailer record with the current date. 01 JOB statement. Introduces this job to the operating system.

720

z/OS V1R10.0 DFSORT Application Programming Guide

Sort Examples
02 03 04-06 EXEC statement. Calls DFSORT directly by its alias name SORT. SYSOUT DD statement. Directs DFSORT messages and control statements to sysout class A. SORTIN DD statement. Consists of a concatenation of three input data sets: INPUT.FILE1, INPUT.FILE2 and INPUT.FILE3. DFSORT determines from the data set labels that each data set has RECFM=FB and LRECL=80. The BLKSIZEs vary. Each input data set has a header record, detail records, and a trailer record. SORTOUT DD statement. Creates a new output data set: OUTPUT.FILE. DFSORT sets RECFM=FB, LRECL=80 and selects an appropriate BLKSIZE. The output data set will have one header record, the sorted detail records, and one trailer record. SYSIN DD statement. DFSORT control statements follow. INREC statement. The first IFTHEN WHEN=(logexp) clause identifies and operates on header records (HDR in positions 1-3); OVERLAY puts todays date in the form ddd/yyyy in positions 6-13, adds a 0 in position 81, adds a ZD sequence number in positions 82-83 and does not affect the rest of the record. The second IFTHEN WHEN=(logexp) clause identifies and operates on trailer records (TRL in positions 1-3); OVERLAY puts todays date in the form ddd/yyyy in positions 11-18, adds a 9 in position 81, adds a ZD sequence number in positions 82-83 and does not affect the rest of the record. The IFTHEN WHEN=NONE clause identifies and operates on detail records (not HDR or TRL in positions 1-3); OVERLAY adds a 1 in position 81 and does not affect the rest of the record. DFSORT extends the reformatted input records from 80 bytes to 83 bytes to accommodate the identifier byte added in position 81 and the sequence number added in positions 82-83. The 0, 1 or 9 identifier byte added in position 81 allows us to sort the header records (0) first, followed by the detail records (1), and then the trailer records (9). The sequence number added in positions 82-83 will allow us to keep only the first header record and the first trailer record. The sequence number will be 1 for the first header record, 2 for the second header record and 3 for the third header record. Likewise, the sequence number will be 1 for the first trailer record, 2 for the second trailer record and 3 for the third trailer record. Since the sequence number is not specified for the detail records, it will be blank. 16 SORT statement. FIELDS specifies an ascending 1-byte character control field at position 81 (the identifier byte added by INREC), and an ascending 5-byte character control field starting at position 8 (the key for the detail records). OUTFIL statement. REMOVECC removes the ANSI carriage control characters and ensures that the RECFM is FB rather than FBA. OMIT specifies that reformatted output records with 0 or 9 in position 81 (header or trailer records) and a sequence number in positions 82-83 greater than 1 (second and subsequent header or trailer records), are omitted. OUTREC keeps only positions 1-80 for the OUTFIL output records, thus removing the identifier byte and sequence number we added

07-08

09 10-15

17-19

Chapter 10. Examples of DFSORT Job Streams

721

Sort Examples
in positions 81-83 with the INREC statement (we do not want these temporary fields in the OUTFIL output records).

Merge Examples
This section contains 2 merge examples.

Example 1. Merge with EQUALS

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Blocked fixed-length records on disk Blocked fixed-length records on 3390 Not applicable None EQUALS
01 02 03 04 05 06 07 08 09 10 11

//EXAMP JOB A400,PROGRAMMER //STEP1 EXEC PGM=SORT //SYSOUT DD SYSOUT=A //SORTIN01 DD DSN=M1234.INPUT1,DISP=SHR //SORTIN02 DD DSN=M1234.INPUT2,DISP=SHR //SORTIN03 DD DSN=M1234.INPUT3,DISP=SHR //SORTOUT DD DSN=M1234.MERGOUT,DISP=(,KEEP), // SPACE=(CYL,(2,4)),UNIT=3390 //SYSIN DD * MERGE FIELDS=(1,8,CH,A,20,4,PD,A) OPTION EQUALS

Line 01 02 03 04

Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly by its alias SORT. SYSOUT DD statement. Directs DFSORT messages and control statements to sysout class A. SORTIN01 DD statement. The first input data set is named M1234.INPUT1 and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. SORTIN02 DD statement. The second input data set is named M1234.INPUT2 and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. SORTIN03 DD statement. The third input data set is named M1234.INPUT3 and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. SORTOUT DD statement. The output data set is named M1234.MERGOUT and is to be allocated on 3390 and kept. DFSORT sets the RECFM and LRECL from the SORTINnn data sets and selects an appropriate BLKSIZE. SYSIN DD statement. DFSORT control statements follow. MERGE statement. FIELDS specifies an ascending 8-byte character control field starting at position 1 and an ascending 4-byte packed-decimal field starting at position 20. The records in each input data set must already be in the order specified. OPTION statement. EQUALS specifies that the order of output records with equal control fields is to be based on the file number of the input data sets and the original order of the records within each input data set.

05

06

07-08

09 10

25

722

z/OS V1R10.0 DFSORT Application Programming Guide

Merge Examples

Example 2. Merge with LOCALE and OUTFIL

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Fixed-length record data set Multiple fixed-length record data sets Not applicable None LOCALE, OUTFIL
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19

//EXAMP JOB A400,PROGRAMMER //STEP1 EXEC PGM=SORT //STEPLIB DD DSN=SYS1.SCEERUN,DISP=SHR //SYSOUT DD SYSOUT=A //SORTIN01 DD DSN=INPUT01.GERMAN.GERMANY,DISP=SHR //SORTIN02 DD DSN=INPUT02.GERMAN.GERMANY,DISP=SHR //SORTIN03 DD DSN=INPUT03.GERMAN.GERMANY,DISP=SHR //GP1 DD DSN=OUTPUT.GERMAN.GP1,DISP=OLD //GP2 DD DSN=OUTPUT.GERMAN.GP2,DISP=OLD //GP3 DD DSN=OUTPUT.GERMAN.SAVE,DISP=OLD //DFSPARM DD * LOCALE=De_DE.IBM-1047 MERGE FIELDS=(25,5,CH,A,40,4,PD,D) OUTFIL FNAMES=GP1, INCLUDE=(23,1,CH,LE,C) OUTFIL FNAMES=GP2, INCLUDE=(23,1,CH,GT,C,AND, 23,1,CH,LT,C) OUTFIL FNAMES=GP3,SAVE

Line 01 02 03 04 05

Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly by its alias name SORT. STEPLIB DD statement. Specifies the Language Environment run-time library containing the dynamically loadable locales. SYSOUT statement. Directs DFSORT messages and control statements to sysout class A. SORTIN01 DD statement. The first input data set is named INPUT01.GERMAN.GERMANY and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. SORTIN02 DD statement. The second input data set is named INPUT02.GERMAN.GERMANY and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. SORTIN03 DD statement. The third input data set is named INPUT03.GERMAN.GERMANY and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. GP1 DD statement. The first OUTFIL output data set is named OUTPUT.GERMAN.GP1 and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. GP2 DD statement. The second OUTFIL output data set is named OUTPUT.GERMAN.GP2 and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. GP3 DD statement. The third OUTFIL output data set is named OUTPUT.GERMAN.GP3 and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. DFSPARM DD statement. DFSORT control statements follow. LOCALE parameter. Overrides the installation default for LOCALE. The
Chapter 10. Examples of DFSORT Job Streams

06

07

08

09

10

11 | 12

723

Merge Examples
locale for the German language and the cultural conventions of Germany based on the IBM-1047 encoded character set will be active. 13 MERGE statement. FIELDS specifies an ascending 5-byte character control field starting at position 25, and a descending 4-byte packed decimal control field starting at position 40. The character (CH) control field will be merged according to the collating rules defined in locale De_DE.IBM-1047. The records in each input data set must already be in the order specified. OUTFIL statement. The subset of records with character values less than or equal to in position 23 are written to the GP1 output data set. The character (CH) compare field and character constant will be compared according to the collating rules defined in locale De_DE.IBM-1047. OUTFIL statement. The subset of records with character values greater than but less than in position 23 are written to the GP2 output data set. The character (CH) compare fields and character constants will be compared according to the collating rules defined in locale De_DE.IBM-1047. OUTFIL statement. Any records not written to the GP1 or GP2 output data sets are written to the GP3 output data set.

14-15

16-18

19

Copy Examples
This section contains 2 copy examples.

724

z/OS V1R10.0 DFSORT Application Programming Guide

Copy Examples

Example 1. Copy with EXEC PARMs, SKIPREC, MSGPRT and ABEND

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Blocked fixed-length records on multivolume 3490 Blocked fixed-length records on disk Not applicable None SKIPREC, MSGPRT, ABEND
01 02 03 04 05 06 07 08 09 10

//EXAMP JOB A400,PROGRAMMER //STEP1 EXEC PGM=SORT, // PARM=SKIPREC=500,MSGPRT=CRITICAL,ABEND //SYSOUT DD SYSOUT=A //SORTIN DD DSN=FLY.RECORDS,VOL=SER=(000333,000343), // UNIT=(3490,2),DISP=OLD,LABEL=(,NL), // DCB=(RECFM=FB,LRECL=12000,BLKSIZE=24000) //SORTOUT DD DSN=FLY.RECORDS.COPY,DISP=OLD //SYSIN DD * SORT FIELDS=COPY

Line 01 02-03

Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly by its alias SORT. SKIPREC=500 specifies that the first 500 input records are not to be included in the output data set. MSGPRT=CRITICAL specifies that error messages, but not informational messages, are to be printed. ABEND specifies that DFSORT is to terminate with a user ABEND if it issues an error message. SYSOUT DD statement. Directs DFSORT messages and control statements to sysout class A. SORTIN DD statement. The input data set is named FLY.RECORDS and resides on 3490 volumes 000333 and 000343. The UNIT parameter requests two tape drives, one for each volume of the data set. Because the tape is unlabeled, DCB parameters must be supplied to indicate that the RECFM is FB, the LRECL is 12000 and the BLKSIZE is 24000. SORTOUT DD statement. The output data set is named FLY.RECORDS.COPY and is cataloged. DFSORT determines the RECFM, LRECL and BLKSIZE from the data set label. SYSIN DD statement. DFSORT control statements follow. SORT statement. FIELDS=COPY specifies a copy application.

04 05-07

08

09 10

Chapter 10. Examples of DFSORT Job Streams

725

Copy Examples

Example 2. Copy with INCLUDE and VLSHRT

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Blocked spanned records on disk Blocked spanned records on SYSDA Not applicable None INCLUDE, VLSHRT
01 02 03 04 05 06 07 08 09

//EXAMP JOB A400,PROGRAMMER //COPY EXEC PGM=SORT //SYSOUT DD SYSOUT=A //SORTIN DD DSN=SMF.DATA,DISP=SHR //SORTOUT DD DSN=SMF.VIOL,DISP=(,KEEP),SPACE=(CYL,(2,5)), // UNIT=SYSDA //SYSIN DD * INCLUDE COND=(6,1,FI,EQ,80,AND,19,1,BI,EQ,B1.......) OPTION COPY,VLSHRT

Line 01 02 03 04

Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly by its alias SORT. SYSOUT DD statement. Directs DFSORT messages and control statements to sysout class A. SORTIN DD statement. The input data set is named SMF.DATA and is cataloged. DFSORT determines from the data set label that the RECFM is VBS, the LRECL is 32760 and the BLKSIZE is 23476. SORTOUT DD statement. The output data set is named SMF.VIOL and is to be allocated on SYSDA and kept. DFSORT sets the RECFM and LRECL from SORTIN and selects an appropriate BLKSIZE. SYSIN DD statement. DFSORT control statements follow. INCLUDE statement. COND specifies that only input records with decimal 80 in the 1-byte fixed-point field at position 6 and bit 0 on in the 1-byte binary field at position 19 are to be included in the output data set. OPTION statement. COPY specifies a copy application. VLSHRT specifies that records that are too short to contain all of the INCLUDE compare fields are not to be included in the output data set.

05-06

07 08

09

Example 3. Copy with OUTREC, PARSE and BUILD

INPUT OUTPUT WORK DATA SETS USER EXITS FUNCTIONS/OPTIONS Blocked fixed-length records on disk Blocked fixed-length records on disk Not applicable None OUTREC, PARSE, BUILD 01 02 03 04 05 06 07 08 09 10 11 12 13

//EXAMP JOB A400,PROGRAMMER //S1 EXEC PGM=ICEMAN //SYSOUT DD SYSOUT=A //SORTIN DD DSN=FLY.VAR.FIELDS.IN,DISP=SHR //SORTOUT DD DSN=FLY.FIX.FIELDS.OUT,DISP=OLD //SYSIN DD * OPTION COPY OUTREC PARSE=(%00=(ABSPOS=21,STARTAFT=BLANKS, ENDBEFR=C,,FIXLEN=5), %=(ENDBEFR=C,), %01=(ENDBEFR=C,,FIXLEN=10), %02=(FIXLEN=7)), BUILD=(1,15,

726

z/OS V1R10.0 DFSORT Application Programming Guide

Copy Examples
18:%00,JFY=(SHIFT=RIGHT,LEAD=C(,TRAIL=C),LENGTH=7), 30:%02,SFF,TO=ZD,LENGTH=7, 40:%01,60:X) 14 15 16

Line 01 02 03 04

Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls DFSORT directly. SYSOUT DD statement. Directs DFSORT messages and control statements to sysout class A. SORTIN DD statement. The input data set is named FLY.VAR.FIELDS.IN and is cataloged. DFSORT determines from the data set label that the RECFM is FB, the LRECL is 60 and the BLKSIZE is 27960. SORTOUT DD statement. The output data set is named FLY.FIX.FIELDS.OUT and is cataloged. DFSORT determines from the data set label that the RECFM is FB, the LRECL is 60 and the BLKSIZE is 27960. SYSIN DD statement. DFSORT control statements follow. OPTION statement. COPY specifies a copy application. OUTREC statement. PARSE and BUILD reformat the input records containing one fixed position/length field and four variable position/length fields to output records containing four fixed position/length fields.

05

06 07 08-16

Chapter 10. Examples of DFSORT Job Streams

727

ICEGENER Example

ICEGENER Example
This section contains an ICEGENER example. INPUT Same as for IEBGENER job OUTPUT Same as for IEBGENER job WORK DATA SETS Not applicable USER EXITS None FUNCTIONS/OPTIONS None
//EXAMP //GENR //SYSPRINT //SYSUT1 //SYSUT2 //SYSIN JOB A400,PROGRAMMER EXEC PGM=ICEGENER DD SYSOUT=A DD DSN=CTL.MASTER,DISP=SHR DD DSN=CTL.BACKUP,DISP=OLD DD DUMMY 01 02 03 04 05 06

This example shows how to use the ICEGENER facility for an IEBGENER job if your site has not installed ICEGENER as an automatic replacement for IEBGENER. The ICEGENER facility selects the more efficient DFSORT copy function for this IEBGENER job. Line 01 02 03-06 Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls the ICEGENER facility. PGM=IEBGENER has been replaced by PGM=ICEGENER. No other changes to the IEBGENER job are required.

728

z/OS V1R10.0 DFSORT Application Programming Guide

ICETOOL Example

ICETOOL Example
This section contains an example of ICETOOL with various operators. INPUT Multiple data sets OUTPUT Multiple data sets WORK DATA SETS Dynamically allocated (automatic) USER EXITS ICETOOLs E35 (automatic) FUNCTIONS/OPTIONS OCCUR, COPY, SORT, MODE, VERIFY, STATS, DISPLAY
//EXAMP JOB A400,PROGRAMMER //TOOLRUN EXEC PGM=ICETOOL,REGION=1024K //TOOLMSG DD SYSOUT=A //DFSMSG DD SYSOUT=A //TOOLIN DD * * Print report showing departments with less than 5 employees OCCUR FROM(IN1) LIST(LT5) LOWER(5) BLANK TITLE(Small Departments) PAGE HEADER(Department) HEADER(Employees) ON(45,3,CH) ON(VALCNT) * Sort by last name and first name SORT FROM(IN1) TO(DEPTSD,DEPTSP) USING(ABCD) * Do following operators even if a previous operator failed, * but stop processing if a subsequent operator fails. MODE STOP * Verify decimal fields VERIFY FROM(IN2) ON(22,6,PD) ON(30,3,ZD) * Print statistics for record length and numeric fields STATS FROM(IN2) ON(VLEN) ON(22,6,PD) ON(30,3,ZD) * Sort and produce total for each unique key SORT FROM(IN2) TO(OUT4) USING(CTL1) * Print report containing: * - key and total for each unique key * - lowest and highest of the totals DISPLAY FROM(OUT4) LIST(LIST1) TITLE(Unique key totals report) DATE TIME ON(5,10,CH) ON(22,6,PD) ON(30,3,ZD) MINIMUM(Lowest) MAXIMUM(Highest) PLUS //LT5 DD SYSOUT=A //IN1 DD DSN=FLY.INPUT1,DISP=SHR //ABCDCNTL DD * * Sort by last name, first name SORT FIELDS=(12,15,CH,A,1,10,CH,A) //DEPTSD DD DSN=FLY.OUTPUT1,DISP=SHR //DEPTSP DD SYSOUT=A //IN2 DD DSN=FLY.INPUT2,DISP=SHR //OUT4 DD DSN=FLY.OUTPUT2,DISP=OLD //CTL1CNTL DD * * Sort and produce totals in one record for each unique key SORT FIELDS=(5,10,CH,A) SUM FIELDS=(22,6,PD,30,3,ZD) //LIST1 DD SYSOUT=A 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42

This example shows how ICETOOL can be used to perform multiple operations in a single step. Line 01 02 03 Explanation JOB statement. Introduces this job to the operating system. EXEC statement. Calls ICETOOL specifying the recommended REGION of 1024K. TOOLMSG DD statement. Directs ICETOOL messages and statements to system output class A.
Chapter 10. Examples of DFSORT Job Streams

729

ICETOOL Example
04 05 DFSMSG DD statement. Directs DFSORT messages and control statements to SYSOUT class A. TOOLIN DD statement. ICETOOL statements follow. The MODE for the ICETOOL run is initially set to STOP. If an error is detected for an operator, SCAN mode will be entered. Comment statement. Printed but otherwise ignored. OCCUR operator. Prints, in the LT5 data set, a report detailing each value for the specified field in the IN1 data set and the number of times that value occurs. Comment statement. SORT operator. Records from the IN1 data set are sorted to the DEPTSD and DEPTSP data sets using the DFSORT control statements in the ABCDCNTL data set. As a result, FLY.OUTPUT1 and DEPTSP (SYSOUT) contain the sorted records from FLY.INPUT1. Comment statements. MODE operator. The MODE is reset to STOP (needed in case SCAN mode was entered due to an error for a previous operator). If an error is detected for a subsequent operator, SCAN mode will be entered. This divides the previous operators and subsequent operators into two unrelated groups. Comment statement. VERIFY operator. Identifies invalid values, if any, in the specified decimal fields of the IN2 data set. Used to stop subsequent operations if any invalid value is found in FLY.INPUT2. Comment statement. STATS operator. Prints the minimum, maximum, average, and total for the specified fields of the IN2 data set. ON(VLEN) operates on the record length of the records in FLY.INPUT2. Thus, the values printed for ON(VLEN) represent the shortest record, the longest record, the average record length, and the total number of bytes for FLY.INPUT2. 20 21 Comment statement. SORT operator. Records from the IN2 data set are sorted and summarized to the OUT4 data set using the DFSORT control statements in the CTL1CNTL data set. As a result, FLY.OUTPUT2 contains one record from FLY.INPUT2 for each unique sort field with totals for the sum fields. Comment statements. DISPLAY operator. Prints, in the LIST1 data set, a report detailing each sort and sum value for the OUT4 data set resulting from the previous operation, and the lowest and highest value for each sum field. DD statements. Defines the data sets and DFSORT control statements used for the ICETOOL operations described above.

06 07-10

11 12

13-14 15

16 17

18 19

22-24 25-28

29-42

730

z/OS V1R10.0 DFSORT Application Programming Guide

Appendix A. Using Work Space

Introduction . . . . . . . . . . Hiperspace . . . . . . . . . . Work Data Set Devices . . . . . . Disk and Tape Devices . . . . . Number of Devices . . . . . . Non-Synchronous Storage Subsystems Allocation of Work Data Sets . . . . Dynamic Allocation of Work Data Sets Automatic Dynamic Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731 731 732 732 732 732 733 734 734 Device Defaults . . . . . . . File Size and Dynamic Allocation . . Dynamic Over-Allocation of Work Space JCL Allocation of Work Data Sets . . . Disk Capacity Considerations . . . . . Exceeding Disk Work Space Capacity . Tape Capacity Considerations . . . . . Exceeding Tape Work Space Capacity . . . . . . . . . . . . . . . . . . . . . . . . . 734 734 735 736 737 737 738 738

Introduction
When a sort application cannot be performed entirely in virtual storage, DFSORT must use work space. The amount of work space required depends on: v The amount of data being sorted v The amount of virtual storage available to DFSORT v The amount of Hiperspace available to DFSORT v The type of devices you use v The DFSORT functions and features you use (for example, VLSHRT, locale processing, EFS, and ALTSEQ can increase the amount of work space required). There are three ways to supply work space for a DFSORT application: v Hiperspace v Dynamic allocation of work data sets v JCL allocation of work data sets. For best performance, an optimal amount of Hiperspace, in combination with dynamically allocated disk work data sets, is strongly recommended. See Use Hipersorting on page 694 for more information on using the HIPRMAX option. The DYNAUTO installation option, or the DYNALLOC run-time option, can be used to dynamically allocate work data sets.

Hiperspace
| | | | | | | | | | | | | | Hiperspace is the most efficient form of intermediate storage for DFSORT. Using the default installation option HIPRMAX=OPTIMAL ensures that DFSORT will use Hiperspace for Hipersorting whenever possible. Sites can tune their definition of HIPRMAX=OPTIMAL through use of the EXPMAX, EXPOLD, and EXPRES installation options. See z/OS DFSORT Installation and Customization for more information. DFSORTs use of Hiperspace depends upon the availability of central storage, the needs of other concurrent Hipersorting, memory object sorting, and dataspace sorting applications throughout the time the application runs, and the settings of the EXPMAX, EXPOLD, and EXPRES installation options. Consequently, it is possible for the same application to use varying amounts of Hiperspace from run to run. If enough Hiperspace is available, DFSORT uses Hiperspace exclusively for intermediate storage. If the amount of Hiperspace is insufficient, DFSORT uses a combination of Hiperspace and work data sets, or even work data sets alone. DFSORT only uses Hipersorting when there is sufficient storage to back all the DFSORT Hiperspace data. Hipersorting is very dynamic: multiple concurrent
Copyright IBM Corp. 1973, 2006

731

Using Work Space

Hipersorting applications always know each others storage needs and never try to back their Hiperspaces with the same portion of storage. In addition, DFSORT checks the available storage throughout the run, and switches from using Hiperspace to using disk work data sets when either a storage shortage is predicted or the total Hipersorting, memory object sorting, and dataspace sorting activity on the system reaches the limits set by the EXPMAX, EXPOLD, and EXPRES installation options. Hipersorting requires that work data sets be available, as well as Hiperspace. DFSORT forces the use of dynamic allocation for Hipersorting if work data sets are not requested explicitly. For further details, see the HIPRMAX option of the OPTION Control Statement on page 167.

Work Data Set Devices

The type of device selected for work data sets can have a significant effect on performance. Consider the following when selecting devices for work data sets.

Disk and Tape Devices

For optimal performance, use disk devices to which little other activity is directed, for work data sets. Specify high-speed devices such as IBMs TotalStorage DS8000 storage subsystems, and avoid specifying tape or virtual (VIO). Using tape devices for work data sets rather than disk causes significant performance degradation for the following reasons: v Tape work data sets prevent DFSORT from using its more efficient sorting techniques, Blockset and Peerage/Vale. Disk work data sets allow DFSORT to use these techniques. v Tape work data sets must be accessed sequentially. Disk data sets can be accessed randomly. v Disk control units can provide additional features, such as cache fast write, that are not available with tape devices.

Number of Devices
Although one work data set is sufficient, using two or more work data sets on separate devices usually reduces the elapsed time of the application significantly. In general, using more than three work data sets does not reduce elapsed time any further, and is only necessary if the work data sets are small or the file size is large. For optimum allocation of resources such as virtual storage, avoid specifying a large number of work data sets unnecessarily. No more than 255 work data sets can be specified. If you specify more than 32 work data sets, and the Blockset technique is not selected, a maximum of 32 work data sets is used.

Non-Synchronous Storage Subsystems

Allocation of work data sets on devices attached to non-synchronous storage subsystems can affect the performance of certain DFSORT applications. Whether or not a particular application is affected depends on many factors, the most critical of which is the ratio of input file size to available storage. In general, to maximize performance, DFSORT needs the following:

732

z/OS V1R10.0 DFSORT Application Programming Guide

Using Work Space

v Accurate knowledge of the size of the file being sorted In most cases, DFSORT is able to calculate the file size accurately. However, for applications that sort many input tapes that are not managed by DFSMSrmm or a tape management system that uses ICETPEX (especially compacted input tapes) or that use E15 exits that add or delete records, we recommend that you specify the file size using the FILSZ or SIZE parameter. v Adequate storage relative to the size of the file being sorted Table 75 shows the minimum recommended storage to provide DFSORT based on various input file sizes.
Table 75. Minimum Storage Required for Various File Sizes Input file size Less than 200MB 200MB to 500MB 500MB to 1GB More than 1GB Minimum storage 4MB 8MB 16MB 16-32MB

Allocation of Work Data Sets

| | | | Dynamic allocation has the following advantages over JCL allocation: v Installation options can be used to automatically activate dynamic allocation for all sort applications. To use JCL allocation, appropriate DD statements must be specified for each individual application. v As the characteristics (file size, virtual storage, and so on) of an application change over time, DFSORT can automatically optimize the amount of dynamically allocated work space for the application. This eliminates unneeded allocation of disk space. JCL allocation is fixed; DFSORT cannot adjust it. Disk space might be wasted. v As the amount of Hiperspace available to the application varies from run to run, DFSORT can automatically adjust the amount of space it dynamically allocates to complement the amount of Hiperspace. This eliminates unneeded allocation of disk space. JCL allocation is fixed; DFSORT cannot adjust it, even if all sorting can be done in Hiperspace. Disk space might be wasted. Dynamic allocation has one drawback: for certain applications, as described in File Size and Dynamic Allocation on page 734, you might need to give DFSORT a reasonable estimate of the input file size. Later, if the input file size for the application increases significantly, you must update the file size estimate accordingly. However, JCL allocation has a similar drawback, except that it applies to all applications. Unless you overallocate the work data sets initially and waste space, you have to update the JCL allocation when the input file size increases significantly for any application to avoid out-of-space abends. If you can allocate enough work data set space with JCL to guarantee your applications will never exceed the space allocated, you do not need dynamic allocation. However, since efficient use of disk space is usually desirable, dynamic allocation is recommended over JCL allocation.
Appendix A. Using Work Space

733

Allocation of Work Data Sets

For both dynamic allocation and JCL allocation: v The amount of work space actually used will often be less than the amount allocated. DFSORT tries to minimize dynamic over-allocation while making certain that the application will not fail due to lack of space. With JCL allocation, you could minimize the amount of allocated space manually, but this might require changes to JCL allocation as the characteristics of the application change over time. v Limiting the virtual storage available to DFSORT can increase the amount of work space required. With a reasonable amount of storage, 4MB for example, DFSORT can sort using a reasonable amount of work space. If storage is limited, more work space might be required. If storage is drastically limited (for example, to 200KB), significantly more work space might be required.

Dynamic Allocation of Work Data Sets

| Installation options are available to request automatic dynamic allocation of work data sets and to supply defaults for the device type and number of devices. For certain applications, it is very important to specify a reasonable estimate of the input file size when using dynamic allocation.

Automatic Dynamic Allocation

Your system programmer has set the DYNAUTO installation option to control whether dynamic allocation is used automatically, or only when requested by the DYNALLOC run-time option. DYNAUTO also controls whether dynamic allocation or JCL allocation takes precedence when JCL work data sets are specified. If your system programmer selected DYNAUTO=IGNWKDD, dynamic allocation takes precedence over JCL allocation (JCL work data sets are actually deallocated). If you want the opposite precedence for selected applications, use the run-time option USEWKDD. If your system programmer selected DYNAUTO=YES, JCL allocation takes precedence over dynamic allocation. If you want the opposite precedence, you must remove the JCL allocation statements. If your system programmer selected DYNAUTO=NO, dynamic allocation of work data sets is not used unless you specify the DYNALLOC run-time option. JCL allocation takes precedence over dynamic allocation.

Device Defaults
When the device type, or the number of devices for dynamic allocation, is not explicitly specified, DFSORT obtains the missing information from the DYNALOC installation option information supplied by your system programmer.

File Size and Dynamic Allocation

DFSORT bases the amount of work space it dynamically allocates on the number of bytes to be sortedthe input file size. Generally, DFSORT can automatically make an accurate determination of the file size by determining the number of input records. However, DFSORT cannot always determine the input file size accurately in the following cases: v An E15 user exit routine supplies all input records (an input data set is not present). DFSORT cannot automatically determine the number of records to be inserted.

734

z/OS V1R10.0 DFSORT Application Programming Guide

Allocation of Work Data Sets

v An input data set is present, along with an E15 user exit routine. DFSORT can automatically determine the number of records in the input data set, but cannot automatically determine the number of records to be inserted or deleted. v A spool (DD *) or pipe data set is used as input. v The input consists of small data sets on tape that are not managed by DFSMSrmm or a tape management system that uses ICETPEX. When the tape data sets are not managed, DFSORT cannot know how much of the tapes are used, so it determines the file size assuming full volumes at the maximum regular density for the drives. v The Improved Data Recording Capability (IDRC) feature is used for the input device and the tape data sets are not managed by DFSMSrmm or a tape management system that uses ICETPEX. v Input data sets are members of partitioned data sets. DFSORT cannot determine the size of a member in a partitioned data set. Therefore, when input data sets are partitioned, DFSORT uses the size of the entire data set as the input file size. This is usually an over-estimation, which leads to over-allocation of work space. In the above circumstances, if the number of records is not supplied by the FILSZ or SIZE option, you will receive message ICE118I. If dynamic allocation of work data sets is used, DFSORT allocates the primary space according to the DYNSPC value in effect. This can result in underallocation or overallocation, possibly leading to wasted space or an out-of-space condition, respectively. If this happens, you should specify FILSZ=En with a reasonably accurate estimate of the number of records to be sorted. If you cannot specify FILSZ=En, you should use DYNSPC=n to adjust the primary space for dynamically allocated work data sets, as appropriate. Note: FILSZ=E0 is ignored. For variable-length records, DFSORT uses one-half of the maximum record length (LRECL) in conjunction with the number of records to determine the input file size, unless you specify AVGRLEN=n. If your actual average record length is significantly different from one-half of the maximum record length, specifying AVGRLEN=n can prevent DFSORT from overallocating or underallocating dynamic work space. See OPTION Control Statement on page 167 for more information about the AVGRLEN, DYNSPC, FILSZ, and SIZE options.

Dynamic Over-Allocation of Work Space

DFSORT can dynamically over-allocate the work space even when you specify the number of records under the following circumstances: v When you delete a significant number of records using: An INCLUDE or OMIT statement, or the SKIPREC option. Use of these statements and options does not force DFSORT to use a SIZE=En or FILSZ=En specification. DFSORT ignores the En value unless it cannot compute the input file size. One or more partitioned data set members as input. DFSORT uses the size of the entire partitioned data set rather than the size of the member in its calculations. DFSORT ignores any SIZE=En or FILSZ=En value unless it cannot determine the input file size itself. You can avoid over-allocation in these cases by specifying SIZE=Un or FILSZ=Un.
Appendix A. Using Work Space

735

Allocation of Work Data Sets

v When the average record length of variable-length records is substantially shorter than one-half of the maximum record length. If DFSORT uses your exact or estimated number of records, it uses one-half of the maximum record length to determine the file size. You can avoid over-allocation in this case by specifying AVGRLEN=n. Dynamic over-allocation of work space can occur when you do not specify the number of records (for example, with small input data sets on tape), or even when you do (for example, when a significant number of records is deleted). In these cases, you might prefer to use JCL allocation of work data sets to control the amount of space allocated. However, there are drawbacks to doing so, as previously explained. If DYNAUTO=IGNWKDD is used, remember to specify run-time option USEWKDD when you want to use JCL allocation of work data sets.

JCL Allocation of Work Data Sets

The amount of required work space is dependent on many factors such as virtual storage and type of devices used, but is especially sensitive to the file size of the input data set. Because of the number of variables involved, an exact formula cannot be given for calculating the needed work space. However, the following guidelines usually hold true: v For fixed length record (FLR) sort applications, 1.5 to 2 times the input file size is usually adequate. v For variable-length record (VLR) sort applications, 1.5 to 2.5 times the input file size is usually adequate. These guidelines assume that a reasonable amount of storage (at least 1M) is available to DFSORT. Limiting the available amount of storage can increase the amount of needed work space. DFSORT can often run with less than the amount of work space indicated by the above guidelines. To get the best performance using JCL allocation of work data sets: v Use devices without much activity on them. v Use high-speed disk devices such as IBMs TotalStorage DS8000 subsystems for work data sets, and avoid using tape or virtual (VIO) for work data sets. v Allocate space in cylinders. v Specify contiguous space for each work data set, and make sure there is enough primary space so that secondary space is not needed. v Allocate two or more work data sets. v Use multiple channel paths to the devices. v Use different volumes and separate channel paths for the work data sets and the input/output data sets. The following table shows the work data set space needed with 4M of storage for applications with various characteristics when Hipersorting, dataspace sorting, and memory object sorting are not used (HIPRMAX=0, DSPSIZE=0 and MOSIZE=0).

| |

| |

736

z/OS V1R10.0 DFSORT Application Programming Guide

Allocation of Work Data Sets

Table 76. Work Space Requirements for Various Input Characteristics Input Data set Characteristics Filesize (MB) FLR/VLR 4 4 20 20 20 40 40 40 150 4 40 40 150 150 FLR FLR FLR FLR FLR FLR FLR FLR FLR VLR VLR VLR VLR VLR Max LRECL 80 160 80 160 1000 80 160 1000 160 300 300 6000 300 6000 BLKSIZE 27920 27840 27920 27840 27000 27920 27840 27000 27840 27998 27998 27998 27998 27998 Cylinders (3390) Input Data Set 6 6 26 26 26 51 51 52 189 6 51 55 188 203 Work Data Set 6 6 36 36 36 56 56 56 198 9 63 59 200 200

Disk Capacity Considerations

You can specify a mixture of disk devices for a given sort application. Any IBM disk device supported by your operating system can be used for work data sets. | | For best performance, use high-speed devices such as IBMs TotalStorage DS8000 storage subsystems for work data sets. System performance is improved if work data sets are specified in cylinders, rather than tracks or blocks. Storage on temporary work data sets will be readjusted to cylinders if possible. The number of tracks per cylinder for disk devices is shown in Table 77.
Table 77. Number of Tracks per Cylinder for Disk Devices Device 3380 3390 9345 Tracks per Cylinder 15 15 15 Maximum Bytes used per Track 47476 56664 46456

If WRKSEC is in effect and the work data set is not allocated to VIO, DFSORT allocates secondary extents as required, even if not requested in the JCL.

Exceeding Disk Work Space Capacity

If during sorting, the allocation of secondary space on one of the work data sets fails, the system issues a B37 informational message. DFSORT can recover by allocating space on one of the other work data sets, if one is available.

Appendix A. Using Work Space

737

Disk Capacity Considerations

DFSORT normally allocates secondary extents for work data sets, even if not requested in the JCL. This reduces the probability of exceeding work space capacity. If the disk work space is not sufficient to perform the sort, DFSORT issues a message and terminates.

Tape Capacity Considerations

Any IBM tape device supported by your operating system can be used for work space. However, using tape devices for work data sets rather than disk causes significant performance degradation and should, therefore, be avoided. Three different tape work data set techniques are available to DFSORT: Balanced, Polyphase, and Oscillating. For information on how to calculate their requirements, see Table 78. Note: The value you obtain for min is literally a minimum value; if, for example, your input uses a more efficient blocking factor than DFSORT or is spanned, you need more work space. Space requirements are also summarized in Table 78. DFSORT selects the most appropriate tape technique using these criteria.
Table 78. Work Space Requirements of the Various Tape Techniques Tape Technique Balanced tape (BALN) Polyphase tape (POLY) Oscillating tape (OSCL) Maximum Input 15 volumes Work Space Areas Required Max. No. of Work Areas Comments Used if more than three work storage tapes are provided and file size is not given. Used if three work storage tapes are provided. File size must be given. The tape drive containing SORTIN cannot be used as a work unit.

Min=2(V+1)* tape units 32 volumes

1 volume 15 volumes

Min=3 tape units Min=V+2* or 4 tape units, whichever is greater

17 volumes 17 volumes

Note: V = Number of input volumes. Number of input volumes of blocking equals work space blocking.

Exceeding Tape Work Space Capacity

At the beginning of a sort using tape work data sets, DFSORT estimates the maximum sort capacity (Nmax) and issues message ICE038I. See the explanation of this message for details. The value for Nmax printed in message ICE038I is an average value rounded down to the nearest thousand. This value assumes random input. If you have a reversed sequenced file and tape work space, sort capacity may be exceeded at a lower value because of the higher number of partly empty, end-of-string blocks. For magnetic tape, a tape length of 2400 feet is assumed in calculating Nmax. For tapes of other lengths, the figure is not correct. When tapes with mixed density are used, the smallest density is used in the calculation.

738

z/OS V1R10.0 DFSORT Application Programming Guide

Disk Capacity Considerations

If you specify an actual data set size, and that size is larger than the maximum capacity estimated by the program (Nmax), the program terminates before beginning to sort. If you specify an estimated data set size, or none at all, and the number of records reaches the maximum (Nmax), the program gives control to your routine at user exit E16, if you have written and included one. This routine can direct the program to take one of the following actions: v Continue sorting the entire input data set with available work space. If the estimate of the input data set size was high, enough work space may remain to complete the application. v Continue sorting with only part of the input data set; the remainder could be sorted later and the two results merged to complete the application. v Terminate the program without any further processing. If you do not include an E16 routine, DFSORT continues to process records for as long as possible. If the work space is sufficient to contain all the records in the input data set, DFSORT completes normally; when work space is not sufficient, DFSORT issues a message and terminates. The program generates a separate message for each of the three possible error conditions. They are: 1. ICE041AN GT NMAX: Generated before sorting begins when the exact file size is greater than Nmax. 2. ICE046ASORT CAPACITY EXCEEDED: Generated when the sort has used all available work space. 3. ICE048INMAX EXCEEDED: Generated when the sort has exceeded Nmax and has transferred control to a user-written E16 routine for further action. The test for message ICE041A is made with the maximum possible calculated value, that is, DFSORT is sure it will fail. In case of doubt, the message is not issued.

Appendix A. Using Work Space

739

740

z/OS V1R10.0 DFSORT Application Programming Guide

Appendix B. Specification/Override of DFSORT Options

Installation Defaults on page 16 discusses DFSORTs installation options and environments, and shows you how to use ICETOOLs DEFAULTS operator to list the installation defaults selected at your site. Listed below are the places in DFSORT where you can specify various options that will override the IBM-supplied defaults. The sources for the options are listed in override order; that is, any option specified in a higher place in the list overrides one specified in a lower place. Directly Invoked DFSORT v DFSPARM data set PARM options DEBUG and OPTION control statements Other control statements. v EXEC statement PARM options v SYSIN data set DEBUG and OPTION control statements Other control statements. v Installation options set with PARMLIB ICEPRMxx members (JCL, TSO or TDx). v Installation options set with ICEMAC (JCL, TSO or TDx). Program Invoked DFSORT v DFSPARM data set PARM options DEBUG and OPTION control statements Other control statements. v SORTCNTL data set DEBUG and OPTION control statements Other control statements. v Parameter list DEBUG and OPTION control statements Other control statements. v Installation options set with PARMLIB ICEPRMxx members (INV, TSOINV or TDx). v Installation options set with ICEMAC (INV, TSO or TDx). Notes: 1. DFSORTs EXEC PARMs can be specified in the EXEC statement when DFSORT is directly invoked. For example:
//S1 EXEC PGM=ICEMAN,PARM=EQUALS,ABEND

| |

| | |

DFSORTs EXEC PARMs are ignored if DFSORT is invoked from a program. 2. DFSPARM PARMs can be specifed in the DFSPARM data set when DFSORT is directly invoked or invoked from a program. For example:
//DFSPARM DD * EQUAL,ABEND

3. DFSORTs control statements can be specified in the DFSPARM or SYSIN data set when DFSORT is directly invoked. At least one blank must precede the operation field (SORT, MERGE, INCLUDE, and so on). For example:

Copyright IBM Corp. 1973, 2006

741

Specification/Override Of Options
//SYSIN DD * SORT FIELDS=(5,4,CH,A) OPTION EQUALS DEBUG ABEND

4. DFSORTs control statements can be specified in the DFSPARM or SORTCNTL data set, or in the parameter list, when DFSORT is invoked from a program. At least one blank must precede the operation field (SORT, MERGE, INCLUDE, and so on). For example:
//SORTCNTL DD * SORT FIELDS=(5,4,CH,A) OPTION EQUALS DEBUG ABEND

5. For the DEBUG and OPTION statements, override is at the option level. For example, with:
//DFSPARM DD * OPTION EQUALS //SYSIN DD * OPTION NOEQUALS,SKIPREC=50

EQUALS from DFSPARM overrides NOEQUALS from SYSIN, but SKIPREC=50 from SYSIN in not affected by the OPTION statement in DFSPARM, so both EQUALS and SKIPREC=50 will be used. For control statements other than DEBUG and OPTION, override is at the statement level. For example, with:
//DFSPARM DD * MODS E15=(CHECK,4096,EXIT) //SYSIN DD * MODS E35=(MOVE,2048,EXITX)

the MODS statement in DFSPARM completely overrides the MODS statement in SYSIN, so the E15 exit will be used, but the E35 exit will not. 6. An EFS program or an installation initialization exit (ICEIEXIT) routine can also be used to override options. ICEIEXIT changes override any corresponding changes made by an EFS program. 7. For OUTFIL statements, override is at the ddname level. See OUTFIL Statements Notes on page 340 for details.

Main Features of Sources of DFSORT Options

| | | There are five sources for run-time options that allow you to override your sites installation defaults. To help you decide which source is most efficient for you for a given situation, compare their main features using the following lists:

DFSPARM Data Set

v Use with direct or program invocation. v Overrides all other sources. v Accepts all DFSORT program control statements, and all EXEC PARM options, including those OPTION statement parameters ignored by SYSIN and SORTCNTL. v Permits comment statements, blank statements, and remarks.

EXEC Statement PARM Options

v Use with direct invocation only.

742

z/OS V1R10.0 DFSORT Application Programming Guide

Specification/Override Of Options
v Accepts all EXEC PARM options, including those equivalent to the OPTION statement parameters ignored by SYSIN and SORTCNTL.

SORTCNTL Data Set

v Use with program invocation only. v Accepts all DFSORT program control statements. v Ignores these OPTION statement parameters: EFS, LIST, NOLIST, LISTX, NOLISTX, LOCALE, MSGPRT, MSGDDN, SMF, SORTDD, SORTIN, SORTOUT, and USEWKDD. v Permits comment statements, blank statements, and remarks. v Using multiple parameter lists to rename the SORTCNTL data set permits different control statements to be used for a program that invokes DFSORT more than once.

SYSIN Data Set

v Use with direct invocation only. v Accepts all DFSORT program control statements. v Ignores these OPTION statement parameters: EFS, LIST, NOLIST, LISTX, NOLISTX, LOCALE, MSGPRT, MSGDDN, SMF, SORTDD, SORTIN, SORTOUT, and USEWKDD. v Permits comment statements, blank statements, and remarks. v Can contain user exit routines in object deck format for link-editing.

Parameter Lists
v Use with program invocation only. v Extended parameter list accepts all DFSORT program control statements, including those OPTION statement parameters ignored by SYSIN and SORTCNTL. v 24-bit parameter list accepts a subset of DFSORT program control statements. v Using multiple parameter lists to rename the SORTCNTL data set permits different control statements to be used for a program that invokes DFSORT more than once. v Can be used to pass the addresses of any user exits that your program has placed in main storage. Note: The extended parameter list can perform a superset of the functions in the 24-bit parameter list.

Override Tables
The following tables show the possible sources of specification and order of override for individual options. v The order of override between sources of specification is from left to right. A specification overrides all specifications to its right. v The order of override within a source is from top to bottom. A specification overrides all specifications below it. v For DFSPARM, keyword (for example, BSAM) indicates a PARM option, whereas operation keyword (for example, DEBUG BSAM) indicates a control statement option. v The Function columns indicate which functions (S=sort, M=merge, or C=copy) can use the option.
Appendix B. Specification/Override of DFSORT Options

743

Specification/Override Of Options
v Although alias names are available for many of the options, they are not shown here.

Directly Invoked DFSORT

Table 79 on page 745 shows where each sort, merge, or copy option may be specified when DFSORT is directly invoked (that is, not invoked by programs). DFSPARM: PARM options selectively override corresponding options in any other source. DEBUG and OPTION control statement options selectively override corresponding options in EXEC PARM and SYSIN. Control statements other than DEBUG and OPTION completely override corresponding control statements in SYSIN. EXEC PARM options selectively override options in SYSIN. SORT and MERGE are considered to be corresponding control statements. INCLUDE and OMIT are considered to be corresponding control statements.

744

z/OS V1R10.0 DFSORT Application Programming Guide

|
Specified with EXEC PARM Specified with SYSIN NO DEBUG ABSTP ALTSEQ CODE OPTION ARESALL DEBUG NOASSIST OPTION AVGRLEN DEBUG BSAM DEBUG CFW|NOCFW OPTION CHALT|NOCHALT OPTION CHECK|NOCHECK OPTION CINV|NOCINV OPTION COBEXIT INCLUDE|OMIT COND|FORMAT OPTION COPY SORT|MERGE FIELDS DEBUG CTRx NO CFW CHALT CHECK CINV COBEXIT NO NO NO Time-of-day for activation NO DIAGSIM NO NO NO ARESALL ALTSEQ NO Abnormal stop Alternate sequence ABCODE ABEND code NO NO NO ARESALL NO AVGRLEN BSAM NO NO NO CINV|NOCINV COBEXIT NO NO NO NO Installation (JCL, TSO or TDx) Description of Option Function S,M,C S,M,C S,M System storage S,M,C above 16MB virtual Bypass Sorting Instructions Average record length Force BSAM Cache fast write CH field sequence S S S,M,C S S,M Record count check S,M,C Control interval access COBOL library Include|Omit fields Copy records ABEND record count Simulate SORTDIAG DD Statement Simulate SORTDIAG DD Statement OPTION DSA DSA Dynamic storage adjustment limit S,M,C S,M,C S,M,C C S,M S,M,C NO S,M,C

Table 79. Directly Invoked DFSORT Option Specification/Override. Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

NO

DEBUG ABSTP

ALTSEQ CODE

ARESALL OPTION ARESALL

DEBUG NOASSIST

AVGRLEN OPTION AVGRLEN

BSAM DEBUG BSAM

DEBUG CFW|NOCFW

OPTION CHALT|NOCHALT

OPTION CHECK|NOCHECK

CINV|NOCINV OPTION CINV|NOCINV

COBEXIT OPTION COBEXIT

INCLUDE|OMIT COND|FORMAT

OPTION COPY SORT|MERGE FIELDS

DEBUG CTRx

NO

Appendix B. Specification/Override of DFSORT Options DSA

NO

Specification/Override Of Options

DSA OPTION DSA

745

|
Specified with EXEC PARM Specified with SYSIN OPTION DSPSIZE OPTION DYNALLOC SORT DYNALLOC OPTION DYNALLOC SORT DYNALLOC OPTION DYNSPC NO2 EFS ENABLE EQUALS NO OPTION EQUALS|NOEQUALS SORT|MERGE EQUALS|NOEQUALS DEBUG EQUCOUNT DEBUG ABEND|NOABEND DEBUG ESTAE|NOESTAE OPTION EXITCK NO DYNSPC DYNAUTO DYNALOC1 Dynamic SORTWKs S DSPSIZE Dataspace sorting S DSPSIZE DYNALLOC Installation (JCL, TSO or TDx) Description of Option Function DYNALLOC Automatic dynamic S allocation Dynamic allocation default space EFS program specified S S,M,C Enable Time-of-Day S,M,C modules Equal record order S,M

746
DYNSPC EFS NO EQUALS|NOEQUALS NO ABEND|NOABEND NO NO NO NO ERET ESTAE EXITCK EXPMAX Equal key count message Error action ESTAE routine E15/E35 return code checking S S,M,C S,M,C S,M,C Available expanded S storage limit for all DFSORT Hiperspaces EXPOLD Old expanded storage limit for all DFSORT Hiperspaces S NO NO

Table 79. Directly Invoked DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

DSPSIZE OPTION DSPSIZE

DYNALLOC OPTION DYNALLOC SORT DYNALLOC

Specification/Override Of Options

DYNALLOC OPTION DYNALLOC|USEWKDD SORT DYNALLOC

DYNSPC OPTION DYNSPC

EFS OPTION EFS

z/OS V1R10.0 DFSORT Application Programming Guide

NO

EQUALS|NOEQUALS OPTION EQUALS|NOEQUALS SORT|MERGE EQUALS|NOEQUALS

DEBUG EQUCOUNT

ABEND|NOABEND DEBUG ABEND|NOABEND

DEBUG ESTAE|NOESTAE

OPTION EXITCK

NO

NO

|
Specified with EXEC PARM Specified with SYSIN NO EXPRES Available expanded S storage reserved for non-Hipersorting use User Exit Exx (xx=11,15-19, 31,35,37-39, and 61) INREC reformatting OUTREC reformatting Control fields Sum fields NO FSZEST Merge input files File size S,M,C3 NO Installation (JCL, TSO or TDx) Description of Option Function E15=COB E35=COB MODS Exx|HILEVEL=YES NO NO NO NO NO NO FILSZ OPTION FILSZ|SIZE SORT|MERGE FILSZ|SIZE OPTION HIPRMAX NO NO OPTION CKPT SORT CKPT4 NO
4

Table 79. Directly Invoked DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

NO

E15=COB PARM E35=COB MODS Exx|HILEVEL=YES INREC parameters OUTREC parameters SORT|MERGE FIELDS|FORMAT SUM FIELDS/FORMAT MERGE FILES NO NO NO NO

INREC parameters

S,M,C S,M,C S,M S,M M S,M

OUTREC parameters

SORT|MERGE FIELDS|FORMAT

SUM FIELDS/FORMAT

MERGE FILES

FILSZ OPTION FILSZ|SIZE SORT|MERGE FILSZ|SIZE HIPRMAX NO NO NO NO

HIPRMAX OPTION HIPRMAX

HIPRMAX IDRCPCT IEXIT IGNCKPT IOMAXBF

Hipersorting IDRC compaction ICEIEXIT Checkpoints Maximum SORTIN/ SORTOUT data set buffer space

S S S,M,C S S,M,C

NO

NO

OPTION CKPT SORT CKPT4

NO

RECORD LENGTH LIST|NOLIST

NO

RECORD LENGTH NO
2

NO LIST

Record lengths Print DFSORT control statements5

S,M,C S,M,C

Appendix B. Specification/Override of DFSORT Options

Specification/Override Of Options

LIST|NOLIST OPTION LIST|NOLIST

747

|
Specified with EXEC PARM Specified with SYSIN NO2 LISTX LISTX|NOLISTX Print control S,M,C statements returned by an EFS program5 Locale processing Maximum storage below 16MB virtual6 Minimum storage Memory object sorting Alternate message data set Write messages on master console MSGPRT NO NOMSGDD Print messages Bypass Blockset Action when message data set missing NULLOUT Action when no records for SORTOUT ODMAXBF Maximum OUTFIL data set buffer space NO OPTION NOOUTREL OPTION NOOUTSEC OUTREL OUTSEC OUTFIL processing S,M,C S,M,C Installation (JCL, TSO or TDx) Description of Option Function LOCALE NO NO MAXLIM NO2 LOCALE

748
NO MOSIZE MSGDDN NO MSGPRT NO NO NO OPTION NOBLKSET NO2 NO NO2 MSGDDN MSGCON OPTION MOSIZE MOSIZE NO MINLIM S,M,C S S,M,C S,M,C S,M,C S,M S,M,C NULLOUT OPTION NULLOUT S,M,C ODMAXBF OPTION ODMAXBF S,M,C OUTFIL9 OUTREL|NOOUTREL NO OUTFIL9 S,M,C Release output data S,M,C set space Output data set secondary allocation S,M,C

Table 79. Directly Invoked DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

LISTX|NOLISTX OPTION LISTX|NOLISTX

LOCALE OPTION LOCALE

Specification/Override Of Options

NO

NO

MOSIZE OPTION MOSIZE

z/OS V1R10.0 DFSORT Application Programming Guide

MSGDDN OPTION MSGDDN

NO

MSGPRT OPTION MSGPRT

OPTION NOBLKSET

NO

NULLOUT OPTION NULLOUT

ODMAXBF OPTION ODMAXBF

OUTFIL9

OUTREL|NOOUTREL OPTION NOOUTREL

OPTION NOOUTSEC

|
Specified with EXEC PARM Specified with SYSIN NO OPTION OVFLO OPTION PAD NO OPTION RESALL OPTION RESET|NORESET OPTION SDB SDB RESET RESALL PARMDDN PAD OVFLO Summary fields overflow action DFSORT LRECL padding action Alternate ddname for DFSPARM System reserved storage6 NEW or MOD VSAM output Systemdetermined output data set block size SDBMSG Systemdetermined block size for message and list data sets SIZE NO Storage Skip records OVERRGN Storage over REGION NO OVFLO PAD NO RESALL RESET|NORESET SDB Installation (JCL, TSO or TDx) Description of Option Function S,M,C S,M S,M,C S,M,C S,M,C S,M,C S,M,C NO NO S,M,C SIZE SKIPREC OPTION SKIPREC SORT SKIPREC NO OPTION SOLRF|NOSOLRF NO2 NO2 NO OPTION MAINSIZE S,M,C S,C NO SOLRF|NOSOLRF NO NO NO SMF SOLRF NO NO SORTLIB SMF records SORTOUT length ddname prefix Alternate SORTIN ddname Conventional modules library S,M,C S,M,C S,M,C S,C S,M

Table 79. Directly Invoked DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

NO

OVFLO OPTION OVFLO

PAD OPTION PAD

NO

RESALL OPTION RESALL

RESET|NORESET OPTION RESET|NORESET

SDB OPTION SDB

NO

SIZE OPTION MAINSIZE

SKIPREC OPTION SKIPREC SORT SKIPREC

OPTION SMF

SOLRF|NOSOLRF OPTION SOLRF|NOSOLRF

OPTION SORTDD

Appendix B. Specification/Override of DFSORT Options

OPTION SORTIN

Specification/Override Of Options

NO

749

|
Specified with EXEC PARM Specified with SYSIN NO2 NO SPANINC Incomplete spanned records action Input limit Alternate SORTOUT ddname OPTION SPANINC NO SPANINC S,M,C S,M,C Installation (JCL, TSO or TDx) Description of Option Function STOPAFT OPTION STOPAFT SORT STOPAFT NO OPTION SZERO|NOSZERO NO NO TEXIT TMAXLIM SZERO SVC NO S,C

750
NO SZERO|NOSZERO NO NO DFSORT SVC Information S,M,C Signed or unsigned S,M,C zero ICETEXIT Maximum storage above and below 16MB virtual6 TRUNC NO VERIFY VIO VLLONG VLSCMP VLSHRT DFSORT LRECL truncation action Record format Sequence check SORTWK virtual I/O Truncate long output records Pad short compare fields Action for short control or compare fields NO OPTION VSAMEMT|NVSAMEMT VSAMBSP VSAMEMT S,M,C S,M,C TRUNC NO VERIFY|NOVERIFY NO VLLONG|NOVLLONG VLSCMP|NOVLSCMP VLSHRT|NOVLSHRT NO OPTION VLLONG|NOVLLONG OPTION VLSCMP|NOVLSCMP OPTION VLSHRT|NOVLSHRT OPTION VERIFY|NOVERIFY RECORD TYPE OPTION TRUNC S,M,C S,M,C S,M S S,M,C S,M,C S,M,C NO VSAMEMT|NVSAMEMT VSAM buffer space S Emty VSAM input S,M,C

Table 79. Directly Invoked DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

OPTION SORTOUT8

SPANINC OPTION SPANINC

STOPAFT OPTION STOPAFT SORT STOPAFT

Specification/Override Of Options

NO

SZERO|NOSZERO OPTION SZERO|NOSZERO

z/OS V1R10.0 DFSORT Application Programming Guide

NO

NO

TRUNC OPTION TRUNC

RECORD TYPE

VERIFY|NOVERIFY OPTION VERIFY|NOVERIFY

NO

VLLONG|NOVLLONG OPTION VLLONG|NOVLLONG

VLSCMP|NOVLSCMP OPTION VLSCMP|NOVLSCMP

VLSHRT|NOVLSHRT OPTION VLSHRT|NOVLSHRT

NO

VSAMEMT|NVSAMEMT OPTION VSAMEMT|NVSAMEMT

|
Specified with EXEC PARM Specified with SYSIN OPTION VSAMIO|NOVSAMIO OPTION WRKREL|NOWRKREL OPTION WRKSEC|NOWRKSEC WRKSEC SORTWK secondary allocation Set century window ZD SUM results WRKREL Release SORTWK space VSAMIO Same VSAM input and output S S S VSAMIO|NOVSAMIO WRKREL|NOWRKREL WRKSEC|NOWRKSEC Installation (JCL, TSO or TDx) Description of Option Function Y2PAST OPTION Y2PAST SORT|MERGE Y2PAST OPTION ZDPRINT|NZDPRINT ZDPRINT Y2PAST S,M,C ZDPRINT|NZDPRINT S,M

Table 79. Directly Invoked DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

VSAMIO|NOVSAMIO OPTION VSAMIO|NOVSAMIO

WRKREL|NOWRKREL OPTION WRKREL|NOWRKREL

WRKSEC|NOWRKSEC OPTION WRKSEC|NOWRKSEC

Y2PAST OPTION Y2PAST SORT|MERGE Y2PAST

ZDPRINT|NZDPRINT OPTION ZDPRINT|NZDPRINT

Appendix B. Specification/Override of DFSORT Options

Specification/Override Of Options

751

Specification/Override Of Options

Notes to Directly Invoked DFSORT Table

1 2 3

Does not request dynamic allocation; only supplies defaults. Not used in SYSIN. All functions do not apply to all exits. See Table 51 on page 417 and Table 52 on page 417 for applicable exits. Not used if Blockset is selected and IGNCKPT=YES was specified. Not used if MSGPRT=NONE is in effect; in this case control statements are not printed. Not used unless MAINSIZE=MAX is in effect. Overrides SORTDD for the SORT input ddname. Overrides SORTDD for the SORT output ddname. Override is at the ddname level.

4 5

6 7 8 9

Program Invoked DFSORT with the Extended Parameter List

Table 80 on page 753 shows where each sort, merge, or copy option may be specified when DFSORT is program invoked and an extended parameter list is passed to it. DFSPARM: PARM options selectively override corresponding options in any other source. DEBUG and OPTION control statement options selectively override corresponding options in SORTCNTL and the Parameter List. Control statements other than DEBUG and OPTION completely override corresponding control statements in SORTCNTL and the Parameter List. SORTCNTL: DEBUG and OPTION control statement options selectively override corresponding options in the Parameter List. Control statements other than DEBUG and OPTION completely override corresponding control statements in the Parameter List. SORT and MERGE are considered to be corresponding control statements. INCLUDE and OMIT are considered to be corresponding control statements.

752

z/OS V1R10.0 DFSORT Application Programming Guide

|
Specified with SORTCNTL NO DEBUG ABSTP ALTSEQ CODE OPTION ARESALL OPTION ARESINV OPTION ARESINV ARESINV OPTION ARESALL ARESALL Offset 16 entry ALTSEQ CODE ALTSEQ Alternate sequence System storage above 16MB virtual Storage above 16MB virtual for invoking program Bypass Sorting Instructions Average record length Force BSAM Cache fast write CHALT CHECK CINV COBEXIT CH field sequence Record count check Control interval access COBOL library Include|Omit fields NO NO NO NO OPTION DSA day DIAGSIM DSA Copy records ABEND record count Time-of-day for activation Simulate SORTDIAG DD statement Dynamic storage adjustment limit DEBUG ABSTP NO Abnormal stop NO ABCODE ABEND code Specified with Extended Parameter Installation (INV, List TSOINV or TDx) Description of Option Function S,M,C S,M,C S,M S,M,C S,M,C DEBUG NOASSIST OPTION AVGRLEN DEBUG BSAM DEBUG CFW|NOCFW OPTION CHALT|NOCHALT OPTION CHECK|NOCHECK OPTION CINV|NOCINV OPTION COBEXIT OPTION COBEXIT OPTION CINV|NOCINV OPTION CHECK|NOCHECK OPTION CHALT|NOCHALT DEBUG CFW|NOCFW CFW DEBUG BSAM NO OPTION AVGRLEN NO DEBUG NOASSIST NO S S S,M,C S S,M S,M,C S,M,C S,M,C S,M,C C S,M S,M,C S,M,C S OPTION COPY SORT|MERGE FIELDS2 DEBUG CTRx NO NO OPTION DSA OPTION COPY SORT|MERGE FIELDS DEBUG CTRx

Table 80. Extended Parameter List DFSORT Option Specification/Override. Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

NO

DEBUG ABSTP

ALTSEQ CODE

ARESALL OPTION ARESALL

OPTION ARESINV

DEBUG NOASSIST

AVGRLEN OPTION AVGRLEN

BSAM DEBUG BSAM

DEBUG CFW|NOCFW

OPTION CHALT|NOCHALT

OPTION CHECK|NOCHECK

CINV|NOCINV OPTION CINV|NOCINV

COBEXIT OPTION COBEXIT

INCLUDE|OMIT COND|FORMAT INCLUDE|OMIT COND|FORMAT INCLUDE|OMIT COND|FORMAT NO

OPTION COPY SORT|MERGE FIELDS

DEBUG CTRx

NO

Appendix B. Specification/Override of DFSORT Options

NO

Specification/Override Of Options

DSA OPTION DSA

753

|
Specified with SORTCNTL OPTION DSPSIZE OPTION DYNALLOC SORT DYNALLOC2 OPTION DYNALLOC SORT DYNALLOC OPTION DYNALLOC| USEWKDD SORT DYNALLOC OPTION DYNSPC OPTION EFS NO OPTION EQUALS|NOEQUALS SORT|MERGE EQUALS|NOEQUALS DEBUG EQUCOUNT DEBUG ABEND|NOABEND DEBUG ESTAE|NOESTAE OPTION EXITCK NO NO ERET ESTAE EXITCK EXPMAX EQUALS ENABLE EFS DYNSPC DYNAUTO Automatic DYNALLOC OPTION DYNALLOC SORT DYNALLOC DYNALOC1 Dynamic SORTWKs OPTION DSPSIZE DSPSIZE Dataspace sorting S S Specified with Extended Parameter Installation (INV, List TSOINV or TDx) Description of Option Function

754
S OPTION DYNSPC NO3 NO OPTION EQUALS|NOEQUALS SORT|MERGE EQUALS|NOEQUALS2 DEBUG EQUCOUNT DEBUG ABEND|NOABEND DEBUG ESTAE|NOESTAE OPTION EXITCK NO Dynamic allocation default space EFS program specified Enable Time-of-Day modules Equal record order S S,M,C S,M,C S,M Equal key count message Error action ESTAE routine E15/E35 return code checking Available expanded storage limit for all DFSORT Hiperspaces NO EXPOLD Old expanded storage limit for all DFSORT Hiperspaces NO EXPRES Available expanded storage reserved for non-Hipersorting use S S,M,C S,M,C S,M,C S NO S NO S

Table 80. Extended Parameter List DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

DSPSIZE OPTION DSPSIZE

DYNALLOC OPTION DYNALLOC SORT DYNALLOC

Specification/Override Of Options

DYNALLOC OPTION DYNALLOC| USEWKDD SORT DYNALLOC

DYNSPC OPTION DYNSPC

EFS OPTION EFS

z/OS V1R10.0 DFSORT Application Programming Guide

NO

EQUALS|NOEQUALS OPTION EQUALS|NOEQUALS SORT|MERGE EQUALS|NOEQUALS

DEBUG EQUCOUNT

ABEND|NOABEND DEBUG ABEND|NOABEND

DEBUG ESTAE|NOESTAE

OPTION EXITCK

NO

NO

NO

|
Specified with SORTCNTL MODS E154|HILEVEL=YES NO NO NO
4

Table 80. Extended Parameter List DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.
Specified with Extended Parameter Installation (INV, List TSOINV or TDx) Description of Option Exit E15 Exit E18 Exit E32 Exit E35 Exit E39 User Exit Exx (xx=11,16,17,19, 31,37,38, and 61) INREC reformatting OUTREC reformatting Control fields NO NO FSZEST Sum fields Merge input files File size Offset 4 entry4 MODS E154|HILEVEL=YES Offset 24 entry4 MODS E184 Offset 4 entry
4

Specified with DFSPARM

Function S,C S M S,M,C S,M,C S,M,C5

E15=COB MODS E154|HILEVEL=YES MODS E184 NO MODS E35 |HILEVEL=YES MODS E394 NO NO MODS Exx MODS Exx Offset 28 entry4 MODS E394 Offset 8 entry MODS E354|HILEVEL=YES NO

MODS E184

NO

E35=COB MODS E354|HILEVEL=YES

MODS E394

MODS Exx

INREC parameters OUTREC parameters SORT|MERGE FIELDS|FORMAT SUM FIELDS|FORMAT MERGE FILES OPTION FILSZ|SIZE SORT|MERGE FILSZ|SIZE2 NO NO NO OPTION HIPRMAX NO NO OPTION CKPT6 SORT|MERGE CKPT2,6 NO OPTION HIPRMAX NO NO OPTION CKPT6 SORT|MERGE CKPT6 NO NO OPTION FILSZ|SIZE SORT|MERGE FILSZ|SIZE MERGE FILES SUM FIELDS|FORMAT SORT|MERGE FIELDS|FORMAT NO OUTREC parameters NO

INREC parameters

INREC parameters

NO

S,M,C S,M,C S,M S,M M S,M

OUTREC parameters

SORT|MERGE FIELDS|FORMAT

SUM FIELDS|FORMAT

MERGE FILES

FILSZ OPTION FILSZ|SIZE SORT|MERGE FILSZ|SIZE

NO

GENER GNPAD GNTRUNC HIPRMAX IDRCPCT IEXIT IGNCKPT

IEBGENER name ICEGENER LRECL padding action ICEGENER LRECL truncation action Hipersorting IDRC compaction ICEIEXIT Checkpoints

C C C S S S,M,C S

NO

NO

HIPRMAX OPTION HIPRMAX

NO

Appendix B. Specification/Override of DFSORT Options

NO

Specification/Override Of Options

OPTION CKPT6 SORT|MERGE CKPT6

755

|
Specified with SORTCNTL NO NO IOMAXBF Maximum SORTIN/SORTOUT data set buffer space Record lengths Print DFSORT control statements7 Specified with Extended Parameter Installation (INV, List TSOINV or TDx) Description of Option S,M,C Function RECORD LENGTH NO3 OPTION LIST|NOLIST OPTION LISTX|NOLISTX LISTX LIST NO3 RECORD LENGTH NO S,M,C S,M,C

756
Print control statements S,M,C returned by an EFS program7 Locale processing Maximum storage below 16MB virtual8 Minimum storage Memory object sorting Alternate message ddname MSGCON MSGPRT NO NOMSGDD NULLOUT ODMAXBF OUTFIL11 OPTION NOOUTREL NO OUTREL Write messages on master console Print messages Bypass Blockset Action when message data set missing Action when no records for SORTOUT Maximum OUTFIL data set buffer space OUTFIL processing Release output data set space S,M,C S,M,C S,M,C S S,M,C S,M,C S,M,C S,M S,M,C S,M,C S,M,C S,M,C S,M,C NO3 OPTION LOCALE NO NO OPTION MOSIZE OPTION MSGDDN NO OPTION MSGPRT OPTION NOBLKSET NO OPTION NULLOUT OPTION ODMAXBF MOSIZE MSGDDN MINLIM MAXLIM LOCALE NO NO OPTION MOSIZE NO3 NO NO3 OPTION NOBLKSET NO OPTION NULLOUT OPTION ODMAXBF OUTFIL11 OPTION NOOUTREL

Table 80. Extended Parameter List DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

NO

RECORD LENGTH

LIST|NOLIST OPTION LIST|NOLIST

Specification/Override Of Options

LISTX|NOLISTX OPTION LISTX|NOLISTX

LOCALE OPTION LOCALE

z/OS V1R10.0 DFSORT Application Programming Guide

NO

NO

MOSIZE OPTION MOSIZE

MSGDDN OPTION MSGDDN

NO

MSGPRT OPTION MSGPRT

OPTION NOBLKSET

NO

NULLOUT OPTION NULLOUT

ODMAXBF OPTION ODMAXBF

OUTFIL11

OUTREL|NOOUTREL OPTION NOOUTREL

|
Specified with SORTCNTL OPTION NOOUTSEC NO OPTION OVFLO OPTION PAD NO OPTION RESALL OPTION RESET|NORESET OPTION RESINV OPTION SDB OPTION SDB SDB OPTION RESINV RESINV OPTION RESET|NORESET RESET OPTION RESALL RESALL NO PARMDDN OPTION PAD PAD OPTION OVFLO OVFLO Summary fields overflow action DFSORT LRECL padding action Alternate ddname for DFSPARM System reserved storage8 NEW or MOD VSAM output Program reserved storage8 System-determined output data set block size SDBMSG System-determined block size for message and list data sets SIZE NO Storage Skip records NO OVERRGN Storage over REGION OPTION NOOUTSEC OUTSEC Output data set secondary allocation Specified with Extended Parameter Installation (INV, List TSOINV or TDx) Description of Option Function S,M,C S,M,C S,M S,M,C S,M,C S,M,C S,M,C S,M,C S,M,C NO NO S,M,C OPTION MAINSIZE OPTION SKIPREC SORT|MERGE SKIPREC2 NO OPTION SOLRF|NOSOLRF NO3 NO3 NO OPTION MAINSIZE OPTION SKIPREC SORT|MERGE SKIPREC OPTION SMF OPTION SOLRF|NOSOLRF OPTION SORTDD OPTION SORTIN9 NO S,M,C S,C SMF SOLRF NO NO SORTLIB SMF records SORTOUT length ddname prefix Alternate SORTIN ddname Conventional modules library S,M,C S,M,C S,M,C S,C S,M

Table 80. Extended Parameter List DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

OPTION NOOUTSEC

NO

OVFLO OPTION OVFLO

PAD OPTION PAD

NO

RESALL OPTION RESALL

RESET|NORESET OPTION RESET|NORESET

OPTION RESINV

SDB OPTION SDB

NO

SIZE OPTION MAINSIZE

SKIPREC OPTION SKIPREC SORT|MERGE SKIPREC

OPTION SMF

SOLRF|NOSOLRF OPTION SOLRF|NOSOLRF

OPTION SORTDD

Appendix B. Specification/Override of DFSORT Options

OPTION SORTIN9

Specification/Override Of Options

NO

757

|
Specified with SORTCNTL NO3 NO SPANINC NO Input limit Incomplete spanned records action Alternate SORTOUT ddname OPTION SPANINC OPTION STOPAFT SORT|MERGE STOPAFT2 NO OPTION SZERO|NOSZERO NO NO NO TMAXLIM NO TEXIT OPTION SZERO|NOSZERO SZERO NO SVC OPTION STOPAFT SORT|MERGE STOPAFT OPTION SPANINC OPTION SORTOUT10 Specified with Extended Parameter Installation (INV, List TSOINV or TDx) Description of Option S,M,C S,M,C S,C Function

758
DFSORT SVC information Signed or unsigned zero ICETEXIT S,M,C S,M,C S,M,C Maximum storage S,M,C above and below 16MB virtual8 DFSORT LRECL truncation action NO VERIFY VIO VLLONG VLSCMP VLSHRT VSAMBSP OPTION VSAMEMT|NVSAMEMT VSAMEMT Record format Sequence check SORTWK virtual I/O Ttruncate long output records Pad short compare fields S,M,C S,M,C S,M S S,M,C S,M,C Action for short control S,M,C field or compare field VSAM buffer space Empty VSAM input S S,M,C OPTION TRUNC RECORD TYPE OPTION VERIFY|NOVERIFY NO OPTION VLLONG|NOVLLONG OPTION VLSCMP|NOVLSCMP OPTION VLSHRT|NOVLSHRT NO OPTION VSAMEMT|NVSAMEMT NO NO OPTION VLLONG|NOVLLONG OPTION VLSCMP|NOVLSCMP OPTION VLSHRT|NOVLSHRT OPTION VERIFY|NOVERIFY RECORD TYPE OPTION TRUNC TRUNC OPTION VSAMIO|NOVSAMIO OPTION VSAMIO|NOVSAMIO VSAMIO Same VSAM input and output S

Table 80. Extended Parameter List DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

OPTION SORTOUT10

SPANINC OPTION SPANINC

STOPAFT OPTION STOPAFT SORT|MERGE STOPAFT

Specification/Override Of Options

NO

SZERO|NOSZERO OPTION SZERO|NOSZERO

NO

z/OS V1R10.0 DFSORT Application Programming Guide

NO

TRUNC OPTION TRUNC

RECORD TYPE

VERIFY|NOVERIFY OPTION VERIFY|NOVERIFY

NO

VLLONG|NOVLLONG OPTION VLLONG|NOVLLONG

VLSCMP|NOVLSCMP OPTION VLSCMP|NOVLSCMP

VLSHRT|NOVLSHRT OPTION VLSHRT|NOVLSHRT

NO

VSAMEMT|NVSAMEMT OPTION VSAMEMT| NVSAMEMT

VSAMIO|NOVSAMIO OPTION VSAMIO|NOVSAMIO

|
Specified with SORTCNTL OPTION WRKREL|NOWRKREL OPTION WRKREL|NOWRKREL WRKREL Release SORTWK space S Specified with Extended Parameter Installation (INV, List TSOINV or TDx) Description of Option Function OPTION WRKSEC|NOWRKSEC OPTION WRKSEC|NOWRKSEC WRKSEC SORTWK secondary allocation Set century window S OPTION Y2PAST SORT|MERGE Y2PAST2 OPTION ZDPRINT|NZDPRINT OPTION ZDPRINT|NZDPRINT ZDPRINT OPTION Y2PAST SORT|MERGE Y2PAST Y2PAST S,M,C ZD SUM results S,M

Table 80. Extended Parameter List DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

WRKREL|NOWRKREL OPTION WRKREL|NOWRKREL

WRKSEC|NOWRKSEC OPTION WRKSEC| NOWRKSEC

Y2PAST OPTION Y2PAST SORT|MERGE Y2PAST

ZDPRINT|NZDPRINT OPTION ZDPRINT|NZDPRINT

Appendix B. Specification/Override of DFSORT Options

Specification/Override Of Options

759

Specification/Override Of Options

Notes to Extended Parameter List Table

1 2

Does not request dynamic allocation; only supplies defaults. Does not override corresponding option in an OPTION statement specified via the extended parameter list. Not used in SORTCNTL. DFSORT terminates if the exit is specified via the parameter list entry and the exit is specified in a MODS statement. All functions do not apply to all exits. See Table 51 on page 417 and Table 52 on page 417 for applicable exits. Not used if Blockset is selected and IGNCKPT=YES was specified. Not used if MSGPRT=NONE is in effect; in this case control statements are not printed. Not used unless MAINSIZE=MAX is in effect. Overrides SORTDD for the sort input ddname. Overrides SORTDD for the sort output ddname. Override is at the ddname level.

3 4

6 7

8 9 10 11

Program Invoked DFSORT with the 24-Bit Parameter List

Table 81 on page 761 shows where each sort, merge, or copy option may be specified when DFSORT is program invoked and a 24-bit parameter list is passed to it. DFSPARM: PARM options selectively override corresponding options in any other source. DEBUG and OPTION control statement options selectively override corresponding options in SORTCNTL and the Parameter List. Control statements other than DEBUG and OPTION completely override corresponding control statements in SORTCNTL and the Parameter List. SORTCNTL: DEBUG control statement options selectively override corresponding options in the Parameter List. Control statements other than DEBUG completely override corresponding control statements in the Parameter List. SORT and MERGE are considered to be corresponding control statements. INCLUDE and OMIT are considered to be corresponding control statements.

760

z/OS V1R10.0 DFSORT Application Programming Guide

Table 81. 24-Bit List DFSORT Option Specification/Override. Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.
Specified with SORTCNTL NO DEBUG ABSTP ALTSEQ CODE OPTION ARESALL OPTION ARESINV NO ARESINV NO ARESALL X'F6' entry ALTSEQ CODE ALTSEQ DEBUG ABSTP NO Abnormal stop Alternate sequence NO ABCODE ABEND code Specified with 24-Bit List Installation (INV, TSOINV Description of or TDx) Option Function S,M,C S,M,C S,M

Specified with DFSPARM

NO

DEBUG ABSTP

ALTSEQ CODE

ARESALL OPTION ARESALL

System storage above S,M,C 16MB virtual Storage above 16MB virtual for invoking program Bypass Sorting Instructions Average record length Force BSAM Cache fast write S,M,C

OPTION ARESINV

DEBUG NOASSIST OPTION AVGRLEN DEBUG BSAM DEBUG CFW|NOCFW OPTION CHALT|NOCHALT OPTION CHECK|NOCHECK OPTION CINV|NOCINV OPTION COBEXIT INCLUDE|OMIT COND|FORMAT OPTION COPY SORT|MERGE FIELDS DEBUG CTRx NO NO OPTION DSA NO INCLUDE|OMIT COND|FORMAT SORT|MERGE FIELDS DEBUG CTRx NO NO NO NO NO NO DEBUG CFW|NOCFW CFW CHALT CHECK CINV COBEXIT NO NO NO day DIAGSIM DSA DEBUG BSAM NO NO NO

DEBUG NOASSIST

DEBUG NOASSIST

NO

S S S,M,C S CH field sequence Record count check Control interval access COBOL library Include|Omit fields Copy records S,M S,M,C S,M,C S,M,C S,M,C C ABEND record count S,M Time-of-day for activation Simulate SORTDIAG DD statement Dynamic storage adjustment limit S,M,C S,M,C S

AVGRLEN OPTION AVGRLEN

BSAM DEBUG BSAM

DEBUG CFW|NOCFW

OPTION CHALT|NOCHALT

OPTION CHECK|NOCHECK

CINV|NOCINV OPTION CINV|NOCINV

COBEXIT OPTION COBEXIT

INCLUDE|OMIT COND|FORMAT

OPTION COPY SORT|MERGE FIELDS

DEBUG CTRx

NO

Appendix B. Specification/Override of DFSORT Options

NO

Specification/Override Of Options

DSA OPTION DSA

761

762
Specified with SORTCNTL OPTION DSPSIZE OPTION DYNALLOC SORT DYNALLOC OPTION DYNALLOC SORT DYNALLOC OPTION DYNSPC NO2 NO NO SORT|MERGE EQUALS|NOEQUALS EQUALS ENABLE EFS NO OPTION EQUALS|NOEQUALS SORT|MERGE EQUALS| NOEQUALS DEBUG EQUCOUNT DEBUG ABEND|NOABEND DEBUG ESTAE|NOESTAE OPTION EXITCK NO NO NO DEBUG EQUCOUNT NO NO DYNSPC SORT DYNALLOC DYNAUTO Automatic DYNALLOC Dynamic allocation default space EFS program specified Enable Time-of-Day modules Equal record order SORT DYNALLOC DYNALOC1 Dynamic SORTWKs NO DSPSIZE Dataspace sorting S S Specified with 24-Bit List Installation (INV, TSOINV Description of or TDx) Option Function S S S,M,C S,M,C S,M Equal key count message Error action ESTAE EXITCK EXPMAX ESTAE routine E15/E35 return code checking S S,M,C S,M,C S,M,C Available expanded S storage limit for all DFSORT Hiperspaces NO EXPOLD Old expanded S storage limit for all DFSORT Hiperspaces NO EXPRES Available expanded S storage reserved for non-Hipersorting use DEBUG ABEND|NOABEND ERET DEBUG ESTAE|NOESTAE NO NO

Table 81. 24-Bit List DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

DSPSIZE OPTION DSPSIZE

DYNALLOC OPTION DYNALLOC SORT DYNALLOC

Specification/Override Of Options

DYNALLOC OPTION DYNALLOC|USEWKDD SORT DYNALLOC

DYNSPC OPTION DYNSPC

EFS OPTION EFS

z/OS V1R10.0 DFSORT Application Programming Guide

NO

EQUALS|NOEQUALS OPTION EQUALS|NOEQUALS SORT|MERGE EQUALS| NOEQUALS

DEBUG EQUCOUNT

ABEND|NOABEND DEBUG ABEND|NOABEND

DEBUG ESTAE|NOESTAE

OPTION EXITCK

NO

NO

NO

Table 81. 24-Bit List DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.
Specified with SORTCNTL MODS E153| HILEVEL=YES NO User exit E15 NO MODS E353|HILEVEL=YES NO Offset 22 entry3 MODS E353| HILEVEL=YES MODS Exx NO Offset 18 entry NO User exit E32 User exit E35 Offset 18 entry3 MODS E153| HILEVEL=YES Specified with 24-Bit List Installation (INV, TSOINV Description of or TDx) Option Function S,C

Specified with DFSPARM

E15=COB MODS E153| HILEVEL=YES

NO

M S,M,C

E35=COB MODS E353|HILEVEL=YES MODS Exx

MODS Exx

User Exit Exx (xx=11,16-19, 31,37-39, and 61) INREC reformatting OUTREC reformatting Control fields Sum fields

S,M,C4

INREC parameters OUTREC parameters SORT|MERGE FIELDS|FORMAT SUM FIELDS|FORMAT MERGE FILES OPTION FILSZ|SIZE SORT|MERGE FILSZ|SIZE NO NO NO OPTION HIPRMAX NO NO OPTION CKPT5 SORT|MERGE CKPT5 NO NO NO NO SORT|MERGE CKPT5 NO NO X'04' entry MERGE FILES SORT|MERGE FILSZ|SIZE SUM FIELDS|FORMAT NO NO FSZEST SORT|MERGE FIELDS|FORMAT NO OUTREC parameters NO

INREC parameters

INREC parameters

NO

S,M,C S,M,C S,M,C S,M Merge input files File size M S,M

OUTREC parameters

SORT|MERGE FIELDS|FORMAT

SUM FIELDS|FORMAT

MERGE FILES

FILSZ OPTION FILSZ|SIZE SORT|MERGE FILSZ|SIZE

NO

GENER GNPAD GNTRUNC HIPRMAX IDRCPCT IEXIT IGNCKPT

IEBGENER name ICEGENER LRECL padding action ICEGENER LRECL truncation action Hipersorting IDRC compaction ICEIEXIT Checkpoints

C C C S S S,M,C S

NO

NO

HIPRMAX OPTION HIPRMAX

NO

Appendix B. Specification/Override of DFSORT Options

NO

Specification/Override Of Options

OPTION CKPT5 SORT|MERGE CKPT5

763

764
Specified with SORTCNTL NO NO IOMAXBF Maximum SORTIN/ SORTOUT data set buffer space Record lengths Print DFSORT control statements6 Print control statements returned by an EFS program6 Locale processing Maximum storage below 16MB virtual7 Minimum storage Memory object sorting MSGDDN MSGCON MSGPRT NO NOMSGDD Alternate message ddname Write messages on master console Print messages Bypass Blockset Action when message data set missing NO NULLOUT Action when no records for SORTOUT NO OUTFIL10 ODMAXBF NO Maximum OUTFIL data set buffer space OUTFIL processing Specified with 24-Bit List Installation (INV, TSOINV Description of or TDx) Option S,M,C Function RECORD LENGTH NO2 NO NO LISTX LIST NO2 RECORD LENGTH NO S,M,C S,M,C S,M,C NO2 NO NO NO NO X'03' entry NO X'FF' entry NO NO MINLIM MOSIZE MAXLIM LOCALE NO NO OPTION MOSIZE NO2 NO NO2 OPTION NOBLKSET NO S,M,C S,M,C S,M,C S S,M,C S,M,C S,M,C S,M S,M,C OPTION NULLOUT S,M,C OPTION ODMAXBF OUTFIL10 S,M,C S,M,C

Table 81. 24-Bit List DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

NO

RECORD LENGTH

Specification/Override Of Options

LIST|NOLIST OPTION LIST|NOLIST

LISTX|NOLISTX OPTION LISTX|NOLISTX

LOCALE OPTION LOCALE

z/OS V1R10.0 DFSORT Application Programming Guide

NO

NO

MOSIZE OPTION MOSIZE

MSGDDN OPTION MSGDDN

NO

MSGPRT OPTION MSGPRT

OPTION NOBLKSET

NO

NULLOUT OPTION NULLOUT

ODMAXBF OPTION ODMAXBF

OUTFIL10

Table 81. 24-Bit List DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.
Specified with SORTCNTL OPTION NOOUTREL OPTION NOOUTSEC NO OPTION OVFLO OPTION PAD NO OPTION RESALL OPTION RESET|NORESET OPTION RESINV OPTION SDB NO X'01' entry NO RESET RESINV SDB NO RESALL NO PARMDDN NO PAD NO OVFLO NO OVERRGN Storage over REGION Summary fields overflow action DFSORT LRECL padding action NO OUTSEC NO OUTREL Release output data set space Output data set secondary allocation Specified with 24-Bit List Installation (INV, TSOINV Description of or TDx) Option Function S,M,C S,M,C S,M,C S,M S,M,C Alternate ddname for S,M,C DFSPARM System reserved storage7 NEW or MOD VSAM output Program reserved storage7 System-determined output data set block size SDBMSG S,M,C S,M,C S,M,C S,M,C

Specified with DFSPARM

OUTREL|NOOUTREL OPTION NOOUTREL

OPTION NOOUTSEC

NO

OVFLO OPTION OVFLO

PAD OPTION PAD

NO

RESALL OPTION RESALL

RESET|NORESET OPTION RESET|NORESET

OPTION RESINV

SDB OPTION SDB NO NO

NO

System-determined S,M,C block size for message and list data sets SIZE Storage S,M,C

SIZE OPTION MAINSIZE OPTION SKIPREC SORT|MERGE SKIPREC NO OPTION SOLRF|NOSOLRF NO2

OPTION MAINSIZE

X'00' entry SORT|MERGE SKIPREC

SKIPREC OPTION SKIPREC SORT|MERGE SKIPREC

NO

Skip records

S,C

OPTION SMF

NO NO Prefix entry

SMF SOLRF NO

SMF records SORTOUT length ddname prefix

S,M,C S,M,C S,M,C

Appendix B. Specification/Override of DFSORT Options

SOLRF|NOSOLRF OPTION SOLRF|NOSOLRF

Specification/Override Of Options

765

OPTION SORTDD

766
Specified with SORTCNTL NO2 NO NO NO NO SORT|MERGE STOPAFT NO SPANINC NO SORTLIB Conventional modules library Alternate SORTOUT ddname Incomplete spanned records action Input limit NO Alternate SORTIN ddname NO NO2 OPTION SPANINC OPTION STOPAFT SORT|MERGE STOPAFT NO OPTION SZERO|NOSZERO NO NO NO NO TEXIT TMAXLIM NO SZERO NO SVC S,C S,M S,M,C S,M,C S,C Specified with 24-Bit List Installation (INV, TSOINV Description of or TDx) Option Function DFSORT SVC information Signed or unsigned zero ICETEXIT Maximum storage above and below 16MB virtual7 TRUNC NO VERIFY VIO VLLONG NO NO VLSCMP VLSHRT DFSORT LRECL truncation action Record format Sequence check S,M,C S,M,C S,M,C S,M,C OPTION TRUNC RECORD TYPE OPTION VERIFY|NOVERIFY NO OPTION VLLONG|NOVLLONG OPTION VLSCMP|NOVLSCMP OPTION VLSHRT|NOVLSHRT NO NO NO RECORD TYPE NO S,M,C S,M,C S,M SORTWK virtual I/O S Truncate long output records Pad short compare fields Action for short control or compare field NO VSAMBSP VSAM buffer space S,M,C S,M,C S,M,C NO S

Table 81. 24-Bit List DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.

Specified with DFSPARM

OPTION SORTIN8

NO

OPTION SORTOUT9

Specification/Override Of Options

SPANINC OPTION SPANINC

STOPAFT OPTION STOPAFT SORT|MERGE STOPAFT

z/OS V1R10.0 DFSORT Application Programming Guide

NO

SZERO|NOSZERO OPTION SZERO|NOSZERO

NO

NO

TRUNC OPTION TRUNC

RECORD TYPE

VERIFY|NOVERIFY OPTION VERIFY|NOVERIFY

NO

VLLONG|NOVLLONG OPTION VLLONG|NOVLLONG

VLSCMP|NOVLSCMP OPTION VLSCMP|NOVLSCMP

VLSHRT|NOVLSHRT OPTION VLSHRT|NOVLSHRT

NO

Table 81. 24-Bit List DFSORT Option Specification/Override (continued). Options are arranged alphabetically on the Installation column. If NO is specified in the Installation column, move to the next column to the left and so on.

The order of override is from left to right and from top to bottom within a row.
Specified with SORTCNTL OPTION VSAMEMT|NVSAMEMT NO VSAMEMT Empty VSAM input Specified with 24-Bit List Installation (INV, TSOINV Description of or TDx) Option Function S,M,C

Specified with DFSPARM

VSAMEMT|NVSAMEMT OPTION VSAMEMT| NVSAMEMT OPTION VSAMIO|NOVSAMIO OPTION WRKREL|NOWRKREL OPTION WRKSEC| NOWRKSEC OPTION Y2PAST SORT|MERGE Y2PAST OPTION ZDPRINT|NZDPRINT NO ZDPRINT SORT|MERGE Y2PAST Y2PAST NO WRKSEC NO WRKREL NO VSAMIO Same VSAM input and output Release SORTWK space

VSAMIO|NOVSAMIO OPTION VSAMIO|NOVSAMIO

S S S

WRKREL|NOWRKREL OPTION WRKREL|NOWRKREL

WRKSEC|NOWRKSEC OPTION WRKSEC|NOWRKSEC

SORTWK secondary allocation Set century window

Y2PAST OPTION Y2PAST SORT|MERGE Y2PAST

S,M,C

ZDPRINT|NZDPRINT OPTION ZDPRINT|NZDPRINT

ZD SUM results

S,M

Appendix B. Specification/Override of DFSORT Options

Specification/Override Of Options

767

Specification/Override Of Options

Notes to 24-Bit List Table

1 2 3

Does not request dynamic allocation; only supplies defaults. Not used in SORTCNTL. DFSORT terminates if the exit is specified via the parameter list entry and the user exit is specified in a MODS statement. All functions do not apply to all user exits. See Table 51 on page 417 and Table 52 on page 417 for applicable user exits. Not used if Blockset is selected and IGNCKPT=YES was specified. Not used if MSGPRT=NONE or MSGPRT=CRITICAL is in effect; in this case control statements are not printed. Not used unless MAINSIZE=MAX is in effect. Overrides SORTDD for the sort input ddname. Overrides SORTDD for the sort output ddname. Override is at the ddname level.

5 6

7 8 9 10

768

z/OS V1R10.0 DFSORT Application Programming Guide

Appendix C. Data Format Descriptions

DFSORT Data Formats . . . . . . . . . . 769 DFSORT Formats for COBOL Data Types . . . . 778

| Where DFSORT Formats Can be Used . . . . . 776

DFSORT Data Formats

DFSORT supports a large number of data formats as described below.
Format CH Description (character EBCDIC, unsigned). Each character is represented by its 8-bit EBCDIC code. Example: AB7 becomes C1 C2 F7 11000001 11000010 11110111 Notes: 1. If CHALT is in effect, a format CH field collates according to the ALTSEQ (alternate collating sequence) table in effect. AQ format can be used for the same purpose. 2. If locale processing is in effect, a format CH field collates according to the collating rules of the active locale. ZD (zoned decimal, signed). Each digit of the decimal number is converted into its 8-bit EBCDIC representation. The sign indicator replaces the first four bits of the low order byte of the number. Example: 247 becomes 2 4 7 Decimal F2 F4 D7 Hexadecimal 11110010 11110100 11010111 Binary The number +247 becomes F2 F4 C7 11110010 11110100 11000111 Notes: 1. The following are treated as positive sign indicators: F, E, C, A, 8, 6, 4, 2, 0. 2. The following are treated as negative sign indicators: D, B, 9, 7, 5, 3, 1. 3. For SUM processing, 0 through 9 for the sign or A through F for a digit results in a data exception (0C7 ABEND). For example, a ZD value such as 3.5 (X'F34BF5') results in an 0C7 because B is treated as an invalid digit. ICETOOLs DISPLAY or VERIFY operator can be used to identify ZD values with invalid digits. ICETOOLs VERIFY operator can be used to identify ZD values with invalid signs. 4. The first four bits of the last digit is the sign indicator. The first four bits of each other digit is ignored. Thus the EBCDIC strings 0025 and 25 are both treated as 25 because a leading blank (X'40') is equivalent to a 0 digit (X'F0'). PD (packed decimal, signed). Each digit of the decimal number is converted into its 4-bit binary equivalent. The sign indicator is put into the rightmost four bits of the number. Example: 247 becomes 2 4 7 Decimal 2 4 7D Hexadecimal 00100100 01111101 Binary The number +247 becomes 247C in hexadecimal. Notes: 1. The following are treated as positive sign indicators: F, E, C, A, 8, 6, 4, 2, 0. 2. The following are treated as negative sign indicators: D, B, 9, 7, 5, 3, 1. 3. For SUM processing, 0 through 9 for the sign or A through F for a digit results in a data exception (0C7 ABEND). For example, a PD value such as X'0123BF' results in an 0C7 because B is treated as an invalid digit. ICETOOLs DISPLAY or VERIFY operator can be used to identify PD values with invalid digits. ICETOOLs VERIFY operator can be used to identify PD values with invalid signs.

Hexadecimal Binary

Copyright IBM Corp. 1973, 2006

769

Data Format Examples

Format PD0 Description (packed decimal, with sign and first digit ignored) The PD0 format can be represented as follows: xddd...ds x is hexadecimal 0-F and is ignored. d is hexadecimal 0-9 and represents a decimal digit. s is hexadecimal 0-F and is ignored. PD0 can be used for parts of PD fields. For example, in the PD field Pmmddyy (hexadecimal 0mmddyyC), PD0 can be used separately for 0mmd (mm), mddy (dd) and dyyC (yy). FI (fixed-point, signed). The complete number is represented by its binary equivalent with the sign indicator placed in the most significant bit position. 0 for + or 1 for . Negative numbers are in 2s complement form. Example: +247 becomes in halfword form 00F7 Hexadecimal 0000000011110111 Binary 247 becomes in halfword form FF09 Hexadecimal 1111111100001001 Binary BI FL (binary unsigned). Any bit pattern. ( hexadecimal floating-point, signed). The specified number is in the two-part format of characteristic and fraction with the sign indicator in bit position 0. Example: +247 becomes 42F70000... Hexadecimal 0 1000010 111101110000000....... Binary + chara. Fraction 247 is identical, except that the sign bit is changed to 1. C2F70000... Hexadecimal 1 1000010 111101110000000....... Binary - chara. Fraction AQ (character EBCDIC, with alternate collating sequence, unsigned). This is similar to format CH, but the characters collate according to the ALTSEQ (alternate collating sequence) table in effect. (character EBCDIC, with ISCII/ASCII collating sequence, unsigned). This is similar to format CH, but the characters collate according to the ISCII/ASCII collating sequence. (EFS type). User-defined data type (requires an EFS program) D2 (EFS type). User-defined data type (requires an EFS program)

| AC |
D1

770

z/OS V1R10.0 DFSORT Application Programming Guide

Data Format Examples

Format CSF or FS Description (signed numeric with optional leading floating sign). The floating sign format can be represented as follows: <s>d . . .d s is an optional sign immediately to the left of the digits d . . .d. If s is a , the number is treated as negative, otherwise it is treated as positive. Thus, must be used for a minus sign, but any other character (for example, + or blank) can be used for a plus sign. The first non-decimal digit (that is, not 0-9) going from right to left is treated as the sign and anything to the left of the sign is ignored. Examples: Value: 34 +34 00034 003 1234 1234 +01234 0 Treated as: +34 +34 +34 3 1234 +1234 +1234 +0

The types of data handled by the CSF or FS format encompass those produced by several different FORTRAN, PL/I and COBOL formats, such as those shown below (using a width of 4 for purposes of illustration): * FORTRAN: I4 ; G4.0 ; SP,I4 ; SP,I4.3 ; S,I4.3 * PL/I: F(4) ; PS999 ; PSSS9 ; P9 * COBOL: PIC ++9 ; PIC +999 ; PIC ++++ ; PIC 9 ; PIC ; PIC ZZZZ UFF (unsigned free form numeric). This format extracts decimal digits (0-9) from right to left anywhere in the field to form a positive number. Any combination of characters is valid, but characters other than 0-9 are ignored. Examples: Value: $58,272,300.10 $58,272,300.1 $58,272,300 12-31-2004 (402)-125-3721XXX G1*** 52 $ 21 R 000128637.240 +400.52 +400.1 173/821/9072/@3 ABC SFF (signed free form numeric). This format extracts decimal digits (0-9) from right to left anywhere in the field to form a positive or negative number. If - or ) is found anywhere in the field, the number is treated as negative, otherwise it is treated as positive. Any combination of characters is valid, but characters other than 0-9, - and ) are ignored. Examples: Value: 358,272,300.10 358,272,300.1 -358,272,300 (82,316.90) 12-31-2004 G1*** 52 $ 21 R G1*** ) 52 $ 21 R 000128637.240 400.52($400.5) 173/821/9072/@3 X,Y,Z Treated as: +35827230010 +3582723001 -358272300 -8231690 -12312004 +15221 -15221 +128637240 -40052 -4005 +17382190723 +0 Treated as: +5827230010 +582723001 +58272300 +12312004 +4021253721 +15221 +128637240 +40052 +4001 +17382190723 +0

Appendix C. Data Format Descriptions

771

Data Format Examples

Format CSL or LS Description (signed number, leading separate sign). This format refers to decimal data as punched into cards, and then assembled into EBCDIC code. Example: +247 punched in a card becomes + 2 4 7 Punched numeric data 4E F2 F4 F7 Hexadecimal 01001110 11110010 11110100 11110111 Binary EBCDIC code 247 becomes 2 4 7 Punched numeric data 60 F2 F4 F7 Hexadecimal 01100000 11110010 11110100 11110111 Binary EBCDIC code Note: A value with as the leading sign character is treated as a negative value. A value with any leading sign character other than (for example, + (plus) or blank) is treated as a positive value. CST or TS (signed numeric, trailing separate sign). This has the same representation as the CSL format, except that the sign indicator is punched after the number. Example: 247+ punched on the card becomes F2 F4 F7 4E Hexadecimal Note: A value with as the trailing sign character is treated as a negative value. A value with any trailing sign character other than (for example, + (plus) or blank) is treated as a positive value. CLO1 or OL1 (signed numeric, leading overpunch sign). This format again refers to decimal data punched into cards and then assembled into EBCDIC code. The sign indicator is, however, overpunched with the first decimal digit of the number. Example: +2 C2 11000010 Similarly D2 CTO or OT +247 with + overpunched on 2 becomes 4 7 Punched numeric data F4 F7 Hexadecimal 11110100 11110111 Binary EBCDIC code 247 becomes F4 F7

(signed numeric, trailing overpunch sign). This format has the same representation as for the CLO format, except that the sign indicator is overpunched on the last decimal digit of the number. Example: +247 with + overpunched on 7 becomes F2 F4 C7 hexadecimal

ASL

(signed numeric, ASCII, leading separate sign). Similar to the CSL format but with decimal data assembled into ASCII code. Example: +247 punched into card becomes + 2 4 7 Punched numeric data 2B 32 34 37 Hexadecimal 0101011 00110010 00110100 00110111 Binary ASCII code Similarly 247 becomes 2D 32 34 37 hexadecimal Note: A value with as the leading sign character is treated as a negative value. A value with any leading sign character other than (for example, + (plus) or blank) is treated as a positive value.

AST

(signed numeric, ASCII, trailing separate sign). This gives the same bit representation as the ASL format, except that the sign is punched after the number. Example: 247+ becomes 32 34 37 2B hexadecimal Note: A value with as the trailing sign character is treated as a negative value. A value with any trailing sign character other than (for example, + (plus) or blank) is treated as a positive value.

772

z/OS V1R10.0 DFSORT Application Programming Guide

Data Format Examples

Format Y2T Description (character or zoned decimal yyx, yyxx, yyxxx and yyxxxx full date format with special indicators). The date field can be represented as follows: 3,Y2T: 4,Y2T: 5,Y2T: 6,Y2T: Cyyx or Zyyx Cyyxx or Zyyxx Cyyxxx or Zyyxxx Cyyxxxx or Zyyxxxx

y is hexadecimal 0-9 and represents a year digit. x is hexadecimal 0-9 and represents a non-year digit. x...x must be in correct collating order. The special indicators are X00...00 (BI zeros), X40...40 (blanks), C0...0 (CH zeros), Z0...0 (ZD zeros), C9...9 (CH nines), Z9...9 (ZD nines) and XFF...FF (BI ones). Y2U (packed decimal yyx and yyxxx full date format with special indicators). The date field can be represented as follows: 2,Y2U: 3,Y2U: Pyyx (Xyyxs) Pyyxxx (Xyyxxxs)

y is hexadecimal 0-9 and represents a year digit. x is hexadecimal 0-9 and represents a non-year digit. s is hexadecimal 0-F and is ignored. xxx must be in correct collating order. The special indicators are P0...0 (PD zeros) and P9...9 (PD nines). Y2V (packed decimal yyxx and yyxxxx full date format with special indicators). The date field can be represented as follows: 3,Y2V: 4,Y2V: Pyyxx (X0yyxxs) Pyyxxxx (X0yyxxxxs)

y is hexadecimal 0-9 and represents a year digit. x is hexadecimal 0-9 and represents a non-year digit. s is hexadecimal 0-F and is ignored. xx or xxxx must be in correct collating order. The special indicators are P0...0 (PD zeros) and P9...9 (PD nines). Y2W (character or zoned decimal xyy, xxyy, xxxyy and xxxxyy full date format with special indicators). The date field can be represented as follows: 3,Y2W: 4,Y2W: 5,Y2W: 6,Y2W: Cxyy or Zxyy Cxxyy or Zxxyy Cxxxyy or Zxxxyy Cxxxxyy or Zxxxxyy

y is hexadecimal 0-9 and represents a year digit. x is hexadecimal 0-9 and represents a non-year digit. x...x must be in correct collating order. x...xyy will be treated as yyx...x when collating the date field. The special indicators are X00...00 (BI zeros), X40...40 (blanks), C0...0 (CH zeros), Z0...0 (ZD zeros), C9...9 (CH nines), Z9...9 (ZD nines) and XFF...FF (BI ones). Y2X (packed decimal xyy and xxxyy full date format with special indicators). The date field can be represented as follows: 2,Y2X: 3,Y2X: Pxyy (Xxyys) Pxxxyy (Xxxxyys)

y is hexadecimal 0-9 and represents a year digit. x is hexadecimal 0-9 and represents a non-year digit. s is hexadecimal 0-F and is ignored. xxx must be in correct collating order. x...xyy will be treated as yyx...x when collating the date field. The special indicators are P0...0 (PD zeros) and P9...9 (PD nines).

Appendix C. Data Format Descriptions

773

Data Format Examples

Format Y2Y Description (packed decimal xxyy and xxxxyy full date format with special indicators). The date field can be represented as follows: 3,Y2Y: 4,Y2Y: Pxxyy (X0xxyys) Pxxxxyy (X0xxxxyys)

y is hexadecimal 0-9 and represents a year digit. x is hexadecimal 0-9 and represents a non-year digit. s is hexadecimal 0-F and is ignored. xx or xxxx must be in correct collating order. x...xyy will be treated as yyx...x when collating the date field. The special indicators are P0...0 (PD zeros) and P9...9 (PD nines). Y2C or Y2Z (two-digit, two-byte character or zoned-decimal year data). The two-digit year data can be represented as follows: xyxy y is hexadecimal 0-9 and represents a year digit. x is hexadecimal 0-F and is ignored. Thus, 96 might be represented as hexadecimal F9F6 (character 96) or as hexadecimal F9C6 or 0906 (zoned decimal 96). Y2P (two-digit, two-byte packed-decimal year data). The two-digit year data can be represented as follows: xyyx y is hexadecimal 0-9 and represents a year digit. x is hexadecimal 0-F and is ignored. Thus, 96 might be represented as hexadecimal 096F or 896C (packed decimal 96). Y2D (two-digit, one-byte decimal year data). The two-digit year data can represented as follows: yy y is hexadecimal 0-9 and represents a year digit. Thus, 96 would be represented as hexadecimal 96 (decimal 96). Y2S (two-digit, two-byte character or zoned-decimal year data with special indicators). The two-digit year data can represented as follows: xyxy y is hexadecimal 0-9 and represents a year digit. x is hexadecimal 0-F and is ignored. Thus, 96 might be represented as hexadecimal F9F6 (character 96) or as hexadecimal F9C6 or 0906 (zoned decimal 96). The special indicators can be represented as follows: qxzx qx is hexadecimal 00, 40 or FF. zx is hexadecimal 00-FF (although typically 00, 40 and FF). Thus, special indicators might be hexadecimal 0000, 0005, 4040, FFFF, FF85 and so on. Y2B (two-digit, one-byte binary year data). The binary year data can be represented as follows: hh hh is the hexadecimal equivalent of a decimal yy value as follows: Binary Values X00-X63 X64-XC7 XC8-XFF Decimal Values 00-99 100-199 200-255 yy 00-99 00-99 00-55

Thus, 96 might be represented as hexadecimal 60 (decimal 96) or C4 (decimal 196).

774

z/OS V1R10.0 DFSORT Application Programming Guide

Data Format Examples

Format DT1 Description (SMF date interpreted as Zyyyymmdd). A 4-byte SMF date value in the form Pcyyddd (X0cyydddF) is converted to a Zyyyymmdd value. c represents the century indicator (c=0 is transformed to 19, c=1 is transformed to 20 and c>1 is transformed to 21), yy represents the two-digit year (00-99), ddd represents the day of the year (001-366), yyyy represents the four-digit year, mm represents the month (01-12) and dd represents the day (01-31). (SMF date interpreted as Zyyyymm). A 4-byte SMF date value in the form Pcyyddd (X0cyydddF) is converted to a Zyyyymm value. c represents the century indicator (c=0 is transformed to 19, c=1 is transformed to 20 and c>1 is transformed to 21), yy represents the two-digit year (00-99), ddd represents the day of the year (001-366), yyyy represents the four-digit year and mm represents the month (01-12). (SMF date interpreted as Zyyyyddd). A 4-byte SMF date value in the form Pcyyddd (X0cyydddF) is converted to a Zyyyyddd value. c represents the century indicator (c=0 is transformed to 19, c=1 is transformed to 20 and c>1 is transformed to 21), yy represents the two-digit year (00-99), ddd represents the day of the year (001-366) and yyyy represents the four-digit year. (TOD date interpreted as Zyyyymmdd). The 8 bytes of an input clock value, in the basic time-of-day (TOD) format, is converted to a Zyyyymmdd value. The STCKCONV macro is used to do the conversion. yyyy represents the four-digit year, mm represents the month (01-12) and dd represents the day (01-31). (TOD date interpreted as Zyyyymm). The 8 bytes of an input clock value, in the basic time-of-day (TOD) format, is converted to a Zyyyymm value. The STCKCONV macro is used to do the conversion. yyyy represents the four-digit year and mm represents the month (01-12). (TOD date interpreted as Zyyyyddd). The 8 bytes of an input clock value, in the basic time-of-day (TOD) format, is converted to a Zyyyyddd value. The STCKCONV macro is used to do the conversion. yyyy represents the four-digit year and ddd represents the day of the year (001-366). (ETOD date interpreted as Zyyyymmdd). The first 8 bytes of an input clock value, in the extended time-of-day (ETOD) format, is converted to a Zyyyymmdd value. The STCKCONV macro is used to do the conversion. yyyy represents the four-digit year, mm represents the month (01-12) and dd represents the day (01-31). (ETOD date interpreted as Zyyyymm). The first 8 bytes of an input clock value, in the extended time-of-day (ETOD) format is converted to a Zyyyymm value. The STCKCONV macro is used to do the conversion. yyyy represents the four-digit year and mm represents the month (01-12). (ETOD date interpreted as Zyyyyddd). The first 8 bytes of an input clock value, in the extended time-of-day (ETOD) format is converted to a Zyyyyddd value. The STCKCONV macro is used to do the conversion. yyyy represents the four-digit year and ddd represents the day of the year (001-366). (SMF time interpreted as Zhhmmss). A 4-byte binary SMF time value in hundredths of a second is converted to a Zhhmmss value. hh represents the hour (00-23), mm represents the minutes (00-59) and ss represents the seconds (00-59). (SMF time interpreted as Zhhmm). A 4-byte binary SMF time value in hundredths of a second is converted to a Zhhmm value. hh represents the hour (00-23) and mm represents the minutes (00-59). (SMF time interpreted as Zhh). A 4-byte binary SMF time value in hundredths of a second is converted to a Zhh value. hh represents the hour (00-23). (SMF time interpreted as Zhhmmssxx). A 4-byte binary SMF time value in hundredths of a second is converted to a Zhhmmssxx value. hh represents the hour (00-23), mm represents the minutes (00-59), ss represents the seconds (00-59), and xx represents hundredths of a second (00-99). (TOD time interpreted as Zhhmmss). The 8 bytes of an input clock value, in the basic time-of-day (TOD) format, is converted to a Zhhmmss value. The STCKCONV macro is used to do the conversion. hh represents the hour (00-23), mm represents the minutes (00-59) and ss represents the seconds (00-59). (TOD time interpreted as Zhhmm). The 8 bytes of an input clock value, in the basic time-of-day (TOD) format, is converted to a Zhhmm value. The STCKCONV macro is used to do the conversion. hh represents the hour (00-23) and mm represents the minutes (00-59). (TOD time interpreted as Zhh). The 8 bytes of an input clock value, in the basic time-of-day (TOD) format, is converted to a Zhh value. The STCKCONV macro is used to do the conversion. hh represents the hour (00-23). (TOD time interpreted as Zhhmmssxx). The 8 bytes of an input clock value, in the basic time-of-day (TOD) format, is converted to a Zhhmmssxx value. The STCKCONV macro is used to do the conversion. hh represents the hour (00-23), mm represents the minutes (00-59), ss represents the seconds (00-59) and xx represents hundredths of a second (00-99). (ETOD time interpreted as Zhhmmss). The first 8 bytes of an input clock value, in the extended time-of-day (ETOD) format, is converted to a Zhhmmss value. The STCKCONV macro is used to do the conversion. hh represents the hour (00-23), mm represents the minutes (00-59) and ss represents the seconds (00-59).

| |
DT2

|
DT3

|
DC1

|
DC2

|
DC3

|
DE1

| |
DE2

|
DE3

|
TM1

TM2 TM3 TM4

TC1

TC2

TC3

TC4

TE1

Appendix C. Data Format Descriptions

775

Data Format Examples

Format TE2 Description (ETOD time interpreted as Zhhmm). The first 8 bytes of an input clock value, in the extended time-of-day (ETOD) format, is converted to a Zhhmm value. The STCKCONV macro is used to do the conversion. hh represents the hour (00-23) and mm represents the minutes (00-59). (ETOD time interpreted as Zhh). The first 8 bytes of an input clock value, in the extended time-of-day (ETOD) format, is converted to a Zhh value. The STCKCONV macro is used to do the conversion. hh represents the hour (00-23). (ETOD time interpreted as Zhhmmssxx). The first 8 bytes of an input clock value, in the extended time-of-day (ETOD) format, is converted to a Zhhmmssxx value. The STCKCONV macro is used to do the conversion. hh represents the hour (00-23), mm represents the minutes (00-59), ss represents the seconds (00-59) and xx represents hundredths of a second (00-99).
1

TE3

TE4

The overpunch sign bit is always C for positive and D for negative.

Where DFSORT Formats Can be Used

The following tables show the statements, operands, and operators allowed with each of the various data formats.
Table 82. Allowed with Frequently Used Data Types PD or ZD FS or CSF UFF or SFF DTn, DCn, DEn, TMn, TCn, or TEn

Statement, Operand, or Operator DFSORT statements INCLUDE MERGE OMIT SORT SUM INREC statement operands IFTHEN WHEN=(logexp) FIELDS BUILD OVERLAY IFTHEN BUILD IFTHEN OVERLAY OUTREC statement operands IFTHEN WHEN=(logexp) FIELDS BUILD OVERLAY IFTHEN BUILD IFTHEN OVERLAY OUTFIL statement operands INCLUDE OMIT IFTHEN WHEN=(logexp) OUTREC

CH

BI or FI

X X X X

X X X X X

X X X X X

X X X X

X X X X

X X X X X X

X X X X X X

X X X X X X

X X X X X X X X X X X

X X X X X X

X X X X X X

X X X X X X

X X X X X X X X X X X

X X X

X X X X

X X X X

X X X X

X X X X X

776

z/OS V1R10.0 DFSORT Application Programming Guide

Data Format Examples

Table 82. Allowed with Frequently Used Data Types (continued) PD or ZD X X X X X FS or CSF X X X X X UFF or SFF X X X X X DTn, DCn, DEn, TMn, TCn, or TEn X X X X

Statement, Operand, or Operator BUILD OVERLAY IFTHEN BUILD IFTHEN OVERLAY TRAILERx ICETOOL operators DISPLAY (ON, BREAK) OCCUR (ON) RANGE (ON) SELECT (ON) SPLICE (ON) STATS (ON) UNIQUE (ON) VERIFY (ON) Table 83. Allowed with Other Data Types
Statement or Operand DFSORT statements INCLUDE MERGE OMIT SORT SUM INREC statement operands IFTHEN WHEN=(exp) FIELDS BUILD OVERLAY IFTHEN BUILD IFTHEN OVERLAY OUTREC statement operands IFTHEN WHEN=(exp) FIELDS BUILD OVERLAY IFTHEN BUILD IFTHEN OVERLAY OUTFIL statement operands INCLUDE OMIT IFTHEN WHEN=(exp) OUTREC BUILD OVERLAY AQ AC FL LS or CSL

CH

BI or FI X X X X X

X X

X X X

X X X X X X X X

X X X X X X X

X X X X X X X

X X

X X

X X X X

TS or OL or OT or CST CLO CTO

ASL

AST

D1

D2

PD0

Y2x

X X X X

X X X X

X X X

X X X X

X X X X

X X X X

X X X X

X X X X

X X X X

X X X X

X X X X

X X X X

X X X X X X

X X X X X X

X X X X X X

X X X X X X

X X X X X X

X X X X X X

X X X

X X X X X X

X X X

X X X

X X X

X X X

X X X

X X X

X X X X X X

X X X X X X

Appendix C. Data Format Descriptions

777

Data Format Examples

Table 83. Allowed with Other Data Types (continued)
Statement or Operand IFTHEN BUILD IFTHEN OVERLAY ICETOOL operators DISPLAY (ON) AQ AC FL X X X LS or CSL TS or OL or OT or CST CLO CTO ASL AST D1 D2 PD0 X X Y2x X X

DFSORT Formats for COBOL Data Types

Both DFSORT and COBOL support a large number of data types. COBOL describes these data types in one way, and DFSORT describes them in another way. If you SORT or MERGE with COBOL, the compiler automatically generates a SORT or MERGE control statement for you with the correct DFSORT descriptions for the COBOL fields you specify. But to take full advantage of DFSORT, you will often want to describe your fields in your own DFSORT control statements (for example, SORT, MERGE, INCLUDE, OMIT, INREC, OUTREC, OUTFIL, SUM) either outside of COBOL or in a DFSPARM data set used with COBOL. The table below will show you what DFSORT length and format to use for the various commonly used COBOL data types. For example, say you want to separate out records in a very large file into two data sets based on the values in a PIC S9(4) COMP field starting in position 21. In the first data set, you want records with values in the field that are greater than or equal to +5000. In the second data set, you want records with values in the field that are less than -1000. You could use the table below to determine that a PIC S9(4) COMP field is equivalent to a DFSORT field with a length of 2 and a format of FI, allowing you to code your DFSORT statements as follows:
OPTION COPY OUTFIL FNAMES=OUT1,INCLUDE=(21,2,FI,GE,+5000) OUTFIL FNAMES=OUT2,INCLUDE=(21,2,FI,LT,-1000) Table 84. Equivalent DFSORT formats for various COBOL data types
COBOL data type PIC X(n) USAGE DISPLAY GROUP DATA ITEMS with n bytes PIC 9(n) DISPLAY PIC S9(n) DISPLAY <TRAILING> PIC S9(n) DISPLAY LEADING PIC S9(n) DISPLAY SEPARATE <TRAILING> PIC S9(n) DISPLAY LEADING SEPARATE PIC 9(n) COMP|BINARY|COMP-4|COMP-5 n = 1 to 4 n = 5 to 9 n >= 10 PIC S9(n) COMP|BINARY|COMP-4|COMP-5 n = 1 to 4 n = 5 to 9 n >= 10 PIC 9(n) COMP-3|PACKED-DECIMAL PIC S9(n) COMP-3|PACKED-DECIMAL 2 4 8 (n/2)+1 (n/2)+1 FI FI FI PD PD 2 4 8 BI BI BI DFSORT Length n n n n n n+1 n+1 DFSORT Format CH CH ZD ZD CLO CST CSL or FS

778

z/OS V1R10.0 DFSORT Application Programming Guide

Data Format Examples

Table 84. Equivalent DFSORT formats for various COBOL data types (continued)
COBOL data type COMP-1 COMP-2 DFSORT Length 4 8 DFSORT Format FL FL

Notes: 1. PIC 9(x)V9(y) can be treated like PIC 9(n) where n=x+y. (COBOL does NOT store the decimal point internally.) 2. PIC S9(x)V9(y) can be treated like PIC S9(n) where n=x+y. (COBOL does NOT store the decimal point internally.)

Appendix C. Data Format Descriptions

779

Data Format Examples

780

z/OS V1R10.0 DFSORT Application Programming Guide

Appendix D. EBCDIC and ISCII/ASCII Collating Sequences

EBCDIC
Table 85 shows the collating sequence for EBCDIC character and unsigned decimal data. The collating sequence ranges from low (00000000) to high (11111111). The bit configurations which do not correspond to symbols (that is, 0 through 73, 81 through 89, and so forth) are not shown. Some of these correspond to control commands for the printer and other devices. ALTSEQ, CHALT, and LOCALE can be used to select alternate collating sequences for character data. Packed decimal, zoned decimal, fixed-point, and normalized floating-point data are collated algebraically, that is, each quantity is interpreted as having a sign.
Table 85. EBCDIC Collating Sequence Collating Sequence 0 . . 64 . . 74 75 76 77 78 79 80 . . 90 91 92 93 94 95 96 97 107 108 109 110 111 . . 122 123 124 125 Bit Configuration 00000000 Symbol Meaning

01000000

SP

Space

01001010 01001011 01001100 01001101 01001110 01001111 01010000

. < ( + I &

Cent sign Period, decimal point Less than sign Left parenthesis Plus sign Vertical bar, Logical OR Ampersand

01011010 01011011 01011100 01011101 01011110 01011111 01100000 01100001 01101011 01101100 01101101 01101110 01101111

! $ * ) ; / , % _ > ?

Exclamation point Dollar sign Asterisk Right parenthesis Semicolon Logical not Minus, hyphen Slash Comma Percent sign Underscore Greater than sign Question mark

01111010 01111011 01111100 01111101

: # @

Colon Number sign Commercial At Apostrophe, prime

Copyright IBM Corp. 1973, 2006

781

Table 85. EBCDIC Collating Sequence (continued) Collating Sequence 126 127 . . 129 130 131 132 133 134 135 136 137 . . 145 146 147 148 149 150 151 152 153 . . 162 163 164 165 166 167 168 169 193 194 195 196 197 198 199 200 201 . . 209 210 211 212 213 214 215 216 Bit Configuration 01111110 01111111 Symbol = Meaning Equal sign Quotation marks

10000001 10000010 10000011 10000100 10000101 10000110 10000111 10001000 10001001

a b c d e f g h i

10010001 10010010 10010011 10010100 10010101 10010110 10010111 10011000 10011001

j k l m n 0 p q r

10100010 10100011 10100100 10100101 10100110 10100111 10101000 10101001 11000001 11000010 11000011 11000100 11000101 11000110 11000111 11001000 11001001

s t u v w x y z A B C D E F G H I

11010001 11010010 11010011 11010100 11010101 11010110 11010111 11011000

J K L M N O P Q

782

z/OS V1R10.0 DFSORT Application Programming Guide

Table 85. EBCDIC Collating Sequence (continued) Collating Sequence 217 . . 226 227 228 229 230 231 232 233 . . 240 241 242 243 244 245 246 247 248 249 . . 255 Bit Configuration 11011001 Symbol R Meaning

11100010 11100011 11100100 11100101 11100010 11100111 11101000 11101001

S T U V W X Y Z

11110000 11110001 11110010 11110011 11110100 11110101 11110110 11110111 11111000 11111001

0 1 2 3 4 5 6 7 8 9

11111111

ISCII/ASCII
Table 86 shows the collating sequence for ISCII/ASCII, character, and unsigned decimal data. The collating sequence ranges from low (00000000) to high (01111111). Bit configurations that do not correspond to symbols are not shown. Packed decimal, zoned decimal, fixed-point normalized floating-point data, and the signed numeric data formats are collated algebraically; that is, each quantity is interpreted as having a sign.
Table 86. ISCII/ASCII Collating Sequence Collating Sequence 0 . . 32 33 34 35 36 37 38 39 . . Bit Configuration 00000000 Symbol Null Meaning

00100000 00100001 00100010 00100011 00100100 00100101 00100110 00100111

SP ! # $ % &

Space Exclamation point Quotation mark Number sign Dollar sign Percent Ampersand Apostrophe, prime

Appendix D. EBCDIC and ISCII/ASCII Collating Sequences

783

Table 86. ISCII/ASCII Collating Sequence (continued) Collating Sequence 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 Bit Configuration 00101000 00101001 00101010 00101011 00101100 00101101 00101110 00101111 00110000 00110001 00110010 00110011 00110100 00110101 001101100 00110111 00111000 00111001 00111010 00111011 00111100 00111101 00111110 00111111 01000000 01000001 01000010 01000011 01000100 01000101 01000110 01000111 01001000 01001001 01001010 01001011 01001100 01001101 01001110 01001111 01010000 01010001 01010010 01010011 01010100 01010101 01010110 01010111 01011000 01011001 01011010 01011011 01011100 Symbol ( ) * + , . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ Meaning Opening parenthesis Closing parenthesis Asterisk Plus Comma Hyphen, minus Period, decimal point Slash

Colon Semicolon Less than Equals Greater than Question mark Commercial At

Opening bracket Reverse slash

784

z/OS V1R10.0 DFSORT Application Programming Guide

Table 86. ISCII/ASCII Collating Sequence (continued) Collating Sequence 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 Bit Configuration 01011101 01011110 01011111 01100000 01100001 01100010 01100011 01100100 01100101 01100110 01100111 01101000 01101001 01101010 01101011 01101100 01101101 01101110 01101111 01110000 01110001 01110010 01110011 01110100 01110101 01110110 01110111 01111000 01111001 01111010 01111011 01111100 01111101 01111110 Symbol ] ^ _ ` a b c d e f g h i j k l m n o p q r s t u v w x y z { I } ~ Meaning Closing bracket Circumflex, Logical NOT Underscore Grave Accent

Opening Brace Vertical Line Closing Brace Tilde

Appendix D. EBCDIC and ISCII/ASCII Collating Sequences

785

786

z/OS V1R10.0 DFSORT Application Programming Guide

Appendix E. DFSORT Abend Processing

This appendix explains how DFSORT processes an abend. It is intended to help you get the dump you need to diagnose the error causing the abend. All abend dumps produced by DFSORT are system abend dumps that can be processed by standard dump analysis programs. A dump will be generated if you have included a SYSUDUMP, SYSABEND, or SYSMDUMP DD statement in your application. The actual output of the system dump depends on the system parameters specified in the IEADMP00, IEAABD00 or IEADMR00 members of SYS1.PARMLIB by your installation. At the beginning of each run, DFSORT establishes an ESTAE recovery routine to trap system or user abends for Blockset and Peer/Vale applications. You can delete the routine by specifying installation option ESTAE=NO, or by specifying NOESTAE on the DEBUG control statement. We recommend that you always run with ESTAE in effect so that in the event of an abend the following benefits are available: v In general, you get dumps closer to the time of the abend. v You get additional information useful in diagnosing the problem causing the abend. v If you have activated SMF, an ICETEXIT routine, or an EFS program, DFSORT attempts to continue processing. That is, an SMF record is created, the termination exit is called, or Major Calls 4 and 5 are made to the EFS program before the application terminates processing. Of course, if one of these functions caused the abend, that function will not complete successfully. At the end of its recovery routine, DFSORT always returns control to the system to allow termination to continue. The system will then invoke the next higher level ESTAE recovery routine.

Checkpoint/Restart
Checkpoint/Restart is a facility of the operating system that allows information about an application to be recorded so that same application can be restarted after abnormal termination or after some portion of the application has been completed. Restart can take place immediately or be deferred until the application is resubmitted. DFSORT takes checkpoints when requested during a sort that uses the Peerage or Vale techniques. To have DFSORT record checkpoints you must code a SORTCKPT DD statement and ensure the Peerage or Vale technique is selected. See SORTCKPT DD Statement on page 76 and OPTION Control Statement on page 167 for more information on the SORTCKPT and CKPT options, respectively. In general, no checkpoints are taken if the following conditions exist: v No work data set is specified. v The application is a copy or merge. v Blockset is selected.
Copyright IBM Corp. 1973, 2006

787

Abend Processing
Notes: 1. No ANSI Standard Label tape files can be open during Checkpoint/Restart processing. 2. Do not specify CHKPT=EOV on any DFSORT DD statement. For more information on the Checkpoint/Restart facility, see z/OS DFSMSdfp Checkpoint/Restart.

DFSORT Abend Categories

There are two categories of abends for DFSORT: unexpected abends and user abends issued by DFSORT. v Unexpected abends These are system abends or user abends not issued by DFSORT. The abend code in these cases is the system abend code or the user abend code. See z/OS DFSORT Messages, Codes and Diagnosis Guide for information about detecting common user errors and reporting DFSORT program failures. v User abends issued by DFSORT DFSORT will issue user abends under the following circumstances: The ABEND or ABSTP option is in effect and DFSORT encounters an error that prevents completion of the run. DFSORT detects an error in its internal logic. See z/OS DFSORT Messages, Codes and Diagnosis Guide for complete information about user abends issued by DFSORT.

Abend Recovery Processing for Unexpected Abends

DFSORT normally has an ESTAE recovery routine established to trap system or user exit routine abends for Blockset and Peer/Vale applications. If an abend occurs, the system will pass control to this routine. The DFSORT ESTAE recovery routine functions are shown below: v Abend dump The recovery routine will first have the system issue an abend dump to capture the environment at the time the error occurred. v Termination functions DFSORT tries to accomplish the following tasks when they are specified, whether the program terminates normally or abnormally. Calls 4 and 5 to an EFS program Create the SMF record Call the ICETEXIT routine The DFSORT recovery routine runs any of the functions specified above if they have not already been run at the time of the abend. v Abend information message For unexpected system or user exit routine abends, the DFSORT recovery routine issues message ICE185A giving information about when the abend occurred. The description of this message is in z/OS DFSORT Messages, Codes and Diagnosis Guide. v Snap dumps The DFSORT recovery routine provides a snap dump of the system diagnostic work area (SDWA). The snap dumps are written to a dynamically allocated data set whether or not a SYSUDUMP (or SYSABEND or SYSMDUMP) DD statement is included in the application.

788

z/OS V1R10.0 DFSORT Application Programming Guide

Abend Processing
v Copy system diagnostic work area If an invoking program passes the address of an SDWA area in the 24-bit or extended parameter list, DFSORT will copy the first 104 or 112 bytes of the system diagnostic work area into the user SDWA area. See Chapter 5, Invoking DFSORT from a Program, on page 461 for more information. v Continuation of an application after successful SORTOUT output If an unexpected abend occurs after the sort, merge, or copy application writes the SORTOUT data set successfully, DFSORT issues message ICE186A and completes its normal cleanup and termination functions. The SORTOUT data set written by DFSORT is closed. The run is successful except for the function causing the abend. Message ICE186A says that the SORTOUT data set is usable even though the run has abended. You can then decide to use the SORTOUT data set or rerun the application. v DFSORT returns control to the system at the end of its abend recovery processing so that recovery routines can be invoked. The DFSORT abend recovery routine functions described above may not be performed after an abend if NOESTAE is in effect. The DFSORT ESTAE recovery routine is always established at the beginning of a run. It is deleted early in DFSORT processing if NOESTAE is in effect.

Processing of Error Abends with A-Type Messages

When DFSORT encounters a critical error, it issues an A-type message and terminates. You can specify that DFSORT is to terminate the application with an abend through the ABEND or ABSTP options. If abend termination is in effect and DFSORT encounters a critical error, DFSORT first causes an abend dump to capture the environment at the time of the error. Then, it issues the A-type message. It also runs the termination functions described earlier before terminating with an abend. The abend code will be the error message number, or a number between 1-99, as determined during installation with the ABCODE installation option. With NOESTAE and ABEND in effect, the abend dump is produced after the A-type message is printed and other termination functions are run. As a result, the dump produced might not reflect the conditions at the time of the error. It may not include the module that encountered the error. With NOESTAE and ABSTP in effect, the correct module will be dumped but the A-type message will not be issued.

CTRx Abend processing

The CTRx option can be used to diagnose a problem by requesting that DFSORT abend during record input or output processing. See the DEBUG control statement in Chapter 3, Using DFSORT Program Control Statements, on page 81. DFSORT will cause an 0C1 abend when the CTRx count is satisfied. The DFSORT ESTAE recovery routine will process the abend in the same way as it does for an unexpected abend described earlier. The DFSORT ESTAE recovery routine will return control to the system, which will pass control to any ESTAE recovery routines established by invoking programs.

Appendix E. DFSORT Abend Processing

789

Abend Processing
As described earlier, the DFSORT ESTAE recovery routine will save the first 104 or 112 bytes of the system diagnostic work area in the invoking programs SDWA area if the address of the area is passed to DFSORT. Since PL/I normally has an ESPIE in effect to intercept program checks (0Cx abend codes), the DFSORT ESTAE recovery routine is not entered after these errors unless you have specified NOSPIE. DFSORT abend recovery processing will occur for all other types of abends. Invocations from COBOL programs or use of COBOL exits can result in more than one abend dump.

790

z/OS V1R10.0 DFSORT Application Programming Guide

Appendix F. Accessibility
Accessibility features help a user who has a physical disability, such as restricted mobility or limited vision, to use software products successfully. The major accessibility features in z/OS enable users to: v Use assistive technologies such as screen readers and screen magnifier software v Operate specific or equivalent features using only the keyboard v Customize display attributes such as color, contrast, and font size

Using assistive technologies

Assistive technology products, such as screen readers, function with the user interfaces found in z/OS. Consult the assistive technology documentation for specific information when using such products to access z/OS interfaces.

Keyboard navigation of the user interface

Users can access z/OS user interfaces using TSO/E or ISPF. Refer to z/OS TSO/E Primer, z/OS TSO/E Users Guide, and z/OS ISPF Users Guide Vol Ifor information about accessing TSO/E and ISPF interfaces. These guides describe how to use TSO/E and ISPF, including the use of keyboard shortcuts or function keys (PF keys). Each guide includes the default settings for the PF keys and explains how to modify their functions.

z/OS information
z/OS information is accessible using screen readers with the BookServer/Library Server versions of z/OS books in the Internet library at:
http://www.ibm.com/systems/z/os/zos/bkserv/

Copyright IBM Corp. 1973, 2006

791

792

z/OS V1R10.0 DFSORT Application Programming Guide

Notices
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the users responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATIONAS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation Mail Station P300
Copyright IBM Corp. 1973, 2006

793

2455 South Road Poughkeepsie, NY 12601-5400 USA Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.

Programming Interface Information

This publication primarily documents information that is NOT intended to be used as Programming Interfaces of DFSORT. This publication also documents intended Programming Interfaces that allow the customer to write programs to obtain the services of DFSORT. This information is identified where it occurs, either by an introductory statement to a chapter or section or by the following marking: Programming Interface information End of Programming Interface information

Trademarks
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:
DFSMSrmm DFSORT ESCON Hiperspace IBM IBMLink Language Environment RACF RAMAC Resource Linkz/OS z/VM 3090

Linux is a trademark of Linus Torvalds in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others.

794

z/OS V1R10.0 DFSORT Application Programming Guide

Index Special characters

/OT (trailing overpunch sign) format description 772 % parameter of PARSE operand on OUTFIL statement 235 %nn parameter of PARSE operand on OUTFIL statement 235 ALIAS statement 421 aliases DFSORT 27 OPTION statement options 216 PARM options 60 alignment field 130, 370 allocating storage intermediate storage 692 main storage 689 temporary work space 692 allocating temporary work space efficiently 692, 694 altering records 418 See also reformatting records 125 ALTSEQ installation option 18 ALTSEQ control statement 91 examples 90 function 84 TABLE Option 89 using 89, 91 ALTSEQ Statement Examples 90, 91 AMODE 419, 423 AQ (character EBCDIC, with alternate collating sequence, unsigned) format description 770 where allowed 777 ARESALL EXEC PARM option 33 installation option 18 OPTION control statement option 170 releasing main storage 691 using RESERVEX instead of ARESALL 34 ARESINV installation option 18 OPTION control statement option 170 releasing main storage 691 arithmetic INREC 138 OUTFIL 275 OUTREC 377 ASL (ISCII/ASCII leading sign) format description 772 where allowed 777 Assembler user exit routines input phase user exits 423, 433 output phase user exits 433, 439 AST (ISCII/ASCII trailing sign) format description 772 where allowed 777 ATTACH description 461 writing macro instructions 473 Attention do not return return code 420 Explanation field length 471 invalid syntax for incorrectly placed blanks 88 Attention (continued) performance degradation 34 RDW 255, 256, 257, 258, 373 reformatted input record 134 TRAN=ALTSEQ 258, 259 unpredictable results with order of data sets when using BSAM processing with concatenated SORTIN input 93 using the SIZE or FILSZ parameter 184 using TRAN=UTOL for numeric data 257, 258 when USING(xxxx) is not specified 605 where USING(xxxx) is not specified 549 AVGRLEN EXEC PARM option 34 OPTION control statement option 171

Numerics
24-bit parameter list examples 473, 476 format 464, 469

A
ABCODE ABEND Code 33 installation option 18 abend categories 788 checkpoint/restart 787 critical 789 CTRx processing 789 processing 787, 790 processing for unexpected abends 788, 789 recovery 788, 789 ESTAE 787 ABEND DEBUG control statement option 92 EXEC PARM option 33 ABSPOS=p parameter of PARSE operand on OUTFIL statement 237 ABSTP DEBUG control statement option 93 processing 788 AC (ISCII/ASCII character) format description 770 where allowed 777 accessibility 791 action codes 659 adding fields and constants INREC 138 OUTFIL 275 OUTREC 377 adding record values 2 adding records 418 E15 user exit 424, 445 E35 user exit 451 ADDPOS=x parameter of PARSE operand on OUTFIL statement 237 addressing EFS program 648 EFS program user exit routine 673 user exits 419 Copyright IBM Corp. 1973, 2006

B
BI (binary) format description 770 where allowed 777 bit comparison tests 114 bit operators 114 BLDINDEX 699 BLKCCH1 parameter OUTFIL control statements option 339 BLKCCH2 parameter OUTFIL control statements option 339 BLKCCT1 parameter OUTFIL control statements option 340 block minimum length 14 blocking records 682 Blockset DFSORT 23 BSAM DEBUG control statement option E18 user exit 428 E19 user exit 431 EXEC PARM option 34 BUILD parameter INREC statement 128 OUTFIL statement 224, 244 OUTREC statement 368

93

C
cache fast write specifying use of with OPTION control statement 93 using to improve performance 685

795

cataloged procedures defined 27 SORT 27 SORT cataloged procedure 27 SORTD 28 SORTD cataloged procedure 28 specifying 27 century window 215, 352, 402, 751 CFW installation option 18 using on OPTION control statement 93 using to improve performance 685 CH (character) format description 769 where allowed 777 CHALT installation option 18 OPTION control statement option 171 changing records 418 E15 user exit 424, 445 E35 435, 436 E35 user exit 451 See also reformatting records 125 changing the collating sequence 89 character constants 106, 131, 249, 309, 316, 370 character strings for current date 107 for future date 108 for past date 108 CHECK installation option 18 OPTION control statement option 172 checkpoint/restart (CHKPT) restrictions 788 using 787 CINV EXEC PARM option 35 installation option 18 OPTION control statement option 172 CKPT efficiency 688 OPTION control statement option 173 SORT control statement option 404 CLIST examples 703 CLO (leading overpunch sign) format description 772 where allowed 777 closing data sets E17 user exit 427 E37 user exit 438 housekeeping 657 with an EFS program 653, 657 with user exits 419 COBEXIT EXEC PARM option 35 installation option 18 OPTION control statement option 173 COBOL input phase user exits 445 output phase user exit 451

COBOL (continued) overview 443 requirements for copy processing 444 storage requirements 444 user exit routine requirements 443 user exit routines 443, 445, 451 COBOL E15 user exit altering records 456 changing records for Sort 445 passing records for Sort 445 COBOL E35 user exit changing records 451 inserting records 457 CODE ALTSEQ control statement option 89 coding control statements 84 coding restrictions 89 collating sequence 89 altering with user exit 418 alternate 6 defined 6 EBCDIC 6 ISCII/ASCII 6 modifying 6 combining data sets See merging records 156 comment statement 88 Compare Field Formats and Lengths Table 102 comparison operator 101, 120 comparisons OMIT control statement 164 COND INCLUDE control statement option 100 OMIT control statement option 165 considerations data set 12 key-sequenced data set (KSDS) 16 QSAM data set 15 record descriptor word (RDW) 16 VSAM data set 16 constants bit string 118, 127 character string 106, 131, 249, 309, 316, 370 for current date 107 for future date 108 for past date 108 date string 121 decimal number 104 for current date 105 for future date 105 for past date 106 for current date 249 for future date 250 for past date 251 hexadecimal string 109, 131, 249, 309, 316, 371 continuation column 86 continuation lines 86, 87 continuing control statements 87 control field defined 5, 6 deleting with INREC control statement 125

control field (continued) deleting (continued) with OUTREC control statement 365 describing on MERGE control statement 157 describing on SORT control statement 399 efficient design 682 equal 6 format 401 length 401 modifying with E61 user exit 432 modifying with user exit 418 overview 5, 6 reordering with INREC control statement 125 with OUTREC control statement 365 Control Field Formats and Lengths Table 401 control statement coding 84 coding restrictions 89 comment statement 88 continuation column 86 EFS coding rules 660, 662 EFS interface request list 660 EFS string 660 examining, altering, or ignoring 655 format 85 functions 83, 84 label field 85 operand field 85 operation field 85 overview 82 preparing image 463 printing with an EFS program 657 remark field 86 request list 660 string returned by the EFS program 662 string sent to the EFS program 660 summary 83, 84 using with EXEC statement 29 control statements using other IBM programs 89 control word 399 conventions, notational xvi CONVERT parameter OUTFIL control statements option 224, 290 COPY OPTION control statement option 174 copy examples 724, 726 COPY operator (ICETOOL) 491 copy restrictions 477 copying data set requirements 12 defined 1 overview 12 copying records SORT control statement option 404 with MERGE control statement 157 COUNT operator (ICETOOL) 494

796

z/OS V1R10.0 DFSORT Application Programming Guide

critical errors 789 CSF (floating sign) format description 771 where allowed 777 CSL (leading sign) format description 772 where allowed 777 CST (trailing sign) format description 772 where allowed 777 CTO (trailing overpunch sign) format description 772 where allowed 777 CTRx abend processing 789 DEBUG control statement option 94 cultural environment See LOCALE 7 current date character string for 107 decimal number constant for 105 cylinders 684, 737

D
D1 (EFS type) format description 770 where allowed 777 D2 (EFS type) format description 770 where allowed 777 data formats 514 descriptions 769 where allowed 777 data management rules system data management rules 13 data set 12 closing 419 closing with user exit routines 427, 438 defining 12 handling input with user exit routines 439 handling output with user exit routines 439 input 11 shared tape unit 64 key-sequenced, considerations 16 message data set 23 notes and limitations 13, 16 opening with user exit routines 417, 423, 434 output 12 shared tape unit 64 page=end.considerations 16 QSAM considerations 15 requirements 12 system data management rules 13 valid types 12 VSAM considerations 16 data space definition 175 specifying with EXEC PARM 36 specifying with OPTION control statement 175 data types 13

dataspace sorting advantages 694 considerations 694 definition 694 date comparisons 119 date constant 107, 121, 132, 371 date constants 249 date formats descriptions 775 where allowed 777 DBCS ordering 647 DCn (TOD date) format description 775 where allowed 777 DD statements overview 61 program DD statements 66 summary 25 system DD statements 64 using 61, 79 ddnames duplicate 64 DEBUG control statement example 92, 97 function 84 special handling 661 using 92, 97 DEBUG Statement Examples 97 debugging jobs 92 decimal number constants 104 for current date 105 for future date 105 for past date 106 defaults installation 16 listing with ICETOOL 18 DEFAULTS operator (ICETOOL) 497 defaults, installation 16 definitions cataloged procedures 27 collating sequence 6 control field 5 copying 1 DD statements 25 direct invocation 5 EXEC statement 27 installation options 18, 22 JOB statement 27 key 5 merging 1 program invocation 5 sorting 1 deleting control fields with INREC 125 with OUTREC control statement 370 deleting records 418 E15 user exit 424, 445 E35 user exit 451 with INCLUDE control statement 98, 163 with OMIT control statement 163 DEn (ETOD date) format description 775 where allowed 777 designing applications to maximize performance 682, 689 designing new applications 682

determining action when intermediate storage is insufficient 419 devices, improving elapsed time with 685 DFSORT 16 calls to your EFS program 649 dynamic invocation 461 exit routines 413 improving efficiency 681 invoking 4 job control statements 25, 79 logic examples for input/user exit/output 416 messages 22 override of options 741 overview 1 processing order 7 processing OUTFIL operands 226 program control statements 82, 412 program phases 414, 649 terminating with user exit 419 DFSORT home page 4 DFSORT phases definition 649 initialization 651, 677 input 653 termination 653, 679 DFSPARM data set 742 DFSPARM DD statement defined 26 function 67 using 77, 79 DFSPARM statement PARM options 29 alias PARM options 60 diagnosis EFS program 676 diagnostic messages 23 DIAGSIM installation option 18 direct invocation definition 5 DFSORT processing 682 using JCL 744 disability 791 disk capacity considerations 737 efficiency 684, 692 exceeding capacity 737 disk storage devices See disk 684 disk work storage devices 692 DISPLAY operator (ICETOOL) 502 dividing fields and constants INREC 138 OUTFIL 275 OUTREC 377 Double Byte Character Set (DBCS) ordering See DBCS ordering 13 Double Byte Character Set Ordering Support Program See DBCS ordering 647 DSA EXEC PARM option 36 OPTION control statement option 174 Index

797

DSA (Dynamic Storage Adjustment) enhancing performance 685 installation option 18 limit 745, 753, 761 DSPSIZE enhancing performance 685 EXEC PARM option 36 installation option 19 OPTION control statement option 175 DTn (SMF date) format description 775 where allowed 777 duplicate ddnames 64 duplicate records OCCUR operator (ICETOOL) 549 SELECT operator (ICETOOL) 566 SUM control statement 408 DYNALLOC EXEC PARM option 37 OPTION control statement option 176 SORT control statement option 404 DYNALLOC=OFF EXEC PARM option 37 OPTION control statement option 177 DYNALOC installation option 19 dynamic link-editing See link-editing 423 Dynamic Storage Adjustment (DSA) enhancing performance 685 installation option 18 limit 745, 753, 761 dynamically-invoked DFSORT with the 24-bit parameter list 760, 769 with the extended parameter list 752, 760 DYNAUTO installation option 19 DYNSPC EXEC PARM option 38 installation option 19 OPTION control statement option 178

E
E11 user exit initializing routines 423 opening data sets 423 E15 user exit changing records for sort and copy applications 424 EXEC PARM option 39 passing records for sort and copy applications 424 return codes 425 E15 User Exit altering record length 440 interface with COBOL 445 LINKAGE SECTION code example for fixed-length records 448 LINKAGE SECTION code example for variable-length records 449

E15 User Exit (continued) LINKAGE SECTION fields for fixed-length records 448 LINKAGE SECTION fields for variable-length records 448 PROCEDURE DIVISION requirements 450 return codes 449 E15/E35 return codes and EXITCK 458, 460 E16 user exit handling intermediate storage miscalculation 427 return codes 427 sorting current records when NMAX is exceeded 441 E17 user exit closing data sets 427 E18 user exit handling input data sets 427 using with QSAM/BSAM 428 using with VSAM 429 E19 user exit handling output to work data sets 431 using with QSAM/BSAM 431 E31 user exit initializing routines 434 opening data sets 434 E32 user exit handling input to a merge only 434 restriction with MERGE control statement 160 return codes 435 E35 user exit altering record length 441 Changing Records 435 EXEC PARM option 39 interface with COBOL 451 LINKAGE SECTION fields for fixed-length records 453 LINKAGE SECTION fields for variable-length records 453 Procedure Division Requirements 456 return codes 437 E37 user exit closing data sets 438 E38 user exit handling input data sets 439 using with VSAM 439 E39 user exit handling output data sets 439 using with QSAM/BSAM 439 using with VSAM 439 E61 user exit altering control fields 442 information DFSORT passes to your routine 433 modifying control fields 432 uses 432 edit masks ICETOOL DISPLAY operator 509, 510 OUTFIL 264, 272 editing records See reformatting records 125

efficiency using main storage 681 EFS 663 efficiency 689 EXEC PARM option 38 exit routines 653 initialization phase 651 input phase 653 installation option 19 OPTION control statement option 179 phases 649 processing 649 termination phase 653 using 647, 679 what you can do with EFS 654, 657 EFS interface control statement length 666 control statement request list 660 control statement string 660, 662 D1 format 663 D2 format 664 defined 657 DFSORT action codes 659 extract buffer offsets list 666 function 648 information flags 667 message list 668 program context area 666 record lengths list 666 EFS program addressing and residence mode 648 closing data sets 657 context area 666 examining, altering, ignoring control statements 655 example 677 exit routine 657, 670, 671 function 669 functions 647, 654 interface parameter list 657, 669 opening and initializing data sets 655 restrictions program in effect 89 restrictions when program in effect 89 return codes you must supply 674 supplying messages 657 terminating DFSORT 657 user exit routine addressing and residence mode 673 EFS Program example 679 EFS01 function description 669 parameter list 671 user exit routine 670 EFS02 address=0 679 function description 669 parameter list 672 user exit routine 671 EFSDPAFT 676 DEBUG control statement option 94 EFSDPBFR 676 DEBUG control statement option 94

798

z/OS V1R10.0 DFSORT Application Programming Guide

elapsed time improving with devices 685 END control statement examples 97 function 84 using 97, 98 ENDAT=BLANKS parameter of PARSE operand on OUTFIL statement 242 ENDAT=string parameter of PARSE operand on OUTFIL statement 241 ENDBEFR=BLANKS parameter of PARSE operand on OUTFIL statement 241 ENDBEFR=string parameter of PARSE operand on OUTFIL statement 240 ENDREC parameter OUTFIL control statements option 224, 228 enhancing performance with installation options 685 EODAD 429 EQUALS 6 efficiency 688 EXEC PARM option 39 installation option 19 MERGE control statement option 158 OPTION control statement option 180 SORT control statement option 405 EQUCOUNT DEBUG control statement option 95 efficiency 688 ERET installation option 19 EROPT 428 error messages 23 error recovery routine user exit 418 errors critical 789 debugging jobs 92 diagnosing EFS 676 error recovery routines 418 ESTAE DEBUG control statement option 95 installation option 19 recovery routine 787 ETOD date (DEn) and time (TEn) formats descriptions 775 where allowed 777 exceeding tape work space capacity 738, 739 EXEC statement cataloged procedure SORT 27, 66 SORTD 28, 66 cataloged procedures 27 defined 27 operands 30, 59 PARM options 29, 742 alias PARM options 60 syntax 30 using 27, 61 using with control statements 29

execution phase 649 exit MODS control statement option 160 See also user exit 413 exit routine EFS 669 EXITCK ICEMAC installation option 424, 458 installation option 19 OPTION control statement option 181 user exit return codes 458 EXLST 428, 432 EXPMAX installation option 19, 687, 731 EXPOLD installation option 19, 687, 731 EXPRES installation option 19, 687, 731 Extended Function Support See EFS 647 extended parameter list example 476 format 470, 473 extract buffer offsets list 666

F
FASTSRT efficiency 686 FI (fixed-point) format description 770 where allowed 777 Field and Constant Symbols overview 617 field formats compare 102 control 401 ICETOOL operators DISPLAY 506 RANGE 552, 564 SELECT 569 STATS 604 UNIQUE 606 VERIFY 608 summary 409 fields fixed position/length 1 variable position/length 1 FIELDS parameter INREC statement 128 MERGE statement 157 OUTREC statement 368 SORT statement 399 SUM statement 408 FIELDS=(COPY) SORT control statement option 404 FIELDS=COPY MERGE control statement option 157 SORT control statement option 404 FILES parameter MERGE control statement option 158 OUTFIL control statements option 223, 227 FILSZ EXEC PARM option 40 variation summary 41 MERGE control statement option 158 OPTION control statement option 181

FILSZ (continued) SORT control statement option 405 filtering records 98, 163 fixed century window 215 fixed parsed fields extracting variable position/length fields into INREC control statement 128 OUTFIL control statement 232 OUTREC control statement 367 fixed position/length fields 1 FIXLEN=m parameter of PARSE operand on OUTFIL statement 236 FL ( hexadecimal floating-point) format description 770 FL (hexadecimal floating-point) format where allowed 777 floating-point data 124, 403, 418 floating-point fields 410 FNAMES parameter OUTFIL control statements option 223, 226 format alternate character format See AQ (alternate character) format binary format See BI (binary) format character format See CH (character) format date formats See DCn, DEn, DTn fixed-point format See FI (fixed-point) format floating sign format See CSF/FS (floating sign) format floating-point format See FL (floating-point) format ISCII/ASCII character format See AC (ISCII/ASCII character) format ISCII/ASCII leading sign format See ASL (ISCII/ASCII leading sign) format ISCII/ASCII trailing sign format See AST (ISCII/ASCII trailing sign) format leading overpunch sign format See CLO/OL (leading overpunch sign) format leading sign format See CSL/LS (leading sign) format packed decimal format See PD (packed decimal) format signed free form format See SFF (signed free form) format time formats See TCn, TEn, TMn trailing overpunch sign format See CTO/OT (trailing overpunch sign) format trailing sign format See CST/TS (trailing sign) format unsigned free form format See UFF (unsigned free form) format

Index

799

format (continued) user defined format (D1) See D1 format user defined format (D2) See D2 format zoned decimal format See ZD (zoned decimal) format format of 24-bit parameter list 464, 469 format of extended parameter list 470, 473 FORMAT=f INCLUDE control statement option 98, 100 MERGE control statement option 158 OMIT control statement option 163, 165 SORT control statement option 404 SUM control statement option 409 formatting OUTFIL 261 four-digit year transforming dates 215 FS (floating sign) format description 771 where allowed 777 FSZEST installation option 19 FTOV parameter OUTFIL control statements option 225, 301 FTP site 4 functions of routines at user exits 416, 419 future date character string for 108 decimal number constant for 105

HEADER2 parameter OUTFIL control statements option 225, 321 HEADER3 parameter OUTFIL control statements option 331 hexadecimal constants 109, 131, 249, 309, 316, 371 hexadecimal display DISPLAY operator 514 OCCUR operator 555 HFS 16 HILEVEL=YES MODS control statement option 161 Hipersorting advantages to using 694 defined 694 Hiperspace defined 694 limiting factors 185 HIPRMAX efficiency 694 EXEC PARM option 42 installation option 19 OPTION control statement option 185 home page (web) 4 how EFS works 648, 654 how user exit routines affect DFSORT performance 420

I
I/O errors 418 ICEGENER efficiency 696 example 728 return codes 699 ICEGENER facility 696, 699 ICEMAC installation options 18, 22 ICETOOL 480 calling from a program 609 coding rules 490 complete sample job 729 description 480 example of simple job 482 examples 484, 485, 493, 497, 531, 547, 560, 565, 571, 577, 587, 604, 606, 608 ICETOOL/DFSORT relationship 480 invoking 483 JCL 481 DFSMSG DD statement 481 JOBLIB DD statement 481 restrictions 489 statements 487 STEPLIB DD statement 481 summary 481 SYMNAMES DD statemen 481 SYMNOUT DD statemen 481 TOOLIN DD statement 481, 488 TOOLMSG DD statement 481, 487 operators 481 COPY 482, 486, 491 COUNT 482, 494 DEFAULTS 497 DISPLAY 482, 484, 502

G
GENER installation option 19 general coding rules 84, 89 general considerations 13, 14 GNPAD installation option 19, 698 GNTRUNC installation option 19, 698

H
handling input data sets E18 user exit 427 E38 user exit 439 handling input to a merge E32 user exit 434 handling intermediate storage miscalculation E16 user exit 427 handling output data sets E39 user exit 439 handling output to work data sets E19 user exit 431 handling special I/O 418 HEADER parameter DISPLAY operator 520 OCCUR operator 559 HEADER1 parameter OUTFIL control statements option 225, 308, 313

ICETOOL (continued) operators (continued) MODE 482, 484, 485, 486, 546 OCCUR 482, 485, 548 RANGE 482, 484, 563 SELECT 482, 486, 566 SORT 482, 486, 575 SPLICE 482, 579 STATS 482, 484, 603 summary 481 UNIQUE 482, 486, 605 VERIFY 482, 484, 607 Parameter List Interface 483, 488, 609 restrictions 615 return codes 616 statements 490 TOOLIN Interface 483, 488, 609 using symbols 483 IDRCPCT installation option 19 IEBGENER 696 IEFUSI 691, 692 IEXIT installation option 19 IFTHEN parameter INREC statement 143 OUTFIL statement 224, 244 OUTREC statement 382 IGNCKPT installation option 19 improving efficiency 681, 699 INCLUDE control statement efficiency 687 examples 110, 119 function 83 logical operator 124 relational condition 101 comparison operator 101, 120 substring comparison operator 113 INCLUDE parameter OUTFIL control statements option 224, 229 INCLUDE/OMIT statement notes 124 INCLUDE/OMIT Statement Notes 125 including records 1, 98, 163 user-defined data types 647 information DFSORT passes to your routine E15 user exit 425 E32 user exit 434 E35 user exit 436 E61 user exit 433 information flags 667 Initialization Phase 651 initializing data sets 417, 651 initializing routines E11 user exit 423 E31 user exit 434 initiating DFSORT See invoking DFSORT 461 INPFIL control statement 89 input data set requirements 12 valid types 12 input data sets missing attributes of set by DFSORT 69 input field 134 input file size and efficiency 684

800

z/OS V1R10.0 DFSORT Application Programming Guide

Input Phase 653 INREC control statement column alignment 130 examples 149, 151, 152 function 83 input field 134 notes 147, 149 separation field binary zero separation 131 blank separation 130 character string separation 131 hexadecimal string separation 132 using 125, 151, 152 inserting comment statements 88, 89 inserting records 418 installation defaults 16 displaying with DEFAULTS operator (ICETOOL) 497 listing with ICETOOL 18 summary of options 18 installation options 18, 22, 169 installation options, using to enhance performance 685 insufficient intermediate storage 737 intermediate storage 739 Internet 4 introducing DFSORT 1, 23 invoking DFSORT 24-bit parameter list 463, 469 dynamically 461 extended parameter list 470, 473 from a program 461, 477 methods 4 using JCL 25 IOMAXBF installation option 20

K
keeping records 1 key-sequenced data set (KSDS) key, defined 5 keyboard 791 16

lookup and change 225, 277, 350 LS (leading sign) format description 772 where allowed 777

M L
label field 85 length altered control statement 666 LRECL for variable-length record 16 maximum record 14 original control statement 666 record descriptor word (RDW) 16 record lengths list 666 limitations data set 13 length maximum record 14 minimum block 14 minimum record 14 record maximum length 14 storage constraints 14 LINES parameter OUTFIL control statements option 225 LINK 461 writing macro instructions 473 link-editing performance 689 user exit routines 423 linkage conventions 421 linkage editor 66 linkage examples 422 LIST EXEC PARM option 43 installation option 20 OPTION control statement option 186 with an EFS program 657 LISTX EXEC PARM option 43 installation option 20 OPTION control statement option 187 with an EFS program 657 loading user exit routines 421 locale affecting INCLUDE and OMIT processing 110 affecting MERGE processing 157 defined 7 restrictions CHALT 172 EFS 38, 179 LOCALE efficiency 687, 688 EXEC PARM option 44 installation option 20 OPTION control statement option 188 using 6 logical operator 124 LookAt message retrieval tool xv macro instructions See system macro instructions 461 main features of sources of DFSORT options 742, 743 main storage allocating consequences of increasing 691 allocating efficiently 689 minimum 689 releasing 691 tuning 689 using efficiently 689, 692 MAINSIZE See also SIZE allocating storage 689 OPTION control statement option 189 releasing main storage 691 Major Call 1 677 Major Call 2 677 Major Call 3 678 Major Call 4 679 Major Call 5 679 major control field See control field managing system data, rules system data management rules 13 master console messages 23 Match SPLICE operator 579 MAX EXEC PARM option 52 maximizing performance 681 maximum of fields and constants INREC 138 OUTFIL 275 OUTREC 377 MAXLIM allocating storage 689 installation option 20 releasing main storage 691 memory object definition 190 specifying with EXEC PARM 44 specifying with OPTION control statement 190 memory object sorting advantages 695 considerations 695 definition 695 MERGE control statement examples 159, 160 function 83 using 156, 160 merge examples 722, 724 merge restriction 477 merging data set requirements 13 defined 1 overview 13 Index

J
Japanese characters 13, 647 JCL 25 cataloged procedure 66 cataloged procedures, specifying 27 DD statement summary 25 EFS coding rules 661 EXEC statement 27 improving DFSORT efficiency 682 JOB statement 27 overview 25 procedures, cataloged 27 required 25 JCL DD statements 462 JCL DD Statements 471 JCL-invoked DFSORT 744, 752 job control language see also JCL 25 JOB statement defined 27 using 27 JOBLIB DD statement defined 25 using 64 Join SPLICE operator 579

801

merging (continued) records 156 specifying the estimated number of records to merge 41 specifying the exact number of records to merge 40 specifying the number of records to merge 41 user-defined data types 647, 653 message data set 23 message list 668 message retrieval tool, LookAt xv messages master console messages 23 message data set 23 return codes 22 migration 22 minimum block length 14 minimum of fields and constants INREC 138 OUTFIL 275 OUTREC 377 minimum record length 14 MINLIM allocating storage 690 installation option 20 minor control field See control field missing attributes of input data sets set by DFSORT 69 modifying 89 modifying control fields E61 user exit 432 with user exit 418 modifying the collating sequence 89 MODS control statement examples 163 function 84 using 160, 163 modulus of fields and constants INREC 138 OUTFIL 275 OUTREC 377 MOSIZE enhancing performance 687 EXEC PARM option 44 installation option 20 OPTION control statement option 190 MSGCON installation option 20 MSGDDN EXEC PARM option 45 installation option 20 OPTION control statement option 192 MSGPRT alternate forms 46 EXEC PARM option 45 installation option 20 OPTION control statement option 192 multiple output data sets creating with OUTFIL 4, 222, 344 multiplying fields and constants INREC 138 OUTFIL 275 OUTREC 377

N
NOABEND DEBUG control statement option 92 EXEC PARM option 33 NOASSIST DEBUG control statement option 96 NOBLKSET efficiency 689 OPTION control statement option 193 NOCFW using on OPTION control statement 93 NOCHALT OPTION control statement option 171 NOCHECK OPTION control statement option 172 NOCINV efficiency 688 EXEC PARM option 35 OPTION control statement option 172 NODETAIL parameter OUTFIL control statements option 225, 339 NOEQUALS EXEC PARM option 39 MERGE control statement option 158 OPTION control statement option 180 NOESTAE DEBUG control statement option 95 NOHEADER parameter DISPLAY operator 521 OCCUR operator 559 NOLIST EXEC PARM option 43 OPTION control statement option 186 with an EFS program 657 NOLISTX EXEC PARM option 43 OPTION control statement option 187 with an EFS program 657 NOMSGDD installation option 20 NOOUTREL EXEC PARM option 48 OPTION control statement option 193 NOOUTSEC OPTION control statement option 194 NORESET EXEC PARM option 50 NOSOLRF EXEC PARM option 53 OPTION control statement option 203 NOSZERO EXEC PARM option 54 OPTION control statement option 207 notational conventions xvi

NOVERIFY EXEC PARM option 55 OPTION control statement option 209 NOVLLONG EXEC PARM option 56 OPTION control statement option 210 NOVLSCMP EXEC PARM option 56 OPTION control statement option 210 NOVLSHRT EXEC PARM option 57 OPTION control statement option 212 NOVSAMIO EXEC PARM option 58 NOWRKREL EXEC PARM option 58 OPTION control statement option 214 NOWRKSEC EXEC PARM option 59 OPTION control statement option 215 NULLOFL installation option 20 NULLOFL parameter OUTFIL control statements option 306 NULLOUT EXEC PARM option 46 OPTION control statement option 194 NULLOUT installation option 20 numeric tests 122 numerice editing and formatting DISPLAY operator 508 NVSAMEMT EXEC PARM option 57 NZDPRINT EXEC PARM option 60 OPTION control statement option 216

O
occurrences OCCUR operator (ICETOOL) 549 SELECT operator (ICETOOL) 566 ODMAXBF EXEC PARM option 47 installation option 20 OPTION control statement option 195 OUTFIL control statements option 340 OL (leading overpunch sign) format description 772 where allowed 777 OMIT control statement efficiency 687 example 166 function 83 using 166

802

z/OS V1R10.0 DFSORT Application Programming Guide

OMIT parameter OUTFIL control statements option 224, 230 OMIT Statement Example 166 omitting records 1, 163 user-defined data types 647 opening and initializing data sets 417, 655 opening data sets E11 user exit 423 E31 user exit 434 EFS 651 user exit routines 417 operand field 85 operation field 85 OPTION control statement examples 217, 221 function 83 special handling 661 using 167, 221 OPTION Statement Examples 217, 221 options, installation 16 OT (trailing overpunch sign) format where allowed 777 OUTFIL DD statement 74 digits needed for numeric fields 267 edit field formats and lengths 261 edit mask output field lengths 267 edit mask patterns 264 edit mask signs 266 efficiency 687 lookup and change 225, 277, 350 parsed input 277 producing reports 225, 247 storage limits 189, 341, 690 table lookup and change 277, 350 OUTFIL control statement function 83 OUTFIL control statements examples 344, 353, 354 function 83 using 221, 353, 354 outfil DD statement defined 26 function 67 OUTFIL statements examples 344, 353, 354 OUTFIL statements notes 340, 344 output data set requirements 12 valid types 12 OUTREC control statement column alignment 370 examples 152, 387, 389, 390 function 83 input field 372 separation field binary zero separation 370 blank separation 370 character string separation 370 current date constant 371 future date constant 371 hexadecimal string separation 371 past date constant 371 time constant 371 using 152, 389, 390

OUTREC control statements using 365 OUTREC parameter OUTFIL statement 224, 244 OUTREC statement examples 387, 389, 390 OUTREC statement notes 386 OUTREL EXEC PARM option 48 installation option 20 OUTSEC installation option 20 overflow 148, 411 OVERLAY parameter INREC statement 141 OUTFIL statement 224, 244 OUTREC statement 380 OVERRGN 692 installation option 20 releasing main storage 691 override tables 743 overriding defaults 741 installation defaults 169 Overriding control statements 462 overview, DFSORT 1 OVFLO EXEC PARM option 48 installation option 20 OPTION control statement option 196

P
PAD EXEC PARM option 49 installation option 20 OPTION control statement option 196 padding GNPAD 698 INCLUDE/OMIT 109 records 14, 109 truncating 109 PAGEHEAD parameter OUTFIL control statements 333 PAIR=APOST parameter of PARSE operand on OUTFIL statement 242 PAIR=QUOTE parameter of PARSE operand on OUTFIL statement 243 parameter list control statements 463, 470 description 743 format 464, 470 PARM options alias PARM options 60 PARMDDN installation option 20 PARSE parameter INREC statement 127 OUTFIL statement 224, 231 OUTREC statement 367 parsing records 1 passing control to user exits 160 passing records E15 user exit 424, 445

past date character string for 108 decimal number constant for 106 PD (packed decimal) format description 769 where allowed 777 PD0 (part of packed decimal) format description 770 where allowed 777 performance application design 682 dataspace sorting 694 efficient blocking 682 Hipersorting 694 HIPRMAX 694 ICEGENER 696 improving elapsed time with devices 685 JCL 682 main storage 689 maximizing 681 merging techniques 683 ODMAXBF effects 340 options that degrade 688 options that enhance 685 sorting techniques 683 specifying data sets 683 temporary work space 692 using BLDINDEX support 699 using DFSORTs Performance Booster for The SAS System 699 Pipe Sort example 718 procedures, catalogued defined 27 specifying 27 processing and invoking programs 789 processing of error abends with A-type messages 789 processing order, record 7 processing user-defined data types with EFS program user exit routines 657 program control statements extended parameter list 470, 473 using with EXEC statement 29 program DD statements 66 Program DD statements 79 program invocation, defined 5 program phase defined 414 initialization 651 input 653 termination 653

Q
QSAM data set 12 data set considerations E18 user exit 428 E19 user exit 431 15

R
RANGE operator (ICETOOL) 563 Index

803

rearranging records See sorting records 398 Recommendation comparing padded bytes to excess bytes in the binary field 118 record blocking 682 changing with user exit routines 435, 436 copying 157 data types 13 deleting 98, 163 with OMIT control statement 163 descriptor word (RDW) 16 EFS constraints 14 estimated number to be sorted 41 exact number to be sorted 40 formatting 125 inserting, deleting, and altering 418 maximum length 14 merging 156 minimum length 14 modifying with user exit 418 number to be sorted 41 padding 109, 698 passing with user exit routines 424 processing for OUTFIL 224 processing order 7, 124, 147, 148, 386 EFS 674 reformatting 365 sorting 398 storage constraints 14 summing 2, 408 E35 user exit 438 with user exits 418 truncating 109, 698 user-defined data types 647 variable-length efficiency 684 RECORD control statement coding notes 397 examples 397 function 84 using 394 record processing order 674, 675 record type specifying 394 records duplicate 408, 549, 566 unique OCCUR operator (ICETOOL) 549 SELECT operator (ICETOOL) 566 UNIQUE operator (ICETOOL) 605 recovering from unexpected abends 788 reformatting records after processing examples 387 before processing examples 149 with INREC statement BUILD 125 FIELDS 125 IFTHEN 125 OVERLAY 125 with OUTFIL statement BUILD 244

reformatting records (continued) with OUTFIL statement (continued) IFTHEN 244 OUTREC 244 OVERLAY 244 with OUTREC statement BUILD 365 FIELDS 365 IFTHEN 365 OVERLAY 365 REGION allocating storage 690 determining storage 689 releasing main storage 691 size 689 Related reading additional functions with ICETOOL SELECT not available with XSUM 411 relational condition comparison operator 101, 120 constants character string format 106 date string format 121 decimal number format 104 hexadecimal string format 109 defined 101 description 101 format 101, 109, 119 relational condition format 123 releasing main storage 691 remark field 86 REMOVECC parameter OUTFIL control statements option 340 RENT 421 reordering control fields See reformatting records 125, 365 REPEAT parameter OUTFIL control statements option 303 report ANSI carriage control character 225, 247, 302, 315, 321, 324, 329, 331, 335, 340, 341 header, OUTFIL 308 ICETOOL DISPLAY 503, 542 ICETOOL OCCUR 549, 562, 563 OUTFIL elements 4, 223 producing for OUTFIL 225, 247 trailer, OUTFIL 315 requesting a SNAP dump 676 requirements input data set 12 JCL 25 output data set 12 RESALL EXEC PARM option 49 installation option 20 OPTION control statement option 197 RESERVEX See ARESALL EXEC PARM option RESET installation option 20 OPTION control statement option 198

residence mode EFS program 648 EFS program user exit routine 673 user exits 419 RESINV 691 installation option 20 OPTION control statement option 198 restarting after an abend 787 Restriction invoking DFSORT using ICEMAN 4 using OUTREC instead of INREC could cause overflow 150 Restrictions ICETOOL limitations 480 restrictions for dynamic invocation 477 Return Code DFSORT 22 return codes EFS 674 Return Codes ICEGENER 699 ICETOOL 616 REXX examples 702 RMODE 423 rules for parsing 662 rules, for managing system data system data management rules 13 run-time phase 649 running DFSORT with JCL 61, 79

S
sample job streams 701 sample jobs listing installation defaults 18 SAMPLE parameter OUTFIL control statements option 228 sample routines written in Assembler 440, 442 sample routines written in COBOL 456, 457 SAS DFSORTs Performance Booster for The SAS System 699 SAVE parameter OUTFIL control statements option 224, 231 SDB EXEC PARM option 50 installation option 21 OPTION control statement option 199 SDB (system-determined block size) installation option 75 SDBMSG installation option 21 SECTIONS parameter OUTFIL control statements option 225, 329 SELECT operator (ICETOOL) 566 separation field 130, 370 sequence numbers INREC 140 OUTFIL OUTREC 289 OUTREC 379

804

z/OS V1R10.0 DFSORT Application Programming Guide

SFF (signed free form) format description 771 where allowed 777 shared tape units 64 shortcut keys 791 SIZE allocating storage 689 EXEC PARM option 51 installation option 21 MERGE control statement option 158 OPTION control statement option 181, 202 releasing main storage 691 SORT control statement option 405 SKIP parameter OUTFIL control statements 330 SKIPREC efficiency 687 EXEC PARM option 52 MERGE control statement option 158 OPTION control statement option 202 SORT control statement option 405 sliding century window 215 SmartBatch pipe and ICETOOL 615 SmartBatch pipes OUTFIL example 351 SMF installation option 21 OPTION control statement option 202 SMF date (DTn) and time (TMn) formats descriptions 508, 526, 553, 775 where allowed 777 SNAP dump 676 SOLRF EXEC PARM option 53 installation option 21 OPTION control statement option 203 SORT cataloged procedure 27, 28, 66 SORT control statement effects of EQUALS 399 examples 406, 407 field formats 401 function 83 using 398, 407, 408 sort examples 703, 719 SORT operator (ICETOOL) 575 SORT statement examples 406, 407 SORT statement image example 463, 464 SORT statement note 406 SORTCKPT DD statement function 67 using 76 SORTCNTL data set 743 SORTCNTL DD statement defined 26 function 67 using 76 SORTD cataloged procedure 66 SORTDD OPTION control statement option 204 SORTDIAG DD statement defined 26

SORTDIAG DD statement (continued) function 67 using 79 SORTDKdd DD statement function 67 using 79 SORTIN OPTION control statement option 205 SORTIN DD statement defined 26 function 67 using 68, 70 sorting data set requirements 12 defined 1 identifying information to sort 5 overview 12 records 398 specifying the estimated number of records to sort 41 specifying the exact number of records to sort 40 specifying the number of records to sort 41 user-defined data types 647, 653 using data space 686 sorting records 398 SORTINnn DD statement defined 26 duplicate 64 function 67 using 70, 71 SORTLIB ICEMAC installation option 68 SORTLIB DD statement defined 25 function 66 using 68 SORTLIB installation option 21 SORTMODS DD statement defined 26 function 67 SORTOUT OPTION control statement option 205 OUTFIL ddname 223 SORTOUT DD statement defined 26 function 67 using 74, 76 SORTSNAP DD statement defined 26 function 67 using 79 SORTWKdd DD statement defined 26 duplicate 64 function 67 using 72 SORTWKdd DD Statement dataspace sorting 72 SPANINC EXEC PARM option 53 installation option 21 option control statement 206

special handling of OPTION and DEBUG control statements 661 specification/override of DFSORT options 741, 769 specifying efficient sort/merge techniques 683 specifying input/output data set characteristics accurately 683 SPLICE operator (ICETOOL) 579 SPLIT parameter OUTFIL control statements option 304 SPLIT1R parameter OUTFIL control statements option 306 SPLITBY parameter OUTFIL control statements option 305, 307 SS See substring comparison operator STARTAFT=BLANKS parameter of PARSE operand on OUTFIL statement 238 STARTAFT=string parameter of PARSE operand on OUTFIL statement 238 STARTAT=BLANKS parameter of PARSE operand on OUTFIL statement 239 STARTAT=NONBLANK parameter of PARSE operand on OUTFIL statement 239 STARTAT=string parameter of PARSE operand on OUTFIL statement 238 STARTREC parameter OUTFIL control statements option 224, 228 STATS operator (ICETOOL) 603 STEPLIB DD statement defined 25 using 64 STOPAFT efficiency 687 EXEC PARM option 54 MERGE control statement option 159 OPTION control statement option 206 SORT control statement option 405 storage efficient 684, 738 exceeding capacity 737, 738 intermediate 692 limits, OUTFIL 341 main releasing 691 tuning 689 specifying for user exit routine 160, 162 temporary 692 tracks versus cylinders 684, 737 user exit routine 419, 444 storage administrator examples 702 storage usage records at E35 user exit 438

Index

805

SUBPOS=y parameter of PARSE operand on OUTFIL statement 237 substring comparison operator 113 substring comparison tests 114 relational condition format 113 subtracting fields and constants INREC 138 OUTFIL 275 OUTREC 377 SUM control statement 412 description 408 efficiency 688 examples 411, 412 function 84 summary field 408 using 412 SUM statement examples 411, 412 SUM statement notes 410, 411 summarizing records 408 summary field formats 408 table of formats and lengths 409 Summary Field Formats and Lengths Table 409 summing records 408, 418 records at E35 user exit 438 summing records 2 supplying messages for printing to the message data set 657 SVC installation option 21 symbols using 4 Symbols Comment and Blank Statement 620 example 618 for fields and constants 617 in DFSORT Statements 633 in ICETOOL Operators DISPLAY 641 ICETOOL Example 642 OCCUR 642 RANGE 641, 642 SELECT 642 SPLICE 642 STATS, UNIQUE and VERIFY 642 in ICETOOL statements 641 INCLUDE and OMIT 635 INREC and OUTREC 636 Keyword Statements 630 Notes 644 OUTFIL 638 overview 617 SORT and MERGE 634 SUM 635 Symbol Statements 621 SYMNAMES DD Statement 620 SYMNAMES Statements 620 SYMNOUT DD Statement 620 SYMNAMES DD statement defined 25 function 66 SYMNOUT DD statement defined 26 function 67

SYNAD 428, 432 syntax diagrams notational conventions xvi option control statement 167 SYSABEND DD statement defined 26 using 66 SYSIN data set 743 SYSIN DD statement defined 26 using 64 SYSLIN DD statement defined 26 using 66 SYSLMOD DD statement defined 26 using 66 SYSMDUMP DD statement defined 26 using 66 SYSOUT DD statement defined 25 using 65 SYSPRINT DD statement defined 26 using 66 system DD statements 64, 66 system macro instructions defined 461 using 461, 473 writing 473, 476 system-determined block size (SDB) SYSUDUMP DD statement defined 26 using 66 SYSUT1 DD statement defined 26 using 66 SZERO EXEC PARM option 54 installation option 21 OPTION control statement option 207

75

T
tape capacity considerations 738, 739 efficiency 689, 693, 738 insufficient intermediate storage 738 work space capacity 738 work storage devices 693 TCn (TOD time) format description 775 where allowed 777 TEn (ETOD time) format description 775 where allowed 777 terminating DFSORT E35 user exit 451 with an EFS program 657 with user exits 419 TEXIT installation option 21 time constant 133, 251, 371 time formats descriptions 775 where allowed 777

TMAXLIM allocating storage 689 installation option 21 releasing main storage 691 TMn (SMF time) format description 775 where allowed 777 TOD date (DCn) and time (TCn) formats descriptions 775 where allowed 777 tracks 684, 737 TRAILER1 parameter OUTFIL control statements option 225, 313, 321 TRAILER2 parameter OUTFIL control statements option 225, 329 TRAILER3 parameter OUTFIL control statements option 333 Translate characters ALTSEQ 89, 136, 258, 374 lowercase to uppercase 126, 135, 256, 374 uppercase to lowercase 126, 135, 257, 374 TRUNC EXEC PARM option 55 installation option 21 OPTION control statement option 208 truncating GNTRUNC 698 INCLUDE/OMIT 109 records 14 truncating records 109 TS (trailing sign) format description 772 where allowed 777 tuning main storage 689 two-digit year conversion 215, 352 sorting 407 transforming dates 4, 223 TYPE RECORD control statement option 394

U
UFF (unsigned free form) format description 771 where allowed 777 unexpected abends 788 UNIQUE operator (ICETOOL) 605 unique records OCCUR operator (ICETOOL) 549 SELECT operator (ICETOOL) 566 UNIQUE operator (ICETOOL) 605 user exit activating 414 addressing and residence mode 419 assembler routines input phase 423 output phase 433 COBOL routines input phase 445

806

z/OS V1R10.0 DFSORT Application Programming Guide

user exit (continued) COBOL routines (continued) output phase 451 overview 443 conventions for routines 420 DFSORT performance 420 E11 423 E15 424, 445 E16 427 E17 427 E18 427 E19 431 E31 434 E32 434 E35 435, 436, 451 E37 438 E38 439 E39 439 E61 432 efficiency 689 functions 416 language requirements 414 link-editing 423 linkage conventions 421 loading routines 421 overview 413 passing control with MODS control statement 160 summary of rules 420, 423 using RECORD control statement 394 using routines 413, 439 using your own routines 440, 460 user exit linkage conventions 421 USEWKDD OPTION control statement option 209 using control statements from other IBM programs 89 using DD statements 61, 79 using DFSORT program control statements 82, 412 using options that enhance performance 685

V
variable position/length fields 1 extracting into parsed fields INREC control statement 128 OUTFIL control statement 232 OUTREC control statement 367 variable-length record longest record length 16 record descriptor word 16 VERIFY efficiency 689 EXEC PARM option 55 installation option 21 OPTION control statement option 209 VERIFY operator (ICETOOL) 607 VIO ICEMAC installation option 79 installation option 21

VLFILL parameter OUTFIL control statements option 300 VLLONG EXEC PARM option 56 installation option 21 OPTION control statement option 210 VLSCMP EXEC PARM option 56 installation option 21 OPTION control statement option 210 VLSHRT EXEC PARM option 57 installation option 21 OPTION control statement option 212 VLTRIM parameter OUTFIL control statements option 302 VSAM data set 12 data set considerations 16 E18 user exit 429 E38 user exit 439 E39 user exit 439 key-sequenced data set (KSDS) maximum record size with INREC control statement 147, 386 user exit functions 419 using RECORD control statement 394 VSAMBSP installation option 21 VSAMEMT EXEC PARM option 57 installation option 21 OPTION control statement option 213 VSAMIO EXEC PARM option 58 installation option 21 OPTION control statement option 214 VTOF parameter OUTFIL control statements option 290

X
XCTL using 461 writing macro instructions 473

Y
Y2 formats description 773 where allowed 777 Y2PAST EXEC PARM option 59 installation option 21 MERGE control statement option 159 OPTION control statement option 215 SORT control statement option 405 Year 2000 century window 215 comparing dates 121 ordering dates 402 transforming dates 259

Z
16 ZD (zoned decimal) format description 769 where allowed 777 ZDPRINT EXEC PARM option 60 installation option 22 OPTION control statement option 216

W
Web 4 web site 4 work space requirements for DFSORT 731 using 731, 739 WRKREL EXEC PARM option 58 installation option 21 OPTION control statement option 214 WRKSEC EXEC PARM option 59 installation option 21 OPTION control statement option 215

Index

807

808

z/OS V1R10.0 DFSORT Application Programming Guide

Readers Comments Wed Like to Hear from You

z/OS DFSORT Application Programming Guide Publication No. SC26-7523-03 We appreciate your comments about this publication. Please comment on specific errors or omissions, accuracy, organization, subject matter, or completeness of this book. The comments you send should pertain to only the information in this manual or product and the way in which the information is presented. For technical questions and information about products and prices, please contact your IBM branch office, your IBM business partner, or your authorized remarketer. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use the personal information that you supply to contact you about the issues that you state on this form. Comments:

Thank you for your support. Send your comments to the address on the reverse side of this form. If you would like a response from IBM, please fill in the following information:

Name Company or Organization Phone No.

Address

E-mail address

___________________________________________________________________________________________________

Readers Comments Wed Like to Hear from You

SC26-7523-03

Cut or Fold Along Line

Fold and _ _ _ _ _ _ _ _ _ _Fold and_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please _ _ _ _ _ staple _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ Tape _ _ _ _ _ _ _ _ Tape _ _ _ _ do not _ _ _ _ NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES

BUSINESS REPLY MAIL

FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK POSTAGE WILL BE PAID BY ADDRESSEE

International Business Machines Corporation Department 55JA, Mail Station P384 2455 South Road Poughkeepsie, NY United States of America 12601-5400

_________________________________________________________________________________________ Please do not staple Fold and Tape Fold and Tape

SC26-7523-03

Cut or Fold Along Line

Program Number: 5694-A01

Printed in USA

SC26-7523-03