csi-sort · 2017-03-31 · csi-sort the complete vse sort package user guide version 2.01 • great...

CSI-SORT The complete VSE sort package

User GuideVersion 2.01

• Great for the basic requirements of a sort package at a lower cost

• Provides compatibility for all DFSORT commands

• Activate by including the CSI-SORT library in front of your current sort product’s library. Since parameters are used or ignored, no JCL changes are required.

• Ask us about Data-Miner, or use OUTFIL or E35 exit, for more exten-sive formatting

• Offers better performance for inter-nal sorts without changing your applications

• Features support for FIELDS=COPY and MERGE

• All sorts are performed in your choice of data space or partition GETVIS

• Involves smaller partition require-ments when data space area is used

• Interfaces for calls both from JCL (external) and from applications (internal)

• A work file is used only if data exceeds allocated space

• MERGE is treated like a sort without any arguments, allowing for one

code path to improve performance and reduce complexity

• Formatted output (OUTREC) is available and behaves like INREC

• Support for tape and disk (including VSAM)

• Support for E15, E32, and E35 exits

• Support for INPFIL and OUTFIL exits

• Support for reader input, and punch or print output

• Full support for INCLUDE, OMIT, INREC, and SUM

CSI-SORT is the complete sort package for z/VSE

Copyright © 2006–2017 by Connectivity Systems, Inc.

All Rights Reserved

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the Government is subject to the restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013.

This material contains confidential and proprietary material of Connectivity Systems, Inc. (hereafter also referred to as CSI International and CSI) and may not be used in any way without written authorization from Connectivity Systems, Inc. This material may not be reproduced, in whole or in part, in any way, without prior written permission from Connectivity Systems, Inc.

Permission is hereby granted to copy and distribute this document as follows:

• Each copy must be a complete and accurate copy.• All copyright notices must be retained.• No modifications may be made.• Use of each copy is restricted to the evaluation and/or promotion of

the CSI-SORT product from Connectivity Systems, Inc. or in accordance with a license agreement.

CSI-SORTVersion 2.01March 2017

Published by Connectivity Systems, Inc.8120 State Route 138, Williamsport OH 43164Phone: 800-795-4914Fax: 740-986-6022

Internet: http://www.csi-international.com

E-Mail: [email protected]

Technical Support: [email protected]

Documentation comments: [email protected]

Contents

About This DocumentOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi

Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiBenefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiSystem Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiDocument Chapter Grouping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Chapter 1 Introducing CSI-SORTIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.1

Additional Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.2Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.3

Chapter 2 Invoking CSI-SORTIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.1

Term Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.1Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.1

Chapter 3 WorkingsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.1

Control Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.1Collating Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.2Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.3

Processing Explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.3Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.5

Chapter 4 Things to ConsiderIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.1

Copyright © 2006-2017 by Connectivity Systems, Inc.i

CSI-SORT User Guide Contents

Input and Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.1SAM ESDS Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.3Record and Data Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.3Record Length and Block Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.4

Chapter 5 Input/Output DevicesIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5.1

Pooling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5.1Device sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5.2

Chapter 6 Storage DevicesIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6.1

Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6.1

Chapter 7 Messages and Return CodesMessage and Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7.1

Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7.1Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7.1Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7.2

Chapter 8 Introducing Job Control LanguageIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8.1

Chapter 9 Using Job Control LanguageUsing JCL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9.1

JCC and JCS Descriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9.2Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9.3Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9.3

Chapter 10 Defining FilesDefining Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10.1

Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10.1File Manage System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10.2Default Filename. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10.2

Input File Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10.3Output File Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10.3Work File Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10.3

Chapter 11 Using Program Control StatementsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1

Copyright © 2006-2017 by Connectivity Systems, Inc.ii


Chapter 12 Control Statement SummaryIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12.1

Primary Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12.1Including or Omitting Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12.2Reformatting and Editing Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12.2Input/Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12.3Functions and Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12.3Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12.3

Chapter 13 Coding RulesIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13.1

Continuation Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13.1Coding Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13.2

Chapter 14 ALTSEQ Control StatementALTSEQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14.1

Operand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14.2Miscellaneous Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14.2

Chapter 15 END Control StatementEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15.1

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15.1

Chapter 16 INCLUDE and OMIT Control StatementsINCLUDE and OMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16.1

INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16.1OMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16.1Logical Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16.2

Nesting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16.2Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16.3Relational Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16.4Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16.4Continued Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16.5

Chapter 17 INCLUDE and OMIT ComparisonsComparisons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17.1

Relational Condition Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17.1Comparison Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17.2Compare Field Formats and Lengths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17.3

Copyright © 2006-2017 by Connectivity Systems, Inc.iii


Field-to-Field Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17.3Field-to-Constant Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17.4

Padding and Truncating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17.6Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17.7Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17.8

Chapter 18 INCLUDE and OMIT Substring TestsSubstring Comparison Tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18.1

Relational Condition Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18.1Substring Comparison Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18.2Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18.3

Chapter 19 INCLUDE and OMIT Bit Logic TestsBit Logic Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19.1

Bit Operator Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19.1Relational Condition Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19.2Padding and Truncation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19.3Bit Operator Test Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19.4

Bit Comparison Tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19.5Relational Condition Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19.5Padding and Truncation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19.6Bit Comparison Test Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19.7

Chapter 20 INPFIL Control StatementINPFIL Control Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20.1

Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20.2Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20.4Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20.5Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20.6

Chapter 21 INREC Control StatementINREC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21.1


Chapter 22 MERGE Control StatementMERGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22.1

Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22.2Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22.2

Copyright © 2006-2017 by Connectivity Systems, Inc.iv


Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22.2

Chapter 23 MODS Control StatementMODS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23.1


Chapter 24 OPTION Control StatementOPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24.1

Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24.7Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24.10

Chapter 25 OUTFIL Control StatementOUTFIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25.1


Chapter 26 OUTREC Control StatementOUTREC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26.1

Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26.1Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26.3Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26.4Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26.6

Chapter 27 RECORD Control StatementRECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27.1

Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27.2Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27.3

Chapter 28 SORT Control StatementSORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28.1


Copyright © 2006-2017 by Connectivity Systems, Inc.v


Chapter 29 SUM Control StatementSUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29.1


Chapter 30 Using User Exit RoutinesIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30.1

Topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30.2

Chapter 31 Processing PhrasesProcessing Phases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31.1

Input, User Exit, Output Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31.3Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31.3Phases and User Exit Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31.4

Chapter 32 User Exit Routine FunctionsFunctions of Routines at User Exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32.1

Opening and Initializing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32.1Processing Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32.2Controlling Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32.2Altering, Deleting, Inserting Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32.2

E15 User Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32.2E32 User Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32.3E35 User Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32.4

Summing Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32.4Closing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32.4Terminating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32.4Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32.4

Chapter 33 User Exit ModesModes for User Exit Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33.1

Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33.2

Chapter 34 User Exit Performance EffectsPerformance Effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34.1


Copyright © 2006-2017 by Connectivity Systems, Inc.vi


Chapter 35 Loading and LinkingIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35.1

Passing Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35.1Passing Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35.2Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35.3

Chapter 36 E15/E32 User Exit RoutineIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36.1

Entry 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36.1Entry 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36.1Entry 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36.2Entry 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36.2

Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36.4

Chapter 37 E35 User Exit RoutineIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37.1

Entry 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37.1Entry 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37.1Entry 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37.2Entry 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37.2Entry 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37.2Entry 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37.2

Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37.2Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37.4

Chapter 38 Invoking From a ProgramIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38.1

Chapter 39 Defining System MacrosDefining System Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39.1


Chapter 40 Using System MacrosUsing System Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40.1

Chapter 41 SubtaskingSubtasking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41.1


Copyright © 2006-2017 by Connectivity Systems, Inc.vii


Chapter 42 Requiring Job Control LanguageRequiring JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42.1

Chapter 43 Using General Registers to Pass InformationPassing Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43.1

Chapter 44 Using Address and Residence ModesModes for an Invoking Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44.1


Chapter 45 Using Parameter ListPassing Parameters with Parameter List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45.1

Control Statement Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45.2Branch Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45.2Return Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45.3Alternative Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45.3Sample Coding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45.4Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45.7

Chapter 46 Improving EfficiencyIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46.1

Chapter 47 Designing ApplicationsDesigning Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.1

Directly Invoke Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.1Planning Ahead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.2

Efficient Blocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.2Specifying File Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.2

Direct Access Storage Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.2Improving Time Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.3Improving Performance Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.3

WORK=0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.3DSPSIZE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.4INCLUDE/OMIT, STOPAFT/SKIPREC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.4INREC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.4SUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.5

Avoiding Degrading Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47.6

Chapter 48 Using Dataspace SortingUsing Dataspace Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48.1

Copyright © 2006-2017 by Connectivity Systems, Inc.viii


Chapter 49 Examples of ApplicationsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49.1

Chapter 50 Sort Application ExamplesSort Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50.1

Sort Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50.1Line Explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50.2





Sort Example 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50.10Line Explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50.10

Sort Example 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50.11Line Explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50.12

Sort Example 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50.13Line Explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50.14

Chapter 51 Copy Application ExamplesCopy Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51.1

Copy Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51.1Line Explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51.1

Copy Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51.3Line Explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51.3

Appendix A Estimating Storage RequirementsUsing Virtual Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.1

Minimum Virtual Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.1Additional Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2Using Data Space Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2

Appendix B Data Format ExamplesData Format Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B.1

Appendix C EBCDIC Collating SequencesEBCDIC Collating Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C.1

Copyright © 2006-2017 by Connectivity Systems, Inc.ix


Appendix D ISCII/ASCII Collating SequencesISCII/ASCII Collating Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D.1

Appendix E Error MessagesError Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.1

CSS000E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.1CSS001E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.2CSS002E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.2CSS003E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.2CSS004E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.3CSS005E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.3CSS006E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.3CSS010E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.4CSS011E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.4CSS013E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.4CSS014E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.5CSS015E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.5CSS016E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.5CSS017E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.5CSS018E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.6CSS019E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.6CSS020E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E.6

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Glossary.1

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .IX.1

Copyright © 2006-2017 by Connectivity Systems, Inc.x

About This Document

Overview

This document provides information about the CSI-SORT program. It is designed with chapters that are generally small in page count. Therefore, read the chapters consecutively.

Definition What is CSI-SORT?

Sort—To reorder data into a new sequence.

CSI-Sort is a mainframe sort package that often generates a new file by:

Sorting filenames and test lists.

Reordering lines of text.

Sorting records by one or more fields.

The results of the sort can be used in reporting, programs, and archiving data according to variables chosen by the programmer.

Sort does nothing to the data except arranges it in a specific order and/or selects specific data according to the variable specified.

It is a simple process that speeds up a manual process and allows tasks to be done where they would be physically impossible to do manually within an appropriate amount of time.

Benefits One benefit to using CSI-SORT is the support from VSE. Other benefits include how CSI-SORT uses algorithms in a way that use dataspaces to:

Provide cost savings.

Increase processing speed.

Copyright © 2006-2017 by Connectivity Systems, Inc.xi

CSI-SORT User Guide About This Document

Ensure efficiency.

System Requirements

CSI-SORT is compatible with VSE/ESA-supported processors, such as the following releases:

VSE/ESA version 2

z/VSE version 3

CSI-SORT also operates with any device SAM or VSAM uses for input or output and any tape device.

Document Chapter Grouping

About Table 0-1 on page -xii provides a description of the subject and the chapters containing the information:About Table 0-1.Section Topic-to-Chapter/Appendix

Subject Chapters or Appendix

CSI-SORT Overview Chapter 1 through Chapter 7

Invoking CSI-SORT with Job Control Language Chapter 8 through Chapter 10

Using CSI-SORT Program Control Statements Chapter 11 through Chapter 29

Using own user exit routines Chapter 30 through Chapter 37

Invoking CSI-SORT from a program Chapter 38 through Chapter 45

Improving Efficiency Chapter 46 through Chapter 53

Examples of CSI-SORT applications Chapter 49 through Chapter 58

Estimating Storage Requirements Appendix A

Examples of data formats Appendix B

EBCDIC collating sequences Appendix C

ISCII/ASCII collating sequences Appendix D

Current CSI-SORT error messages Appendix E

Copyright © 2006-2017 by Connectivity Systems, Inc.xii

Copyright © 2006-2017 by Connectivity Systems, Inc.1.1

1
Introducing CSI-SORT
Introduction

This section provides an overview of the CSI-SORT program that allows a user to perform any of the following basic activities on records:

Sort—arranges the records in a particular sequence, choosing an order more useful than the original.

Sort allows a user to sort records from up to nine input files to one output file.

Merge—combines the contents of two or more previously-sorted files into one.

The user must first sort the input files for information that will be used to merge them and that they are in the same order required for output.

A user can merge records from up to nine input files to one output file.

A merge application is treated like a sort but without any sort fields.

Copy—makes an exact duplicate of each record in the file.

Copy allows a user to copy records from up to nine input files to one output file.

CSI-SORT User Guide Introducing CSI-SORT

Additional Processing

Besides the three basic functions mentioned earlier, the following additional processing functions can be performed simultaneously:

Control Records—Use INCLUDE and OMIT control statements in the applications to control which records to keep in the final output file of the CSI-SORT run. The control statement tests each record against criteria and retains only the ones identified for the output file.

For example, do this if choosing to work only with records having a value of Kona Kailia in the office location field, or to leave out any record dated after 1994 if it also contains a value greater than 35 for the number of employees.

Edit and Reformat Records—Use the INREC and OUTREC control statements and E35 exit to edit and reformat records before or after other processing. Use the control statements to:

— Delete fields from records.

— Rearrange the order of the fields within records.

— Insert separators, such as blanks or binary zeros, before, between, or after fields.

For example, do this to create a file containing financial data without identifying any of the original names.

Sum Numeric Information—Use the SUM control statement to sum numeric information from records.

For example, use this for any of the following:

— To know the total amount of a yearly payroll.

— To add values for a field with salaries from all employees’ records.

Control Functions—Control functions with using other control statements such as specifying alternate collating sequences, invoking user exit routines, or overriding installation defaults.

Pass Control—Direct CSI-SORT to pass control during run time to user-designed routines and to write to the user.

For example, write user exit routines to summarize, insert, delete, shorten, or alter records during processing as well an routines to open and close files.



Additional Information

For more information about editing capabilities, see any of the following control statements:

INCLUDE

OMIT

INREC

OUTREC

SUM



2
Invoking CSI-SORT
Introduction

This section provides an overview of how to invoke the CSI-SORT processing.

Invoke the CSI-SORT processing using any of the following methods:

EXEC job control statement in the input stream, using SORT as the program name. See Chapter 8, ‘‘Introducing Job Control Language.’’

Program written in assembler language using a system macro. See Chapter 30, ‘‘Using User Exit Routines.’’

Programs written in COBOL, PL/I, or RPG II with the Auto-Report feature.

Term Definitions This document uses the following term definitions:

Directly invoked—CSI-SORT does not initiate from another program.

Program invoked—CSI-SORT initiates from another program.


For more information about writing programs in COBOL, PL/I, or RPG II, see the programmer’s guide describing the compiler version available at the site.

CSI-SORT User Guide Invoking CSI-SORT



3
Workings
Introduction

This section provides information about the following:

‘‘Control Fields’’ on page 3-1 and ‘‘Collating Sequences’’ on page 3-2 to sort, merge, and copy file records.

‘‘Processing’’ on page 3-3

Control Fields Control fields identify the information to sort or merge. For file contents, this may include names, dates, account numbers, or other useful information. For example, arranging records in alphabetical order by family name when sorting files. Use the byte position and length (in bytes) of the portion of each record containing a family name to define it as a control field to manipulate with CSI-SORT.

CSI-SORT uses the defined control fields as keys in processing. A key is a concept the user has in mind when designing a record processing strategy for a particular application. a control field is a discrete portion of a record that contains the text or symbols corresponding to that in formation in a form used by CSI-SORT to identify and sort or merge the records. Essentiality, keys are equivalent to the control fields CSI-SORT uses in processing.

To arrange records in a specific order, identify one or more control fields to use as keys. CSI-SORT uses the sequence in which the control fields are listed as the order of priority to arrange the records. Major control field is the name of the first control field specified. Subsequent control fields are called minor control fields, as in first, second, third minor control fields.

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. This continues until a difference is found or no more control fields are available.

CSI-SORT User Guide Workings

Records with identical values for all the specified control fields always retain their original input order. Therefore, CSI-SORT ignores EQUALS/NOEQUALS.

Control fields may overlap or be contained within other control fields. They do not need to be contiguous but observe the following restrictions:

Note:Note:CSI-SORT issues an error message and terminates if any of the restrictions is violated to provide compatibility with other sort products.

Located within the first 4092 bytes of the record.

Total lengths must not exceed 3072 bytes.

Total number of control fields limited to 64.

Collating Sequences

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.

CSI-SORT provides several standard collating sequences. Choose either to arrange records according to:

The standard collating sequences or

Other sequence based on an optional patch.

When sorting or merging records, CSE-Sort uses one of the following collating sequences:

EBCDIC.

ISCII/ASCII.

Collating sequence for character data and binary data is absolute, meaning character and binary fields are not interpreted as having signs.

The following data formats are numerically collated, where each value is interpreted as having a positive or negative sign:

Packed decimal.

Zoned decimal.

Fixed-point.

Normalized floating-point.

Signed numeric.

Modify the standard EBCDIC sequence to collate differently, for example to allow alphabetic collation of national characters.

Define an alternate collating sequence at run-time with the ALTSEQ control statement.



Processing The user must prepare job control language (JCL) statements and CSI-SORT program control statements to invoke CSI-SORT processing. The operating system processes job control statements, which describe files to the operating system and initiates CSI-SORT processing.

CSI-SORT processes the CSI-SORT program control statements, which describe the functions to perform and invokes the requested processing.

CSI-SORT performs all sorts in data space(s) or partition GETVIS. If a sort work file is requested, the records are kept in this file if insufficient data space or partition GETVIS is available to accommodate all the data to be stored.

Use job control statements to indicate the intermediate storage device to use and the amount of work space required for any sort application.S

ProcessingExplanation

Below is an explanation of the CSI-SORT processing:

1. CSI-SORT checks for a supplied EXIT operand in the INPFIL control statement for a sort, merge, or copy applications.

If not, CSI-SORT reads the input records from SORTINn files:

Sort application—If EXIT operand present, use E15 user exit routine to insert all records as CSI-SORT does not read the input records from SORTINn files.

Merge ot copy application—If EXIT operand present, use E32 user exit routine to insert all records as CSI-SORT does not read the input records from SORTINn files.

2. CSI-SORT performs processing specified with SKIPREC option if input records for sort or copy application are read from SORTINn files.

CSI-SORT skips records without processing until the SKIPREC count is satisfied. Eliminating records before sort or copy processing gives better performance.

3. CSI-SORT checks for a specified E15 user exit if the input records for a sort application are read from SORTINn files.

If found, CSI-SORT transfers control to the user exit routine. The E15 user exit routine inserts, deletes, or reformats records.

4. CSI-SORT checks for a specified E32 user exit if the input records for a merge or copy application are read from SORTINn files.

If found, CSI-SORT transfers control to the user exit routine. The E32 user exit routine only replaces the records.



5. CSI-SORT performs processing specified with the INCLUDE or OMIT function.

If using an E15 user exit routine to modify record format, the INCLUDE or OMIT control field definitions must apply to the current format rather than to the original format.

Applications run more efficiently if using the INCLUDE or OMIT function to delete unnecessary records before sort, merge, or copy processing.

6. For sort or copy applications, CSI-SORT performs processing specified with the STOPAFT option. CSI-SORT stops accepting records for processing after the maximum number of record specified is reached.

CSI-SORT accepts records for processing if they are:

Read from SORTINn files inserted by the E15 user exit routine.

Not deleted by a SKIPREC option.

Not deleted by the E15 user exit routine.

Not deleted by an INCLUDE or OMIT function.

7. CSI-SORT performs processing specified with an INREC function.

If the record format was changed before this step, the specified INREC control and separation field definitions must apply to the current format rather than the original format.

Use the INREC function to shorten records before further processing to gain better performance.

8. CSI-SORT performs processing specified in the SORT or MERGE control statement:

For a sort application, all input records process before any output record processes.

For a merge or copy application, all input records process before any output record processes.

For a sort or merge application, if a SUM control statement is present, CSI-SORT processes it during the sort or merge processing.

CSI-SORT summarizes the records and deletes duplicates as soon as possible to gain better performance.

If any changes were made to the record format prior to this step, the specified SORT or MERGE and SUM control field definitions must apply to the current format rather than to the original format.



9. CSI-SORT transfers control to the E35 user exit routine after processing for all input records complete for a sort application.

For a merge or copy application, CSI-SORT transfers control to the E35 user exit routine after processing all input records

If the record format was changed before this step, the E35 user exit routine receives the records in the current format instead of in the original format.

Use the E35 user exit routine to insert, delete, reformat, or sum records.

10. The E35 user exit routine must dispose of all records if the OUTFIL control statement contains an EXIT operand because CSI-SORT treats these records as deleted.

11. CSI-SORT writes records to the SORTOUT file, if it’s present.


For more information about job control statements, see Chapter 8, ‘‘Introducing Job Control Language.’’

For more information about CSI-SORT program control statements, see Chapter 11, ‘‘Using Program Control Statements.’’

For more information about methods for determining the amount of work space required, see Appendix A, ‘‘Estimating Storage Requirements.’’



4
Things to Consider
Introduction

The user must define any files that are provided for CSI-SORT according to the conventions required by the operating system.

This section discusses the following:

‘‘Input and Output Files’’ on page 4-1.

‘‘SAM ESDS Files’’ on page 4-3.

‘‘Record and Data Format’’ on page 4-3.

‘‘Record Length and Block Size’’ on page 4-4.

Input and Output Files

The input and output files are of various characteristics, as provided in.Table 4-1 on page 4-1.Table 4-1. Input and Output File Characteristics

Characteristics Sort Input Merge (M) InputCopy (C) Input Output

Files

Type of extent Type 1 and 8 Type 1 and 8 Type 1 and 8

Organization1 SAM

VSAM

Note: Cannot be mixed.

SAM

VSAM


SAM

VSAM

CSI-SORT User Guide Things to Consider

Number2 1–9 files 1–9 files (M)

1–9 files (C)

1 file

Note: Cannot be multivolume.

Size No restriction No restriction No restriction

Blocking Blocked3

Unblocked

Blocked3

Unblocked

Blocked

Unblocked

Block size Can differ; biggest must be specified.

Can differ; biggest must be specified (M)

Contents Unsorted records

Sorted records; or

Empty

Unsorted records

Sorted records; or

Empty

Sorted, Copied, or Merged records

Labels Any

None

Mixed

Any

None

Mixed

Any

None

Pooling4 Can be pooled with output

Can be pooled with output after read

Can be pooled with sort input

Records

Format Fixed

Variable


Fixed

Variable

Note: Cannot be mixed (M)

Fixed

Variable

Code EBCDIC

ISCII/ASCII

Note: Cannot be mixed

EBCDIC

ISCII/ASCII

Note: Cannot be mixed (M)

Same as input

Control Fields

Number 1–64 1–64 (M)

Format Mixed Mixed (M)

Order Ascending

Descending

Both

Ascending

Descending

Both (M)5

Output to a VSAM KSDS file must be in primary key sequence

Table 4-1. Input and Output File Characteristics




The files reside on any of the following:

Tape.

Count-key-data (CKD).

Extended-count-key-data (ECKD).

Fixed block architecture (FBA) disks.

SAM ESDS Files SAM ESDS files require the VSAM operand in the DLBL job control statements.

SAM files are accessed as VSAM if the VSAM or ESDS operand is specified in the INPFIL or OUTFIL control statement. Otherwise, they are assessed as SAM.

SAM ESDS files in control interval format are accessed as either SAM or VSAM. As input, if they are mixed with ordinary SAM files, they must be accessed as SAM files.

If mixed with VSAM files, they must be accessed as VSAM files.

If SAM ESDS files are not in control interval format, they cannot be accessed as VSAM by CSI-SORT but can be read or written using E15, E32, and E35 user exit routines.

Record and Data Format

Record lengths are one of the following:

Fixed (FLR)

Variable (VLR)

Total lengths, maximum

3072 bytes 3072 bytes (M)

Location Must be within first 4092 bytes of record

Must be within first 4092 bytes of record (M)

1. SAM ESDS files may be mixed with SAM or VSAM files but not both at once.

2. If on tape, each unit may have as many alternates as permitted by VSE/ESA.

3. With fixed-length records, short blocks are accepted if their length is a multiple of record length.

4. VSAM input and output can be the same file only if the file was defined with the REUSE attribute and the REUSE operand is specified in the OUTFIL control statement.

5. When records with equal control fields are sorted or merged, their output order is in the order read due to the sorting method.

Table 4-1. Input and Output File Characteristics




Variable length spanned records are permitted, however they exclude the use of either the ADDROUT or ADDROUT=D option.

The record data is either numeric or alphanumeric coded EBCDIC; ISCII/ASCII for tape input and output files.

Record Length and Block Size

The maximum block size for input and output files is as follows:

EBCDIC data—Track capacity.

ISCII/ASCII data—9999 bytes.

Two restriction for using the large blocks are:

The larger the blocks, the more virtual storage the sort, merge, or copy application needs.

For CKD devices, cannot define an output block size larger than track capacity for the specified output device.

Table 4-2 on page 4-4 provides a description for record length:Table 4-2. Record Length

Device Minimum Length (in bytes)

Maximum Length(in bytes)

FLR VLR FLR VLR

Tape input 12 12 32767 327671

1. Implies spanned records.

Tape output 18 18 32767 327671

CKD input/output 1 5 Track Capacity

Track Capacity

FBA input/output 1 5 32761 327671

SAM ESDS input/output 1 5 32761 327671

VSAM input/output 1 22

2. Must add four bytes when specifying the length because CSI-SORT adds a record descriptor word (RDW).

327671 327671



Table 4-3 on page 4-5 provides a description of the block size:Table 4-3. Block Size

Device Minimum Block Size (in bytes)

Maximum Block Size (in bytes)

ECKD 1 56664

FBA 1 32761

Tape input 12 32767

Tape output 18 32767



5
Input/Output Devices
Introduction

VSAM or SAM ESDS input/output files reside on any disk devices supported by the VSAM release.

SAM files reside on any operating system supported CKD, ECKD, FBA, or tape device.

Input files can be a mixture of any of the device types allowed by the system.

Output files can be written to printers and punch devices using any of the following:

The E35 exit routine.

The SORTOUT parameter of the OPTION control statement.

This section includes information about the following:

‘‘Pooling’’ on page 5-1.

‘‘Device sharing’’ on page 5-2.

Pooling I/O pooling is defined as designing a sort application where two input/output files share the same disk extents or tape units and allows the user to run the sort application with fewer devices.

The output file writes over the input file, therefore be sure to check that files are correctly specified.

Rules for I/O pooling are:

Sort input and output files can be pooled.

Use any file name.

CSI-SORT User Guide Input/Output Devices

Files can be multivolume and multiextent.

Merge and copy is handled like sort.

Do not pool sort work files with any other sort file. If this occurs, the system produces an error message and terminates CSI-SORT.

Device sharing During a sort application, several tape input files can use the same device. These files are read serially.

Unmount each tape after reading before mounting another tape to read. This process uses only the input function, however it does increase capacity of a given number of devices.



6
Storage Devices
Introduction

This section discusses information about intermediate storage devices.

Intermediate storage is used if requested by the WORK= operand of the SORT control field.This storage must be on a disk device.

CSI-SORT allocates the work file as an SD or VSAM-managed SAM file, which may have multiple extents.


For more information about the types of devices available for intermediate storage, see Appendix A, ‘‘Estimating Storage Requirements.’’

For more information about determining the amount of space required, see Appendix A, ‘‘Estimating Storage Requirements.’’

CSI-SORT User Guide Storage Devices



7
Messages and Return Codes
Message and Return Codes

CSI-SORT writes messages to:

SYSLST file

System console

Messages written by CSI-SORT, determined at run time, are any of the following:

Critical error messages.

Informational messages.

Diagnostic messages.

Messages CSI-SORT replies to either the operating system or the invoking program with one of the following return codes:

0 or 4—Successful completion.

16 or 20—Unsuccessful completion.

Return Codes Below are definitions for CSI-SORT return codes:

0—Successful.

16—Unsuccessful. Error detected that prevented successful complete.

xxx—GETVIS error, return code = xxx-256.

xxx—Load error, return code = xxx-512.

The return code is available to both of the following:

CSI-SORT User Guide Messages and Return Codes

Directly invoked applications—Return code passes in general register 15 using the VSE/ESA EOJ macro.

Program invoked applications—Return code available in a user-specified area addressed by the CSI-SORT parameter list.


For additional information about CSI-SORT error messages, see Appendix E, ‘‘Error Messages.’’

For more information about the VSE/ESA EOJ macro, see the VSE/ESA Guide to System Functions.



8
Introducing Job Control
Language

Introduction

This section discusses the following topics that are used to invoke CSI-SORT with JCL (job control language):

Chapter 9, ‘‘Using Job Control Language.’’

Chapter 10, ‘‘Defining Files.’’

CSI-SORT User Guide Introducing Job Control Language



9
Using Job Control Language
Using JCL

This section provides an overview of the job control language and its statements and commands.

The operating system uses JCL supplied with CSI-SORT program control statements to:

Identify an authorized user.

Allocate resources to run the application.

Run the application.

Return results.

Terminate the application.

CSI-SORT User Guide Using Job Control Language

JCC and JCS Descriptions

JCC are job control commands and JCS are job control statements, both making up the JCL. Table 9-1 on page 9-2 provides a description of the JCC and JCS functions:Table 9-1. JCC/JCS Description

Statement Command Description

JOB First statement of the application.

All parameters in operand field are optional.

Note: This is true even if the site made mandatory, information such as account number and programmer name.

ASSGN Required only if devices used in an application were not previously assigned to symbolic names (SYS numbers) used in CSI-SORT application.

Not required for VSAM or SAM ESDS files.

TLBL Required for every tape file with standard labels.

DLBL Required for every disk file. Requirements are:

BLKSIZE must be specified.

Different file ID for the two files if both on the same disk used by the program.

VSAM file—File ID must specify the cluster name.

EXTENT One statement required for each direct access area to define limits used by the program:

Type 1—Used for input/output files and work files.

Type 8—Used for input/output files.

Must include SYS number of the device containing the extent.

Not required for VSAM or SAM ESDS files.

Required for SAM ESDS files only if they are implicitly defined.

EXEC Must be followed by CSI-SORT program control statements.

Must contain name of CSI-SORT call program (SORT).

ALLOC Defines a virtual partition size.

SIZE Defines size of a partition program area.

SYSDEF Defines the size of a data space.

RSTRT Required to continue execution of an interrupted job from a checkpoint record.



Format Below is the job control statement format:

Below is the JOB job control statement format:

Below is the EXEC job control statement format:


For more information about JCC and JCS and their formats, see VSE/ESA System Control Statements.



10
Defining Files
Defining Files

This section discusses defining files according to VSE/ESA standard.

All files used in a sort, merge, or copy application must be defined according to VSE/ESA standard.

Rules Below are rules in which to adhere:

The file SYS number must be assigned to a device address (ASSGN job control statement).

The exception to this is VSAM and SAM ESDS files.

If the SYS number default values are not used, specify the values in the appropriate SORTIN or SORTOUT operand of the OPTION program control statement.

Include the filename in the DLBL or TLBL job control statement.

Specify filenames in the FILNN operand of the OPTION program control statement if the default filenames are not used.

At least one EXTENT job control statement is required for each DLBL job control statement.

The exception to this is with VSAM or previously defined SAM ESDS files.

The DLBL job control statement must include a value with the CISIZE parameter if input is from an FBA device.

The DLBL job control statement should include a value with the CISIZE parameter if output if to an FBA device.

If no value is included, CSI-SORT uses the minimum valid value to hold the specified or defaulted block size in the OUTFIL program control statement.

CSI-SORT User Guide Defining Files

Specify DISP=(NEW, DELETE) in the DLBL job control statement for SAM ESDS work files.

VSAM files and SAM ESDS files should be defined using the VSAM Service program prior to invoking sort.

Only SAM ESDS output and work files can be defined implicitly with RECORDS and RECSIZE parameters in the DLBL job control statement, which adds to the overall time taken by CSI-SORT.

Implicitly defined SAM ESDS output files—Defined with record format undefined (RECFM=UNDEF). Read these files using SAM as either fixed or variable. If reading the files using VSAM, the access method provides an entire block to the reading program, which then performs its own deblocking.

Explicitly defined SAM ESDS output files—If implicitly defined not desired, define the files with RECFM=FB or RECFM=VS as required.

File Manage System File Management System provides benefits such as:

Dynamic logical and physical device assignment.

Dynamic primary and secondary extent allocation.

Define input, output, and work files according to the requirements of the File Management System if it is installed at the site.

CSI-SORT attempts to interact with the File Management System installed at the site:

And tries to continue processing when an input, output or work file is not defined completely, by assuming file definition will be dynamically resolved at open time.

Or tries to allocate a secondary extent dynamically if the allocated work file space is exhausted.

Default Filename If a default SYS number is occupied by another file, CSI-SORT uses the next free number. Table 10-1 on page 10-2 provides a description of the file default names:Table 10-1. Filenames and Default SYS Numbers

File Type File Name Symbolic Unit Name

Output SORTOUT SYS001 SYS001 SYS001

Input SORTIN1

.

.

.SORTIN9

SYS002

.

.

.SYS

SYS001

.

.

.SYS



Input File Statements

For a filename using SORTINn, n is any value from 1 to 9, depending on the number of input files.

The input file ID must be included on each TLBL or DLBL job control statement.

When the input file is a direct access multiextent file, only the first EXTENT job control statements contains the specified or defaulted SYS number. Other EXTENT job control statements specify any valid SYS number.

Output File Statements

An output file on disk is defined by SORTOUT DLBL and EXTENT job control statements.

Multivolume or multiextent output, or both, for a disk file is accomplished by use of VSE/ESA standards:

One DLBL job control statement is supplied for the entire file, followed by one EXTENT job control statement for each separate extent that the file occupies on disk.

When the output file is a direct access multiextent file, only the first EXTENT job control statement contains the specified or defaulted SYS number. Other EXTENT job control statements each specify any valid SYS number.

Work File Statements

The SORTWK1 DLBL and EXTENT job control statements define a work file.

The file is defined as SD only.

Users of SAM ESDS files:

Use the special file-ID prefix to cause a single extent to be allocated for the primary allocation.

Specify DISP=(,DELETE).

Note:Note:DISP=(,DELETE) does not have to be specified if the work file is defined with a DTF containing TYPEFLE=WORK and DELETFL is not specified.

Work SORTWK1

.

.

.SORTWK9

SYS

.

.

.SYS

SYS002

.

.

.SYS

SYS

.

.

.SYS

SYS001

.

.

.SYS

Checkpoint SORTCKP SYS000 SYS000 SYS000 SYS000

Table 10-1. Filenames and Default SYS Numbers

File Type File Name Symbolic Unit Name



Note:Note:The SAM ESDS file is defined implicitly. No EXTENT job control statement is needed if the default model for the volume is used.

If the primary extent is filled, a second extent is allocated.

Any valid SYS number that correctly defines the device is used for sort work files.

Area for SORTWK1 is used only if all input data does not fit in the allocated data space or, if specified, in the partition GETVIS.



11
Using Program Control
Statements

Introduction

Program control statements direct CSI-SORT in processing records. Some program control statements are required while others are optional. Use the control statements to:

Indicate the application to perform: sort, merge, or copy.

Describe control fields to use.

Indicate program user exits for transferring control.

Describe CSI-SORT functions to invoke.

Describe input, output, and work files.

Indicate various options to use during processing.

Provide program control statements to CSI-SORT from one of the following:

SYSIPT file.

Parameter list.

CSI-SORT checks each control statement for validity. If it finds an error in a statement, CSI-SORT issues a message and then skips the rest of the statement, including any continuation lines, and continues checking the next statement.

If an error was found, CSI-SORT terminates after it completes checking all statements.

This sections provides information on the following topics:

Chapter 12, ‘‘Control Statement Summary.’’

Chapter 13, ‘‘Coding Rules.’’

CSI-SORT User Guide Using Program Control Statements

Chapter 14, ‘‘ALTSEQ Control Statement.’’

Chapter 18, ‘‘ANALYZE Control Statement.’’

Chapter 15, ‘‘END Control Statement.’’

Chapter 16, ‘‘INCLUDE and OMIT Control Statements.’’

Chapter 20, ‘‘INPFIL Control Statement.’’

Chapter 21, ‘‘INREC Control Statement.’’

Chapter 22, ‘‘MERGE Control Statement.’’

Chapter 23, ‘‘MODS Control Statement.’’

Chapter 24, ‘‘OMIT Control Statement.’’

Chapter 24, ‘‘OPTION Control Statement.’’

Chapter 25, ‘‘OUTFIL Control Statement.’’

Chapter 26, ‘‘OUTREC Control Statement.’’

Chapter 27, ‘‘RECORD Control Statement.’’

Chapter 28, ‘‘SORT Control Statement.’’

Chapter 29, ‘‘SUM Control Statement.’’



12
Control Statement Summary
Introduction

This section provides a summary of CSI-SORT program control statements, which includes the following topics:

‘‘Primary Task’’ on page 12-1.

‘‘Including or Omitting Records’’ on page 12-2.

‘‘Reformatting and Editing Records’’ on page 12-2.

‘‘Input/Output Files’’ on page 12-3.

‘‘Functions and Options’’ on page 12-3.

Primary Task A CSI-Sort application requires two control statements:

RECORD—Specifies record length and type information.

Plus either of the following:

— SORT—Specifies whether to sort or copy a record.

— MERGE—Specifies whether to merge or copy a record.

Note:Note:Copying can be specified using either the SORT or MERGE control statement.

CSI-SORT User Guide Control Statement Summary

Table 12-1 on page 12-2 provides a description of the primary task:

Including or Omitting Records

Including or omitting records allows a user to specify whether certain records are included in the output file or omitted from it. Table 12-2 on page 12-2 provides a description:

Reformatting and Editing Records

Reformatting and editing records allows a user to modify individual records by deleting and reordering fields and inserting blanks or binary zeros. Table 12-3 on page 12-2 provides a description:

Table 12-1. Primary Task Description

Task Description

SORT Describes control fields and the number of input and work files if coding a sort application, or specifies a copy application.

Indicates ascending or descending order for the sort.

MERGE Describes control fields and the number of input files coding a merge application, or specifies a copy application.

Indicates ascending or descending order for the merge.

RECORD Describes record length and type information.

Table 12-2. Include or Omit Records

Statement Description

INCLUDE Specifies to include only records whose fields meet certain criteria.

OMIT Specifies to omit any records whose fields meet certain criteria.

Table 12-3. Reformat or Edit Records


OUTREC Maps output record fields.

INREC Maps input record fields.



Input/Output Files Input and output files allows a user to define the characteristics. Table 12-4 on page 12-3 provides a description:

Functions and Options

This area discusses additional functions and options using control statements to perform a variety of tasks. Table 12-5 on page 12-3 provides a description:


For more information about user exit routines, see Chapter 30, ‘‘Using User Exit Routines.’’

Table 12-4. Describing Input and Output Files


INPFIL Describes the input files and specifies procedures to follow when tape input files are opened and closed.

Requires an INPFIL control statement if any default value for input processing is not applicable.

OUTFIL Describes the output files and specifies procedures to follow when tape output files are opened and closed.

Requires an OUTFIL control statement if any default value for output processing is not applicable.

Table 12-5. Additional Functions and Options


ALTSEQ Modifies the default collating sequence.

The modified sequence is used for any control field with a specified format of AQ.

ANALYZE Not supported; option is ignored.

END Causes CSI-SORT to discontinue accepting control statements.

MODS Specifies use of one or more user exit routines.

OPTION Overrides defaults, such as CHALT and PRINT.

Supplies optional information, such as LABEL.

SUM Specifies numeric summary fields in records with equal control fields



13
Coding Rules
Introduction

This section discusses general coding rules containing the following topics:

‘‘Continuation Lines’’ on page 13-1.

‘‘Coding Restrictions’’ on page 13-2.

Continuation Lines

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 and continue on the next.

Figure 13-1 on page 13-1 displays the format of the CSI-SORT continuation line:

Figure 13-1.Continuation Line Format

Column 1 is blank. 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.

The following list of rules apply to continuation lines:

CSI-SORT User Guide Coding Rules

Column 72 must contain a non-blank character if a remark field is broken or is started on a new line.

The continuation begins in any column from 2 through 16.

If an operand field is broken after a comma, the continuation column (72) can be left blank and continuation begins between column 2 through column 16.

If the comma is in column 71 and column 72 contains a non-blank character, the continuation must begin in column 16.

If an operand field is not broken after a comma, the operand field must be broken at column 71.

Column 72 must contain a non-blank character.

The continuation must begin in column 16.

Figure 13-2 on page 13-2 contains an example of valid continuation lines:

Figure 13-2.Example of Valid Continuation Lines

Coding Restrictions

The following rules apply to control statement preparation:

Labels, operation definers, and operands must be in uppercase EBCDIC.

Column 1 of each control statement can be used only for a label.

Labels must begin in column 1 and conform to operating system requirements for statement labels.

The entire operation definer must be on the first line of a control statement.

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.

Blanks are not allowed in operands. Anything following a blank is considered part of the remark field.

Values can contain no more than eight alphanumeric characters.



— Values that specify record counts or storage requirements can contain up to 10 digits.

Examples of record count values are those for SKIPREC and STOPAFT options.

Examples of storage requirements are STORAGE, GVSIZE, GVSRLOW, and GVSRANY options.

Note:Note:Currently, GVSIZE is the only one supported.

Commas, equal signs, parentheses, and blanks can be used only as delimiters.

They can be used in values only if the values are constants.

Each type of control statement can appear only once for each CSI-SORT execution.



14
ALTSEQ Control Statement
ALTSEQ

This section discusses the ALTSEQ control statement:

The ALTSEQ control statement changes the default collating sequence of EBCDIC character data. It does not change data; it changes only the order data is collected.

The ALTSEQ control statement also overrides any modified version of the collating sequence available by default at installation.

When supplying an ALTSEQ control statement, CSI-SORT applies the modified collating sequence to any field whose format is specified as AQ in the SORT, MERGE, INCLUDE, or OMIT control statement.

If specifying AQ without supplying an ALTSEQ control statement, CSI-SORT uses the standard EBCDIC collating sequence.

CSI-SORT User Guide ALTSEQ Control Statement

Operand Table 14-1 on page 14-2 provides a description of the operand for the ALTSEQ control statement:

Miscellaneous Information

Below is additional information concerning the ALTSEQ control statement:

If CHALT in effect, control fields with format CH are collated using the ALTSEQ translate table in addition to those with format AQ.

The moved character (ff) is considered equal to any character already occupying position tt.

A character can only be moved once.

The field where the alternative sequence applies must be in format AQ in the SORT, MERGE, INCLUDE, or OMIT control statement referencing it, or format CH if CHALT is in effect.

Each group of hexadecimal digits must contain four digits.

ALTSEQ control statement causes additional processing for each record, which can degrade performance.

Examples Below are examples of altering EBCDIC collating sequence.

Example 1

Example 1 shows that character $ (X’B’) is to collate at position X’EA’ after uppercase Z (X’E9)

Example 2

In example 2, numbers 0–9 collate before uppercase letters, but after lowercase letters.

Table 14-1. Operand for ALTSEQ Control Statement

Operand Description

CODE Specifies original and modified EBCDIC collating position, in no particular order.

ff—EBCDIC collating position to change; in hexadecimal.

tt—New EBCDIC collating position for the character; in hexadecimal.

Default—Standard EBCDIC.



Example 3

In example 3, uppercase A (X’C1’) collates at the same position as 1 (X’F1’) and uppercase B (X’C2’) collates at the same position as 2 (X’F2’).

Example 4

For example 4, uppercase A collates before lowercase a, B before b; this continues through to Z before z.

Example 5

In example 5, each lowercase letter collates at the same position as the corresponding uppercase letter. For example, a (X’81’) collates at the same position as A (X’C1’). Result is collating that is not case-sensitive.



15
END Control Statement
END

The END control statement allows CSI-SORT to discontinue accepting control statements:

CSI-SORT reads but does not process any statements between END and /*.

A /* JCL statement must follow CSI-SORT control statements in the SYSIPT file.

Example Below is an example of a discontinue processing control statement. The OPTION control statement is read, but not processed, because it appears after the END control statement.

CSI-SORT User Guide END Control Statement



16
INCLUDE and OMIT Control
Statements

INCLUDE and OMIT

This section discusses the INCLUDE and OMIT control statements.

Both control statements are similar in their syntax and capabilities.

One thing to remember is both statements cannot be specified in the same CSI-SORT run. So, when specifying:

INCLUDE, do not specify an OMIT.

OMIT, do not specify an INCLUDE.

INCLUDE The INCLUDE statement allows a user to select the records to sort or merge from the input file(s):

OMIT The OMIT statement selects the records the user does not include. It allows a user to skip certain records from the input file(s) from being sorted or merged:

Use the OMIT control statement for any or all input records that are not to appear in the output file.

CSI-SORT User Guide INCLUDE and OMIT Control Statements

Logical Expression

A logical expression, used by both INCLUDE and OMIT, is one or more logically-combined relational conditions, based on fields in the input record, and represented at a high level as follows:

For the INCLUDE statement, a record is included in the output file if the logical expression is true for that given record.

For the OMIT statement, the record is omitted from the output file if the logical expression is true for a given record.

Table 16-1 on page 16-2 provides a description of the three types of relational conditions:

Nesting Nesting relational conditions within parentheses allows a user to create logical expressions of higher complexity.

Comparisons, substring comparison tests, and bit logic tests can be combined to form logical expressions.

Table 16-1. Relational Conditions Description

Condition Description Examples

Comparisons Compare two compare fields or a compare field and a decimal, hexadecimal, or character constant.

For INCLUDE—Comparing a field with a specified date and including only those records of a more recent date.

For OMIT—Comparing the first six bytes of each record with its last six bytes and omitting records where those fields are not identica

Substring Comparison Tests

Search for a constant within a field value or a field value within a constant.

For INCLUDE— Searching the character constant C’AB,LM,DE’ for the value of a two-byte field and including only those records where C’AB’, C’LM’, or C’DE’ appear in the field.

For OMIT—Searching the value in a six-byte field for the character constant C’OK’, and omitting those records not containing that constant in the field.

Bit Logic Tests Test the state of selected bits in a binary field using a bit or hexadecimal mask or a bit constant. The state is either on or off.

For INCLUDE—Including only those records that have bits 3 and 12 on and bits 6 and 8 off in a two-byte field.

For OMIT—Omitting only the records that have bits 0 and 2 on in a one-byte field.



Operands Table 16-2 on page 16-3 provides a description of the operands used in the INCLUDE and OMIT control statementS:Table 16-2. Operands for INCLUDE and OMIT Control StatementS

Operand Description

COND logical expression—Specifies one or more logically combined relational condition, based on fields in the input record.

If true, the record is either included in or omitted from the output file, depending on which control statement is being used.

All or (ALL)—Specifies to include all input records in the output file or to omit all input records from the output file, depending on which control statement is being used.

NONE or (NONE)—Do not include any input records in the output file or do not omit any input records from the output file, depending on which control statement is being used.

Default—None; must specify.

FORMAT=f Use only when all the input fields in the entire logical expression have the same format

SS—Substring; only allowed for substring comparison tests.

BI—Unsigned binary; only allowed for bit logic tests.

AC, AST, and ASL—Allowed only when DATA=A in the INPFIL control statement.

Default—None; must specify if not included in the COND operand.



Relational Condition

The relational condition specifies to perform a comparison or bit logic test.

Relational conditions may be combined with AND or OR to form a logical expression. If combined, the following rules apply:

AND statements evaluated before OR statements, unless using parentheses to change the order of evaluation.

Expressions inside parentheses are always evaluated first.

Nesting parentheses limited only by amount of available storage.

Symbols for AND (&) and OR (|) can be used in place of the words.

Miscellaneous Some additional information to know about INCLUDE and OMITcontrol statements is:

Floating point compare fields cannot be referenced in either control statement.

Both control statements are mutually exclusive with the other:

— INCLUDE control statements are mutually exclusive with OMIT control statements.

— OMIT control statements are mutually exclusive with INCLUDE control statements.

Any selection can be performed with either an INCLUDE or an OMIT control statement.

In the compare fields and decimal self-defining term, +0, 0, and –0 are treated as the same number and compare equal.

If several relational conditions are joined with a combination of AND and OR logical operators, the AND logical expression is evaluated first.

The order of evaluation can be changed by using parentheses inside the COND logical expression.

If any changes are made to record formats by the E15 or E32 user exit routines, the INCLUDE or OMIT control statement must apply to the newest formats.



Table 16-3 on page 16-5 provides information to help a user get the desired result when writing complex INCLUDE or OMIT control statements and relational condition is followed by AND or an OR logical operator:

Continued Information

Continue to the following chapters:

Chapter 17, ‘‘INCLUDE and OMIT Comparisons,’’ for information about the comparisons relational condition and permissible field formats, continue with

Chapter 18, ‘‘INCLUDE and OMIT Substring Tests,’’for information about substring comparison tests relational condition.

Chapter 19, ‘‘INCLUDE and OMIT Bit Logic Tests,’’for information about bit logic tests relational condition.

Table 16-3. Control Statements Logic Table

Relational Condition Program Action if Next Logical Operator is:

Compare AND OR

True Check next compare or, if last compare:

include the record for INCLUDE

omit the record for OMIT



False omit the record for OMIT


Check next compare, or if last compare,





17
INCLUDE and OMIT
Comparisons

Comparisons

This section discusses comparisons of two compare fields or a compare field and a decimal, hexadecimal, or character constant.

is a continuation of the INCLUDE and OMIT control statement. It discusses the comparisons:

‘‘Relational Condition Format’’ on page 17-1.

‘‘Padding and Truncating’’ on page 17-6.

Information contained in this section is also relevant to the OMIT control statement.

Relational Condition Format

Below are two formats used for the relational condition:

Comparison Relational Condition Format 1.

If FORMAT operand is used:

Comparison Relational Condition Format 2.

CSI-SORT User Guide INCLUDE and OMIT Comparisons

ComparisonOperators

Table 17-1 on page 17-2 provides definitions of the comparison operators and fields:Table 17-1. Comparison Operators and Field Description

Comparison Operator Field Description

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

Note: The fields below are variables that specify the field, in the input record, to be compared either to another field in the input record or to a constant.

p1 Specifies the first byte of the compare field relative to the beginning of the 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. This is because the first four bytes contain the record descriptor word.

All compare fields must start on a byte boundary.

No compare field can extend beyond byte 4092.

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

m1 Specifies the length of the compare field.

See for acceptable lengths for different formats.

f1 Specifies format of the data in the compare field.

If DATA=A in specified in the INPFIL control statement, use only AC, AST, and ASL.

See for allowable formats for comparison.

Note: Omit this value if all compare fields contain the same type of data. Use FORMAT=f operand instead.



Compare FieldFormats and

Lengths

Table 17-2 on page 17-3 provides a description of the compare field formats and lengths:

Field-to-FieldComparisons

Parameters p2, m2, and f2 specify another field in which to compare with p1, m1, and, f1.

Table 17-3 on page 17-4 shows the allowable comparisons between compare fields with different formats for INCLUDE and OMIT control statements:

Table 17-2. Compare Field Formats and Lengths

Format Length Description

CH1

1. If CHALT is in effect, CH is treated as AQ.

1–256 bytes Character

AQ 1–256 bytes Character with alternate collating sequence

ZD 1–18 bytes Signed zone decimal

PD 1–16 bytes Signed packed decimal

FI 1–256 bytes Signed fixed-point

BI 1–256 bytes Unsigned binary

AC 1–256 bytes ISCII/ASCII character

CSL 2–256 bytes Signed numeric with leading separate sign

CST 2–256 bytes Signed numeric with trailing separate sign

CLO 1–256 bytes Signed numeric with leading overpunch sign

CTO 1–256 bytes Signed numeric with trailing overpunch sign

ASL 2–256 bytes Signed ISCII/ASCII numeric with leading separate sign

AST 2–256 bytes Signed ISCII/ASCII numeric with trailing separate sign



Note:Note:AC, ASL, and AST formats sequence EBCDIC data using the ISCII/ASCII collating sequence.

Field-to-ConstantComparison

A constant is either a decimal, character, or hexadecimal.

Table 17-4 on page 17-4 shows allowable comparisons between compare fields and constants for INCLUDE and OMIT control statements:

Table 17-3. Allowable Field-to-Field Comparisons

Field Format BI C

HZD

PD FI A

C

ASL

AST

CSL

CST

CLO

CTO

AQ

BI X X

CH X X

ZD X X

PD X X

FI X

AC X

ASL X X

AST X X

CSL X X

CST X X

CLO X X

CTO X X

AQ X

Table 17-4. Allowable Field-to-Constant Comparisons

Field Format Self-Defining Term

Decimal Number Character String Hexadecimal String

BI X X

CH X X

ZD X

PD X

FI X



Decimal String Format

Format for a decimal constant is [*] [n. . . n] [. nn. . . n]

where n is any decimal digit.

Specify any number of digits except when comparing the constant with a field of F1 format, when the constant may be no larger than 2147483467 nor smaller than -2147483468.

The decimal point is not allowed in comparisons with format fields FI, ZD, or PD.

If specified, the decimal point is counted in the constant length and included in it as a character.

Table 17-5 on page 17-5 provides examples of valid and invalid decimal constants:

AC X X

ASL X

AST X

CSL X

CST X

CLO X

CTO X

AQ X X

Table 17-5. Examples of Valid and Invalid Decimal Constants

Valid Invalid Explanation

11 ++11 Too many sign characters

+11 11+ Incorrect sign placement

–11 –11. Invalid decimal point

14.09 1.4.09 Too many decimal points

18000000 1,800,000 Contains invalid characters

Table 17-4. Allowable Field-to-Constant Comparisons

Field Format Self-Defining Term

Decimal Number Character String Hexadecimal String



Character String Format

Format for a character string constant is C’cc...c’

where c may be any EBCDIC character, up to 256 characters. The EBCDIC character string is translated properly for comparison to an AC or AQ field.

To include a single apostrophe in the character string, such as for the name O’Malley, specify it with two single apostrophes. For example, C’O’ ‘Malley’

Table 17-6 on page 17-6 provides examples of valid and invalid character string constants:

Hexadecimal String Format

The format for hexadecimal is X’ xx...xx’

where xx is any pair of hexadecimal digits, up to 256 pairs. Valid hexadecimal digits are 0–9, A, B, C, D, E, and F.

Table 17-7 on page 17-6 provides examples of valid and invalid hexadecimal constants:

Padding and Truncating

The shorter compare field is padded in field-to-field comparisons.

The constant is padded or truncated to the length of the compare field in field-to-constant comparisons

Character and hexadecimal strings are truncated and padded on the right.

Table 17-6. Valid and Invalid Character Constants


C’ JDCO’ C’ ‘ ‘ ‘ ‘ Apostrophes not paired

C’ $@#’ ‘ABCDEF’ C identifier missing

C’ +0.193’ C’ ABCDEF Apostrophe missing

C’ Frank’ ‘s’ C’ Frank’s’ Two single apostrophes needed for one

Table 17-7. Valid and Invalid Hexadecimal Examples


X’ ABCD’ X’ ABGD’ Invalid hexadecimal digit

X’ BF3C’ X’ BF3’ Incomplete pair of digits

X’ AF050505’ ‘ AF050505’ Missing X identifier

X’ BF3C’ ‘ BF3C’ X X identifier in wrong place



Decimal constants are padded and truncated on the left. Padding is done with zeros, using the correct format.

Padding characters are:

X’40’—EBCDIC character string; blank character.

X’20’—ISCII/ASCII character string; blank character.

X’00’—Hexadecimal string; binary zeros.

Examples Below are comparison examples of including records in the output file.

Example 1

Example 1 illustrates how to include records where:

The fixed-integer number in bytes 5–12 is greater than the fixed-integer number in bytes 13–20,

OR

The fixed-integer number in bytes 105–108 is less than or equal to 1000.

Example 2

Example 2 displays how to include records where:

The first 10 bytes contain STOCKHOLM (string is padded on right with a blank)

AND

The zoned decimal number in bytes 21–28 is greater than 50000,

OR

Bytes 31–34 do not contain HERR.

The AND is evaluated before the OR. Ending a line with a comma followed by a blank indicates the parameters continue on the next line, starting in any position from columns 2–16.

Example 3



Example 3 displays how to include records based on a two-digit character year field in bytes 21–22.

This includes records with a value greater than or equal to C’85’ in bytes 21–22 or with a value less than or equal to C’03’ in bytes 21–22, which effectively can include records where the year is between 1985 and 2003, inclusive.

Below is an example for omitting records from the output file:

Example 4

Example 4 omits records where:

Byte 27 contains D

AND

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:Note:The AND and OR operators can be written using the AND and OR signs. Parentheses are used to change the order in which AND and OR are evaluated.


For more information about format descriptions, see Appendix B, ‘‘Data Format Examples.’’

For more information about local processing, see Chapter 3, ‘‘Workings.’’



18
INCLUDE and OMIT Substring
Tests

Substring Comparison Tests

There are two types of substring comparison tests:

1. Find a constant within a field value.

For example, search the value in a six-byte field for character constant C’OK’. The relation condition is true if the field value is C’**OK**’ or C’****OK’; false if the field value is C’**ERR*’.

2. Find a field value within a constant.

For example, search character constant C’J69,L92,J82’ for the value in a three-byte field. The relational condition is true if the field value is C’J69’, C’L92’, or C’J82’; false if the field value is C’X24’. Notice the comma is used within the constant to separate the valid three-character values; any character not appearing in the field value can be used as a separator in the constant.

This section discusses:

‘‘Relational Condition Format’’ on page 18-1.

‘‘Substring Comparison Examples’’ on page 18-2.


Relational Condition Format

There are two formats for the substring comparison relational condition:

Substring Comparison Format 1.

OR, if using FORMAT=SS operand:

CSI-SORT User Guide INCLUDE and OMIT Substring Tests

Substring Comparison Format 2.

Table 18-1 on page 18-2 provides a definition of the substring comparison operators:

Substring Comparison Examples

Below is an example for including records in the output file using substring comparison:

Table 18-1. Substring Comparison Operators

Operator Field Description

EQ Equal to

NE Not equal to

Note: The following variables specify the character field in the input record for the substring test.

p1 Specifies first byte of character input field.

First data byte of a fixed-length is relative position 1.

First data byte of a variable-length record is relative position 5; the first four bytes contain the record descriptor word.

All fields to be tested must start on a byte boundary and must not extend beyond byte 4092.

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

m1 Specifies length of field to be tested.

Length is 1 to 256 bytes.

Constant A character string or a hexadecimal string.

If m1 greater than constant length:

The field value is searched for the constant, and.

Condition is true if a match is found when the EQ comparison operator is specified, or

Condition is true if no match found when the NE comparison operator is specified

If m1 is smaller than the constant length:

The constant is searched for the field value constant, andCondition is true if match found with EQ comparison operator specified, orCondition is true if no match found when NE comparison operator specified.



The example assumes the following to demonstrate how to include only records where:

OK is found somewhere within bytes 11 through 16

OR

Bytes 21 through 23 contain J69, L92, or J92.


For more information about character string format, see "Character String Format" in Chapter 17, ‘‘INCLUDE and OMIT Comparisons.’’

For more information about hexadecimal string format, see "Hexadecimal String Format" in Chapter 17, ‘‘INCLUDE and OMIT Comparisons.’’



19
INCLUDE and OMIT Bit Logic
Tests

Bit Logic Tests

This section discusses bit logic tests, in which there are two separate and unique methods:

‘‘Bit Operator Tests’’ on page 19-1.

‘‘Bit Comparison Tests’’ on page 19-5.

Having the ability to specify selected bit in a field reduces the number of INCLUDE conditions that must be specified to achieve a given result. This is because it eliminates the need to account for unspecified bits.


Bit Operator Tests Bit operator tests are used with either hexadecimal or bit mask.

This method allows the user to test whether selected bits in a binary field are in any of the following conditions:

On.

Off

Mixed on–off.

Selected combinations.

This method allows the user to test many different possible bit combinations with a single operation, but it is less suited to determine whether a field contains exactly one particular combination of on and off bits.

CSI-SORT User Guide INCLUDE and OMIT Bit Logic Tests

Relational ConditionFormat

There are two formats for the bit operator tests relational condition:

Bit Operator Test Format 1.

Or, if using the FORMAT=BI operand:

Bit Operator Test Format 2.

Bit Operators

Table 19-1 on page 19-2 provides a description of the bit operators that describe the input field to mask relationship to be tested:Table 19-1. Input Field to Mask Relationship

1st Operator Set1

1. The 1st operator set is for those who like meaningful mnemonics. Operator sets are either or.

2nd Operator Set2

2. The 2nd operator set is for those familiar with the conditions associated with the TM (Test Under Mask) instruction.

Description

ALL BO All mask bits are on in the input field

SOME BM Some, but not all mask bits are on in the input field

NONE BZ No mask bits are on in the input field

NOTALL BNO Some or no mask bits are on in the input field

NOTSOME BNM All or no mask bits are on in the input field

NOTNONE BNZ All or some mask bits are on in the input field



Fields

Table 19-2 on page 19-3 provides a description of the fields:

Masks

Masks are either a hexadecimal string or a bit string that indicates the bits in the field selected for testing:

Bit mask set to on (1)—Tests corresponding bit in the field.

Bit mask set to off (0)—Ignores corresponding bit in the field.

The hexadecimal string format is X’yy...yy’

where yy is any pair of hexadecimal digits that make up a byte (8 bits). Each bit must be 1 (test bit) or 0 (ignore bit). Specify up to 256 pairs of hexadecimal digits.

The bit string format is B’bbbbbbbb...bbbbbbbb’

where bbbbbbbb is eight bits that make up a byte. Each bit must be 1 (test bit) or 0 (ignore bit). Specify up to 256 groups of eight bits. The bit total in the mask must be a multiple of eight.Use only with a bit operator.

Padding andTruncation

The hexadecimal or bit mask is truncated or padded on the right to the byte length of the binary field.

The padding character is X’00’, all bit off and not tested.

Table 19-2. Field Description

Field Description

p1 Specifies the first byte of the binary input field to be tested against the mask.

The first data byte of a fixed-length record is at relative position 1.

The first data byte of a variable-length record is at relative position 5. The first four bytes contain the record descriptor word.



m1 Specifies the length of the field to be tested; 1 to 256 bytes.



Bit Operator TestExamples

Below are three examples of bit operator tests.

Example 1; Bit Operator Test

Example 1 shows how to include only records where:

Byte 27 contains D

OR

Byte 18 has bit 0 set to on.


Example 2 shows how to include records where byte 11 has some, but not all of bit 0, 5, and 7. Table 19-3 on page 19-4 provides the results for the selected fields in example 2:


Example 3 shows how to include records where:

Bytes 11 through 12 have all of bits 3, 6, 10, 11, and 13 on

OR

Byte 21 has none of bits 1, 4, or 5 on:

Table 19-3. Example 2 Results

11, 1, BI Value 11, 1, BI Result Action

X’85’ False Omit Record

X’C1’ True Include Record

X’84’ True Include Record




Table 19-4 on page 19-5 provides the results for the selected fields in example 3:

Bit Comparison Tests

Bit comparison tests allows the user to test if selected bits in a binary field are in an exact pattern of on and off bits, or not in that exact pattern

Using this method:

Only equal and unequal comparison allowed.

Tests for a precise combination of on and off bits.

Relational ConditionFormat

There are two formats for the bit comparison tests relational condition:

Bit Comparison Test Format 1.

Or, if using the FORMAT=BI operand:

Bit Comparison Test Format 2.

Bit Comparison Operators

Table 19-5 on page 19-5 provides a description of the bit comparison operators:

Table 19-4. Example 3 Results

11,2,BI Value

11,2,BI Result

21,1,BI Value

21,1,BI Result Action

X’1234’ True X’4C’ False Include Record

X’02C4’ False X’81’ True Include Record

X’0204’ False X’40’ False Omit Record

X’F334’ True X’00’ True Include Record

X’1238’ False X’4F’ False Omit Record

Table 19-5. Bit Comparison Operators

Operator Description

EQ Equal to

NE Not equal to



Fields

Table 19-6 on page 19-6 provides a description of the fields:

Bit Constant

A bit string constant specifies the pattern to which the binary field is compared:

Bit in constant set to 1 or 0—Corresponding bit in the field is compared to 1 or 0, respectively.

Bit in constant set to a period(.)—Ignores corresponding bit in the field.

The bit string format is B’bbbbbbbb...bbbbbbbb’

where bbbbbbbb is eight bits that make up a byte. Each bit must be:

— 1—Test bit for 1

— 0—Test bit for 0

— . (period)—Ignore bit.

Specify up to 256 groups of eight bits. The bit total in the mask must be a multiple of eight.

Use only with a bit constant for bit comparison test (BI format and EQ or NE operator).

Padding andTruncation

The bit constant is truncated or padded on the right to the byte length of the binary field.

The padding character is B’00000000’ (all bits equal to 0).

Note:Note:The padded bytes are compared to the excess bytes in the binary field; shorten the field length to eliminate padding characters or increase

Table 19-6. Bit Comparison Field Description

Field Description

p1 Specifies the first byte of the binary input field to be compared to the bit constant.

The first data byte of a fixed-length record is at relative position 1.

The first data byte of a variable-length record is at relative position 5. The first four bytes contain the record descriptor word.



m1 Specifies the length of the field to be tested; 1 to 256 bytes.



length of the bit constant to specify exact test pattern to ensure no unwanted results.

Bit Comparison TestExamples

Below are three examples for bit comparison tests.

Example 1; Bit Comparison Test

Example 1 shows how to include only records where:

Byte 27 contains D

AND

Byte 18 is equal to the specified pattern of bit 0 on.


Example 2 shows how to include records where byte 11 is not equal to the specified pattern of bit 0 on, bit 1 off, bit 5 on and bit 7 on:

Table 19-7 on page 19-7 provides the results for the selected fields in example 2:


Example 3 shows how to include records where:

Table 19-7. Example 2 Results for Bit Comparison

11, 1, BI Value 11, 1, BI Result Action


X’C1’1

1. Bit 1 on, bit 5 off.

True Include Record

X’84’2

2. Bit 7 off.

True Include Record




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

Byte 21 is equal to the specified pattern of bit 0 off and bit 1 on:

Table 19-8 on page 19-8 provides the results for the selected fields in example 3:Table 19-8. Example 3 Results for Bit Comparison

11,2,BI Value

11,2,BI Result

21,1,BI Value

21,1,BI Result Action

X’1221’ True X’C0’1

1. Bit 0 on.

False Include Record

X’02C4’2

2. Bit 3 off, bit 8 on, bit 15 off.

False X’41’ True Include Record

X’1234’3

3. Bit 15 off.

False X’00’4

4. Bit 1 off.

False Omit Record

X’5F7F’ True X’7F’ True Include Record

X’FFFF’5

5. Bit 2 on, bit 8 on.

False X’2F’6

6. Bit 1 off.

False Omit Record



20
INPFIL Control Statement
INPFIL Control Statement

This section discusses the INPFIL control statement:

The INPFIL control statement:

Defines the input files to CSI-SORT

Specifies the procedure to follow when tape input files are opened and closed.

Is only required if a default value for input processing is not applicable.

CSI-SORT User Guide INPFIL Control Statement

Operands Table 20-1 on page 20-2 provides a description of the operands identified in the INPFIL control statement:Table 20-1. INPFIL Operands

Operand Description

BLKSIZE=n Specifies the maximum input block size in bytes. It is not required if:

Input files are VSAM files, accessed as VSAM, or

All input files are on FBA devices, or

All input files are unblocked.

Otherwise, BLKSIZE must be supplied as CSI-SORT does not support the DLBL job control statement BLKSIZE parameter.

When specified for variable-length records, BLKSIZE must include the four-byte block descriptor word. For ISCII/ASCII data, it must include BUFOFF value.

If input files have different block sizes, n must be equal to the largest block size.

Default: Fixed-length records—L1 value, from RECORD

control statement.

Variable-length records—L1 value, from RECORD control statement, plus four bytes.

ISCII/ASCII variable-length records—L1 value from RECORD control statement, plus BUFOFF value.

BUFOFF=n Specifies block prefix size at the front of each physical record on the input files.

Use BUFOFF only with variable-length ISCII/ASCII data.

n is any value from 0–99.

Default—0.

BYPASS Specifies CSI-SORT skip incorrectly read input data blocks and physical records that are the wrong length. CSI-SORT then prints an information message and continues.

If not specified, CSI-SORT issues an error message and terminates if it encounters incorrectly read input data blocks or physical records that are the wrong length.

Bypasses the remainder of the control interval with an error if specified for SAM ESDS files.

Ignored—If specified for FBA input files.

Skips all complete and partial records in a block with an error if specified in conjunction with SPAN operand.

Default—None, optional.



CLOSE=xx Specifies procedure to follow when tape input files are closed.

When xx is:

RWD—Rewind tapes.

UNLD—Rewind and unload tapes.

NORWD—Do not rewind tapes.

Default—RWD.

DATA=x Specifies input data format.

When x is

E—Input data format is EBCDIC.

A—Input data format is ISCII/ASCII; only valid for tape input files.

Default—E.

EXIT Specifies the user exit routine read all input data and pass each record to CSI-SORT.

The user must:

Activate E15 user exit by specifying its name in the MODS control statement.

Provide a routine at E15 user exit that opens and reads the files and passes the records one at a time to CSI-SORT.

When specified, all other INPFIL control statement operands, except DATA, are ignored.

Default—None; optional.

NOCHAIN Ignored if specified.

OPEN=xx Specifies procedure to use for opened tape input files.

When xx is:

RWD—Rewind first volume of each input file before reading.

NORWD—Do not rewind first volume of each input file before reading.

Default—RWD.

SPAN Specifies SAM input files consist of variable-length EBCDIC records and that the records may be spanned.

RECORD control statement must specify TYPE=V.

Not required if VSAM input files consist of spanned records.


Table 20-1. INPFIL Operands

Operand Description



Miscellaneous Some additional information to know about the INPFIL control statement is:

Any operands that precede EXIT in the INPFIL control statement are checked for syntax errors and flagged.

Any operands that follow EXIT in the INPFIL control statement are checked for syntax errors and flagged, but all values are ignored.

The presence or absence of the EXIT operand affects the default symbolic unit names for the other files CSI-SORT uses.

If the EXIT operand and the ADDROUT or ADDROUT=D option are specified, CSI-Sort terminates and issues an applicable message.

CSI-SORT adds a four-byte record descriptor word to every variable-length record received from VSAM files. The user-written exit routines that handle variable-length records received from CSI-SORT do not need to be designed separately for handling VSAM and SAM files.

TOL Specifies CSI-SORT tolerate a warning code from VSAM when opening/accessing VSAM input files.


VOLUME=n

VOLUME=(n,n,n,...n)

Specifies number of volumes for each input file.

n is a value between 1 and 255.

Value order is SORTIN1,SORTIN2,...SORTIN9.

Use only for unlabeled or nonstandard labeled files.

Ignores labeled files.

Default—1.

VSAM Specifies input files are VSAM files.

If not specified, assumes SAM files.

Also access SAM ESDS files with VSAM.

Overrides all other INPFIL control statement operands except TOL and EXIT. EXIT overrides VSAM.


Note: Mixture of SAM and VSAM input files not allowed. SAM ESDS files can be mixed with either provided all input files are accessed the same way, either all SAM or all VSAM.

Table 20-1. INPFIL Operands

Operand Description



If TOL is not specified for VSAM input files, a warning return code from VSAM is normally recognized as an error; an error message is then issued and CSI-SORT terminates.

If TOL is specified, CSI-SORT reads input files without repairing and no error message issued.

Condition examples that produce warning messages are:

‘NOT PROPERLY CLOSED’

‘SYSTEM TIME STAMPS OF DATA AND INDEX DO NOT MATCH’.

Whether or not TOL is specified, a critical return code from VSAM terminates CSI-SORT, except for a null VSAM file (return code X’6E’).

Use BYPASS to prevent records in files with an incorrect record length from causing CSI-SORT termination.

For SAM ESDS files, the BLKSIZE operand refers to maximum logical block size. It should match the RECORDSIZE (maximum) operand specified in DEFINE command for the file when it was created with VSAM Access Method Services (AMS).

Note:Note:Fixed-length input blocks that are too long are truncated by data management and cannot be checked by CSI-SORT.

Examples Below are examples of defining input files.

Example 1

Table 20-2 on page 20-5 provides an explanation of the operands used in Example 1:Table 20-2. Operands Used in Example 1

Operand Used Description

VOLUME The four input files consist of three, five, two, and one unlabeled tape volumes, respectively.

BLKSIZE Block size is 400 bytes.

OPEN Do not rewind before being read the first volume of each input file.

BYPASS Ignore incorrectly read input data blocks.

DATA Input data is ISCII/ASCII.

BUFOFF Each block buffer offset is 99 bytes.



Example 2

The definition for the operand used in example 2 is:

EXIT—All input data is received by CSI-SORT from E15 user exit routine.


For more information about block size, see "Record Length and Block Size" in Chapter 4, ‘‘Things to Consider.’’

For more information about performance, see Chapter 46, ‘‘Improving Efficiency.’’



21
INREC Control Statement
INREC

This section discusses the INREC control statement:

The INREC control statements allows a user to reformat an input record before processing. The user can:

Define the parts of an input record to be included in the reformatted input record.

Denote the order they are to appear.

How they are to be aligned.

Insert blanks and binary zeros as separators before, between, and after the fields in the reformatted input records.

The reformatted input record:

Consists only of the user-specified fields in the order denoted, and

Are aligned on the boundaries or in the columns indicated.

Operands INREC uses one operand, FIELDS, which must be specified.

CSI-SORT User Guide INREC Control Statement

Table 21-1 on page 21-2 provides a description of the values:Table 21-1. Values for Fields Operand

Value Description

s The separation field to be inserted into the reformatted input record. Insert in the position coded, relative to the other fields. Specify before or after any input field and can specify consecutive separation fields. For variable-length records:

Do not specify before first input field, this is the record descriptor word.

Do not specify after the variable part of the input record.

Include at least one byte of fixed data in the reformatted input record.

Specify as one of the following:

nX—Blank separation. n bytes of EBCDIC blanks (X’40’) are inserted in the reformatted input records. Range 1 to 256.

Uses 1 if n omitted.Inserts n bytes of ISCII/ASCII blanks (x’20’) if DATA=A in the INPFIL control statement.Examples are:

nZ—Binary zero separation. Inserts n bytes of binary zeros (X’00’) in the reformatted input records. Range is 1 to 256.

Uses 1 if n is omitted.Examples are:

Table 21-2. Valid and Invalid Blank Separation

Validity Specified Result

Valid 1X or X 1 blank

Valid 256X 256 blanks

Invalid 500X Too many repetitions. Use two adjacent separation fields instead, such as 256X and 244X

Invalid 0X 0 is not allowed

Table 21-3. Valid and Invalid Zero Separation


Valid 1Z or Z 1 byte of binary zeros

Valid 256Z 256 bytes of binary zeros

Invalid 500Z Too many repetitions. Use two adjacent separation fields instead, such as 256Z and 244Z

Invalid 0Z 0 is not allowed



Miscellaneous Some additional information to know about the INREC control statement is:

When specified, CSI-SORT reformats the input records after E15 user exit and INCLUDE or OMIT processing finishes.

References to fields by E15 user exit routine and INCLUDE or OMIT control statements are not affected, but SORT and SUM control statements must refer to fields in the reformatted input records.

The E35 user exit routine must refer to fields in the reformatted output record.

p, m, a p—Specifies first byte of input field of the input record.

First data byte of a fixed-length record has relative position 1.

First data bye of a variable-length record has relative position 5; first four bytes are the record descriptor word.

Fields start anyplace within the record on a byte boundary. See ‘‘Miscellaneous’’ on page 21-3 for more information about special rules concerning variable-length records.

Note: If the E15 user exit routine reformats the record, p must refer to the record as reformatted by the routine.m—Specifies length of the input field.

Must include the sign, if the data is signed, and an integer number of bytes. See ‘‘Miscellaneous’’ on page 21-3 for more information.

a—Specifies alignment (displacement) of the input field in the reformatted input record, relative to the beginning of the reformatted input record.

Allowable values are:

— H—Halfword aligned. This displacement (p-1) of the field from the beginning of the reformatted input record, in bytes, is a multiple of two. For example, position 1, 3, 5).

— F—Fullword aligned. The displacement is a multiple of four; 1,5, 9).

— D—Doubleword aligned. The displacement is a multiple of eight; 1, 9, 17).

Unused space preceding aligned fields is padded with binary zeros.

Note: Alignment may be required if data is in a COBOL application program where computational items align through the synchronized clause.

p Specifies variable part, outside minimum record length, of the input record is to appear in the reformatted input record as the last field.

Specify a value less than or equal to the minimum input record length, plus one byte.

Note: Null records with only an RDW may result if reformatted input record includes only the RDW and the variable part of the input record.

Table 21-1. Values for Fields Operand

Value Description



When the INREC control statement is specified, be aware of resulting changes to record size and layout for reformatted input records.

Use the INREC control statement only if needed to reformat records.

This reduces the length of the records and improves performance.

For variable-length records, specify or include the 4-byte record descriptor word (RDW) in the first input field of the FIELDS operand.

CSI-SORT sets length of reformatted record in the RDW.

If the first field in the data portion of the input record immediately follows the RDW in the reformatted record, the first input field in the FIELDS operand can specify both RDW and data field. Otherwise, include RDW in the reformatted record.

The variable part of the input record can be included in the reformatted input record as the last part.

Using this scenario, specify a value for p (‘‘p’’ on page 21-3) that is less than or equal to the minimum record length, plus one byte; omit m and a.

Null records with only an RDW could result if the reformatted input record includes on the RDS and the variable part of the input record.

Input records are reformatted before processing, as specified by the INREC control statement.

Records passed to sort or merge are in the format specified by the INREC control statement when stipulated.

Fields referenced in the INREC control statement can overlap:

— Each other, and

— Control fields, or

— Both.

If input is variable-length, output is also variable length.

Each record is given the correct RDW by CSI-SORT before output.

If overflow occurs during summation, use the INREC control statement to create a larger summary field in the reformatted input record to stop the overflow.

This action could result in a larger record for sorting or merging.

CSI-SORT calculates the L3 value.

Consider the calculated L3 value when specifying the BLKSIZE operand in the OUTFIL control statement.

Examples Below are examples for reformatting records before processing.



Example 1 INREC Method

Examples 1 show the following:

How three fixed-length input files are sorted and reformatted for output.

Unnecessary fields eliminated from the output records.

Input record size is 80 bytes, three records per block.

The INCLUDE control statement includes or excludes records while the SUM control statement sums them.

Reformatted input records are fixed-length; record size is 23 bytes.

Table 21-4 on page 21-5 provides a description of the reformatted records after INREC processing:

For INREC, the INCLUDE COND operands must refer to the fields of the original input records:

The OUTFIL indicates the 23 byte records are written as ten records per block in the output file.

Example 2

Example 2 shows how overflow of a summary field can be prevented when three fixed-length files are sorted and reformatted for output. Input record size is 80 bytes.

Table 21-4. Reformatted Records After Processing

Position Contents

1–3 Input positions 10 through 12



23 Input position 5



Table 21-5 on page 21-6 provides a description of the reformatted input records, which are fixed-length with 82-byte record size:

SORT and SUM statements must refer to fields of the reformatted input records.

Reformatted output records are identical to reformatted input records.

To prevent overflow of the summary field, the two-byte summary field at positions 36 and 37 in the original input records expands to a four-byte summary field in positions 36 through 39 of the reformatted input/output record before sorting.

The OUTFIL maintains the three records per block but with a record length of 82 instead of 80.

Note:Note:Do not use this method with negative FI summary fields as padding with zeros rather than ones changes the sign.

Table 21-5. Example 2 Reformatted Input Records

Position Contents


36–37 Binary zeros; used to prevent overflow





For more information about the interaction of INREC control statements, see any of the following:

‘‘Miscellaneous’’ on page 21-3.

Chapter 46, ‘‘Improving Efficiency.’’

For more information about record length, see Chapter 27, ‘‘RECORD Control Statement.’’



22
MERGE Control Statement
MERGE

This section discusses the MERGE control statement:

Use the MERGE control statement:

To perform a merge application, where it describes the control fields for the previously sorted input records.

To perform a copy application.

To merge or copy up to nine files.

CSI-SORT User Guide MERGE Control Statement

Operands Table 22-1 on page 22-2 provides a description of the operands identified in the MERGE control statement:

Miscellaneous Additional information to know about the MERGE control statement is:

In the control fields, +0, 0, and –0 are treated as the same number and compare equal.

Input files must be either all SAM or all VSAM.

Specify the number of volumes using the VOLUME operand of the INPFIL control statement if any of the input files are multivolume and unlabeled or nonstandard labeled.

Examples Below are examples for merging and copying.

Table 22-1. MERGE Operands

Operand Description

FIELDS Specify as p, m, f, or s.

Same as SORT, see Chapter 28, ‘‘SORT Control Statement.’’

FIELDS=COPY or

FIELDS=(COPY)

Copies one or more input files to an output file.

When FIELDS=COPY:

Ignores all other MERGE operands, except SKIPREC and STOPAFT.

CSI-SORT terminates when specified with SUM or INREC control statement.


FORMAT Use only when all control fields in the entire FIELDS expression have the same format.

See description for f in Chapter 28, ‘‘SORT Control Statement.’’

Default—None; must specify if not included in FIELDS operand.

EQUALS

NOEQUALS

See Chapter 24, ‘‘OPTION Control Statement.’’

FILES Specifies number of input files to be merged or copied.

Specify as FILES=n, where n is any number from 1 through 9.

Default—None; must specify for merge applications; 1 for copy applications.

SKIPREC Specify as SKIPREC=n.


STOPAFT Specify as STOPAFT=n.




Example 1

Example 1 illustrates the following:

The FIELDS control field:

— Begins on byte 2 of each record in the input files

— Is five bytes long

— Contains character, EBCDIC, data that will be sorted in ascending order.

FILES shows merge three input files.

Example 2

Either statement shown in example 2 illustrates the following:

FIELDS major control field:

— Begins on byte 25 of each record

— Is four bytes long

— Contains zoned decimal data that will be sorted in ascending order

FIELDS second control field:

— begins on byte 48

— Is eight bytes long

— Contains the same data format as the major field

— Will be sorted in ascending order when the major control field is the same in two records

FORMAT operand used because both control fields have the same data format—zoned decimal.

FILES indicates to merge nine files.

Example 3

Example 3 indicates copy the input file to the output file without merging. This is treated like a SORT of no fields.



23
MODS Control Statement
MODS

This section discusses the MODS control statement:

Use the MODS control statement when CSI-SORT passes control to the user exit routines.

The MODS control statement:

Associates the user routines with specific CSI-SORT user exits, and

Provides CSI-SORT with descriptions of the routines.

To use one of the user exits, associate its three-character name with the phase in which it is to be used.

CSI-SORT User Guide MODS Control Statement

Operands Table 23-1 on page 23-2 provides a description of the operands identified in the MODS control statement:

Miscellaneous Some additional information to know about the MODS control statement is:

If using absolute loading address, the length of the module containing the routines is unknown to CSI-SORT.

If the length of user exit routines is specified, the routines must be:

— Self-relocating (unmodified address constants cannot be used, or

— Eligible for relocation by the system loader program.

This allows CSI-SORT to load local routines that leaves maximum virtual storage available for other uses.

Table 23-1. MODS Operand

Operand Description

PHx Specifies the CSI-SORT phase, with x specified as:

1—Initial sorting phase; phase 1.

3—Final merging phase; phase3.

For either PH1 or PH3:

n—Catalog name of routines executed at the specified user exits.

— Omit if routines are already in virtual storage. — Use any valid operating system name for the routines,

which allows keeping several alternative routines with different names in the same library.

m—Loading information. Describes one of two ways CSI-SORT loads user routines may be loaded into virtual storage:

— Omit if routines already in virtual storage. — Value can be absolute loading address (in decimal) or

length of user routines to execute (decimal bytes and prefixed with L).

Default—None; must be specified.

exit Specifies user exits to use in the specified CSI-SORT phase.

Typical values, in any order, are:

E15

E32

E35

Default—None; must specify if using user exit routine.



Examples Below are examples for identifying user exit routines.

Example 1

Example 1 shows user exit routines for the initial sorting phase and the final merging phase.

The USERV module contains a routine 500 bytes long that executes at E15 user exit.

The USERK module contains routines 800 bytes long that execute at E35 user exit.

Example 2

Example 2 shows user exit routines for the final merging phase.

The user exit routines are already in virtual storage, so the name and loading information are not included.

Preloaded user exit routines, which execute at E31 and E35, are used only for program invoked sort, merge, or copy applications.

Note:Note:Only the E35 exit routine is currently supported; the E31 exit routine is ignored.


For more information about user exit routines, see Chapter 30, ‘‘Using User Exit Routines.’’



24
OPTION Control Statement
OPTION

This section discusses the OPTION control statement:

CSI-SORT User Guide OPTION Control Statement

The OPTION control statement allows a user to:

Override options available at installation, such as DIAG, and

Supply optional information, such as ADDROUT and LABEL.

Note:Note:ADDROUT and DIAG are not supported at this time and will be ignored if specified.

Operands Table 24-1 on page 24-2 provides a descriptions of the operands available to the OPTION control statement:Table 24-1. OPTION Operands

Operand Description

ADDROUT CSI-SORT does not currently support this operand.

Ignored if specified.

ADDROUT=D CSI-SORT does not currently support this operand.


CHALT Specifies that CSI-SORT treat CH format fields the same as AQ format. That is, translate character fields using the alternate collating sequence.

Default—Treat CH format fields as character.

NOCHALT This field is ignored since the default is to treat CH format fields as character.

DIAG CSI-SORT does not currently support this operand.


NODIAG CSI-SORT does not currently support this operand.




DSPSIZE Specifies the size of the data space area created for sorting purposes.

Value determines the size of data space CSI-SORT may allocate.

n—Specifies amount, in MB, of data space used for dataspace sorting; must be a value between 0 and 2048.

The n value is overridden if DSPACE=n parameter is specified on the EXEC SORT command; for example:

//EXEC SORT,SIZE=4K,DSPACE=10M

The n value is the maximum size of a single data space area. The actual size is determined by increments of the default allocation up to this value.

If DSPACE is not specified and either DSPSIZE is not specified or is set to zero (0), the default size is used for allocation and maximum size for data space required. This default size is based on the last SYSDEF job control statement processed.

Enter command QUERY DSPACE to determine current values.

DUMP CSI-SORT does not currently support this operand.


NODUMP CSI-SORT does not currently support this operand.


EQUALS CSI-SORT does not need this operand.

The sort and merge algorithms that are used maintain the original order of data when duplicates are found.


NOEQUALS CSI-SORT does not need this operand.



ERASE CSI-SORT does not currently support this operand.


NOERASE CSI-SORT does not currently support this operand.


Table 24-1. OPTION Operands

Operand Description



FILNM Specifies the filename to use in TLBL and DLBL job control statements for the output and input files. Filenames must be in the order output, input1, ... inputn.

A valid filename must begin with an alphabetic character; seven alphanumeric characters are maximum for input and output files.

Work filename prefix can be specified here. If a work filename prefix is supplied:

Specify last and in the eleventh position

Indicate omitted input parameters with commas

And if specified in both FILNM and WORKNM operands, uses the second one specified and overrides the first one specified

Default—Default filenames are assumed for all output and input files if FILNM omitted.

GVSIZE Indicates partition GETVIS are will be used instead of data space area unless GVSIZE=0 is specified.

n—Specifies using n bytes of GETVIS area for getvis sorting.

nK—Specifies using n times 1024 bytes of GETVIS are for getvis sorting.

nM—Specifies using n times 1048576 bytes of GETVIS are for getvis sorting.

Default—GVSIZE=0, indicating data space sorting.

Note: n limit is 10 digits; maximum value is 2047M.

GVSRANY CSI-SORT does not need this operand.


GVSRLOW CSI-SORT does not need this operand.


LABEL Specifies type of label associated with output and input files. Sequence is output, input1, ... inputn.

Specify as:

N—Nonstandard labels; includes user standard labels with additional user header or trailer labels.

Must provide routines at the label checking user exits to open and close files and process the labels.

S—Standard labels; default.

U—Unlabeled.

Default—S.

If omitted, uses standard labels for all input and output files.

LOCALE CSI-SORT does not currently support this operand.



Operand Description



NRECOUT CSI-SORT does not currently support this operand.


PRINT Tells CSI-SORT what messages to produce. Specify as:

ALL—Produce all CSI-SORT messages; includes error, end-of-application, and other informational messages.

NONE—Do not produce CSI-SORT messages.

CRITICAL—Produce only critical error messages; error message signaling conditions that cause CSI-SORT to terminate.

Default—PRINT=ALL if started by job control;

PRINT=CRITICAL if started by an application.

ROUTE CSI-SORT does not currently support this operand.


SKIPREC The number of records to skip before starting to sort or copy the input files:

n—Number of records to skip; limit is 10 digits with maximum value of 2147483647.

Not used if SKIPREC=0 in effect.


Can specify in OPTION, SORT, or MERGE control statements. If used in the OPTION control statement, it overrides any specification on the SORT or MERGE control statement.

Applies only to records read from SORTIN, not from an E15 user exit.

SORTIN Overrides installation option that specifies logical unit numbers of the input files:

Value for a logical unit number is from 1 through 221 or a comma to use the default logical unit number.

Required only for tape files.

Default—002 through 010.

SORTOUT Overrides default value that specifies the output device.

Specify as:

n—Output device logical unit number; values are 1 through 221; required for tape, printer, and punch devices.

LST—Write output to SYSLST.

PCH—Write output to SYSPCH.

Default—SYS001.


Operand Description



STOPAFT Maximum number of records to accept for the following:

Sorting—Includes records read from SORTIN or inserted by E15 user exit routine and not deleted by SKIPREC, the E15 user exit routine, or INCLUDE or OMIT function.

Copying—Includes records read from SORTIN or inserted by E15 user exit routine and not deleted by SKIPREC, INCLUDE or OMIT functions.

Specify as:

n—Maximum number of records to accept; limit is 10 digits (maximum value is 2147483647).


Not used if STOPAFT=0 is in effect.

May be specified in the OPTION, SORT, or MERGE control statement.

If specified in OPTION control statement, overrides any STOPAFT specification in SORT or MERGE control statement.

SORTIN reads no more records when n is reached; an E15 user exit routine continues to be entered as if end of file was encountered until a return code 8 is sent, but no further records accepted for processing.

If end of file is encountered for the last input file before n records accepted, only those records accepted up to that point are sorted or copied.

STORAGE CSI-SORT does not need this operand.


STXIT CSI-SORT does not currently support this operand.


MINSTXIT CSI-SORT does not currently support this operand.


NOSTXIT CSI-SORT does not currently support this operand.


VERIFY CSI-SORT does not currently support this operand.


NOVERIFY CSI-SORT does not currently support this operand.


WORKNM Work file name prefix may be specified here.

This prefix replaces SORT in SORTWK1.

If WORKNM and work file in the FILENM are both specified, the latter of the two found will be used.


Operand Description



Examples Below are 12 examples for specifying CSI-SORT options.

Example 1

Example 1 shows the following:

Produce only critical messages

ROUTE is ignored

STORAGE is ignored

Standard label, by default, for the output file

Nonstandard labels for the two input files

WRKSEC CSI-SORT does not currently support this operand.


NOWRKSEC CSI-SORT does not currently support this operand.


Y2PAST Overrides the installation default that specifies the sliding or fixed century window, which is used to help interpret two-digit year data values as four-digit year data values.

Specify as:

s—Number of years CSI-SORT is to subtract from the current year to set the beginning of the sliding century window.

Must be a value between 0 and 100.

Since Y2PAST value is subtracted from the current year, the century window slides as the current year changes.

For example in 1997, Y2PAST=81 sets a century window of 1916–2015.

f—The beginning of the fixed century window.

Must be a value between 1000 and 3000.

For example, Y2PAST=1962 sets a century window of 1962–2061.

Default—Fixed window from 1980 to 2079.

ZDPRINT CSI-SORT does not currently support this operand.


NZDPRINT CSI-SORT does not currently support this operand.



Operand Description



Example 2


STORAGE is ignored

VERIFY is ignored

ERASE is ignored and unnecessary

Specifies logical unit numbers 003 and 004 of input files

Example 3

Assuming FILES=3 is specified in the SORT control statement, example 3 shows the following:

SORT2 is the name of the output file

Input files are names IN, SORTIN2 (by default), and IN3

Work file name is JOB2WK1

If the work filename prefix is specified in FILNM operand and not in the WORKNM operand, the work filename prefix must be the eleventh value with missing values indicated by commas, as shown below:

Example 5


DPSIZE is ignored because GVSIZE is specified.

Use getvis sorting if the requested 2048 KB GETVIS area is available, otherwise fail.



Example 6

Example 6 illustrates using the NOSTXIT option. CSI-SORT ignores this option.

Example 7

Example 7 illustrates using the STXIT option. CSI-SORT ignores this option.

Example 8

For Example 8 the following applies:

MAX is ignored.

CSI-SORT uses GETVIS for processing; therefore ignores the MAX option and uses data space instead.

If requested, an option patch is available to force another value when MAX is specified.

GVSRLOW is ignored.

GVSRANY is ignored.

Example 9


1000 records of the input files (SKIPREC) are skipped before start of processing.

Accepts for processing 5000 records (STOPAFT) of:

— The input files

— The files inserted by user exit routines, or

— Both

Example 10



For Example 10 WRKSEC is ingored.

Example 11

For Example 11 NOWRKSEC is ignored.

Example 12

For Example 12 ZDPRINT is ignored.


For more information about how ADDROUT and ADDROUT=D affect performance, see Chapter 47, ‘‘Designing Applications.’’

For more information about default filenames, see "Default Filename" in Chapter 10, ‘‘Defining Files.’’

For more information about storage considerations, see any of the following:


Appendix A, ‘‘Estimating Storage Requirements.’’



25
OUTFIL Control Statement
OUTFIL

This section discusses the OUTFIL control statement:

The OUTFILE control statement:

Defines the output file to CSI-SORT

Specifies the procedure to follow when a tape output file is opened or closed

Required only if output processing default values are not applicable

CSI-SORT User Guide OUTFIL Control Statement

Operands Table 25-1 on page 25-2 provides a description of the operands available to the OUTFIL control statement:Table 25-1. OUTFIL Operands

Operand Description

BLKSIZE Maximum output block size in bytes:

Include block descriptor word (four bytes) for variable-length records.

Include BUFOFF value for ISSCII/ASCII data.

Must be consistent with effective value of L3 if INREC is specified.

CSI-SORT does not support the BLKSIZE parameter of the DLBL job control statement.

Not required if output files:

Is VSAM file

Accessed as VSAM, or

Unblocked

Default—L3 value:

For fixed-length records.

Plus four-bytes for variable-length records.

Plus BUFOFF value for ISCII/ASCII variable-length records.

BUFOFF Block prefix size at the front of each physical record on the input file.

Use only with variable-length ISCII/ASCII data.

Specify:

n—0 or 4

Default—0

CLOSE Procedure to follow when tape output file is closed.

Specify as:

RWD—Rewind tape.

UNLD—Rewind and unload tape.

NORWD—Do not rewind tape.

Default—RWD.



EXIT Specifies the E35 user exit routine take responsibility for the output file:

Specify name in the MODS control statement to activate local E35 user exit.

Provide an E35 user exit routine to receive each output record from CSI-SORT; routine must take full responsibility for the output file.

When specified, ignores all other OUTFIL control statement operands.


KSDS

ESDS

RRDS

Specifies the following for the output file:

Is VSAM

Overrides all operands except TOL, REUSE, and EXIT

Default—None; optional

If not specified, assumes a SAM output file.

Specific to KSDS:

Key sequenced

Records were sorted into ascending key sequence on primary VSAM key

Specific to ESDS:

VSAM file is entry sequenced

Specific to RRDS:

VSAM file is relative record

NOTPMK CSI-SORT does not currently support this operand.


OPEN Procedure to follow when tape output file is opened.

Specify as:

RWD—Rewind tape before writing

NORWD—Do not rewind tape before writing

Default—RWD

REUSE Overwrite an existing, non-empty VSAM file defined with REUSE attribute.

Ignored for a SAM file.


Note: The DISP parameter in the output DLBL job control statement overrides REUSE operand if they conflict.

Table 25-1. OUTFIL Operands

Operand Description



Miscellaneous Some additional information to know about the OUTFIL control statement is:

Any operands that precede EXIT are checked only for syntax errors and flagged.

Operands following EXIT are also checked for syntax errors and flagged, however all values are ignored.

Presence or absence of EXIT affects default symbolic unit names for other files used by CSI-SORT.

A VSAM output file must be previously created with the VSAM access method services utility program.

CSI-SORT removes the four-byte record descriptor word (RDW) before writing variable-length records to a VSAM file.

User-written routines at E35, that pass variable-length records back to CSI-SORT, do not need to be designed separately for handling VSAM and SAM files.

CSI-SORT recognizes as an error a warning return code from VSAM if TOL is not specified for a VSAM output file; an error message is issued and CSI-SORT terminates.

If TOL not specified, CSI-SORT writes the output file without repair and issues no error message.

A critical return code from VSAM always causes CSI-SORT to terminate, regardless whether TOL specified.

For SAM ESDS file, BLKSIZE operand refers to the maximum logical block size. It should match the RECORDSIZE operand specified in the

SPAN Specifies output SAM file consists of spanned, variable-length EBCDIC records.


RECORD control statement must specify TYPE=V.

Records spanned blocked if BLKSIZE operand also provided. Else, spanned unblocked with maximum default block size allowed for the output device.

TOL Specifies CSI-SORT tolerate a warning code from VSAM when opening/accessing a VSAM output file.

Valid only for VSAM output files.


Table 25-1. OUTFIL Operands

Operand Description



DEFINE command for the file when it was created with VSAM Access Method Services.

If the file is implicitly defined, VSAM uses the value to calculate control interval size.

For FBA devices, CSI-SORT writes the maximum number of records possible within the control interval specified or defaulted, which can result in a short block within the control interval.

Examples Below are examples for defining the output file.

Example 1


Block size is 300 bytes.

Rewind the output tape (by default) before writing begins.

Rewind and unload at end of file.

Data records are variable-length ISCII/ASCII.

Each output block has a block prefix of length 4.

Example 2

Example 2 illustrates that CSI-SORT provide the output records the E35 user exit routine is to handle.


For more information about the L3 value associated with the OUTFIL control statement, see "Miscellaneous" in Chapter 27, ‘‘RECORD Control Statement.’’

For more information about VSAM organization and for instructions defining a VSAM file, see VSE/VSAM Library.



26
OUTREC Control Statement
OUTREC

This section discusses the OUTREC control statement:

The OUTREC control statements allows a user to reformat an output record before processing. The user can:

Define the parts of an input record to be included in the reformatted output record.

Denote the order they are to appear.

How they are to be aligned.

Insert blanks and binary zeros as separators before, between, and after the fields in the reformatted output records.

The reformatted output record:

Consists only of the user-specified fields in the order denoted, and

Are aligned on the boundaries or in the columns indicated.

Operands OUTREC uses one operand, FIELDS, which must be specified.

CSI-SORT User Guide OUTREC Control Statement

Table 26-1 on page 26-2 provides a description of the values:Table 26-1. Values for Fields Operand

Value Description

s The separation field to be inserted into the reformatted output record. Insert in the position coded, relative to the other fields. Specify before or after any input field and can specify consecutive separation fields. For variable-length records:

Do not specify before first input field, this is the record descriptor word.

Do not specify after the variable part of the input record.

Include at least one byte of fixed data in the reformatted output record.

Specify as one of the following:

nX—Blank separation. n bytes of EBCDIC blanks (X’40’) are inserted in the reformatted output records. Range 1 to 256.

Uses 1 if n omitted.Inserts n bytes of ISCII/ASCII blanks (x’20’) if DATA=A in the INPFIL control statement.Examples are:

nZ—Binary zero separation. Inserts n bytes of binary zeros (X’00’) in the reformatted output records. Range is 1 to 256.

Uses 1 if n is omitted.Examples are:

Table 26-2. Valid and Invalid Blank Separation


Valid 1X or X 1 blank

Valid 256X 256 blanks

Invalid 500X Too many repetitions. Use two adjacent separation fields instead, such as 256X and 244X

Invalid 0X 0 is not allowed

Table 26-3. Valid and Invalid Zero Separation


Valid 1Z or Z 1 byte of binary zeros

Valid 256Z 256 bytes of binary zeros

Invalid 500Z Too many repetitions. Use two adjacent separation fields instead, such as 256Z and 244Z

Invalid 0Z 0 is not allowed



Miscellaneous Some additional information to know about the OUTREC control statement is:

When specified, CSI-SORT reformats the output records after sort finishes.

The E35 user exit routine must refer to fields in the reformatted output record.

When the OUTREC control statement is specified, be aware of resulting changes to record size and layout for reformatted output records.

p, m, a p—Specifies first byte of input field of the input record.

First data byte of a fixed-length record has relative position 1.

First data bye of a variable-length record has relative position 5; first four bytes are the record descriptor word.

Fields start anyplace within the record on a byte boundary. See ‘‘Miscellaneous’’ on page 26-3 for more information about special rules concerning variable-length records.

Note: If the E15 user exit routine reformats the record, p must refer to the record as reformatted by the routine.m—Specifies length of the input field.

Must include the sign, if the data is signed, and an integer number of bytes. See ‘‘Miscellaneous’’ on page 26-3 for more information.

a—Specifies alignment (displacement) of the input field in the reformatted output record, relative to the beginning of the reformatted input record.

Allowable values are:

— H—Halfword aligned. This displacement (p-1) of the field from the beginning of the reformatted input record, in bytes, is a multiple of two. For example, position 1, 3, 5).

— F—Fullword aligned. The displacement is a multiple of four; 1,5, 9).

— D—Doubleword aligned. The displacement is a multiple of eight; 1, 9, 17).

Unused space preceding aligned fields is padded with binary zeros.

Note: Alignment may be required if data is in a COBOL application program where computational items align through the synchronized clause.

p Specifies variable part, outside minimum record length, of the input record is to appear in the reformatted output record as the last field.

Specify a value less than or equal to the minimum input record length, plus one byte.

Note: Null records with only an RDW may result if reformatted output record includes only the RDW and the variable part of the input record.

Table 26-1. Values for Fields Operand

Value Description



Use the OUTREC control statement only if needed to reformat records, rather than or in addition to the E35 user exit.

It is better to use the INREC control statement if shortening the records.

This reduces the length of the records for sort/merge and improves performance.

For variable-length records, specify or include the 4-byte record descriptor word (RDW) in the first input field of the FIELDS operand.

CSI-SORT sets length of reformatted record in the RDW.

If the first field in the data portion of the input record immediately follows the RDW in the reformatted record, the first input field in the FIELDS operand can specify both RDW and data field. Otherwise, include RDW in the reformatted record.

The variable part of the input record can be included in the reformatted output record as the last part.

Using this scenario, specify a value for p (‘‘p’’ on page 26-3) that is less than or equal to the minimum record length, plus one byte; omit m and a.

Null records with only an RDW could result if the reformatted output record includes only the RDS and the variable part of the input record.

Output records are reformatted after processing, as specified by the OUTREC control statement.

Records passed to sort or merge are in the format specified by the INREC control statement when stipulated.

Fields referenced in the OUTREC control statement can overlap:

— Each other, and

— Control fields, or

— Both.

If input is variable-length, output is also variable length.

Each record is given the correct RDW by CSI-SORT before output.

CSI-SORT calculates the L3 value.

Consider the calculated L3 value when specifying the BLKSIZE operand in the OUTFIL control statement.

Example Below is an example for reformatting records after processing.



Example OUTREC Method

The example shows the following:

How three fixed-length input files are sorted and reformatted for output.

Unnecessary fields eliminated from the output records.

Input record size is 80 bytes, three records per block.

The INCLUDE control statement includes or excludes records while the SUM control statement sums them.

Reformatted input records are fixed-length; record size is 23 bytes.

Table 26-4 on page 26-5 provides a description of the reformatted records after OUTREC processing:

For OUTREC, the INCLUDE COND operands must refer to the fields of the original input records:

The OUTFIL indicates the 23 byte records are written as ten records per block in the output file.

Table 26-4. Reformatted Records After Processing

Position Contents




23 Input position 5




For more information about the interaction of OUTREC control statements, see any of the following:

‘‘Miscellaneous’’ on page 26-3.


For more information about record length, see Chapter 27, ‘‘RECORD Control Statement.’’



27
RECORD Control Statement
RECORD

This section discusses the RECORD control statement:

The RECORD control statement:

Describes the format and lengths of the records being processing.

Always provide.

CSI-SORT User Guide RECORD Control Statement

Operands The RECORD control statements has two operands, both of which must be specified. Table 27-1 on page 27-2 provides a description of the operands:

Miscellaneous Some additional information to know about the RECORD control statement is:

The user can drop values from the right; for example LENGTH=(80,70,70,70).

The user can omit values from the middle or left; indicate omission with a comma, for example LENGTH=(80,,30,70).

Table 27-1. RECORD Operands

Operand Description

TYPE Specifies format. Specify as:

F—Fixed-length records.

V—EBCDIC variable-length records.

D—ISCII/ASCII variable-length records.


LENGTH Specifies length of the records. Specify as:

L1—Input record length. For variable-length records, maximum input record length.

Must be specified.


L2—Length after E15; maximum record length for variable-length records after E15.

Ignored if E15 not used.

Specify accurate value if E15 changes the record length.

Default—L1.

L3—Output record length after E35; maximum record length for variable-length records after E35.

Ignored if E35 not used.

Specify accurate value if E35 changes record length.

Default—L2 for sort; L1 for merge and copy.

Note: L4 and L5 apply only to variable-length records. L4—Minimum input record length.

Use only for variable-length record sorts.

If E15 changes record length, specifies minimum record length after E15.

Default—Minimum length needed to contain all control fields; if minimum not specified CSI-SORT sets it to 14 bytes.

L5—Average input record length. Unused by CSI-SORT.

Use only for variable-length record sorts.

If E15 changes record length, specifies average record length after E15.

Default—Average of L2 and L4; (L2+L4)/2.



Parentheses optional for L1 when specified alone.

Parentheses required if any L2 through L5 specified.

Examples Below are examples for describing the record format and lengths.

Example 1

Example 1 shows the records are:

Fixed-length.

Each 80 bytes long in the input file.

Example 2

Example 2 shows the L2 value omitted and the records:

Are fixed-length.

Are each 80 bytes long in the input file.

Lengths changed to 50 bytes by E35 user exit routine.

Example 3

Example 3 shows the records:

Are variable-length.

Maximum length is 104 bytes in the input file.

Minimum record length is 44 bytes.

Average record length is 84 bytes.



28
SORT Control Statement
SORT

This section discusses the SORT control statement:

Use the SORT control statement to either of the following:

Perform a sort application.

It describes the control fields in the input records for CSI-SORT to sort.

Specify a copy application.

Up to nine files can be sorted or copied.

CSI-SORT User Guide SORT Control Statement

Operands Table 28-1 on page 28-2 provides a description of the operands available to the SORT control statement:Table 28-1. SORT Operands

Operand Description

FIELDS Requires to communicate to CSI-SORT four facts about each input record control field:

1. Position of the field within the record.

2. Field length.

3. Data format within the field.

4. Field sequence for ordering.

Locate all control fields, up to 64, within the first 4092 bytes of the record.

Control fields must not extend beyond the shortest record to be sorted; collected fields, comprising the control word, must not exceed 3072 bytes.

p—First byte of a control field relative to the beginning of the 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 with the first four bytes containing the record descriptor word.

All fields, except binary, begin on a byte boundary.

The first byte of a floating-point field is interpreted as a signed exponent; the remaining as the fraction. See for more information.

m—Specifies length of the control field.

Values for all control fields, except binary, must be expressed in integer numbers of bytes. Binary fields are also expressed in notation bytes.bits, see ‘‘Fields Operand, p Parameter’’ on page 28-3 for explanation.

Total bytes for all control fields must not exceed 3072. When determining the total, count a binary field as occupying an entire byte if it occupies any part of it. For example, a binary field beginning on byte 2.6 and is 3 bits long occupies two bytes. All fields must be contained within the first 4092 record bytes.

f—Control field data format. See ‘‘Fields Operand, f Parameter’’ on page 28-4 for acceptable control field lengths, in bytes, and available formats.

s—Specifies control field ordering. Specify as:

A—Ascending order.

D—Descending order.

Default—None, must be specified



Fields Operand, p Parameter

If INREC is specified, p must refer to the record as reformatted by INREC.

FORMAT Use only when all control fields have the same format.

See ‘‘Fields Operand, f Parameter’’ on page 28-4 for acceptable control field lengths, in bytes, and available formats.

Default—None; must specify it not included in FIELDS operand.

FIELDS=COPY or FIELDS=(COPY)

Copies one or more input files to an output file.

When FIELDS=COPY, ignores all other SORT operands except SKIPREC and STOPAFT.

When FIELDS=(COPY), CSI-SORT terminates when specified with a SUM or INREC control statement


CKPT CSI-SORT does not currently support this operand.

EQUALS CSI-SORT does not need this operand.



NOEQUALS CSI-SORT does not need this operand.



FILES The number of input files to be sorted or copied; value is 1–9.

SKIPREC The number of records to skip before starting to sort or copy the input files.

See"SKIPREC" in Chapter 24, ‘‘OPTION Control Statement.’’

STOPAFT Maximum number of records to accept.

See"STOPAFT" in Chapter 24, ‘‘OPTION Control Statement.’’

WORK Describes the work files.

DA—Treated like WORK=1.

n—Specifies number of work file DLBL job control statements supplied; value is 0 through 9.

If 0, CSI-SORT does not use any work files and attempts to perform an incore sort. WORK=0 can be changed with an optional patch.

If 2–9, CSI-SORT treats it the same as WORK=1.

Default—DA.

Table 28-1. SORT Operands

Operand Description



If the E15 reformats the record, and INREC is not specified, p must refer to the record as reformatted by the E15 user exit.

The beginning of a variable-length record must include a four-byte RDW that precedes the actual record.

The above statement also applies to VSAM input records where CSI-SORT supplies the RDW on input to the program and removes it at output.

Fields that contain values are described using notation bytes.bits, where bytes is the byte location relative to the beginning of the record and bits is the bit location relative to the beginning of the byte; bit values are zero (first bit) through seven. The length of a binary field also uses the same notation.

For example, notation 2.3 indicates a binary field beginning on the fourth bit of the second byte of a record.

Fields Operand, f Parameter

Table 28-2 on page 28-4 provides description of control field formats and lengths for the f parameter in the FIELDS operand:Table 28-2. Control Field Formats and Lengths

Format Length (in bytes) Description

CH 1–256 Character

AQ 1–256 Character with alternate collating sequence

ZD 1–256 Signed zoned decimal

PD 1–32 Signed packed decimal

PD0 2–8 Packed decimal with sign and first digit ignored

FI 1–256 Signed fixed-point

BI 1–256 Unsigned binary

FL 1–256 Signed floating-point

AC 1–256 ISCII/ASCII character

CSL 2–256 Signed numeric with leading separate sign

CST 2–256 Signed numeric with trailing separate sign

CLO 1–256 Signed numeric with leading overpunch sign

CTO 1–256 Signed numeric with trailing overpunch sign

ASL 2–256 Signed ISCII/ASCII numeric with leading separate sign

AST 2–256 Signed ISCII/ASCII numeric with trailing separate sign

Y2C or

Y2Z

2 Two-digit character or

zoned decimal year data



The century window established by the Y2PAST option in effect:

Produces the correct order for Y2 format fields. For example:

SORT FIELDS=(1,2,Y2C,A) when used with a 1915–2014 century window produces the following two-character year data ordering 15, 28, 95, 00, 05, 14

Interprets Y2S format two-digit year values, but is not used to interpret Y2S format special indicators. For example:

SORT FIELDS=(1,2,Y2S,A) when used with a 1915–2014 century window produces the following two-digit character year and special indicator data ordering:

X’0000, X’4040, X’F9C7’, XF1F4’, X’FFFF’

The AC format sequences EBCDIC data using the ISCII/ASCII collating sequence.

The user can omit the f parameters and use the "FORMAT" operand if specifying more than one control field and all the control fields contain the same type of data.

Miscellaneous Some additional information to know about the SORT control statement is:

The SORT control statement must refer to fields in the appropriate reformatted record if the records are reformatted by INREC or an E15.

WORK=DA means the same as WORK=1.

CSI-SORT determines if the files are SD or SAM ESDS.

In control fields, +0, 0, and –0 are treated as the same number and compare equal.

Input files must be all SAM or all VSAM.

Specify number of volumes using the VOLUME operand of the INPFIL control statement if any input files are:

— Multivolume and unlabeled, or

— Nonstandard labeled

Y2P 2 Two-digit packed decimal year data

Y2D 1 Two-digit decimal year data

Y2S 2 Two-digit character or zoned decimal year data with special indicators

Y2B 1 Two-digit binary year data

Table 28-2. Control Field Formats and Lengths




EQUALS is ignored when the SUM control statement is specified.

Examples Below are examples of sorting and copying.

Example 1

Example 1 uses the FIELDS operand and illustrates the control field:

Begins on the second byte of each record in the input file

Is five bytes long, and

Contains character, EBCDIC, data.

Sorted in ascending order

The WORK file is used if all the records do not fit in the allocated data space area.

Example 2

Example 2 uses the FIELDS operand and illustrates the major control field:

Begins on byte 25 of each record

Is four bytes long

Contains zoned decimal data, and


The WORK file is used if all the records do not fit in the allocated data space area.

The second control field:

Begins on byte 48

Is eight bytes long

Has same data format as the first field, and


Example 2 also uses the FORMAT operand because both control fields have the same data format.

Example 3



Example 3 uses the FIELDS and FILES operands indicating to copy three input files to the output file without sorting. Records are placed in data space area until written to the output file after all files have been read.

Example 4

Example 4 sorts a packed decimal date field of form P’yyddd’ (X’yydddC)’where yy is the two-digit year, ddd is the day of the year and C is a positive sign.

No work file is used, therefore each input record is stored in data space area.

Continuing with example 4, the first control field:


Is one byte long, and

Sorted in ascending sequence using the century window in effect to interpret the two-digit years as four-digit years



Is two bytes long

Contains packed decimal data, and

Sort in ascending sequence



Example 5

Example 5 illustrates the major control field:

Begins on byte seven of each record,

Is three bytes long

Contains packed decimal data, and

Sorted in descending order

No work file is used, therefore each input record is stored in data space area.


Begins on the fifth bit of byte 398

Remember bits count zero to seven, making bit zero the first bit.

Is seven bytes and six bits long (occupies nine bytes), and

Contains binary data sorted in descending order


For more information about data format descriptions, see Appendix B, ‘‘Data Format Examples.’’

For more information about adding user exits, see Chapter 30, ‘‘Using User Exit Routines.’’

For more information about determining if checkpoint can be used, see the VSE/ESA System Macros Reference



29
SUM Control Statement
SUM

This section describes the SUM control statement:

The SUM control statement specifies that when two records are found with equal control fields, the contents of their summary fields:

Are added

The sum placed in one of the records, and

Delete the other record

CSI-SORT User Guide SUM Control Statement

Operands Table 29-1 on page 29-2 provides a description of the operands identified for the SUM control statement.

FIELDS operand

The FIELDS operand requires three facts about each summary field in the input record:

Field position within the record

Field length

Data format in the field

Table 29-1. SUM Operands

Operand Description

FIELDS Designates numeric fields in the input record as summary fields; see ‘‘FIELDS operand’’ on page 29-2 for more details.

p—specifies the first byte of summary field relative to the beginning of the input record.

The first data byte of a fixed-length record is relative position one.

The first data byte of a variable-length record is relative position five, with the first four bytes containing the RDW.

All fields start on a byte boundary and no field extends beyond byte 4092.

If INREC control statement specified, must refer to record as reformatted by INREC.

If E15 reformats the record and INREC control statement is not specified, must refer to record as reformatted by the E15 routine.

m—Specifies length, in bytes, of the summary field; see ‘‘Format and Length Values for m and f’’ on page 29-3 for details.

f—Specifies format of summary field data; see ‘‘Format and Length Values for m and f’’ on page 29-3 for details.


FORMAT Use only when all summary fields in FIELDS have the same format.

See ‘‘Format and Length Values for m and f’’ on page 29-3 for values.

Default—None; must be specified if not included in the FIELDS operand.

FIELDS=NONE or FIELDS=(NONE)

Eliminates records with duplicate keys.

Only one record with each key is kept.

No summing performed.




A user can write the FIELDS operand in two ways:

Using the first format to describe summary fields that contain different data formats

Using the second format to describe summary fields containing data of the same format.

The second format is optional.

Format and Length Values for m and f

Miscellaneous Below is more information to know about the SUM control statement:

If input records are reformatted by an INREC control statement or an E15 exit routine, the SUM control statement must refer to fields in the appropriate reformatted record.

Summary fields must not:

— Be control fields.

— Must not overlap control fields or each other.

— Must not overlap the RDW.

Do not sum floating-point fields.

The earlier record read receives the sum and the later record is deleted when records are summed.

Fields other than summary fields remain unchanged and are taken from the record that receives the sum.

If overflow occurs, the two records are not summed, meaning:

— Contents are left undisturbed

— Neither record is deleted

— Records remain available for summing.

Overflow does not prevent further summing.

Table 29-2. Summary Field Formats and Lengths


BI 2, 4, or 8 Unsigned binary

FI 2, 4, or 8 Signed fixed-point

PD 1 to 16 Signed packed decimal

ZD 1 to 18 Signed zoned decimal



If both SUM control statement and EQUALS operand in SORT control statement are specified, the EQUALS operand is ignored.

If both SUM control statement and ADDROUT or ADDROUT=D operand of the OPTION control statement are specified, the ADDROUT or ADDROUT=D is ignored.

Summing data with invalid sign or digit codes result in a data exception program check.

Use the E15 exit routine to verify the validity of values that may need to be summed.

Examples Below are examples for specifying summary fields.

Example 1

Example 1 designates the following as summary fields:

An eight-byte packed decimal field at byte 21 and

A four-byte fixed-integer at byte 11

Example 2

Example 2 designates two zoned decimal fields; one is eight-bytes long starting at byte 41 and the other starts at byte 49 and is four-bytes long.

Example 3

Example 3 shows an alternate method to write the SUM control statement using FORMAT since both summary fields have the same data format (zoned decimal).



Example 4

Example 4 eliminates records with duplicate keys without summing.


For more information regarding detailed format descriptions, see Appendix B, ‘‘Data Format Examples.’’



30
Using User Exit Routines
Introduction

CSI-SORT passes program control to user routines at points in the code called user exits.

User exit routines perform several records functions such as:

Deleting.

Inserting.

Altering.

Summing.

CSI-SORT provides several facilities for working with data in various program control statements, such as:

INCLUDE

OMIT

INREC

SUM

MODS, which can be used to activate user exit routines at run time.

CSI-SORT User Guide Using User Exit Routines

Parameters that affect the way user exit routines are handled include:

MODS, see Chapter 23, ‘‘MODS Control Statement.’’

INPFIL, see Chapter 20, ‘‘INPFIL Control Statement.’’

OUTFIL, see Chapter 25, ‘‘OUTFIL Control Statement.’’

Parameter list, see Chapter 38, ‘‘Invoking From a Program.’’

If the files use standard labels or are unlabeled, CSI-SORT handles all opening, closing, and labeling if INPFIL and/or OUTFILE EXIT are not specified.

The user must use the local user exit routines to carry out label processing if there are nonstandard labels (or extra headers or trailers in addition to standard labels).

Topics This section discusses only routines written in Assembler and topics include:

CSI-SORT processing phases, see Chapter 31, ‘‘Processing Phrases.’’

Functions of routines at user exits, see Chapter 32, ‘‘User Exit Routine Functions.’’

Addressing and residence modes for user exit routines, see Chapter 33, ‘‘User Exit Modes.’’

How user exit routines affect performance, see Chapter 34, ‘‘User Exit Performance Effects.’’

Loading and linking to user exit routines, see Chapter 35, ‘‘Loading and Linking.’’

The E15 user exit routine, see Chapter 36, ‘‘E15/E32 User Exit Routine.’’

The E32 user exit routine, see Chapter 37, ‘‘E32 User Exit Routine.’’

The E35 user exit routine, see Chapter 37, ‘‘E35 User Exit Routine.’’



31
Processing Phrases
Processing Phases

CSI-SORT performs specific tasks such as:

Reading input files—Phase 1; initial sorting phase; used only for sort applications.

Writing output file—Phase 2; final merging phase.

The initial sorting and final merging phases may contain user exits that activate at a certain time during CSI-SORT processing.

CSI-SORT returns control to the operating system or the invoking program when the final merging phase completes.

Figure 31-1 on page 31-2 represents the CSI-SORT input, user exit, and output logic:

CSI-SORT User Guide Processing Phrases

Figure 31-1.Input, User, Exit, and Output Logic



Input, User Exit, Output Logic

Figure 31-1 on page 31-2 provides examples of the logic flow for sort, merge, and copy applications as it relates to the following:

SORTINn.

E15 user exits.

E32 user exits.

E35 user exits.

SORTOUT.

It shows how the user exit routines fit into the logic of an application, but not all paths are shown. In deciphering the figure, assume all applicable files and user exits are present and records are not inserted or deleted.

Therefore, Figure 31-1 on page 31-2 demonstrates the following logic:

E15 and E35 user exit routines continue to be entered until they pass back a return code of eight (8).

If the local user exit routine passes a return code of eight, CSI-SORT processes subsequent records without passing them to the local user exit routine.

COPY is treated the same as a SORT with no fields specified.

During SORT/MERGE processing, each record is read from SORTINn and passed to E15/E32 user exit routine.

When all the records are accepted in this manner they are sorted by CSI-SORT, unless they do not fit in the storage area. In which case the records are sorted in stages, if a sort work file is provided, then merged.

Each sorted record is then passed to the local E35 user exit routine or written to SORTOUT.

Procedure Below is information as to what CSI-SORT does:

CSI-SORT first checks whether the user supplied an EXIT operand in the INPFIL control statement for sort, merge, or copy application.

If no EXIT operand supplied, CSI-SORT reads the input records from the SORTINn files.

— Use an E15 user exit routine to insert all the records if an EXIT operand is present for a sort application as CSI-SORT does not read the input records from SORTINn files.

— Use an E32 user exit routine to insert all the records if an EXIT operand is present for a merge or copy application as CSI-SORT does not read the input records from SORTINn files.



CSI-SORT writes each processed record to the SORTOUT file, if present.

However, if an EXIT operand in the OUTFIL control statement is present, the E35 user exit routine disposes of all the records because CSI-SORT treats these records as deleted.

Phases and UserExit Routines

Use the E15 user exit in the CSI-SORT initial sorting phase.

Use the E32 user exit in the CSI-SORT initial merging phase.

Use the E35 user exit in the CSI-SORT output phase.

To determine if a particular user exit is valid for the application, see Chapter 34, ‘‘User Exit Performance Effects.’’



32
User Exit Routine Functions
Functions of Routines at User Exits

A technician uses local user exit routines to accomplish several tasks, such as:

Open and initialize files; ‘‘Opening and Initializing Files’’ on page 32-1.

Process labels; ‘‘Processing Labels’’ on page 32-2.

Control all input and output; ‘‘Controlling Input/Output’’ on page 32-2.

Alter, delete, or insert records; ‘‘Altering, Deleting, Inserting Records’’ on page 32-2.

Sum records; ‘‘Summing Records’’ on page 32-4.

Close files; ‘‘Closing Files’’ on page 32-4.

Terminate CSI-SORT; ‘‘Terminating’’ on page 32-4.

Opening and Initializing Files

Use the E15 user exit to write own user exit routines to open files and perform any necessary initialization.

CSI-SORT User Guide User Exit Routine Functions

Processing Labels CSI-SORT uses the standard facilities of the operating system to performs the work necessary for label processing or opening and closing files if:

Tapes or disks have standard labels, or

Using unlabeled tapes

However, CSI-SORT cannot manage nonstandard labels or user-standard labels (those standard labels with extra header or trailer labels). Process these labels and open and close the files at the user exits.

Controlling Input/Output

A user controls input and output, including special label handling, using user exit routines.

If INPFIL EXIT is specified, it uses E15 or E32 user exit routine to read the input files and pass the records to CSI-SORT.

If OUTFIL EXIT is specified, it uses E35 exit routine to take the output records from CSI-SORT and write them to the output file.

Note:Note:Individual input records can be passed to CSI-SORT by own E15 or E32 user exit routines regardless whether INPFIL EXIT is specified.

Altering, Deleting, Inserting Records

Three user exits are available to manipulate individual records:

E15 to sort records, ‘‘E15 User Exit’’ on page 32-2.

E32 to merge or copy records, ‘‘E32 User Exit’’ on page 32-3.

E35 to write records to the output file, ‘‘E35 User Exit’’ on page 32-4.

E15 User Exit Routines at E15 user exit receive control before records are processed.

These routines are accountable for all sort input when EXIT operand in the INPFIL control statement is specified.

Note:Note:INCLUDE, OMIT, SUM, and INREC functions are performed after E15.

Altering Records

Allows the user to:

Alter the contents of any field in a record, and

Change length of logical record by adding or deleting fields after the last control field; must comply with record description supplied on RECORD control statement.

If changing contents or altering length, ensure fields in the changed record match the fields specified in the SORT, INCLUDE, OMIT, SUM, and INREC control statements. The following applies:



If changing the length of a fixed-length record, specify the modified length by the L2 value in the RECORD control statement.

If changing the maximum, minimum, or modal length of a variable-length record, specify the respective L2, L4, or L5 value in the RECORD control statement. CSI-SORT ignores the modal length (L5) value.

Deleting Records

Allows the user to delete any record in the output file. Performing this function at input rather than at output saves program time.

Using either INCLUDE or OMIT function is an alternate method to using the user exit routine.

Inserting Records

Allows the user to insert records at any time.

E32 User Exit Use the E32 user exit routine at merge or copy input. It functions in two ways, depending whether EXIT in the INPFIL control statement is specified.

EXIT Not Specified

When the EXIT operand in the INPFIL control statement is not specified, a routine at E32 modifies record contents, including control fields, but not record lengths.

Input records cannot be inserted or deleted but may be replaced by one of the user’s records.

EXIT Is Specified

When the EXIT operand in the INPFIL control statement is specified, a routine at E32 user exit is accountable for reading records into the merge or copy. Thus the E32 must do the following for all operations on the input files:

Define them.

Open them.

Process the labels.

The input records’ contents are modified and record lengths are altered.

Records can be deleted or inserted.

When the records are ready to merge or copy, the routine passes them to CSI-SORT (one at a time), which then performs:

The necessary processing

Writes a record to the output file, or

Passes the record to the E35 user exit routine, and

Returns to the E32 to get the next record to copy or merge.



E35 User Exit Use the E35 user exit routine at output.

Altering Records

A user can add, modify, or delete fields anyplace in the records.

If changing the maximum length of the records, specify the length using the L3 value in the RECORD control statement, unless any of the following is specified:

ADDROUT operand; ignored by CSI-SORT

ADDROUT=D operand; ignored by CSI-SORT

INREC control statement

Deleting Records

A user can delete any unwanted record.

Inserting Records

Insert records at any time, but the user exit routine must insert them in the correct sequence.

Summing Records A user can sum records in the output file using two methods:

The E35 user exit routine, or

SUM control statement, see Chapter 29, ‘‘SUM Control Statement.’’

Closing Files Use OUTFIL with E35 exit routine to close files and perform any needed housekeeping.

Terminating Use exit routines E15, E32, and E35 to write own user exit routines to terminate CSI-SORT before all records are processed.


For more information about becoming familiar with label processing procedures, see any of the following documents:

VSE/ESA System Macros Reference

VSE/ESA System Macros User’s Guide

VSE/ESA System control Statements

VSE/ESA Guide to System Functions



33
User Exit Modes
Modes for User Exit Routines

CSI-SORT provides addressing and residence modes for user exit routines. The following features allow user exit routines to reside above or below 16MB virtual storage line and to use either 24-bit or 31-bit addressing mode:

To ensure CSI-SORT enters the proper user exit routine with correct addressing, conform to the following rules:

— If the user exit name is specified in a MODS control statement, the user exit routine is entered with the addressing mode indicated by the linkage editor attributes of the routine; for example, 31-bit addressing mode if AMODE 31 is specified during link-edit of the user exit routine.

— If the user exit routine address is passed to CSI-SORT through the parameter list, the user exit routine is entered:

With 24-bit addressing mode in effect if bit 0 of phase 1 or phase 3 branch table addresses in the list is zero, or

With 31-bit addressing mode in effect if bit 0 of phase 1 or phase 3 branch table addresses in the list is one

User exit routines can return to CSI-SORT with either 24-bit or 31-bit addressing mode in effect.

Must use the return address CSI-SORT places in register 14.

CSI-Sort controls the pointer to the parameter list and the addresses in the parameter list as follows:

— If entered with 24-bit addressing mode in effect, CSI-SORT passes clean (zeros in the first eight bits) 24-bit addresses to the user exit routine.

CSI-SORT User Guide User Exit Modes

— If entered with 31-bit addressing mode in effect, CSI-SORT passes clean 24-bit addresses to the user exit routine.

In either case, the user exit routine must then pass back to CSI-SORT either 31-bit addresses or clean 24-bit addresses.


For more information about passing parameters from a parameter list, see Chapter 38, ‘‘Invoking From a Program.’’



34
User Exit Performance Effects
Performance Effects

This section discusses how user exit routines affect CSI-SORT performance.

Before writing user exit routines, keep in mind the following factors:

The routines occupy virtual storage that would otherwise be available to CSI-SORT, which may result in errors due to the lack of partition GETVIS. The reentrant SORT phase is very small.

All other necessary routines load into partition GETVIS area. Using SIZE=SORT on the EXEC SORT JCL statement maxmizes available GETVIS area for tables, required routines, and personal exit routines. The recommended use is SIZE=4K.

When using relocatable routines, specify their length in the MODS control statement, allowing CSI-SORT to efficiently use virtual storage.

Routines increase overall run time.

Several user exits give the user routine control once for each record, until a do not return return code passes to CSI-SORT.

Note:Note:Applications such as COBOL or PL.I may automatically generate E15/E32, E35, or both user exit routines.

Using INCLUDE, OMIT, INREC, OUTREC, and SUM control statements instead of the routines allows CSI-SORT to more efficiently perform.


For more information about self-relocating and loader-relocatable routines, see the VSE/ESA System Macros User’s Guide.

CSI-SORT User Guide User Exit Performance Effects

For more information about how to pass the OPTION control statement to CSI-SORT via parameter list, see the associated manuals for the programming language being used.

Note:Note:It may be necessary to use the SORT command in the language, instead of MERGE, to build the proper E15 and E35 exit routines.



35
Loading and Linking
Introduction

This section discusses loading and linking to user exit routines.

CSI-SORT loads the user exit routines a user creates

All routines are treated as an entity and cataloged under the name specified in the MODS control statement.

Topics discussed include:

Providing the entry point for each personal user exit routine; ‘‘Passing Control’’ on page 35-1.

Using registers to pass information to the personal user exit routines; ‘‘Passing Information’’ on page 35-2.

Passing Control Users provide the entry point for each of their user exit routines in a branch table at the beginning of a module.

Figure 35-1 on page 35-2 shows the branch tables format for user exit routines:

Note:Note:CSI-Sort currently supports only the E15, E32, and E35 exit routines, but the format must be maintained.

CSI-SORT User Guide Loading and Linking

Figure 35-1.User Exit Branch Tables

All user exits have an entry in the branch table including any that are not used, as shown for the initial sorting phase example in Figure 35-2 on page 35-2:

Figure 35-2.Branch Table Example

Passing Information

CSI-SORT uses registers 1, 13, 14, and 15 in the standard method for calling programs to link to the user exits and pass information to them.



Table 35-1 on page 35-3 provides a description of the system conventions to which the registers comply:

The user exit routines must not change the contents of access registers.

If an invalid return code passes, an error message issues and CSI-SORT terminates.

Figure 35-3 on page 35-3 provides the general method used by CSI-SORT to pass parameters at the different user exits:

Figure 35-3.Passing Parameters General Method


For more information about the contents of the parameter lists and their valid return codes, see any of the following:

Chapter 36, ‘‘E15/E32 User Exit Routine.’’

Chapter 37, ‘‘E35 User Exit Routine.’’

Table 35-1. Register Conventions

Register Use

1 Contains pointer to a list of addresses (parameter list), each pointing to an item of information.

When the routine needs to pass a return code back to CSI-SORT, the same parameter list conventions must be used.

13 Contains the address of a 24-bit save area nine doublewords long in which the personal routine saves the contents of the registers and restores the registers before returning control to CSI-SORT.

14 Contains the return address. The routine returns control by branching to this address.

15 Contains the address of branch table. The user can use this as a base register at the start of processing.



36
E15/E32 User Exit Routine
Introduction

This section discusses the contents of the parameter lists for the E15 user exit and valid return codes (action word).

Table 36-1 on page 36-1 and the following text provides descriptions for the parameter lists and valid return codes:

Entry 1 Parameter list entry 1 points to the record to be processed by the a user’s own user exit routine.

Entry 2 Parameter list entry 2 uses the return code (action word) to tell CSI-SORT what to do when CSI-SORT regains control.

Table 36-1. E15 User Exit Parameter List

Entry Number

Offset (dec) Contents Points to:

1 0 Record address or zeros1

1. Zeros when INPFIL EXIT specified and at end of file.

Next record to process

2 4 Action word address Action word

(one word)

3 8 Record length vector address L1 L2 L3 L4 L5

(five words)

4 12 Record type address Record type code

(one word)

CSI-SORT User Guide E15/E32 User Exit Routine

Insert the proper code in the rightmost byte of the action word; valid codes are:

00 X’00’—Process a record; invalid when EXIT operand specified in the INPFIL control statement.

04 X’04’—Delete a record; invalid when EXIT operand specified in the INPFIL control statement.

08 X’08’—Do not return to this user exit.

12 X’0C’—Insert a record.

16 X’10’—Terminate CSI-SORT.

Entry 3 Parameter list entry 3 gives the address of a 20-byte (5 words) area containing the record length values for L1 through L5.

Entry 4 Parameter list entry 4 provides the byte address for the record type code.

For fixed-length records:

Bit 0 is on and

Bit 1 is off

For variable-length records:

Bit 0 is off and

Bit1 is on

CSI-SORT uses other bits as flags.

Procedure CSI-SORT reads the first input record, then passes control to the user exit routine with the address of record in parameter list entry 1.

The general proceeding is the user’s own user exit routine:

1. Return code X’00’ if the record is acceptable.

2. Return code X’04’ if wanting to delete the record.

3. In order to pass a record the user routine read in from a different file to sort:

Inserts the clean 24- or 31-bit record address in parameter list entry 1

Returns code X’0C’

Parameter list entry 1 restores to its former value for the next time.

4. In order to change a record:

Moves that record to a work area

Changes it

Puts its new clean 24- or 31-bit address in parameter list entry 1



Returns code X’00’

The process repeats for every input record until the exit routine returns code X’08’ or X’10’ to CSI-SORT.

Parameter list entries 3 and 4 make it possible for the user to write an E15 user exit routine by providing all the information needed about record type and length.

If INPFIL EXIT is specified, only Step 3 applies: Parameter list entry 1 always contains zeros, which the user must replace with the address of record read in.

The exit is also responsible for the following:

Initially opening and closing the input file or files.

Handling any user or other special labels.

Note:Note:Return codes X’00 ‘and X’04’ are invalid with INPFIL EXIT specified.



Examples Below are examples of E15 user exit routines.

Example 1

Example 1 shows how an E15 user exit routine inserts records. Since this example only inserts records, it works with and without specifying INPFIL EXIT.



Example 2

Example 2 shows an E15 user exit routine that compares two bytes of each input record with a constant. If the compare is not high, the record prints and then deletes from the input.

This exit assumes INPFIL EXIT has not been specified.



Example 3

Example 3 shows how to compile, linkedit, and use an E15 user exit routine to allow CSI-SORT read instream SYSIPT data.

Specify /* after the END statement.



37
E35 User Exit Routine
Introduction

This section discusses the contents of the parameter lists for the E35 user exit and valid return codes (action word).

Table 37-1 on page 37-1 and the following text provides descriptions for the parameter lists and valid return codes:

Entry 1 Parameter list entry 1 points to the record currently selected for output. Contains all zeros when output is exhausted.

Entry 2 Points to the record most recently moved to the output area. Contains all zeros until the first record moves out.

Table 37-1. E35 User Exit Parameter List

Entry Number

Offset (dec) Contents Points to:

1 0 Current record address Current record

2 4 Previous record address Previous record now in output area

3 8 Action word address Action word (1 word)

4 12 Sequence check word address Sequence check word (1 word)

5 16 Record length vector address L1 L2 L3 L4 L5

(five words)

6 20 Record type address Record type code

(one byte)

CSI-SORT User Guide E35 User Exit Routine

Entry 3 Parameter list entry 3 uses the return code (action word) to tell CSI-SORT what to do when CSI-SORT regains control.

Insert the proper code in the rightmost byte of the action word; valid codes are:

00 X’00’—Process a record.

04 X’04’—Delete a record.

08 X’08’—Do not return to this user exit.

12 X’0C’—Insert a record.

16 X’10’—Terminate CSI-SORT.

Entry 4 Parameter list entry 4 points to the sequence check word that contains zeros. Use it if wanting to insert records that are out of sequence.

Entry 5 Parameter list entry 5 gives the address of a 20-byte (5 words) area containing the record length values for L1 through L5.

Entry 6 Parameter list entry 6 provides the byte address for the record type code.

For fixed-length records:

Bit 0 is on and

Bit 1 is off

For variable-length records:

Bit 0 is off and

Bit1 is on

CSI-SORT uses other bits for flags.

Procedure When the E35 user exit routine first receives control, parameter list entry 1 points to the first output record; parameter list entry 2 contains zeros.

The general proceeding is the user’s own user exit routine:

1. Return code X’00’ if the record is acceptable.

2. Return code X’04’ if wanting to delete the record.



3. In order to insert a record the routine read in, check it against the current record in parameter list entry 1.

If the record collates ahead of the current record, puts its clean 24- or 31-bit address in parameter list entry 1 and returns code X’0C’.

Next time, parameter list entry 1 will have been restored to its former value.

Note:Note:If inserting a record that is out of sequence, put a nonzero value in the sequence check word (see entry 4) to inform CSI-SORT.

4. In order to change a record:

Moves that record to a work area

Changes it

Puts its new clean 24- or 31-bit address in parameter list entry 1

Returns code X’00’

5. In order to sum records in the output file:

Changes the record in the output area

Deletes current record.

CSI-SORT returns to the user’s own user exit routine with the address of a new current record and the same record remains in the output area for further summing.

If not deleting the current record, it is added to the output area where its address replaces the address of the previous record.

CSI-SORT returns with the address of a new current record.

The process repeats for every output record until the routine returns code X’08’ or X’10’.

If OUTFIL EXIT is specified, the routine returns code X’04’ every time until parameter list entry 1 contains all zeros, indicating end of data. At this point the exit must return code X’08’ after finishing any other processing, if necessary. The exit is responsible for the following:

Opening and closing any output files

Handling any user or other special labels.

Code X’10’ is also valid with OUTFIL EXIT to force CSI-SORT to terminate.



Example Below is an example of E35 user exit routines.

Example 1

Example 1 shows how an E35 user exit routine that is self-relocating and uses physical IOCS to print all sorted records on SYSLST.



38
Invoking From a Program
Introduction

Invoke CSI-SORT dynamically from programs written in any of the following:

Assembler

COBOL

PL/I

RPG II with Auto-Report Feature

Note:Note:See the programming guides regarding the above features for specific information about dynamic invocation. JCL requirements are the same as those for Assembler.

This section discusses needed knowledge to initiate CSI-SORT from within the user assembler program using system macros instead of an EXEC job control statement in the input stream.

CSI-SORT User Guide Invoking From a Program

Section topics include:

Chapter 39, ‘‘Defining System Macros.’’

Chapter 40, ‘‘Using System Macros.’’

Chapter 41, ‘‘Subtasking.’’

Chapter 42, ‘‘Requiring Job Control Language.’’

Chapter 43, ‘‘Using General Registers to Pass Information.’’

Chapter 44, ‘‘Using Address and Residence Modes.’’

Chapter 45, ‘‘Using Parameter List.’’



39
Defining System Macros
Defining System Macros

System macros are those macros VSE provides to communicate service requests to the control program.

Use these macros only when programming in assembler language.

Issue a LOAD followed by CALL or ATTACH system macro to initiate CSI-SORT from the assembler program. Use a partition program area address. on the LOAD system macro.

Note:Note:Use the ATTACH system macro only if working in a multiprogramming environment and intend to subtask CSI-SORT.

When the user’s program issues a LOAD system macro, CSI-SORT is brought into virtual storage. The linkage relationship between the user’s program and CSI-SORT depends on the system macro used to initiate CSI-SORT.


For more information regarding a complete description of the system macros and how to use them see VSE/ESA System Macros Reference.

CSI-SORT User Guide Defining System Macros



40
Using System Macros
Using System Macros

This section provides an overview for using system macros.

To initiate CSI-SORT processing with system macros, do the following:

Write the code to load the SORT stub program and to handle any exit needs.

Write CSI-SORT program control statements as operands of assembler DC instructions.

Write a parameter list containing information to pass to CSI-SORT.

Specify a pointer that contains the address of the parameter list.

Branch and link to the loaded SORT program.

When CSI-SORT loads by means of another program, it uses approximately 1K of virtual storage for the SORT stub program. This program then establishes reentrance and loads additional routines required for processing into partition GETVIS area when called.

CSI-SORT User Guide Using System Macros

Unlike other SORT products, CSI-SORT is reusable because the SORT stub program gets work area and loads new copies of its processing routine each time it is called. Upon completion of the SORT routine, the following areas are freed:

All GETVIS area

Loaded processing routines

Data space area



41
Subtasking
Subtasking

Use the ATTACH system macro to subtask CSI-SORT and the DETACH system macro when completed.

Prior to using subtasking, do the following:

1. Use the WORKNM and FILNM operands of the OPTION control statement to specify unique filenames to allocate input, output, and work files for each task that will or can run concurrently.

This prevents different tasks from trying to use the same input, output, and work files.

2. Ensure a large enough partition and sufficient data space area to run the number of simultaneous sorts necessary.

When CSI-SORT is subtasked, message overprinting routed to SYSLST may occur if the main task or other subtasks use the same SYSLST output.

To control overprinting of the messages, CSI-SORT provides the following options allowing the user to:

Specify PRINT=CRITICAL option to write only critical messages from CSI-SORT.

Specify PRINT=NONE option to write no CSI-SORT messages.

If CSI-SORT is being executed from a subtask, register 2 must point to the parameter list. The calling program must then issue a DETACH system macro for its own subtask.


For detailed information about using the ATTACH system macro, see any of the following:

CSI-SORT User Guide Subtasking

VSE/ESA System Macros Reference

VSE/ESA System Macros User’s Guide



42
Requiring Job Control
Language

Requiring JCL

Job control statements are required when invoking CSI-SORT from another program.

The job control statements and their parameters are described in Chapter 9, ‘‘Using Job Control Language,’’ and Chapter 10, ‘‘Defining Files.’’

CSI-SORT User Guide Requiring Job Control Language



43
Using General Registers to
Pass Information

Passing Information

CSI-SORT uses standard linkage conventions when it receives control, indicating it expects the general registers to contain the following information:

Register 1—Address of a parameter list, unless CSI-SORT is subtasked.

Register 2—Address of the parameter list if CSI-SORT is subtasked.

Register 13—Address of a nine-doubleword save area where CSI-SORT saves the contents of the calling program’s registers.

The calling program’s registers restore when CSI-SORT completes its processing.

However, they are not restored when CSI-SORT branches to user exit routines.

Register 14—Address in the calling program where CSI-SORT returns control upon completion.

Register 15—CSI-SORT entry point address.

CSI-SORT User Guide Using General Registers to Pass Information



44
Using Address and Residence
Modes

Modes for an Invoking Program

CSI-SORT can be called from a program located below or above 16MB virtual (any possible calling program’s residency mode) and can receive control in either 24-bit or 31-it addressing mode.

After processing completes, CSI-SORT switches to calling program’s addressing mode and returns control to the caller.

CSI-SORT establishes AMODE 31 upon entry, regardless of the mode of the caller. For this reason, the caller must provide clean 24- or 31-bit addresses for the following:

Save areas

Parameter lists

Addresses in parameter lists

Note:Note:The only exception is for branch table addresses.

CSI-SORT always provides clean 24-bit addresses (zeros in byte 0) for passed data to maintain maximum compatibility, regardless of the AMODE requested by the exit. CSI-Sort sets AMODE 31 upon return from the exit, therefore no concern for the AMODE when returning to CSI-SORT.

Upon sort completion or termination, return is in the caller’s AMODE.

User exit routines can have 24-bit or 31-bit addressing mode and may be located above or below 16MB virtual.

CSI-SORT User Guide Using Address and Residence Modes

If the user exit routines are loaded by the calling program, CSI-SORT treats the high-order bit in the branch table address as follows:

0—24-bit addressing mode.

1—31-bit addressing mode.

If the user exit routine is loaded by CSI-SORT, it uses AMODE attribute assigned by the linkage editor for the user exit routine.


For more information about modes for user exit routines, see Chapter 33, ‘‘User Exit Modes.’’



45
Using Parameter List
Passing Parameters with Parameter List

The parameter list contains addresses that point to control statements and to other required data such as branch tables and the return code halfword save area.

Table 45-1 on page 45-1 provides the specifications for each of the parameter list entries:Table 45-1. Parameter List Byte Explanation

Byte Explanation

0–3 Required. Address of the SORT or MERGE control statement image.

4–7 Required. Address of the RECORD control statement image.

8–11 Optional. Address of INPFIL control statement image. Zeros if none.

12–15 Optional. Address of OUTFIL control statement image. Zeros if none.

16–19 Optional. Address of OPTION control statement image. Zeros if none.

20–23 Optional. Address of MODS control statement image. Zeros if none.

24–27 Optional. Address of branch table for Phase 1 preloaded user exit routines. Zeros if none.

If f (bit 0) is:

0—Enter user exit routines at the Phase 1 with 24-bit addressing mode in effect (AMODE 24).

1—Enter user exit routines at Phase 1 with 31-bit addressing mode in effect (AMODE 31).

28–31 Reserved

CSI-SORT User Guide Using Parameter List

Control Statement Images

Images must be coded in a particular form; no extra blanks, continuation characters, or comments are allowed with a blank to indicate the end of an image.

Figure 45-1 on page 45-2 provides examples of control statement images:

Figure 45-1.Examples of Control Statement Images

The first two lines show how a to code a continuation line. No space required between the command and the apostrophe at the end of the first line.

Branch Tables The CSI-SORT parameter list points to two user exit branch tables that contain the addresses for the preloaded user exit routines for each phase:

32–35 Optional. Address of branch table for Phase 3 preloaded user exit routines. Zeros if none.

If f (bit 0) is:

0—Enter user exit routines at the Phase 3 with 24-bit addressing mode in effect (AMODE 24).

1—Enter user exit routines at Phase 3 with 31-bit addressing mode in effect (AMODE 31).

36–39 Optional. Halfword address for the return code. Zeros if none.

40-63 Optional.

Four-byte address for any of the following, which may appear in any order:

ALTSEQ control statement image or translate table.

ANALYZE control statement image.

INCLUDE or OMIT control statement image

INREC control statement image.

OUTREC control statement image.

SUM control statement image.

Zeros if none.

To provide compatibility with previously defined sort calling programs, the optional parameter list ends when one of the following first occurs:

Anywhere after the first 40 bytes at the first fullword of zeros

The first fullword with bit zero on

Or at the end of the parameter list indication

64–67 Optional. End of the parameter list indicator, (4-byte field containing X’FFFFFFFF’).

Can be used, after the first ten (required) entries in the parameter list, to force completion of parameter list processing.

Table 45-1. Parameter List Byte Explanation

Byte Explanation



First branch table—Specifies phase 1 user exit routines E11, E15, E17, and E18.

Second branch table—Specifies phase 3 user exit routines E31, E32, E35, E37, E38, ad E39.

Each user exit in the branch tables are accounted for with either a branch instruction to the user exit routine or an address constant of zeros.

Return Code CSI-SORT can pass a return code to the invoking program in its parameter list to indicate if the sort, merge, or copy application was successful or unsuccessful.

If successfully completed, CSI-SORT passes either return code zero (0) or four (4).

If unsuccessfully completed, CSI-SORT generally passes either return code 16 or 20. Twenty indicates CSI-SORT failed to load the message phase into partition GETVIS area.

Alternative Sequence

In the CSI-SORT parameter list, an invoking program can specify an address of the ALTSEQ control statement image or an address to an alternative sequence translate table.

If specifying an address to an alternative sequence translate table, place an address to a fullword containing the four characters AQTT in the ALTSEQ entry of the CSI-SORT parameter list.

In the fullword following the four characters, place the address of the alternate sequence translate table.

Figure 45-2 on page 45-3 is an example of how to pass an alternate sequence translate table address to CSI-SORT:

Figure 45-2.Passing Alternate Sequence Translate Table Address Example



Sample Coding Figure 45-3 on page 45-4 shows an example of code to execute CSI-SORT by using a sort application with two preloaded user exit routines active:

Figure 45-3.Example Coding to Initiate Execution



Table 45-1 on page 45-1 provides an explanation of the instruction numbers displayed in the right most column:Table 45-2.

Instruction Explanation

1 LOAD system macro loads CSI-SORT module on the doubleword boundary and LOADLOC address, which is defined by instruction 51.

2 Address of CSI-SORT entry point placed in register 15.

3 Register 1 is loaded with the address of the parameter list.

This list is defined by instructions 9–22.

4 Loads register 13 with the user’s save area address.

5 Loads register 14 with the user’s return address and gives control to CSI-SORT.

After CSI-SORT executes, control returns to the next instruction.

6 Before returning control to the user, CSI-SORT places a return code in the halfword named RETURN.

Tests the return code for successful CSI-SORT completion.

7 If return code is not zero, control passes to the error processing routine SORTERR.

8 Instructions begin here to process a nonzero return code upon CSI-SORT completion.

9–14 The parameter list begins at instruction 9.

The first six address constants point to CSI-SORT control statement images.

The OPTION statement image entry in the parameter list contains zeros, meaning the OPTION control statement is not supplied. In this situation CSI-SORT uses installation defaults.

15–17 These address constants point to the required branch tables.

Instruction 16 always contains zeros.

18 Address of a halfword where CSI-SORT places a return code. The halfword is defined by instruction 32.

19–22 These four address constants point to CSI-SORT control statement images.

One at instruction 22 contains zero, indicating end of optional functions.

The SUM, ALTSEQ, and OMIT functions are defined in instructions 28–30.

23–30 Defines the control statement images.

Since user exit routines are preloaded on the MODS statement, no entries are required for the phase name and the address or length parameters.

31 Defines an area where CSI-SORT saves the contents of user registers.



With CSI-Sort, use CDLOAD instead of load to place the SORT stub program into partition GETVIS.

It is recommended to either load the SORT stub in partition GETVIS or issue a CDLOAD of the sort.

! CAUTION:If loading the SORT module, be aware of and pay attention to where it is being loaded as it may overlay other routines included with the link edit of the user program, such as Logical IOCS modules.

32 Halfword that is set aside for the return code from CSI-SORT.

33 All literals generated by previous coding are collected here.

34 Establishes addressability for the phase 1 branch table and the processing routines that follow the table.

35 First instruction in the branch tables for phase 1, initial sorting phase.

E11 user exit is not used.

36 A branch to the E15 user exit routine.

INPUT is the label of the entry point for this routine.

37–38 E17 and E18 user exits are not used.

39 E15 user exit routine follows the phase 1 branch table.

The first macro saves registers used in the routine.

40 This macro restores registers and returns control to CSI-SORT.

41 Establishes addressability for the phase 3 branch table and the processing routines that follow the table.

42–43 First instruction in the branch tables for phase 3.

E31 user exit is not used.

44 A branch to the E35 user exit routine.

OUTPUT is the label of the entry point for this routine.

45–47 E37, E38, and E39 user exits are not used.

48 E35 user exit routine follows the phase 3 branch table.

The first macro saves registers that are used in the routine.

49 This macro restores registers and returns control to CSI-SORT.

50 All literals generated by previous coding are collected here.

51 CSI-SORT loads here on a doubleword boundary and requires about 1K.

Table 45-2.

Instruction Explanation




For more information about preloaded user exit routines, see Chapter 30, ‘‘Using User Exit Routines.’’

For more information about the ALTSEQ control statement, see Chapter 14, ‘‘ALTSEQ Control Statement.’’

For more information about the linkage editor, see “Linkage Editor” in VSE/ESA System Control Statements.



46
Improving Efficiency
Introduction

CSI-SORT is designed to automatically optimize performance. It sets optimization variables, such as buffer sizes, and uses a merge type of sort, which is the most efficient sort algorithm for use with data space areas.

This section discusses several ways to improve CSI-SORT performance. Topics include:

Designing own applications to maximize performance; Chapter 47, ‘‘Designing Applications.’’

Efficiently using virtual storage; Chapter 49, ‘‘Using Virtual Storage.’’

Efficiently using work space; Chapter 50, ‘‘Using Work Space.’’

Using dataspace sorting; Chapter 48, ‘‘Using Dataspace Sorting.’’

CSI-SORT User Guide Improving Efficiency



47
Designing Applications
Designing Applications

This section discusses designing applications to improve performance.

CSI-SORT automatically optimizes performance when an application runs. However, a user can help improve efficiency using specifications and options that allow CSI-SORT to make the best use of available resources.

Topics include:

Improving performance by directly invoking CSI-SORT; ‘‘Directly Invoke Processing’’ on page 47-1.

Planning ahead when designing new applications; ‘‘Planning Ahead’’ on page 47-2.

Accurately specifying input/output files characteristics; ‘‘Specifying File Characteristics’’ on page 47-2.

Specifying devices that improve elapsed time; ‘‘Improving Time Devices’’ on page 47-3.

Using options that improve performance; ‘‘Improving Performance Options’’ on page 47-3.

Avoiding options that degrade performance; ‘‘Avoiding Degrading Options’’ on page 47-6.

Directly Invoke Processing

To improve performance, try invoking CSI-SORT directly instead of from COBOL, PL/I RPG II or Assembler.

Note:Note:Using COBOL may be convenient, but could degrade performance.

CSI-SORT User Guide Designing Applications

One way to improve efficiency is to take advantage of the way CSI-SORT installation defaults and run-time options are fine-tuned for optimum performance. This is done my making use of control statements that work together, such as INCLUDE or OMIT, INREC, OUTREC, and SUM.

Additional ways:

Eliminate records from input files.

Reformat records to eliminate unwanted fields.

Sum numeric records without requiring routines from other programs.

Planning Ahead When possible, consider the following factors when designing new applications:

Use EBCDIC character or binary control fields.

Avoid using alternative collating sequence character translation.

If a fixed-point control field always contains positive values, specify it as a binary field.

If a packed decimal or zoned decimal control field always contains positive values with the same sign, specify it as a binary field.

Hex C is an example of having the same sign.

Use packed decimal format rather than zoned decimal.

Specify as one control field when the several contiguous character or binary control fields in the correct order of significance are sorted or merged in the same ascending or descending order.

Avoid overlapping control fields.

Avoid using locale processing if SORT, MERGE, INCLUDE, or OMIT character fields can be processed using the binary data encoding.

Efficient Blocking Blocking input and output records significantly improves CSI-SORT performance.

For large files, files on tape, or files that often sort, choose a larger block size; the larger the input and output block sizes, the better CSI-SORT performs.

With FBA devices, use a large CI (control interval) value to give improved performance.

Specifying File Characteristics

CSI-SORT uses all available information to efficiently perform operations, which include ways where a user can help by accurately specifying files characteristics using ‘‘Direct Access Storage Devices’’ on page 47-2.

Direct AccessStorage Devices

Allocating intermediate storage on cylinders boundaries improves system performance.



Table 47-1 on page 47-3 displays the number of tracks per cylinder for direct access devices:

Improving Time Devices

Using 3390s in the following gets the best elapsed time improvements when using DASD with CSI-SORT:

SORTINn.

SORTWKn.

SOUTOUT.

A mixture of 3380s and 3390s for these files may not result in the same elapsed time improvement.CSI-SORT indirectly affects a a mixture of the processing techniques but the less-likely result is primarily due to the improved performance characteristics of the 3390 in relation to the 3380.

When using 3390s, the exact elapsed time improvement depends on which files reside on the 3390s.

The recommendation is to use all 3390s. If that is not possible, use 3390s for SORTINn and SORTOUT files in preference to SORTWKn files.

Improving Performance Options

Another performance enhancement is to fine-tune the specified options at run time. Several options a user can fine-tune are:

Sorting entirely in data space area; ‘‘WORK=0’’ on page 47-3.

Using data space sizing; ‘‘DSPSIZE’’ on page 47-4.

Using large partitions if sorting in partition GETVIS; ‘‘GVSIZE’’ on page 24-4.

The INCLUDE or OMIT, STOPAFT, and SKIPREC control statements; ‘‘INCLUDE/OMIT, STOPAFT/SKIPREC’’ on page 47-4.

The INREC control statement; ‘‘INREC’’ on page 47-4

The OUTREC control statement;

Using a SUM control statement; ‘‘SUM’’ on page 47-5.

WORK=0 Specify the SORT parameter or omit it. It is the default parameter.

Performance improves significantly by loading all records and sorting in the data space. However, be aware that this requires more data space area and may not be feasible to sort very large amounts of data.

Table 47-1. Tracks Per Cylinder for Direct Access Devices

Device Tracks per Cylinder

3390 (ECKD) 15

3380 15



DSPSIZE The DSPSIZE operand in the OPTION control statement, or DSPACE in the //EXEC job control statement, defines the maximum amount of data space used for the data space area defined.

If the size defined during system initialization is too small, additional overhead will be required to manage multiple portions of sorted data that must be merged by CSI-SORT.

CSI-SORT loads the following into data space areas where all sorting and merging takes place:

All records (WORK=0) or

Individual portions of data that are then sorted and finally merged (WORK=1)

Note:Note:Ensure enough data space area is on the system. If the input data does not fit in the data space area, it is segmented into parts, up to 255 parts, that are then merged. For best performance, use large data space sizes to minimize the number of segments as much as possible.

By using only data space area, CSI-SORT reduces complexity and improves overall performance.

CSI-SORT uses only the data space area needed for the requested data and expands as needed in increments of the minimum (default) value specified in the system until the DSPSIZE or (DSPACE) value is reached.

INCLUDE/OMIT,STOPAFT/SKIPREC

Reducing the amount of records being processed can reduce processor and data transfer time.

Using the INCLUDE or OMIT control statements and the STOPAFT and SKIPREC options can aid this action:

INCLUDE and OMIT control statements allow a user to specify to accept for sorting, merging, or copying only those records whose fields meet certain criteria.

STOPAFT option allows a user to specify the maximum number of records to accept for sorting or copying.

SKIPREC option allows a user to skip records at the beginning of the input files and sort or copy only the remaining records.

INREC Using the INREC control statement, the amount of data to process is modified by:

Reducing the size of the input records before sorting, and

Increasing size after sorting if necessary using the OUTREC control statement or the E35 exit.

This saves data transfer time, which usually results in a more efficient sort.



The INREC control statement directs CSI-SORT to reformat input records before sorting. It’s efficiency lies when the user reduces the size of the records. It becomes a less efficient sort if the size increases. Use INREC to shorten the record (eliminating fields).

When used with the INCLUDE or OMIT control statements and the STOPAFT and SKIPREC options only the records remaining in the output file are reformatted after the process of elimination.

Since the INREC control statement cannot reformat after sorting, use the OUTREC control statement or the E35 exit to lengthen the record after sorting by:

repeating or realigning fields

Padding with blanks and inserting strings

The user must understand the change in record size and layout of the resulting reformatted input/output records and which CSI-SORT functions refer to the layout of the reformatted records instead of the original records layout.

INREC removes three types of fields that can result in sorting efficiency:

Padding (blanks or binary zeros) fields can be removed before sorting using INREC then reinsert after sorting using E35 exit.

Fields not required in the output records can be removed before sorting using INREC.

Use the following if padding, repeated fields, or strings must be inserted in the output records:

— Use INREC to remove unwanted fields before sorting

— Use OUTREC or the E35 exit to repeat fields and insert padding and strings after sorting.

If input files are variable-length records being sorted and the only the fixed part is required, eliminate the variable part before sorting.

Note:Note:Using INREC control statement can degrade performance if more time is required to remove the fields than is saved during the sort.

SUM Improve performance using a SUM control statement to add field contents.

The SUM control statement add contents of specified summary fields to records with identical control fields, duplicate keys. The result is placed in one record; the other deleted, which reduces the number of records CSI-SORT outputs.

SUM processes during the sort, which is after SKIPREC, INCLUDE or OMIT, and INREC control statements.

To eliminate records with duplicate keys without summing, when using the SUM control statement, enter SUM FIELDS=NONE.



Avoiding Degrading Options

Certain options may adversely affect performance. Use the following options only when necessary:

BYPASS—Operand in the INPFIL control statement;

WORK=1—Operand of the SORT control statement;

Work file use is less efficient than maintaining all records in data space or partition GETVIS area.

User Exit Routines—When included in an application, increases application run time;

Required run time for most user exits is generally small however at E15, E32, and E35 user exits are entered for each record of the files. For large input files, the total run time for these routines can be relatively large.



48
Using Dataspace Sorting
Using Dataspace Sorting

Dataspace sorting uses available data space with VSE/ESA (ESA supervisor mode) to improve performance of CSI-SORT applications by allowing CSI-SORT to sort large pieces of data without work files. Thus helping reduce CPU time and elapsed time.

Use the DSPSIZE operand of the OPTION control statement to control the amount of data space used for dataspace sorting, keeping in mind the following:

WORK=0 can be used to prevent sort work file use.

WORK=1 can be used to specify work space usage with dataspace sorting.

When dataspace sorting is in effect:

— Data space holds input file records and

— The partition GETVIS area holds the following:

Input

Output

Work buffers and other areas.

CSI-SORT User Guide Using Dataspace Sorting



49
Examples of Applications
Introduction

This section provides examples of various CSI-SORT applications as identified in Table 49-1 on page 49-1.Table 49-1. Applications Examples

ApplicationExample No.

Input Type

Output Type Functions

Sort; see ‘‘Sort Example 1’’ on page 50-1

Tape Tape PRINT, LABEL, E35


Disk Tape PRINT, LABEL, ADDROUT, STORAGE, E35


Disk Disk VSAM, ESDS, FILNM


Tape Tape LABEL, BYPASS, INCLUDE


Tape Tape LABEL, BYPASS, SUM, ALTSEQ


Disk Disk SAM ESDS

CSI-SORT User Guide Examples of Applications


Disk Disk VSAM, work file secondary allocation


Disk Print

Punch

Output to SYSLST and SYSPCH

Copy; see ‘‘Copy Example 1’’ on page 51-1

Tape Tape PRINT, LABEL, CLOSE

Copy; see ‘‘Copy Example 2’’ on page 51-3

Disk Disk Multiple input

Table 49-1. Applications Examples

ApplicationExample No.

Input Type

Output Type Functions



50
Sort Application Examples
Sort Examples

This section includes eight sort examples.

Sort Example 1 Figure 50-1 on page 50-1 displays a sort application with tape input and output.

Figure 50-1.Tape Input and Output

CSI-SORT User Guide Sort Application Examples

Line Explanation Table 50-1 on page 50-2 provides explanations for example 1 lines:Table 50-1. Example 1 Line Explanations

Line Explanation

01 JOB statement.

Indicates beginning of control information for the SAMPLE01 job

02–03 ASSGN statements.

Assign devices to be used as output, input, and work units

SYS001—Output unit assigned to tape unit at address 283

SYS002—Input unit assigned to tape unit at address 282

04 TLBL statement.

Defines a tape file for output.

05 EXEC statement.

Calls CSI-SORT directly by name, SORT, and specifies CSI-SORT is to have 4KB virtual storage and up to 5M per data space.

06 OPTION control statement. Specifies:

Write all CSI-SORT messages

Unlabeled output files

07–08 SORT control statement.

Specifies to execute a sort based on three control fields

No work files available

All input is from one file

09 RECORD control statement.

Specifies to sort variable-length records.

Maximum input record length is 158 bytes; indicated by L1 value of LENGTH operand.

L2 and L3 values same as L1 by default.

L4 value indicates the minimum input record length is 54 bytes

L5 indicates modal record length is 100 bytes

10 INPFIL control statement.

Input block size is 1544 bytes, and

Rewind input volume at end of file

11 OUTFIL control statement.

Output block size is 1544 bytes, and

Rewind output volume at end of application



Sort Example 2 Figure 50-2 on page 50-3 illustrates the use of a sort with input on disk and tape output.

Figure 50-2.Input on Disk, Tape Output

Line Explanation Table 50-2 on page 50-3 provides explanations for example 2 lines:

12 MODS control statement.

CSI-SORT loads SAEXIT user routine to execute during phase 3.

The routine is relocatable and the length is 2000 bytes, which is loaded by CSI-SORT into GETVIS.

User exit E35 handles the output tape label processing.

Upon completion, return code 8 sent to CSI-SORT to end exit calls.

13–14 End-of-data file and end-of job statements.

Table 50-1. Example 1 Line Explanations

Line Explanation


Line Explanation

01 JOB statement.

Indicates beginning of control information for the SAMPLE02 job.


Assign devices to be used as output, input, and work units.

SYS001—Output unit assigned to tape unit at address 284.

SYS002—Input unit assigned to disk unit at address 190.

SYS005—Work unit assigned to disk unit at address 192.

05 TLBL statement.

Defines a tape file for output.



Sort Example 3 Figure 50-3 on page 50-5 illustrates a sort with VSAM input and output.

06–09 DLBL and EXTENT statements.

Define two extents:

One extent containing 500 tracks for input and

One extent containing 700 tracks on one volume for work space

10 EXEC statement.

Calls CSI-SORT directly by name, SORT

Maximum size for data spaces of 2M

11 OPTION control statement. Specifies:


Nonstandard labels for output files

Standard labels for input files, by default

CSI-SORT ignores ADDROUT and STORAGE=64K

12–13 SORT control statement.

Specifies to execute a sort based on four control fields, all containing floating point data

Input file is contained on one file, by default

Uses a work file




L3—Output length from E35 exit is 36 bytes

L4—Value indicates the minimum input record length is 54 7 bytes

L5—Indicates modal record length is 900 bytes


Output block size is 80 bytes

Do not rewind output volume before opening the volume; it rewinds the output volume at the end of applications

Input block size is 1645 bytes, by default, since no INPFIL statement

16 MODS control statement.

CSI-SORT loads PHASE3A user routine to execute during phase 3.

The routine is relocatable and the length is 19000 bytes, which is loaded into partition GETVIS.

Activates user exit E35 for output file nonstandard labels and for creating the output record from fields in the input record.



Line Explanation



Figure 50-3.VSAM Input and Output


Line Explanation

01 JOB statement.




All files on disk devices.


Define VSAM files a input; defined by IDCAMS and previously loaded by another program.


Define a work file on a disk; requires only six tracks.


Define a VSAM file as output; must have been created previously.

11 EXEC statement.

Calls CSI-SORT directly by name, SORT, and specifies CSI-SORT is to have 4KB virtual storage directly available for its use.

Maximum data space size is the defined system default.

Must be sufficient storage remaining in the partition for VSAM use.

12 OPTION control statement. Specifies input filename is INPUT, not the default name SORTIN1

13 SORT control statement.

Specifies to execute a sort based on one control field

One work file available




Specifies to sort fixed-length records

Input record length is 80 bytes; indicated by L1 value of LENGTH operand, which is indicated by no parenthesis


Input file is VSAM.


Output file is an entry-sequenced VSAM file.



Line Explanation



Sort Example 4 Figure 50-4 on page 50-7 illustrates a sort with tape input and output INCLUDE and OUTFIL.

Figure 50-4.Tape Input and Output


Line Explanation

01 JOB statement.




SYS001—Output unit assigned to tape unit at address 284.

SYS002—Input unit assigned to tape unit at address 282.

SYS003 through SYS004—Four work units assigned to disk.


Defines four extents on the two disk work volumes; total 152 tracks allocated.

10 EXEC statement.


11 OPTION control statement.

Output and input tapes both unlabeled.


Execute sort based on two control fields.


Specifies to sort fixed-length records.

Input record length is 80 bytes; indicated by L1 value of LENGTH operand.

Default value for all other length specifications.



Sort Example 5 Figure 50-5 on page 50-8 illustrates a sort with tape input and output, ALTSEQ and SUM.

Figure 50-5.Tape Input and Output, ALTSEQ and SUM

Line Explanation Table 50-5 on page 50-8 provides explanations for example 5 lines:



Bypass input blocks causing I/O errors


Output block size is 800 bytes.

16 INCLUDE control statement.

Examine sixth byte of every record.

Include in sort records whose sixth byte contains a character collating greater than or equal to M; discard all others.



Line Explanation


Line Explanation

01 JOB statement.



Assign devices to be used as output, input, and work units

SYS001—Output unit assigned to tape unit at address 284

SYS002—Input unit assigned to tape unit at address 282



04 EXEC statement.


The maximum size of each data space is 5M.


Output and input tapes both unlabeled.


Execute sort based on one control field.

Use alternative collating sequence, specified in ALTSEQ statement, line 11.



Input record length is 80 bytes; indicated by L1 value of LENGTH operand.

Default value for all other length specifications.



Bypass input blocks causing I/O errors



10 SUM control statement.

Add contents of summary field in bytes 51 through 56 if two records are found with equal sort control fields.

Place the sum in one of the records; delete the other record.

11 ALTSEQ control statement.

Collate national character at end of the alphabet:

X’5B’ collates as X’EA’

X’7B’ collates as X’EB’

X’7C’ collates as X’EC’



Line Explanation



Sort Example 6 Figure 50-6 on page 50-10 illustrates a sort with SAM ESDS input, output, and work files.

Figure 50-6.SAM ESDS Input, Output, and Work File


Line Explanation

01 JOB statement.


02 Comment statement.

03 DLBL statement.

Defines sort input as file ‘INPUT.FILE’ managed by VSAM1; file defined by IDCAMS and previously loaded by another program.

04–05 DLBL statement. Defines sort output as managed by VSAM:

File implicitly defined to contain a thousand 500-byte records.

Ten day retention period

06 EXTENT statements.

Define to VSAM the output file must be defined on a disk with serial number DISK01.

Omit if a default model cataloged that indicates the required disk.

07 DLBL statement.

Defines sort work as a VSAM-managed SAM file previously defined.

08 EXEC statement.




Specifies one work file and assumes one input file by default



Sort Example 7 Figure 50-7 on page 50-11 illustrates a sort with VSAM input and output and SAM ESDS work files.

Figure 50-7.VSAM Input and Output and SAM ESDS Work File




L2 and L3 values same as L1 by default.

L4 value indicates the minimum input record length is 1000 bytes

L5 indicates modal record length is 400 bytes (Unused by CSI-SORT).


Input block size is 4000 bytes

Uses SAM access because VSAM not specified


Output block size is 4000 bytes

Uses SAM access because ESDS not specified


1. All VSAM definitions are assumed to be in the master catalog.


Line Explanation




Line Explanation

01 JOB statement.



03 DLBL statement.

Defines sort input as file SORTINP managed by VSAM1; file defined by IDCAMS and previously loaded by another program.

04 DLBL statement.

Defines sort output as file SORTOTP managed by VSAM; file defined by IDCAMS as ESDS reusable file.

05–06 DLBL statement.

Defines sort work file ‘%DOS.WORKFILE.SYS001.SORT’ as a SAM ESDS file:

First extent—Contains up to one thousand 80-byte records in its first extent, which allocates as a single extent

Second extent—Contains an additional five hundred 80-byte records when the first extent is full.

07 EXTENT statements.

Define to VSAM the work file must be defined on a disk with serial number SYSWK5.

08 EXEC statement.




Control field is binary format

Uses one work file



Default all other length specifications


Input file is VSAM

CSI-SORT is to tolerate a warning code from VSAM when opening or accessing the VSAM input file


Output file is a reusable entry sequence VSAM file

CSI-SORT is to tolerate a warning code from VSAM when opening or accessing the VSAM output file



Sort Example 8 Figure 50-8 on page 50-13 shows a sort with output to printers and punch devices.

Figure 50-8.Output to Printers and Punch Devices



Route ignored by CSI-SORT


1. All VSAM definitions are assumed to be in the master catalog.


Line Explanation




Line Explanation

01 JOB statement.



Assign devices to be used as work and input units.

SYS030—Work unit assigned to disk

SYS001—Input unit assigned to same unit as SYS030

SYS002—Input unit assigned to same unit as SYS030


Defines two sort input files, SORTIN1 and SORTIN2.


Define sort work file, SORTWK1.

11–13 Comment statement.

14 EXEC statement.



Write output file to SYSLST.


Specifies to execute a sort based on two control fields

Both control fields use character format

Sort two input files

Use one work file



Place the sum i one of the records.

Delete the other record.



Input record length is 80 bytes; indicated by L1 value of LENGTH operand



Specifies input block size is 3600 bytes.





Define two sort input files, SORTIN1 and SORTIN 2.


Define sort work file, SORTWK1.

27–29 Comment statements

30 EXEC statement.



Write output file to SYSPCH.


Specifies to execute a sort based on two control fields

Both control fields use character format

Sort two input files

Use one work file



Place the sum in one of the records.

Delete the other record.



Input record length is 80 bytes; indicated by L1 value of LENGTH operand



Specifies input block size is 3600 bytes.



Line Explanation



51
Copy Application Examples
Copy Examples

This sections provides two copy application examples.

Copy Example 1 Figure 51-1 on page 51-1 shows a copy application with tape input and output.

Figure 51-1.Copy With Tape Input and Output


Line Explanation

01 JOB statement.

Indicates the beginning of control information for SAMPLE 14 job.

02–03 ASSGN statement.

Assign devices as output and input units:

SYS001—Output unit to tape unit address 283

SYS002—Input unit to tape unit address 282

CSI-SORT User Guide Copy Application Examples

04 TLBL statement.

Defines tape unit for output.

05 EXEC statement.


The maximum size of data space is 10M. All records load into the data space area before being written to the output file.


Write CSI-SORT messages

Output file has nonstandard labels

Input file is unlabeled


Specifies a copy application; handled like a sort operation with no fields.


Copy variable-length records

Maximum input record length is 158 bytes; L1 value of the LENGTH operand

L2 and L3 values same as L1 by default

L4 value indicates minimum input record length is 54

L5 value indicates modal record length is 100 bytes (Unused by CSI-SORT).


Input block size is 1544 bytes.

Rewind input volume at end of file.



Rewind input volume at end of application.

11–12 End-of-data file and end-of-job statements.


Line Explanation



Copy Example 2 Figure 51-2 on page 51-3 shows a copy application with multiple input.

Figure 51-2.Copy with Multiple Input


Line Explanation

01 JOB statement.

Indicates the beginning of control information for SAMPLE 15 job.


Assign devices to use as output and input units:

SYS011 output unit assign to disk

SYS001–SYS004 input units assign to same unit as SYS011


Define four copy input files, SORTIN1, SORTIN2, SORTIN3, and SORTIN4.


Define copy output file, SORTOUT.

17–19 Comment statement.



20 EXEC statement.


The maximum size of data space is 20M. All records load into the data space area before being written to the output file.

21–22 OPTION control statement.

Write all CSI-SORT messages.

CSI-SORT routes all messages to SYSLST.

Ignores DIAG.

Ignores DUMP.

Output filename is SORTOUT.

Parameter may be omitted because SORTOUT is the default.


Specifies a copy application.

Copy four input files to the output file.


Copy fixed-length records

Input record length is 80 bytes; L1 value of the LENGTH operand



Input block size is 3600 bytes.



27–29 End-of-data file and end-of-job statements.


Line Explanation


Copyright © 2006-2017 by Connectivity Systems, Inc.A.1

A
Estimating Storage
Requirements

Using Virtual Storage

This appendix discusses using virtual storage for estimating storage requirements.

A copy application needs virtual storage and data space or partition GETVIS area.

A sort or merge application needs:

Virtual storage

Work space on direct access devices if WORK=1 is specified, and

Data space or partition GETVIS area

Minimum Virtual Storage

CSI-SORT requires the following:

Minimum 1KB of virtual storage of the partition program area, although 4KB is recommended

200KB in 24 bit in partition GETVIS for programs and work areas, and other partition GETVIS area (24 or 31 bit) for tables and other work areas.

The size is determined by the number of records.

Note:Note:A rule of thumb to use is 16KB for each 1000 records being loaded in data space area; plus record size if loaded in partition GETVIS area. These figures are rough estimates since not all storage is acquired or released at the same time.

CSI-SORT User Guide Estimating Storage Requirements

In addition, partition area is needed for:

User exit routines, if any.

Area required for sort processing.

Application programs, if calling CSI-SORT from an application.

Buffer areas if using sort work files.

Buffer areas for input and output blocks.

Additional Functions

The extra partition program area storage required by some of the additional functions, for example INREC and SUM is about 4KB per function.

The INCLUDE and OMIT control statements are mutually exclusive and may require up to 32KB of partition program area storage, depending on the complexity of the logical expression.

Using Data Space Area

Data space requirements depend on whether a sort work file is used:

If not using sort work, each record loads into data space area.

This means 10,000 records of 500 bytes each require about 4.8M of data space area.

If using sort work area, the more data space area the fewer segments to sort and then merge for CSI-SORT.

Copyright © 2006-2017 by Connectivity Systems, Inc.A.2

Copyright © 2006-2017 by Connectivity Systems, Inc.B.1

B
Data Format Examples
Data Format Examples

This appendix shows format descriptions, which refer to the assembles data formats as used with CSI-SORT.

For example, if FIXED DECIMAL data variable is declared in PI/I, the compiled format of the variable is given in the f field of the SORT control statement–not the PL/I declared format. In this example, the f field is PD because the PL/I compiler converts fixed decimal to packed decimal form.

Table 51-3 on page B-1 provides examples and descriptions of the different formats:Table 51-3. Data Format Examples

Format Description

AC Character ISCII/ASCII; unsigned. Similar to format CH but the characters are represented with ISCII/ASCII code.

ASL Signed numeric; ISCII/ASCII; leading separate sign. Similar to CSL format but with decimal data assembled into ISCII/ASCII code.

<Title of Major Work><ProductName>CSI-VSUM for z/VSE <Title of Major Work>Program Description and

AST Signed numeric; ISCII/ASCII; trailing separate sign. Same bit representation as ASL format except the sign is punched after the number.

BI Binary unsigned. Any bit pattern.

CH Character EBCDIC; unsigned. Each character is represented by its eight-bit EBCDIC code:

If CHALT is in effect, a format CH field collates according to the ALTSEQ table in effect. AQ format can be used for the same purpose.

CLO Signed numeric; leading overpunch sign. Format refers to decimal data punched into cards and then assembled into EBCDIC code. Sign indicator is overpunched with the first decimal digit of the number.

The overpunch sign bit is:

‘C’—Positive

‘D’—Negative

CSL Signed number; leading separate sign. Refers to decimal data as punched into cards and then assembled into EBCDIC code.

CST Signed numeric; trailing separate sign. Same representation as CSL format except sign indicator is punched after the number.

CTO Signed numeric; trailing overpunch sign. Format is same as for CLO except the sign indicator is overpunched on the last decimal digit of the number.

Table 51-3. Data Format Examples

Format Description



FI Fixed point; signed. The complete number is represented by its binary equivalent with the sign indicator placed in the most significant bit position.

FL Floating point; signed. Specified number is in the two-part format of characteristic and fraction with the sign indicator in bit position 0.

PD Packed decimal; signed. Each digit of the decimal number is converted into its four-bit binary equivalent. The sign indicator is put into the rightmost four bits of the number.

Treated as positive sign indicators: F, E, C, A, 8, 6, 4, 2, 0.

Treated as negative sign indicators: D, B, 9, 7, 5, 3, 1.

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, PD value X’0123BF’ results in 0C7 because B is treated as an invalid digit.

PD0 or PZ

Packed decimal; sign and first digit ignored. Required format is

xddd...ds, where:

x—Hexadecimal 0–F and ignored.

d—Hexadecimal 0–9 and represents a decimal digit.

s—Hexadecimal 0–F and ignored.

PD0 and PZ can be used for parts of the PD fields. For example, in PD field P’mmddyy’ (hex: 0mmddyyC), use PD0 or PZ separately for 0mmd (mm), mddy (dd), and dyyC (yy).


Format Description



PSI Packed decimal; sign ignored. Format is:

dd....ds, where



Use PSI to make positive PD fields printable or readable. For example, PSI makes printable PD field P’ddd’ (hex: dddC).

Y2B Two-digit, one-byte binary year data. The binary year data is represented as hh, where hh is the hexadecimal equivalent of a decimal yy value below:

For example, 96 may be represented as:

Hexadecimal 60 (decimal 96), or

C4 (decimal 196).

Y2C or Y2Z

Two-digit, two-byte character or zoned decimal data.Two-digit year data is represented below:

xyxy, where:

y—Hexadecimal 0–9 and represents a year digit.


For example, 96 may be represented as hexadecimal F9F6 (character 96) or F9C6 or 0906 (zoned decimal 96).

Y2D Two-digit, one-byte decimal year data. The two-digit year data is:

yy, where yy is hexadecimal 0–9 and represents a year digit.

For example 96 is represented as hexadecimal 96 (decimal 96).

Y2P Two-digit, two-byte packed decimal year data. The two-digit year data is:

xyyx, where:



For example, 96 is represented as hexadecimal 096F or 896C (packed decimal 96).


Format Description



Y2S Two-digit, two-byte character or zoned decimal year data with special indicators. The two-digit year data is represented as follows:

xyxy, where:



For example, 96 may be represented as hexadecimal F9F6 (character 96) or as F9C6 or 0906 (zoned decimal 96).

The special indicators are represented as follows:

qxzx, where:

qx—Hexadecimal 00, 40, FF, or 20 (if DATA=A in INPFIL control statement.

zx—Hexadecimal 00–FF, although typically 00, 40, or 20, and FF.

For example, the special indicators my be hexadecimal 0000, 0005, 4040, FFFF, FF85 and so forth.

ZD Zoned decimal; signed. Each digit of the decimal number is converted into its eight-bit EBCDIC representation. The sign indicator replaces the first four bits of the low order byte of the number.

Treated as positive sign indicators: F, E, C, A, 8, 6, 4, 2, 0.

Treated as negative sign indicators: D, B, 9, 7, 5, 3, 1.

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 of 3.5 (X’F34BF5’) results in an 0C7 because B is treated as an invalid digit.

Sign indicator is the four bits of the last digit. The first four bits of each other digit is ignored. Therefore, EBCDIC strings ‘0025’ and ‘ 25’ are treated as 25 because a leading blank (X’40’) is equivalent to a 0 digit (X’F0’)

ZSI Zoned decimal; sign ignored. The ZSI format is represented as follows:

zd...sd, where:

z—Hexadecimal 0–F and ignored.



ZSI can be used to make positive ZD fields printable or readable.


Format Description


Copyright © 2006-2017 by Connectivity Systems, Inc.C.1

C
EBCDIC Collating Sequences
EBCDIC Collating Sequences

This appendix shows the collating sequence for EBCDIC character and unsigned decimal data.

The collating sequence ranges from low (00000000) to high (11111111).

Use ALTSEQ, and CHALT to select alternate collating sequences for character data.

The following formats are collated algebraically, each quantity interpreted as having a sign:

Packed decimal

Zoned decimal

Fixed-point data

Normalized floating-point data

Figure C-1 on page C-2 and Figure C-2 on page C-3 shows the collating sequence for EBCDIC character and unsigned decimal data.

Bit configurations that do not correspond to symbols (0 through 73, 81 through 89 and so one) are not shown as some correspond to control commands for the printer and other devices.


Figure C-1. EBCDIC Collating Sequences 0–153



Figure C-2. EBCDIC Collating Sequences 162–255


Copyright © 2006-2017 by Connectivity Systems, Inc.D.1

D
ISCII/ASCII Collating
Sequences

ISCII/ASCII Collating Sequences

This appendix 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.

The following formats are collated algebraically, each quantity interpreted as having a sign:

Packed decimal

Zoned decimal

Fixed-point data

Normalized floating-point data

Signed numeric data

Figure D-1 on page D-2 and Figure D-2 on page D-3 together show the collating sequence for ISCII/ASCII, character, and unsigned decimal data.


Figure D-1. ISCII/ASCII Collating Sequences 0–69



Figure D-2. ISCII/ASCII Collating Sequences 80–126


Copyright © 2006-2017 by Connectivity Systems, Inc.E.1

E
Error Messages
Error Messages

This section provides the following:

Identifies and lists the current CSI-SORT error messages.

An explanation of what occurred or was detected to produce the message.

User action to correct the problem, if required.

CSS000E INVALID CONTROL STATEMENT NEAR COLUMN nnn OF XXXXXXXX

Explanation

An error was discovered near column nnn of CSI-SORT parameter xxxxxxxx.

Action

Correct the parameter in error.


CSS001E XXX AND SORT FIELD CONFLICT AT POSITION nnnnn

Explanation

One of several conflicts occurred with a particular sort field. Possible values for XXX are:

MAX—Field exceeds the defined maximum record length.

RDW—Field position must be after the RDW area for variable-length record files.

SUM—Sum field position conflicts with a field used for sorting.

TYP—Specified value conflicts with the field type.

Action

Correct field in error and try again.

CSS002E ERROR LOADING PHASE XXXXXXXX, RC=nnn

Explanation

An error occurred while attempting to load the requested phase.

The return code indicates the reason.

Action

Depending on the return code, make the correction and try again.

Check return codes for LOAD macro for further information.

CSS003E ERROR DURING DATA SPACE CREATION, RC=XXX,RX=xxxxxxxx

Explanation

An error was detected while trying to create a dataspace area.The return code and reason code are provided.

Action

Check the codes for the DSPSERV macro with the CREATE option for more information.

In most cases:

The error is due to insufficient data space area defined, or

The maximum for a task was exceeded.



CSS004E ERROR ACCESSING DATA SPACE ALET, RC=XXX, RS=xxxxxxxx

Explanation

An error was detected while trying to access a dataspace area.

The return code and reason code are provided.

Action

Check the codes for the ALESERV macro with the ADD option for more information.

Contact CSI technical support if the error cannot be resolved.

CSS005E XXXXXXXXXXXXXXXXX FOUND NEAR COLUMN nnn OF CCCCCCCC

Explanation

Once of several errors occurred during processing of the CCCCCCCC command:

E15/E35 PHASE NOT found for command CCCCCCCC.

E32/E35 PHASE NOT found for command CCCCCCCC.

ERROR IN OPERAND was found for command CCCCCCCC.

NO SORT OR MERGE command was detected.

DUPLICATE OPERAND was found in command CCCCCCCC.

Action

Correct/add the required command and try again.

CSS006E XXXXXXXXXX CONTROL STATEMENT WAS NOT FOUND

Explanation

The required XXXXXXXXXX control statement was not found during parameter processing.

Action

Correct/add the required command and try again.



CSS010E GETVIS ERROR, RC=XXX

Explanation

An error occurred while attempting to get partition GETVIS area.

Action

Increase the size of the partition GETVIS ares if it is too small.

Consult the GETVIS error message in the IBM EXPLAIN file for more information.

CSS011E INPUT FILE, ERR=nnn DURING RECORD OPEN/READ/CLOSE

OUTPUT FILE,ERR=nnn DURING RECORD OPEN/WRITE/CLOSE

Explanation

The specified error, nnn, occurred during input or output record processing.

Action

Determine the reason for the error and correct.

Check for additional information in the printout and the console log.

CSS013E MAX VAR RECORD LEN EXCEEDED, VALUE=nnnnnnn

Explanation

A record of length nnnnnnn was found that exceeds the maximum record length specified in the L1 parameter for a variable-length record file.

Action

If the L1 parameter is correct, check the input file for bad record(s).



CSS014E E1n: VAR REC LEN OUT OF RANGE, VALUE=nnnnnnn

E3n: VAR REC LEN OUT OF RANGE, VALUE=nnnnnnn

Explanation

A record of length, nnnnnnn, was found after processing in the E15, E32, or E35 exit for a variable-length record.

Action

Correct the problem and try again.

CSS015E INCLUDE/OMIT POS OUT OF RANGE, VALUE=XXXXXXX

Explanation

Section criteria for an INCLUDE/OMIT request is outside the record boundary.

Action

Change the criteria to always be within the bounds of the record.

CSS016E E1n: INVALID RETURN CODE, RC=XXX

E3n: INVALID RETURN CODE, RC=XXX

Explanation

The return code from the E15, E32, or E35 exit is either invalid or improper for its function.

Action

Check the supplied exit for proper processing.

CSS017E E1n: NO RECORD ADDRESS PASSED FROM EXIT

E3n: NO RECORD ADDRESS PASSED FROM EXIT

Explanation

No record address was returned from the E15, E32, or E35 exit even though the return code indicated there should be a record.

Action

Correct the exit routine and try again.



CSS018E INREC LENGTH ERROR DURING RECORD LOAD

OUTREC LENGTH ERROR DURING RECORD LOAD

OUT OF SPACE ERROR DURING RECORD LOAD

TERMINATION FORCED DURING RECORD LOAD

Explanation

Either the data space area or GETVIS area (GVSIZE=) is full or the INREC or OUTREC field exceeds the L3 length value, or termination was forced during record access.

Action

Increase the amount of data space or GETVIS, correct the parameter in error, or check messages for the reason for forced termination.

CSS019E SORT FIELD POS EXCEEDS RECORD LENGTH

Explanation

For at least one record, the position to sort exceeds the length of the record.

Action

Change the sort field(s) or determine the problem with the record length.

CSS020E E1n: FORCED SORT TERMINATION REQUEST

E3n: FORCED SORT TERMINATION REQUEST

Explanation

The exit specified in the message returned a return code of 16 to force CSI-SORT to terminate.

Action

Check the exit for the reason why it terminated the sort request.


Glossary

Numerics

A

B

C

CKDcount key data

collating sequenceA specific arrangement of character priority used to determine which of two values in the same control field, of two different records, should come first.

control fieldsDefined by a user to identify the information CSI-SORT is to sort or merge.

CSIConnectivity Systems, Inc.

D

directly invokedCSI-SORT does not initiate from another program.

E

ECKDextended count key data

F

FBAfixed block architecture

FLRfixed length record

G

H

I

J

JCCjob control command

JCLjob control language

JCSjob control statement

K

Copyright © 2006-2017 by Connectivity Systems, Inc.Glossary.1

CSI-SORT User Guide

L

M

major control fieldThe first control field specified by the user.

minor control fieldSubsequent control fields, after the major control field, specified by the user. Usually referred to as first, second, third, et cetera.

N

O

P

program invokedCSI-SORT initiates from another program.

Q

R

S

T

U

V

VLRvariable length record

W

X

Y

Z

Copyright © 2006-2017 by Connectivity Systems, Inc.Glossary.2

Index

Bblock size, 4-4

Ccoding rules, 13-1collating sequences

EBCDIC, C-1ISCII/ASCII, D-1

control statementadditional functions, 12-3additional options, 12-3ALTSEQ, 14-1END, 15-1INCLUDE, 16-1INPFIL, 20-1INREC, 21-1MERGE, 22-1MODS, 23-1OMIT, 16-1OPTION, 24-1OUTFIL, 25-1OUTREC, 26-1primary task, 12-1RECORD, 27-1records, 12-2SORT, 28-1SUM, 29-1summary, 12-1using program, 11-1

CSI-Sortcollating sequences, 3-2

control fields, 3-1error messages, E-1how it works, 3-1invoking, 2-1invoking from a program, 38-1overview, 1-1processing, 3-3requiring JCL, 42-1subtasking, 41-1things to consider, 4-1

Ddefining files

rules, 10-1devices

input/output, 5-1

Eefficiency

designing applications, 47-1improving, 46-1using dataspace sorting, 48-1

error messages, E-1examples

applicationscopy, 51-1introduction, 49-1sort, 50-1

data format, B-1exit routines, see "user exit routines", 30-1

Copyright © 2006-2017 by Connectivity Systems, Inc.IX.1

CSI-SORT User Guide

Ffiles

characteristics, 4-1defining, 10-1input, 4-1output, 4-1SAM ESDS, 4-3

formatdata, 4-3record, 4-3

Ggeneral registers

passing information, 43-1

IINCLUDE

bit logic tests, 19-1comparisons, 17-1control statement, 16-1substring comparison tests, 18-1

input/output devicesintroduction, 5-1pooling, 5-1sharing, 5-2

intermediate storage devices, 6-1introducing

CSI-Sort, 1-1

JJCL, see "job control language", 8-1job control language

introducing, 8-1using, 9-1

Mmessages, 7-1

CSS000E, E-1CSS001E, E-2CSS002E, E-2CSS003E, E-2CSS004E, E-3CSS005E, E-3CSS006E, E-3CSS010E, E-4CSS011E, E-4CSS013E, E-4

CSS014E, E-5CSS015E, E-5CSS016E, E-5CSS017E, E-5CSS018E, E-6CSS019E, E-6CSS020E, E-6

modes, addressing and residencean invoking program, 44-1user exit routines, 33-1

OOMIT

bit logic tests, 19-1comparisons, 17-1control statement, 16-1substring comparison tests, 18-1

OPTIONexamples, 24-7operands, 24-2

OUTFILexamples, 25-5operands, 25-2

Pparameter list

passing parameters, 45-1

RRECORD

examples, 27-3miscellaneous, 27-2operands, 27-2

record length, 4-4return codes, 7-1

SSORT

examples, 28-6miscellaneous, 28-5operands, 28-2

storageestimating requirements, A-1

SUMexamples, 29-4miscellaneous, 29-3


CSI-SORT User Guide

operands, 29-2system macros

defining, 39-1introduction, 38-1invoking from a program, 38-1using, 40-1

Uuser exit routines

E15, 36-1

E32, 36-1E35, 37-1functions, 32-1introduction, 30-1linking and loading, 35-1modes, 33-1performance effects, 34-1processing phases, 31-1topics, 30-2


CSI-SORT User Guide


csi-sort · 2017-03-31 · csi-sort the complete vse sort package user guide version 2.01 • great...

Documents