zos-jcl-5th-edition.9780471236351.31271

TEAMFLY

Team-Fly®

z/OS JOB CONTROL LANGUAGE

F IFTH EDIT ION

Gary DeWard Brown

John Wiley & Sons, Inc.

Publisher: Robert IpsenEditor: Margaret EldridgeDevelopmental Editor: Kathryn A. MalmAssociate Managing Editor: Penny LinskeyNew Media Editor: Brian SnappText Design & Composition: North Market Street Graphics

Designations used by companies to distinguish their products are often claimed astrademarks. In all instances where John Wiley & Sons, Inc., is aware of a claim, theproduct names appear in initial capital or ALL CAPITAL LETTERS. Readers, however,should contact the appropriate companies for more complete information regardingtrademarks and registration.

This book is printed on acid-free paper. ∞�Copyright © 2002 by Gary DeWard Brown. All rights reserved.

Published by John Wiley & Sons, Inc.,Published simultaneously in Canada.

No part of this publication may be reproduced, stored in a retrieval system or trans-mitted in any form or by any means, electronic, mechanical, photocopying, record-ing, scanning or otherwise, except as permitted under Sections 107 or 108 of the 1976United States Copyright Act, without either the prior written permission of the Pub-lisher, or authorization through payment of the appropriate per-copy fee to the Copy-right Clearance Center, 222 Rosewood Drive, Danvers, MA 01923, (978) 750-8400, fax(978) 750-4744. Requests to the Publisher for permission should be addressed to thePermissions Department, John Wiley & Sons, Inc., 605 Third Avenue, New York, NY10158-0012, (212) 850-6011, fax (212) 850-6008, E-Mail: [email protected].

This publication is designed to provide accurate and authoritative information inregard to the subject matter covered. It is sold with the understanding that the pub-lisher is not engaged in professional services. If professional advice or other expertassistance is required, the services of a competent professional person should besought.

Library of Congress Cataloging-in-Publication Data:ISBN 0471-236357

Printed in the United States of America.

10 9 8 7 6 5 4 3 2 1

CONTENTS

Preface ix

Job Control Language Parameters xi

Chapter 1 Introduction 11.1 The Shock of JCL 11.2 The Role of JCL 31.3 The Difficulty of JCL 31.4 The Approach to JCL 4

Chapter 2 Introduction to JCL and z/OS 62.1 z/OS Concepts and Vocabulary 62.2 z/OS Hardware Architecture 102.3 Computer Data 262.4 Data Storage 33

Chapter 3 JCL within a Job 353.1 JCL Statements 353.2 Computer Jobs 363.3 Creating Programs 413.4 Sort Example 423.5 Compile, Linkage Edit, Execute Example 453.6 Cataloged Procedure 50

Chapter 4 JCL Statement Formats and Rules 514.1 JCL Statement Format 514.2 Parameters in the Operand Field 534.3 Parameter Rules 53

iii

4.4 General JCL Rules 544.5 Continuing JCL Statements 554.6 Commenting JCL 564.7 Style in Writing JCL 574.8 Placement of JCL Statements 58

Chapter 5 The JOB Statement 605.1 Jobname: Name of Job 625.2 Accounting Information 635.3 Name: Programmer Name 645.4 CLASS: Job Class 645.5 TIME: Time Limit 655.6 MSGCLASS: System Messages 675.7 MSGLEVEL: Printing JCL Statements 725.8 TYPRUN: Special Job Processing 73

Exercises 74

Chapter 6 The EXEC Statement 776.1 Stepname: Name of Job Step 786.2 PGM: Name of Program 786.3 Procedure: Name of Cataloged Procedure 826.4 Keyword Parameters 836.5 Region Size 836.6 COND: Conditions for Bypassing Job Steps 856.7 IF/THEN/ELSE/ENDIF Statement Construct 926.8 PARM: Pass Parameters to Job Steps 976.9 ACCT: Job Step Accounting Information 99

6.10 SYSUDUMP, SYSABEND, SYSMDUMP: Abnormal Termination Dumps 100Exercises 101

Chapter 7 The DD Statement 1037.1 Overview of Data Sets 1037.2 Data Control Block 1057.3 DD Statement Format 1067.4 ddname: Data Definition Name 1097.5 Referback: Referback Parameter 1097.6 DCB: Data Control Block Parameter 1107.7 DSN: Data Set Name 1207.8 DISP: Data Set Disposition 1257.9 UNIT: I/O Unit 135

iv CONTENTS

7.10 VOL: Volume Parameter 140Exercises 145

Chapter 8 More on the DD Statement 1468.1 Sequential and Partitioned Data Sets 1468.2 DUMMY, NULLFILE: Dummy Data Sets 1478.3 Concatenating Data Sets 149

Exercises 152

Chapter 9 DD Statements for Input Stream and Print Data Sets 153

9.1 *,DATA: Input Stream Data Sets 1539.2 SYSOUT: Output Stream Data Sets 1559.3 The OUTPUT JCL Statement and Output DD Parameter 1589.4 The JES /*OUTPUT Statement 1689.5 The JES3 //*FORMAT PR Statement 1699.6 Parameters Coded on Several Statements 170

Chapter 10 Direct-Access Storage Devices 18110.1 Direct-Access Hardware Devices 18110.2 Space Allocation 18310.3 The SPACE Parameter 18510.4 DCB Parameters 19410.5 Virtual I/O (VIO) Temporary Data Sets 19510.6 Estimating Space 19610.7 The LABEL Parameter: Data Set Labels 20010.8 Multivolume Data Sets 20010.9 Using Data Sets on Direct-Access Volumes 201

10.10 ABSTR: Requesting Specific Tracks 205Exercises 206

Chapter 11 SMS: Storage Management Subsystem 20811.1 The AVGREC Parameter 20911.2 The DATACLAS, STORCLAS, MGMTCLAS,

and SECMODEL Parameters 20911.3 The LIKE and REFDD Parameters 21311.4 RECORG and KEYOFF for VSAM Data Sets 21411.5 DSNTYPE Parameter for Partitioned and Extended

Sequential Data Sets 215

CONTENTS v

Chapter 12 Magnetic Tapes 21712.1 Description of Tape 21712.2 LABEL: Tape Labels 22012.3 DCB Subparameters 22812.4 Using Tapes 22812.5 Compressing Data on Tape 23112.6 Multivolume Tape Data Sets 23212.7 Reading Tapes from Another Installation 23312.8 ISO/ANSI/FIPS Version 3 Labels 233

Exercises 235

Chapter 13 JES2 and JES3 23613.1 Job Entry Subsystems 23613.2 JES2 23613.3 JES3 239

Chapter 14 Cataloged and Instream Procedures 24814.1 Modifying Statements in Cataloged Procedures 24914.2 Cataloged Procedures 25514.3 Instream Procedures 25714.4 Symbolic Parameters 25814.5 Nesting Procedures and the INCLUDE Statement 26714.6 DDNAME: Postponing Definition of Data Sets 27014.7 Example of Cataloged Procedure 272

Exercises 274

Chapter 15 Generation Data Groups 27615.1 Creating the Generation Data Group Base Entry 27615.2 Creating the Model Data Set Label

(Non-SMS-Managed Data Sets Only) 27715.3 Creating a Generation Data Set 27815.4 Retrieving Generation Data Sets 28015.5 Listing Generation Data Group Catalog Information 28015.6 Deleting Generation Data Groups 280

Chapter 16 Miscellaneous JCL Features 28216.1 Checkpoint/Restart 28216.2 Spanned Records 28916.3 Data Set Protection 28916.4 Job Execution Priority 29216.5 Other JCL Parameters 293

vi CONTENTS

16.6 Null Statement 29616.7 Operator Commands 29716.8 CNTL/ENDCNTL Program Control Statements 29816.9 XMIT Data Transmission Statements 298

Chapter 17 VSAM Data Sets 30017.1 Creating VSAM Data Sets with JCL 30417.2 Accessing VSAM Data Sets through JCL 30517.3 The IDCAMS Utility 30717.4 JOBCAT and STEPCAT DD Statements 314

Chapter 18 The Linkage Editor and Loader 31518.1 The Linkage Editor 31518.2 The Loader 328

Exercises 329

Chapter 19 IBM Utility Programs 33119.1 The IDCAMS Utility 33119.2 The Icetool Utility Programs 33619.3 The IBM Utility Programs 341

Chapter 20 Sort/Merge 35220.1 Sorting Concepts 35220.2 The DFSORT Program 35320.3 The SORT Statement 35420.4 MERGE Statement 35820.5 Other SORT Statements 35920.6 Sort Efficiency 376

Exercises 378

Chapter 21 ISPF 37921.1 Using ISPF 37921.2 Using ISPF for Programming 38421.3 Editing Data Sets 38821.4 Browsing Text 40821.5 The ISPF Utilities 409

Chapter 22 TSO/E 41722.1 The TSO/E Language 41722.2 Logging on and off TSO/E 419

CONTENTS vii

22.3 Displaying Information about Data Sets 42022.4 Allocating Data Sets 42222.5 Calling Programs 42422.6 Submitting Jobs 42422.7 Use of TSO/E for Utility Functions 42722.8 TSO/E CLISTs 428

Chapter 23 TSO/E REXX 43823.1 Variables 43923.2 Arithmetic Expressions 44023.3 Logical Expressions 44023.4 Character Operations 44123.5 REXX Statements 44223.6 Supplying Arguments in the Command Line 447

Chapter 24 Hierarchical File System (HFS) Files 44924.1 JCL Parameters for HFS Files 44924.2 TSO/E HFS Parameters 45324.3 The BPXBATCH Utility 453

Chapter 25 JCL and the Internet 45625.1 Useful Web Sites 45625.2 Sending E-Mail from Batch Jobs 457

Index 461

viii CONTENTS

TEAMFLY

Team-Fly®

PREFACE

The IBM mainframe continues to be alive and well, despite all the attentionreceived by PCs. It has adapted to the changing environment, where issuessuch as security and reliability make it an ideal platform for the electroniceconomy. JCL (Job Control Language) is necessary to run batch jobs on IBMlarge mainframe computers, and batch jobs are an inherent part of pro-gramming on the mainframes. z/OS is the next generation of the OS/390operating system. The information for it in this book has been extractedfrom close to 40 IBM manuals. There are so many manuals for z/OS that ifprogrammers were each to have a personal copy of all the manuals theymight need, they would risk crushing the continental plate under theirweight. Since manuals are expensive, this book saves you and your com-pany money.

This is the fifth edition of the JCL book. I have updated it to incorporaterecent changes to JCL and the z/OS features.

My goal for this book continues to be to explain the operating systemand provide readers with most of the information they need to use it. Forthis reason, chapters on such subjects as the linkage editor, the IBM utili-ties, the Sort/Merge utility, VSAM, TSO/E, ISPF, and REXX are included.

Please visit the book’s Web site at www.wiley.com/compbooks/brownfor solutions to the exercises and a summary of obsolete JCL features.

Gary DeWard BrownLos Angeles, CaliforniaApril 2002

ix

Subparam-Parameter eter of Page

ACCODE DD 234ACCT EXEC 101ADDRESS OUTPUT 168ADDRSPC JOB, EXEC 293AFF UNIT 140AMP DD 303AVGREC DD 209BLKSIZE DD, DCB 118BLKSZLIM DD TKBUFND AMP 304BUFNI AMP 304BUFNO DD, DCB 120BUFSP AMP 304BUILDING OUTPUT 168BURST DD, OUTPUT 175BYTES JOB 173CCSID JOB, EXEC TKCHARS DD, OUTPUT 176CHKPT DD 283CKPTLINE OUTPUT 174CKPTPAGE OUTPUT 174CKPTSEC OUTPUT 174CLASS JOB 66CLASS OUTPUT 166CNTL — 296CNTL DD 296COLORMAP OUTPUT TKCOMMAND — 295


COMPACT OUTPUT 178COMSETUP OUTPUT 167COND JOB, EXEC 87CONTROL OUTPUT 178COPIES DD, OUTPUT 171CROPS AMP 304DATA DD 155DATACK OUTPUT 167DATACLAS DD 209DCB DD 112DD — 105DDNAME DD 270DEFAULT OUTPUT 161DEN DD, DCB 228DEPT OUTPUT 168DEST DD, OUTPUT 173DISP DD 127DLM DD 156DPAGELBL OUTPUT 167DSN DD 122DSNTYPE DD 215DSORG DD, DCB 113DUMMY DD 149DUPLEX OUTPUT TKDYNAMNBR EXEC 294ENDCNTL — 296EXEC — 79EXPDT DD, LABEL 289

xi

JOB CONTROL LANGUAGEPARAMETERS


FCB DD, OUTPUT 175FILEDATA DD 440FLASH DD, OUTPUT 177FORMDEF OUTPUT 167FORMLEN OUTPUT TKFORMS OUTPUT 175FREE DD 160GROUP JOB 291GROUPID OUTPUT 167HOLD DD 158IF/THEN/ELSE/ENDIF — 94

INCLUDE DD 268INDEX OUTPUT 179JCLLIB — 257JESDS OUTPUT 166JOB — 62JOBCAT Special DD 311JOBLIB Special DD 81KEYOFF DD 302LABEL DD 220LGSTREAM DD TKLIKE DD 213LINDEX OUTPUT 179LINECT OUTPUT 178LINES JOB 172LRECL DD, DCB 116MEMLIMIT JOB, EXEC TKMGMTCLAS DD 211MODIFY DD, OUTPUT 176MSGCLASS JOB 69MSGLEVEL JOB 74NAME OUTPUT 168NOTIFY JOB 415NOTIFY OUTPUT 166NULLFILE DSN 149OFFSET OUTPUT TKOPTCD DD, DCB, AMP 176OUTBIN OUTPUT 166OUTDISP OUTPUT 166OUTLIM DD 172


OUTPUT — 160OUTPUT DD 160OVERLAY OUTPUT TKOVFL OUTPUT 179PAGEDEF OUTPUT 167PAGES JOB 173PARM EXEC 99PASSWORD JOB 291PATH DD 439PATHDISP DD 440PATHMODE DD 442PATHOPTS DD 440PEND — 257PERFORM JOB, EXEC 293PGM EXEC 80PIMSG OUTPUT 167PRMODE OUTPUT 167PROC — 255PROC EXEC 85PROTECT DD 291PRTERROR OUTPUT TKPRTNO OUTPUT TKPRTOPTNS OUTPUT TKPRTQUEUE OUTPUT TKPRTSP DD, DCB 178PRTY JOB 292PRTY OUTPUT 167QNAME DD 294RD JOB, EXEC 284RECFM DD, DCB 114RECORG DD 302REF VOL 143REFDD DD 213REGION JOB, EXEC 85RESFMT OUTPUT TKRESTART JOB 285RETAIN OUTPUT TKRETRY OUTPUT TKRETPD DD, LABEL 289RLS DD 304ROOM OUTPUT 168

xii JOB CONTROL LANGUAGE PARAMETERS


SCHENV JOB TKSECLABEL JOB 291SECMODEL DD 212SEGMENT DD 159SER VOL 143SET — 263SORTCKPT Special DD 283SPIN DD 159SPACE DD 185STEPCAT Special DD 311STEPLIB Special DD 82STORCLAS DD 209STRNO AMP 304SUBSYS DD 295SYNAD AMP 304SYMNAMES DD TKSYSABEND Special DD 102SYSAREA OUTPUT 168SYSCHK Special DD 287SYSCKEOV Special DD 283SYSIN Special DD 155SYSMDUMP Special DD 103


SYSOUT DD 157SYSUDUMP Special DD 102TERM DD 417THRESHLD OUTPUT 179TIME JOB, EXEC 67TITLE OUTPUT 168TRC OUTPUT 176TRTCH DD, DCB 105TYPRUN JOB 75UNIT DD 137USER JOB 291USERDATA OUTPUT 168USERLIB OUTPUT 168VIO DD 195VOL DD 142WRITER OUTPUT 174XMIT — 297//* — 58// — 295/* — 155* DD 155

JOB CONTROL LANGUAGE PARAMETERS xiii

CHAPTER 1

INTRODUCTION

1.1 THE SHOCK OF JCL

Your first use of JCL (Job Control Language) will be a shock. No doubt youhave used personal computers costing $500 or $1,000 that had wonderfullyhuman-engineered software, giving you an expectation of how easy it is touse a computer. Now, as you use a computer costing several million dollars,you may feel like a waif in a Dickens story standing in the shadow of a mas-sive mainframe computer saying meekly, “Please, sir, may I run my job?” Itwill come as a shock that its software is not wonderfully human engi-neered.

The hardware and software design of large IBM mainframe computersdate back to the days when Kennedy was president. JCL is a language thatmay be older than you are. It was designed at a time when user-friendlinesswas not even a gleam in the eye of its designers. This is easily demonstratedby taking the simple task of copying a file and contrasting how it is donethrough JCL with how it is done on the most popular personal computer system, Windows. To copy a file with Windows, you left-click twice on theMY COMPUTER icon, left-click on the C: drive icon, left-click twice on thefolder containing the file, and right-click on the file to copy. On the resultingmenu, you click on COPY and then left-click twice on the folder into whichyou want the file copied. Finally, you right-click inside the folder and selectPASTE from the menu and you are done. It is wonderfully intuitive andsimple. To do the same thing with JCL, you might write the following, inwhich old-name names the original file and new-name is the name youselect for the copy.

//RT452216 JOB (45992,335),'SAMPLE JOB',CLASS=A//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSUT1 DD DSN=old-name,DISP=SHR//SYSUT2 DD DSN=new-name,DISP=(NEW,CATLG),

1

// UNIT=SYSDA,RECFM=FB,LRECL=80,// SPACE=(0,(100,20))//SYSIN DD *REPRO INFILE(SYSUT1) OUTFILE(SYSUT2)/*

This is far more complicated and not remotely intuitive. But what if youmust copy 50 files? With JCL, you could use your text editor to quicklymake 50 copies of the JCL statements, and overtype all the old-names andnew-names. Then you simply submit the job to the computer, which is eas-ier than going through the Windows clicking and pointing procedure 50 times. Now suppose you must copy the same 50 files on a daily basis.Windows would be a nightmare, but with JCL, a single command lets youresubmit the lines of JCL that copy the 50 files.

Then the inevitable happens. Your boss comes in and, with an accusingeye, asks if you inadvertently forgot to copy a file the previous day. With thepointing and clicking of Windows, you would have no answer. By contrast,JCL produces a listing—an audit trail—that you can wave in your boss’sface to prove that the problem was not yours. The next day your bossinforms you that the copy procedure must be done during the graveyardshift. With Windows, your nights will be sleepless. But with JCL, you canspecify a job class that starts during the graveyard shift, leaving your nightsfree for more enjoyable activities.

What has just been described for JCL is the essence of batch processing(submitting one or many jobs or procedures in one fell swoop) and produc-tion computing. Interactive computing, such as that provided by Windows,Linux, Macintosh, and UNIX is wonderful for many things, but once thosewonderful things are completed and the daily grind of running them begins,JCL comes into its own.

JCL is neither lovable nor simple. It was designed long ago and showsits age in ways such as having to code information in specific columns of aline. However, IBM has made changes to both JCL and the operating systemthat eliminate some of its worst aspects.

The large mainframe computer is an extremely conservative environ-ment. The basic hardware architecture and operating system appear to theuser much as they did over a third of a century ago. The benefit of this isthat programs written back then can still run unchanged today, and knowl-edge gained back then is still valid. The greatest strength of large IBM main-frame computers, indeed, the strongest force in the computing universe, iscompatibility. Billions of dollars are tied up in application software, andmany companies would not accept an incompatible computer with moderndesign and software features even if it were free, because software is thedominating cost in computing, not hardware.

2 z/OS JOB CONTROL LANGUAGE

1.2 THE ROLE OF JCL

You do not use JCL to write computer programs. Instead, it consists of con-trol statements that introduce a computer job to the operating system, pro-vide accounting information, direct the operating system on what is to bedone, request hardware devices, and execute the job. JCL tells the operatingsystem everything it needs to know about a job’s input/output (I/O) require-ments. Sitting above JCL in many installations is a job entry system (JES)with a job entry control language (JECL). You code the JECL statements tospecify on which network computer to run the job, when to run the job, andwhere to send the resulting output. IBM provides two job entry systems forz/OS: JES2 for decentralized control, and JES3 for highly centralized con-trol of several computers. JCL and JES go hand in hand, and this book de-scribes both.

1.3 THE DIFFICULTY OF JCL

JCL provides the means of communicating between an application programand the operating system and computer hardware. Measured by the numberof moving parts, the z/OS operating system is one of humankind’s mostcomplex creations. The computer hardware is less complex, but complexnonetheless.

JCL is difficult because of the way it is used. A normal programminglanguage, however difficult, soon becomes familiar through constant usage.In contrast, JCL has language features used so infrequently that many neverbecome familiar. JCL is also difficult because of its design. It is not a proce-dural language like COBOL or C/C++ in which you build up complex appli-cations step by step from simple statements. JCL consists of individualparameters, each of which has an effect that may take pages to describe. JCLmakes few useful assumptions for you—you must tell it exactly what to do.For example, virtually every batch computer program prints some output.However, the system doesn’t assume this. You must supply a JCL statementto print output.

The z/OS operating system demands an extraordinary amount of in-formation, most of it supplied by JCL, to run a job. For example, to save afile on disk storage, the system wants to know the record type, the recordlength, the block size, the type of I/O unit, the volume serial number of thedisk volume, and more. (The recent changes to simplify JCL have been inthis area.)

JCL was designed at a time when people were relatively cheap and com-puters expensive. In 1965, one million computer instructions were roughly

INTRODUCTION 3

equivalent in cost to 15 minutes of a programmer’s time. Today the oppositeis true. People are expensive and computers are cheap. A million instruc-tions today buys less than a fraction of a millisecond of a programmer’stime. Consequently, JCL, designed to be efficient in computer time, is oper-ating today in an environment where the cost of a person’s time is the dom-inant expense. This book attempts to save you time—not just save computertime. Some of the worse things done in computing have been for efficiency.Saving two bytes in the year field is an extreme example that made the new millennium stressful for many. The cost performance of computerchips is still doubling roughly every 18 months, and while this can’t lastforever, it would be foolhardy to predict when it will end. This has a pro-found effect on how much effort a company wants to invest in optimizingprograms.

1.4 THE APPROACH TO JCL

The first several chapters of this book describe the individual languagestatements, tell how to write them, explain what they do, and suggest howto use them. With this as background, the book shifts to functional descrip-tions of the hardware devices, access methods, and other topics. Becauseyou rarely need many JCL features, the book notes whether a feature isESSENTIAL, SOMETIMES USED, or RARELY USED. You should pick andchoose.

The goal of this book is to give you all the information you need to pro-gram on z/OS, except for the programming language you use. To accomplishthis, the book goes far beyond JCL. The book introduces the concepts andfacilities of the operating system from the application programmer’s point ofview. Several non-JCL operating system facilities are also described, includ-ing IBM utility programs, the Sort/Merge program, the linkage editor, VSAM(Virtual Sequential Access Method), TSO/E (Time Sharing Option), andREXX (REstructured eXtended eXecutor).

This book explains JCL and shows you how to use it, but it won’t try tomake you like it because JCL is not a likable language. Almost no one, evenprogrammers with years of experience, can sit down and write JCL state-ments the way they could COBOL or C++ statements. Consequently, peoplewho write JCL generally know what they want to do and then consult someexisting JCL to use as a prototype to write the new JCL statements. The bookgives many short examples to serve as prototypes with the assumption thatshort, concise examples are preferable to lengthy explanations.

The book gives special attention to the use of JCL with COBOL, FORTRAN, PL/I, C/C++, and Assembler Language. Where appropriate, thebook describes their interfaces to JCL. The book is based on the z/OS ver-


TEAMFLY

Team-Fly®

sion of the operating system. Although IBM occasionally releases new ver-sions of z/OS, the new releases seldom change existing JCL.

If you are just learning z/OS, you can use this book as an introductionto the operating system and JCL, skipping over the RARELY USED, beingselective with the SOMETIMES USED, and concentrating on the ESSEN-TIAL features. The book presumes you have some familiarity with a higher-level language. If you are an experienced z/OS programmer, you can usethis book to learn unfamiliar JCL features or to refresh your memory on seldom-used features. Finally, the book serves as a reference for all whoprogram in z/OS.

For classroom usage, read Chapters 1 to 14 in sequence, working in theinstallation’s particular requirements. Then select topics from the remain-ing chapters as needed. Exercises at the end of many chapters consist ofshort, simple problems that can be run on a computer. They are designed asmuch to teach you about your installation and the problems of actually run-ning jobs as they are about JCL as a language.

JCL provides many abbreviations and alternate names for coding. Forsimplicity and to reduce errors, the book shows only one form, the shortest,except when the short form conveys no meaning (CANCEL rather than C) orthe long form is very short (NO rather than N). The book displays JCL state-ments and parameters in capital letters, with italics denoting items forwhich you select values. Text comments about a JCL statement are set off inbrackets beneath the statement:

//SYSUT1 DD DSN=new-name,DISP=NEW

[The new-name represents a name you choose for the file. Codeuppercase characters exactly as shown.]

INTRODUCTION 5

CHAPTER 2

INTRODUCTIONTO JCL AND z/OS

Essential

This chapter introduces z/OS concepts and vocabulary. You may be famil-iar with many of the concepts, but perhaps not in the z/OS context. Whilelarge mainframe computers have essentially the same hardware compo-nents as all other computers, including personal computers (PCs), the ter-minology differs. The formidable-sounding direct-access storage device (orDASD—pronounced daz-dee) on a mainframe becomes the more unassum-ing hard disk on a PC. Likewise, the impressive term data set on a main-frame turns out to be just a file on the PC.

The computer is essentially a device that reads some data, does somecomputing or processing, and writes some data. The main computer hard-ware that concerns you is illustrated in Figure 2.1 and consists of

� The CPU, or central processing unit. (Corresponding to a Pentiumchip on a PC.)

� Central storage—formerly called real storage, computer memory, andcore storage. (Corresponding to RAM, random access memory, on a PC.)

� Input/output (I/O) devices, often called peripherals, such as disks,tapes, and printers.

2.1 z/OS CONCEPTS AND VOCABULARY

The IBM Mainframe consists of a computer (the zSeries 900), an operatingsystem (z/OS), and a vocabulary. People who work on z/OS form a separateculture, and you need to understand the concepts and speak the language tobe accepted within the culture. Acronyms are the key to acceptancebecause everyone uses them, quickly forgetting what they represent.

6

2.1.1 The People

One difference between large IBM mainframes and smaller computers is the number of people required to support them. Computer operators run themainframe, schedule jobs, mount tapes, and distribute output. One of theadvantages of a large computer is that you don’t have to worry about hard-ware problems or paper jams—the operators do this.

System programmers on large IBM mainframe computers install, main-tain, and tune the operating system software. The software on large IBMmainframe computers is extremely complicated to install, and once in-stalled, is even more difficult to maintain and tune for good performance.System programmers are highly skilled and valuable—and aware of thisfact.

Installations usually have support staff to establish and enforce stan-dards and procedures for using the computer. The support staff must alsoprovide security, issue passwords and userids, and control access to thecomputer. Many installations also have a hot line or a help desk for answer-ing questions. The first thing to do in any installation is to find out whereto go for help.

INTRODUCTION TO JCL AND z/OS 7

FIGURE 2.1 A typical computer.

CPU

Centralstorage

Channel

Input/outputoperationsinterface

I/Odevicesor bus

CPU — The central processing unit executes instructions to perform computations, initiates input/output and directs the operation of the computer. It is the part of the computer that does the computing.

Central storage — The computer memory holds both the instructions and data during computations and is termed central storage or real storage. It corresponds to random access memory (RAM) on a PC.

I/O device — The input/output devices contain external data. A collection of data stored on an external device is called a data set or file. I/O devices consist of a recording device and access mechanism, a control unit (actually a small computer itself), and a channel or bus to transmit the data between the I/O device and the computer’s storage. The most popular I/O devices are disk, tape, and printer.

2.1.2 The Operating System (z/OS)

The z/OS operating system introduces programs to the computer, initiatestheir execution, and schedules all the resources and services they require,such as printers, central storage, and disk storage space. The operating sys-tem is made up of a general library of programs that can be tailored toaccommodate a variety of applications on a wide range of hardware config-urations. The system programmers select the portions that an installationneeds through a system-generating process (SYSGEN), add their own pro-cedures, and update the procedures as the needs change.

The programs and routines that comprise the operating system are clas-sified as either control or processing programs. Control programs performthe tasks of the operating system: reading, scheduling, initiating, allocating,executing, and terminating jobs in a continuous flow; supervising the dis-patching and service requests of all work in the system; storing and retriev-ing all the data; controlling the user of virtual, central, and expandedstorage; allocating the computer’s resources; and finally, recovery from sys-tem and hardware failures.

Processing programs consist of language translators (such as theCOBOL and C++ compilers), service programs (such as the linkage editorand sort programs), and application programs (such as the programs thatyou write.)

Batch versus On-LineThe original System/360 operating system was designed as a batch systemthat could run on-line jobs. This is in contrast to the PC, UNIX, andVM/ESA (the other popular system on large IBM mainframe computers),which were designed as on-line systems that could run batch jobs. With abatch system, you prepare a complete job and submit it to the computer.The computer’s operating system schedules the job and executes it at itsconvenience, which may be hours later. You have no control over the jobonce you submit it. Often you submit a job and then hours later, when youget your output, find that a minor JCL error caused the entire job not to run.(With JCL, there is no such thing as a minor error.) On-line or interactivejobs are submitted from your computer terminal and you stay at the termi-nal while the job runs, usually interacting with the job to supply necessaryinformation. You can quickly correct any errors.

Batch execution is great for long-running jobs, especially those run on aroutine basis—production jobs. They have several advantages over interac-tive jobs:

You needn’t wait at your terminal for your job to complete. You can goaway and come back later.


You can run the job off shift, when computer rates are usually lower.

You can set up a complex job once and then keep resubmitting it ratherthan having to retype all the run commands each time.

The job may run more efficiently because it doesn’t require the com-puter resources of an on-line job.

The computer can schedule the jobs at its convenience to make the mosteffective use of its hardware to maximize throughput.

Your program will produce an audit trail so you can reconstruct whathappened during the run.

Of course, there are also disadvantages to running jobs in batch withJCL:

You don’t get immediate turnaround, as a rule.

You must learn to use JCL.

If something goes wrong while a job is running, you don’t get a chanceto correct it and continue.

You must set the entire job up in advance, anticipating all the contin-gencies. You can’t play it by ear.

You don’t get to interact with the job and enter data and directionswhile it is running.

On-line is great for jobs requiring interaction while the job runs, jobsthat change frequently, and jobs requiring quick turnaround. In practice,on-line is usually used for program development, data entry, inquiry, andquick response, whereas batch is used for production runs once the pro-grams are developed.

Since many jobs are run concurrently on a mainframe computer, theresources of the computer must be shared so that each job eventually getsthe resources it needs. This is done by multiprogramming and time-sharing.

Time-Sharing and MultiprogrammingTime-sharing allows many people to use a computer simultaneously insuch a way that each is unaware that others are using the computer. Theusual case is an on-line system with several consoles using the main com-puter at the same time. Time-sharing attempts to maximize an individual’suse of the computer, not the efficiency of the computer itself. Time-sharingis supported on z/OS by such systems as the TSO/E (Time-Sharing Option),CICS (Customer Information Control System), IMS (Information Manage-ment System/Virtual Storage), VTAM (Virtual Telecommunications AccessMethod), and UNIX and Linux.


Multiprogramming is just the opposite of time-sharing in concept. Itattempts to maximize the efficiency of the computer by keeping all themajor components busy, such as the CPU, I/O devices, and central storage.Most jobs running on a large general-purpose computer do not use all theI/O devices or storage. Moreover, not all of the CPU is used since time isspent waiting for some I/O action to complete. Rewinding a tape is anextreme case in point.

Since most jobs do not use all of the storage, all of the I/O devices, or allof the CPU, a multiprogramming system can keep several jobs inside thecomputer at the same time and switch back and forth between them. Sev-eral jobs are loaded into storage and the operating system gives control toone job. It then switches control to another whenever one becomes idle. Bybalancing I/O-bound jobs with the compute-bound jobs, several jobs can becompleted in little more time than it would take to complete a single job.

2.2 z/OS HARDWARE ARCHITECTURE

Perhaps the best way to understand the architecture is to trace its individualcomponents to see why they were added. z/OS has evolved over the pastthird of century, and while not elegant or simple, it is eminently practical.

2.2.1 The 1960s and the Quest for Multiprogramming: MVT

Before the introduction of System/360 (z/OS’s ancestor) in 1964, IBM com-puters ran a single program at a time. Business and scientific applicationsused different computers with different instruction sets and operating sys-tems. Different-sized computers also had their own instruction sets andoperating systems. System/360 gave all IBM mainframes the same hardwarearchitecture so that applications could run independent of a particular com-puter model. The System/360 ancestor of today’s operating system, MVT(Multiprogramming with Variable Tasks), could run a maximum of 15 jobsconcurrently in the same central storage. The programs were placed in vari-able-sized areas called regions as shown in Figure 2.2. The computer used24 bits for addressing, and so could address 16MB of memory or central stor-age. (The amount of storage that a computer can address is termed itsaddress space, which is determined by the number of bits used to form anaddress. The address space size is calculated by the number of bits raised tothe power of 2, so that 15 bits gives a 215 = 32,768 address space.) However,memory was so expensive that a 512K machine was considered large.

Multiprogramming added immensely to the complexity of the operatingsystem. The system had to protect each job in storage from other jobs. Thiswas implemented through a hardware feature called storage protection in


which each region could change data only in its own region, protectingother regions and the operating system. The system also had to dole out thecomputer’s resources so that the mixture of jobs in storage did not contendfor nonshareable resources, such as tape drives. (PCs went through this bar-rier when Windows replaced MS-DOS.) The system had to hold back a jobif it needed an unavailable resource and schedule another job whoseresource requirements could be met.

The fact that the large mainframe computer was shared was a major rea-son it became so complex and difficult to use. Files and applications werepotentially accessed by hundreds of users, making security a critical issue.If the mainframe crashed, hundreds of people could be affected, and inmany cases, prolonged downtime could destroy a company. The main-frame, by necessity, became a serious environment.

The system, since it scheduled jobs based on their resource require-ments, had to be told what resources each job needed. This was (and still is)done with JCL statements. For example, if a job needed a tape, a JCL state-ment had to describe the tape unit needed. The system would not schedulethe job until such a tape unit became available. This prevented the job fromsitting idle in central storage waiting for an available tape unit.

Figure 2.3 illustrates the original MVT multiprogramming system. Eachjob occupied a contiguous region in central storage, and the jobs remainedthere until they were complete. Users specified their region size with JCLstatements. Some regions, such as the readers or writers, never completedand were always resident. The system decided which region to run and forhow long and was made as crashproof as possible so that, although a par-ticular job might fail, the system was not disturbed. This continues today,


FIGURE 2.2 Central storage in MVT.

Program 1

Resident portion ofthe operating system

This area istermed a region

The CPU executes instructions forone program, then quickly switchesto another program and executesinstructions for it.

Program 2

Program 3

Program 4

Program 5

•

Program N

and much of the expense of the mainframe is in hardware and softwaredesigned to isolate problems and speed recovery. One of the advantages ofz/OS as an old system is that most of the bugs have been shaken out and itis extremely reliable. (But not bugfree. Nothing as complex as an operatingsystem is without bugs.)

The first region contained the nucleus or resident portion of the operat-ing system (those portions of the system not kept on a direct-access storagedevice). The reader/interpreter (or reader) read in jobs and queued them ona direct-access volume. The term volume referred to a specific storage unitsuch as a direct-access storage volume or a tape cartridge. A direct-accessstorage volume was usually a disk pack—a large version of the hard disk ona PC. The writers wrote output from the queue on the direct-access volumeonto the proper output device. Queuing the input and output on direct-access volumes was called spooling, which you might equate to the take-upreel of a movie projector. Spooling was an acronym for simultaneousperipheral operation on-line; one of those rare cases where an acronymconveys more meaning than that for which it stands. The sequence of linesread by the reader was called the input stream, and the sequence of outputwritten by the writers was called the output stream.

The unit record devices (printers, and, back then but never today, cardreaders and cardpunches) were normally assigned to the readers and writ-ers. All other I/O units except tapes could be concurrently used by any ofthe regions. The system could assign a tape unit to only one region at a time.


FIGURE 2.3 MVT multiprogramming system.

Printer

Printer Writer

Printer Writer

Regions

Resident system

Direct-accessstorage device

Direct-accessstorage device

Reader/interpreter

15 regions maximum

Writer

This was one reason for using direct-access storage devices—the jobs werenot kept waiting for a tape unit to become free.

To capsulate the operating system: The reader/interpreter read jobs fromthe input stream and queued them on a direct-access volume. When a jobcame to the top of its queue, a system program called the initiator/termina-tor loaded it into a region and executed it. If the job read data from the inputstream, the system fetched the lines from a direct-access volume where theyhad been stored. If the job printed output, this output was again queued ona direct-access volume. A job never printed directly—it was all done byqueuing on a direct-access volume. The job was not aware of this becausethe system did it automatically. After the output was queued on a direct-access volume, the writers wrote it out to the appropriate output device. Fig-ure 2.4 illustrates how spooling worked. All of this holds true today, exceptthat users often examine their output on-line through a terminal while theoutput is in the output queue, and then decide whether to discard or print it.Although the running of a single region has been described here, severalregions could be kept running concurrently in a similar manner.

Multiprogramming, which divided the computer’s central storage intoregions, presented several problems. A job was limited to the size of thelargest region, and inevitably, some applications needed more central stor-age to run than the computer had. Central storage was often wasted when itbecame fragmented because jobs could only be run in contiguous storage.

Two applications aggravated these problems, time-sharing and telepro-cessing. Time-sharing gave many people access to a computer at the sametime with fast response required for each. Teleprocessing connected remotedevices to the main computer through communication lines. The applica-


FIGURE 2.4 Spooling.

Printer

Program 1“prints” lines

Program 2“prints” lines

Data set to print

Disk

Data set to print

Print queue is sent to printer

tions were often real time as typified by an airline reservations system inwhich an agent at a remote location reserved a seat on an airliner by com-municating with the central computer. Time-sharing and teleprocessingapplications were both characterized by long periods of inactivity and thenbrief spurts of frenzied activity requiring fast response.

Because the MVT was a batch system, on-line systems had to be devel-oped that would run under its control in a region. Even today, such on-linesystems as TSO/E, CICS, and VTAM are executed as batch jobs through JCLstatements, and once running in their region, they begin supporting themany on-line users as illustrated in Figure 2.5.

2.2.2 The 1970s and the Quest for Central Storage: OS/VS2 and MVS/370

By the 1970s, the amount of central storage became a critical bottleneck.The operating system provided for 15 concurrent users, but there wasn’tenough central storage for more than a few to reside in the computer at thesame time. Central storage was still extremely expensive.

In 1972, IBM introduced the 370 family of computers with new cir-cuitry that included a major architectural component called virtual storage.With virtual storage, the storage addresses of an application program weremade independent of the addresses of the computer’s central storage. The


FIGURE 2.5 On-line system supporting many users.

CICSregion 1

Terminals

CICSregion 2

TSOregion 3

CICSregion 4

•••

Nucleus

Controller

TEAMFLY

Team-Fly®

program, still limited to 16MB, was stored on disk (virtual storage), and thesystem brought small portions of the program into central storage ondemand. A hardware feature was added to translate the user’s virtual stor-age addresses to the computer’s central storage addresses during execution.The MVT operating system was renamed OS/VS2 (Operating System/Vir-tual Storage 2), and it could operate as if it had the maximum of 16MB ofcentral storage when in fact the actual amount might be (and generally was)considerably smaller. Each region residing in virtual storage could also be amaximum of 16MB, including space occupied by the operating system, butthe total for all regions was limited to 16MB as illustrated in Figure 2.6.

One of the limitations in any computer is the amount of storage it canaddress—its address space. The IBM mainframe was a 32-bit computer.However, it used only 24 bits to contain addresses, and the maximum sizeof the address space was 224 or roughly 16 million (MB) bytes.

Sixteen million bytes of address space seemed like a lot of memory backwhen the typical computer had only 512K of memory. A thousand bytes ofmemory—actually 1,024 bytes—is called a kilobyte and abbreviated as K.The 1,024 is used because it is a power of two. A million bytes is termed a


FIGURE 2.6 OS/VS2 with virtual storage.

Region 15

Virtual storagein OS/VS2

Region 14

Region 13

•••

Region 3

Region 4

Region 2

Region 1

Nucleus ofoperating system0MB

16MB

Physical storagein OS/VS2

0MB

16MBmax

Actualstorage

••••••

••••••

Centralstorage

megabyte or just a meg and abbreviated as MB. A billion bytes are termed agigabyte or just a gig, abbreviated as GB. But application programs keptgrowing. Also, the operating system required a portion of the application’sprogram address space, and less address space became available as theoperating system grew to where little more than 8MB was available to anapplication program. Programs also grew larger. Finally, applications suchas CICS, IMS, VTAM, and DB2 required huge amounts of address space forbuffers. Even worse, some, such as CICS, were designed to run all of theiron-line applications in the same address space.

Virtual storage relieved much of this problem. When a program beganexecution, the system first loaded it onto a direct-access volume—the vir-tual storage—rather than directly into the computer’s memory, or centralstorage. The system divided the application program into small parts calledpages. Central storage was likewise divided into parts termed page framesto contain the pages on the direct-access volume. A paging supervisor in theoperating system loaded each page from the direct-access volume into cen-tral storage on demand as illustrated in Figure 2.7. Thus, large portions ofan application program might reside on a direct-access volume, the exter-nal paging storage, rather than in central storage at any given time duringexecution. The implications of this were twofold: the size of the programcould exceed that of central storage, and inactive portions of programswasted little central storage.

When the hardware detected a reference to a virtual storage address ofa page not in central storage, it notified the paging supervisor, an event


FIGURE 2.7 Virtual paging hardware.

Hardware translatesvirtual addresses to makeit appear to program as

if the pages are incontiguous central storage

Pagingstorage

Region divided intopages contains an

application program

Pages incentral storage

Paging supervisor

Residentnucleus

termed a page break. The paging supervisor looked around in central stor-age for a free page frame in which to load the page. If it found no free pageframe, it looked for an inactive page in central storage to swap out.

With virtual storage, a program need occupy only a relatively smallamount of central storage. This let programs run whose size exceeded thecentral storage available on the computer. It had another important benefitin that it allowed a larger number of programs to be run on the computer atthe same time, although there was still a limit of 15. Only the virtual stor-age (disk) needed to contain an entire program while it was executing. Vir-tual storage remains an inherent part of z/OS today.

In 1974, IBM changed the name of the operating system to MVS/370(Multiple Virtual Storage/370). It also scraped together two additional bitsfor addressing. With 26-bit addressing, the address space increased to64MB. Central storage could be 64MB, the sum total of all concurrent pro-grams in virtual storage could be 128MB, but individual programs were stilllimited to 16MB. MVS/370 also eliminated the restriction of 15 concurrentregions maximum. Figure 2.8 illustrates MVS/370.

By the end of the 1970s, another bottleneck appeared. Virtual storageallowed the computer to think it had a very large storage, but the 16MB


FIGURE 2.8 MVS/370 Virtual storage and regions.

Physicalstorage

Virtualstorage

Centralstorage

0MB

64MBmax

128MB max

Userarea

(region)

Commonarea

0MB

16MBper

addressspace

Actualhardwarestorage

installed

••••••

••••••

Systemarea

12

34

••••n

maximum for individual programs and 128MB limit for all programs in vir-tual storage became a problem. Programs were now sharing data, and theshared data was placed in a common area that came out of a program’saddress space, as did the nucleus of the operating system. (Considering that16MB today is insufficient for one user in Windows, this was a severe lim-itation indeed.)

2.2.3 The 1980s and the Quest for Address Space: MVS/XA and MVS/ESA

In 1983, IBM introduced the successor to MVS/370 and called it System/370-XA (System/370-Extended Address) to reflect the computer’s ability tonow use 31 bits for addressing, which provided 2GB of address space.Although central storage could in theory be 2GB, XA supported only a256MB central storage. However, applications residing in virtual storagecould address 2GB as shown in Figure 2.9.


FIGURE 2.9 MVS/XA storage.

Physicalstorage

Virtualstorage

Centralstorage

0MB

2GBmax

Userarea

Commonarea

Extendedcommon

area

Extendeduser area

0MB

2GBper

addressspace

256MBactualmax

16MB

••••••

••••••

Systemarea

12

34

••••n

Increasing the address space from 26 to 31 bits required changing boththe hardware and the format of the computer’s instructions. For compati-bility, old programs could be marked to run in the 16MB address spacemode, whereas new programs could use the entire 2GB address space. Pro-grams that exceeded the 16MB address space were termed above the line.This could occur in two ways. First, a program could require more than16MB in which to run. This would be a very large program and was rare.Second, and far more common, were CICS applications. In CICS, all theapplications had to run in the same address space, and so even a small pro-gram could be forced above the 16MB line because of other applicationsloaded into storage below it, as depicted in Figure 2.10.

Users had to set special parameters during compilation and linkageediting for a program to run above the 16MB line. But if one didn’t writevery large programs or CICS programs, one generally didn’t have to worryabout it.

MVS/XA fulfilled the address space need for the large IBM mainframefor only a few years. As very large database applications were developed,address space again became a bottleneck. In response to this, IBM enhancedthe operating system again in 1985 and renamed it MVS/ESA (EnterpriseSystems Architecture). MVS/ESA allowed central storage to be as large as2GB. Like MVS/XA, it also permitted an application to have a 2GB addressspace, but additionally permitted the same application to have multiple2GB address spaces as illustrated in Figure 2.11.

MVS/ESA not only provided a larger effective address space, it alsoallowed huge applications to be segregated into functional parts. This espe-cially benefited CICS because now each on-line application’s data could beplaced in a separate segment so that one application could no longer clob-ber another’s data. Before this, CICS couldn’t be impacted by a non-CICS job


FIGURE 2.10 Jobs “above the line.”

24MBProgram

Very largejob abovethe 16MB line

Small job abovethe 16MB linein CICS

0

24MB

0

20MB

14MB

8MB

16MB line

6MBProgram

6MB

Program

8MBProgram

and vice versa, but one CICS application could take down the entire CICSsystem. MVS/ESA solved this problem first by allowing each CICS applica-tion to have its own data space. It then implemented subsystem storage pro-tection to protect system code, control blocks, and data areas within thesame region. With this, one CICS user could not take down another CICSuser or the CICS system.

In MVS/ESA, the first address space was called the application space,and programs had to execute in it. The extended storage of the otheraddress spaces were called data spaces and, as their name implies, couldcontain only data. They could contain a program as a file of data, but the


FIGURE 2.11 MVS/ESA storage.

Physicalstorage

Virtual storage

Centralstorage

0MB

2GBmax

Userarea

Addressspace

Commonarea

Extendedcommon

area

Extendeduser area

User 1

0MB

2GBper

addressspace

16MB

••••••

••••••

Systemarea

12

…n

•••1

2…

n

12

…n

User 2

User n

program could not be executed in a data space. The system had to copy it tothe application space to execute it. The operating system didn’t take up anypart of the data space, so each data space had the full 2GB available for data.The data space was byte addressable, resided in virtual storage for the dura-tion of a job, and was used as a logical extension of the address space forcontaining large tables, databases, and buffers.

MVS/ESA also added a facility called Hiperspaces, which allowed tem-porary data to be stored or retrieved in 4K blocks under program control,using the fast paging hardware of the computer. An application programcould create a hyperspace as an alternative to storing temporary data sets ondisk. The system moved the data from the hyperspace in 4K blocks into theapplication space for the application program to use the data.

2.2.4 The 1990s and the Quest for Capacity: OS/390

With MVS/ESA, the mainframe was well suited for large applications.Meanwhile, the PC had become dominate for small applications. PCs grewin CPU speed, central storage, and disk space. The mainframe had alwaysmaintained a large edge in speed over the PC, partly because it used a bipo-lar technology in its chips in which power was permanently applied to savetime in executing a logical operation. But by the early 1990s, bipolar tech-nology hit a wall. The chips generated large quantities of heat, and evenwith air conditioning and water cooling, heat could not be dissipated fastenough to allow circuits to be packed closer together. Consequently, IBMbegan switching to CMOS (Complementary Metal Oxide Semiconductor)technology, long used in PCs. In CMOS technology, power was applied onlyduring an actual logical operation, generating less heat and consuming lesselectricity. This not only saved money, but also made battery backup morepractical as a guard against power outages. CMOS technology had beenslowly gaining on bipolar technology to where today, it exceeds it.

One of the consequences of the bipolar limits and the switch to CMOSwas that the mainframe CPU lost its speed advantage over the PC. Size con-veys no speed advantage in computers because with chips, smaller is faster.In fact, OS/390 is at a disadvantage because of its large, robust instructionset, and many smaller computers achieve their high speeds by reducingtheir instruction sets (RISC, reduced instruction set computers).

Central storage became so inexpensive on the PC that 128MB is consid-ered average. Hard disks grew to where 40GB is common. How was a poormainframe to compete against such a PC that cost only a few hundred dol-lars? Why not connect the PCs into a network; write some software toschedule applications, share data, and handle security; and scrap the main-frame? Some installations did this, only to discover that at great time andexpense, they had reinvented the mainframe.


The mainframe cannot compete with the PC in interactivity. An indi-vidual PC may or may not be as fast as the CPU of mainframe, but it servesonly one user whereas the mainframe serves many. Unused CPU cycles ona PC are valueless, so no one begrudges that PC systems devote most of theirCPU cycles to screen savers.

What then was the role of the mainframe? It seemed as if the commentsmade back in the 1950s by T. J. Watson, Sr., the founder of IBM, that therewould be a need for no more than a dozen or so large computers to handlethe world’s needs might indeed be prophetic.

However, there was less to all this than met the eye. Mainframes con-tinued to be as busy as ever and IBM continued to sell as many as ever. Thereason for this is threefold. First, many old applications are still running onthe mainframe that would be expensive and impractical to migrate to thePC. Second, the mainframe is superb at what it does best: process vastamounts of data. When performance is measured in throughput (processingtransactions, large databases), the PC cannot touch the mainframe. Whenthere is no throughput and performance is measured by interactivity (wordprocessing, spreadsheets, small databases, and graphics), the mainframecannot touch the PC. The mainframe’s high-speed channels, high-capacityI/O devices, its large address space, the reliability of the hardware and thesoftware, its backup procedures and standards, and its software tools forhandling databases all permit the mainframe to tackle applications involv-ing large amounts of data that would be impractical on a PC. Such applica-tions are also the life stream of many corporations.

The third is, of course, the Internet. Since the Internet provides accessto data and most of the data is on a mainframe, mainframes quickly evolvedinto servers on the Internet. The IBM mainframe also supports UNIX withits z/OS UNIX System Services, and can also support hundreds of Linuximages running open source applications. And it runs everything concur-rently in one system.

There is another thing that the IBM mainframes do very well that wedon’t often think about. They are secure systems. Security was an inher-ent part of the system design, not something recently added. While thishas been important in the past, it is likely to become the overriding con-sideration for future computer systems as we plunge into an informationeconomy. Aside from issues of privacy, trillions of dollars move over theelectronic highways in a hostile environment in which many people withmany motivations, ranging from teenage hackers to disgruntled employ-ees to terrorists to sophisticated crooks, stand ready to attack our com-puter systems.

Since individual CPUs were limited in speed, IBM developed the Par-allel Sysplex (System Complex) to interconnect multiple systems withhigh-speed fiber optics so that they act as if they were a single logical entity.


Individual processors (one or more CPUs operating on the same storage)could be dynamically connected and disconnected into the Sysplex with-out stopping systems operations for both hardware and software updatesand maintenance. Even new processors could be added without bringingdown the system.

The Parallel Sysplex also provided for shared data in which separateservers in a client/server environment share the same image of both theoperating system and user data. This permitted multiple users connectedto multiple servers to operate on the same database. It was the opposite ofdistributed data systems in which different portions of the database weresent to different servers, and different than partitioned data systems inwhich multiple servers could each access different portions of a database.Shared data also allowed work to be balanced across multiple processors.The processors could share the same libraries for ease of maintenanceand reduced cost.

As shown in Figure 2.12, OS/390 computers could also have multipleCPUs that operated on the same processor storage, so that when the CPUran out of gas, the installation could add another. In addition, multipleprocessors could be configured as n-way multiprocessors in which two ormore individual processors could either act as one large computer system


FIGURE 2.12 Multiple CPUs.

Centralstorage

Expandedstorage

2nd-levelbuffer

Systemcontrol

unit

Interconnectcommunications

element

Channelcontrolelement

I/O devices

CPU 1

CPU 2

CPU 3

CPU 4

or be physically partitioned into two independent operating systems thatshared a single mechanical frame. The partitions (now called LPARS, logi-cal partitions) might run different operating systems or different versions ofthe operating system, or hardware and software maintenance might be per-formed on one without affecting the other, as illustrated in Figure 2.13.

DASD was also changed. Large disk drives still abounded, but IBM also provided the RAMAC disk storage based on RAID technology. RAID(Redundant Array of Independent Disks) groups several smaller hard disksinto a single unit. Data can then be stored sequentially in strips across theseveral individual disks rather than continuously on one disk to reduceaccess time. The hard disks are essentially those found on a PC. Because aRAID device has more disk units, there is more potential for hardware error.This is minimized by three levels of parity written onto a separate disk toallow all the data in an entire disk to be recovered, should it be lost. (Theconcept of parity is simple. If you stored the number 45 on one hard diskand the number 23 on another, the system could write the sum, 68, on theparity disk. Then if the number were lost on any one of the disks, the sys-tem could recover it from the other two.) All this enabled individual disksto be hot-plugged in a RAMAC unit without bringing the system down.


FIGURE 2.13 N-way multiprocessor.

Expandedstorage

Centralstorage

Systemcontrolelement

CPU 1


CPU 3

CPU 5

Expandedstorage

Centralstorage

Systemcontrolelement

CPU 2

CPU 4

CPU 6


TEAMFLY

Team-Fly®

And finally, IBM provided for concurrent copy when writing to DASDin which the hardware simultaneously writes to a second I/O device (disk,tape, or optical storage), which, with fiber-optic cables, could be locatedmany miles away for off-site backup.

2.2.5 The 21st Century and Back to Basics

IBM made every change possible to squeeze the maximum address spaceout of a 32-bit computer. The changes worked, but they were not clean andwhile clever, things like extended storage were a bit of a kludge. With z/Osin 2001, IBM solved the address space problem with a simple, straightfor-ward change. They made it a 64-bit computer with a 64-bit address spacefor both virtual and real storage. To visualize this, the maximum 31-bitaddress space was 2,147,483,648 bytes. With 64-bit addressing, you doublethis. Then you double it again. And again. Double it 33 times for the 64-bitaddress space. For compatibility, z/OS can still operate in the old 24- or31-bit addressing modes, but native 64-bit addressing is the future. Severalnew machine instructions were added for 64-bit operations and data.Despite this major change, you as an application programmer, unless youare writing an assembler language program with 64-bit integer arithmetic,will see no change. Your programs and your applications run as theyalways did. The system merely processes them faster.

For the mainframe in which there was once a single CPU, limited mem-ory, and channels hard wired to I/O devices, z/OS has multiple CPUs, largememory, and multiple channels connected together in a three dimensionalmatrix. One or more CPUs can be assigned to an application’s memory (anLPAR) based on demand that might change during the day. Channels can beswitched among I/O devices based on I/O activity, with multiple channelseven assigned to a single I/O device. The system monitors itself to make thechanges automatically. Not only can the computer dynamically reconfigureitself as demand changes, its different components can be taken off line,repaired, or replaced while the computer is running.

For security, IBM has long provided RACF (Resource Access ControlFacility) that protects data with passwords. z/OS added ICRF (IntegratedCryptographic Service Feature) in which new hardware instructions encryptand decrypt information at high speeds for additional security. z/OS alsoadded hardware to compress and decompress data as it leaves or entersprocessor storage, reducing the I/O load and storage space requirements.

And finally, z/OS interacts with other computers (mainly those runningUNIX and Linux) using industry standards, and runs UNIX and Linuxapplications on z/OS.


2.3 COMPUTER DATA

A program, while executing, may read data from tapes or direct-access stor-age devices and write output to the printer, tapes, or direct-access storagedevices.

2.3.1 Forms of Computer Data

Computer data consists of bits, bytes, and words. A bit is a single binarydigit, 0 or 1. Think of it as a light switch that can have two values: on andoff. A byte is the minimal addressable element in z/OS and consists of eightbits. All storage sizes and capacities in z/OS are expressed in bytes. It is alsothe amount of storage required to contain a single character, such as an A,B, C, etc. A word is 32 bits, or 4 bytes, or the amount of storage containing asingle-precision integer or real number.

Since it is very cumbersome to write binary numbers (a byte containinga binary 1 is written as 00000001), hexadecimal (base 16) notation is used.A hexadecimal digit occupies four bits, and two hexadecimal digits equalone byte. The binary equivalents of the hexadecimal digits are shown inTable 2.1.

For example, we would represent the binary digits 1111000011011011as F0DB in hexadecimal, which saves space and reduces the chance forerror in copying the number. Hexadecimal notation is used to representbinary data.

Eight bits represent a character so that one character is contained in abyte. The Extended-Binary-Coded-Decimal-Interchange Code (EBCDIC) isused in z/OS to represent the characters internally in the computer. Thecharacters are subdivided into several subsets, which vary, depending onthe context. JCL defines alphanumeric characters as A to Z and 0 to 9;national characters as @, $, and #; and special characters as blank , . / ’) (*& + − =.


TABLE 2.1 Binary Equivalents of Hexadecimal Digits

Binary Hex Decimal Binary Hex Decimal

0000 0 0 1000 8 80001 1 1 1001 9 90010 2 2 1010 A 100011 3 3 1011 B 110100 4 4 1100 C 120101 5 5 1101 D 130110 6 6 1110 E 140111 7 7 1111 F 15

The EBCDIC character set on IBM mainframe computers is differentfrom the ASCII (American Standard Character Code for Information Inter-change) character set that is standard on most other computers, includingPCs. The binary codes are different, as are many of the special characters,and even the collating sequences. z/OS also supports ASCII so that UNIXand Linux applications can operate with ASCII data. z/OS can convertASCII to EBCDIC and back, but some of the special characters get lost in theprocess. Some common characters do not convert to their equivalent asshown in Table 2.2.

The square brackets in ASCII ([]) are especially unfortunate for C/C++programmers because they are used for subscripts. The ASCII/EBCDIC sortsequences are also different (the characters sort into a different order), mak-ing the incompatibility between ASCII and EBCDIC a serious problem.

z/OS stores numeric data in four formats:

Character data. Each byte contains a digit. Data is converted to thisform for display and printing. To perform arithmetic on characterdata, it must be converted to one of the following forms.

Packed-decimal data. Each digit is stored in a half-byte (4 bits), with amaximum of 18 digits of data. For signed numbers, half a byte isreserved for the sign. This data is mainly used for business applica-tions in which data must be precise to the penny. z/OS has hard-ware instructions to do arithmetic directly on this form of data.

Binary data. The data is stored in half-word (maximum value of32,767) or full word (maximum value of 2,147,483,647) and consistsof a stream of binary digits. Binary data is especially convenient forinteger data. Arithmetic operations are performed in the general-purpose registers and are very fast.

Floating-point data. The data is stored in two parts: the significantdigits of the number and an exponent that determines the magni-tude of the number. Floating point is single precision (6 significantdigits) or double precision (16 significant digits). Values can rangein magnitude from 10−78 to 10+75. This form of data is important for


TABLE 2.2 ASCII/EBCDIC Problem Characters

ASCII EBCDIC

! |[ ¢] !^ ¬

scientific applications in which operations are performed on a widerange of data values. Arithmetic operations are performed in thefloating-point registers and are quite fast.

2.3.2 Data Records

Tokenized or Delimited DataA logical unit of related data is termed a record. A record on z/OS is unlikethat data on a PC or in UNIX. Typically, those systems use some character(token), such as a space or a comma, to separate the items of data (tokenizethem), and the data is transmitted as a stream. For example, typical datamight be as follows in which a comma delimits the items of data. (This istermed comma delimited data.)

Smith,John,102 Oak Street,Los Angeles,CA,90020-1629,10000Jones,Mary,77 6th Street,New York,NY,80010-0827,15000

The problem with tokenized data is that it might contain the delimitercharacter. If the 10000 were written as 10,000, it would mess things up.Tokenized data is less efficient to process. The computer must scan downthe line looking for the delimiter character to find where a data item beginsand ends. The 10000 is a number recorded in character form, and the com-puter must convert this to its binary equivalent to do arithmetic on it. (Youcan’t use a delimiter character for binary data because binary data might beany combination of bits, including that of any delimiter you might choose.)

z/OS RecordsAlthough z/OS can and does process tokenized data, z/OS data is usuallyorganized into record form. Rather than separating the items of data with acharacter, each data field is stored in fixed column positions like this:

Smith John 102 Oak Street Los Angeles CA90020-1629 1001110001000Jones Mary 77 6th Street New York NY90020-0827 1110101001100

Notice that the 10000 and 15000 are stored as binary numbers, andwould take either half or a full word of storage. The zip codes, since theydon’t participate in arithmetic operations, are stored as character data. Theadvantage of data in record form is that it is faster to process because thelength of each data item is known and numeric data need not be convertedfrom character to binary. No character need be reserved as the delimitercharacter. The disadvantage of record data is that you must decide howwide to make a field, not an easy matter for names and addresses, and it isrelatively difficult to widen a field or insert a new field in the data. This is


one reason it is difficult to expand a two-digit year to four digits to solve theyear 2000 problem.

Types of RecordsA record may consist of any number of bytes; for example, a payroll recordmight be all the payroll data relating to an individual such as name, salary,and exemptions. The words record and logical record are used inter-changeably.

z/OS records have three forms: fixed, variable, and undefined. Fixedrecords are all of the same length. This works well when you know howmany fields there are and the maximum width of each field. It can be waste-ful in storage space when a field can have a wide range of width because allrecords must be the maximum width of the longest record.

Variable records have varying lengths, with the first four bytes of therecord specifying the record length. For example, a personnel file contain-ing employee information might have variable-length records because dif-ferent information might be retained for each person.

Undefined records have varying lengths, but the record length is notcontained in the record. Records are separated by a physical gap on the stor-age device called an interblock gap (IBG). The computer is able to sense thisgap when transmitting a record and thus can distinguish between records.Undefined-length records are used where there is no predetermined unit ofdata, such as a line sent from a terminal. They are also used for tokenizeddata.

Blocking DataData is transferred between storage and I/O devices in blocks; each blockseparated by an interblock gap. Several fixed- or variable-length recordsmay be contained in a single block; an undefined-length record is equiva-lent to a block. A block then consists of one or more records to be transmit-ted at a time. Fixed-length records can be processed slightly faster thanvariable-length records because they are easier to block and unblock. In ablock containing variable-length records, the first four bytes specify thenumber of bytes in the block.

Data can be transmitted very quickly (over 6.5 million bytes per second)between storage and a direct-access volume or tape once the transmissionof data actually begins. However, it may take quite long (more than 10 mil-liseconds) to start the transmission because of mechanical inertia, time toposition the access mechanism, and the rotation time of the direct-accessvolume. Blocking allows large, efficient groups of data to be transmitted atone time. It is rather like filling an airliner with people and flying them allcoast to coast rather than flying them one person at a time. Blocking further


conserves storage space on the volume by limiting the number of interblockgaps.

The number of records per block is called the blocking factor. A block issometimes called a physical record, but this term is easily confused withlogical record. Blocking is done only for hardware efficiency and is unre-lated to the way you want to process your data. The system usually does allblocking and unblocking and determines the appropriate block size to usefor an I/O device.

A block of data is read into an area of storage called a buffer. When thelast record of a block is processed, the system reads in another block. Thereverse occurs when data is written. The system uses several internalbuffers so that while a program is processing data in one buffer, the systemis reading the next block of data into another buffer. This increases effi-ciency since I/O is overlapped; that is, data is read or written simultane-ously with computations being done in the computer.

Data sets must be opened before they can be used and closed after pro-cessing is completed. When a data set is opened, the system creates all the internal tables needed to keep track of the I/O, allocates storage for thebuffers, positions the data set to the starting point, and generally readies thedata set for processing. Closing a data set releases all buffers and tables asso-ciated with the data set, frees any tape drive used, releases temporarydirect-access storage, and generally cleans up after processing the data set.

Access TechniquesAn access technique is a method of moving data between central storageand an I/O device. Two ways of reading or writing are provided in z/OS,basic and queued. In the basic access technique, a read or write commandstarts the transfer between central storage and the I/O device. Since I/Ooperations are overlapped, the program can continue execution while theI/O action completes. It is the user’s responsibility to provide buffers and tosynchronize the I/O (that is, detect that a buffer is completely written beforemoving more data into it). The basic technique gives relatively completecontrol over I/O, but it requires more effort to use, and is rarely used.

In the queued access technique, the system does all buffering and syn-chronization. The program gets or puts a record and the system does all theI/O, buffering, blocking, and deblocking. The queued access technique isthe easiest to use, is provided in all languages, and is usually used.

Data Set OrganizationAny named collection of data (source modules, object modules, or data) is called a data set. The words data set and file are synonymous. Data set


organization can be sequential, partitioned, direct, or key-sequenced. Tounderstand the difference, visualize several decks of cards. Sequentialorganization consists of stacking the decks one on top of the other and pro-cessing the cards one at a time in the order in which they appear in thestack. Tape, the printer, and direct-access storage devices can containsequential data sets. Sequential organization is most appropriate when thedata set is processed in the order in which it is stored. A payroll file inwhich all employee records are processed is an example. Figure 2.14 illus-trates sequential organization.

If you leave the card decks in separate stacks, you could pick up a par-ticular deck and process it by reading it sequentially. This partitioned orga-nization, where the individual card decks are called members, is used mostoften for subroutine and program libraries since one subroutine or program(member) can be selected or replaced without disturbing the others. Youcan process a partitioned data set sequentially by concatenating the mem-bers, that is, effectively stacking the members end to end. Partitioned datasets can be used only from direct-access volumes. Figure 2.15 illustratespartitioned data sets.

z/OS provides two forms of the partitioned data sets. The new, improvedversion is the PDSE, partitioned data set extended, and the older version isthe PDS. The JCL for the two is the same, except for specifying which youwant. The only reason for using the older PDS is for old libraries createdwhen only the PDS was available.

If you spread all the cards out on the table so that each individual cardcan be seen, you could select or replace any card directly, without disturb-ing the others. Direct data set organization can exist only on direct-accessvolumes and is appropriate where records are processed randomly; that is,the next record to be processed bears no physical relationship to the recordjust processed. An example would be an on-line telephone directory inwhich a person’s telephone number is retrieved by giving that person’sname. Figure 2.16 illustrates direct organization.

z/OS also provides the Virtual Storage Access Method (VSAM) for stor-ing data on direct-access volumes. VSAM data sets can be organized as an


FIGURE 2.14 Sequen-tial organization. Recordscan only be read in theorder they are stored.

Record 1

Record 2

•••

Record 3

Record n

entry-sequence data set, which is functionally equivalent to a sequentialdata set, as a relative record data set, which is functionally equivalent to adirect data set, and as a key-sequenced data set.

The key-sequenced access method provides both sequential and ran-dom access. A better analogy for key-sequenced data sets is the publiclibrary where each book is assigned a key (a Dewey decimal number) andthe books are arranged in collating sequence—the sequence in which thecharacter set of the computer is ordered (based on the key), such as A to Z,0 to 9, and so forth. Books are placed on shelves and can be removed oradded without disturbing other books on other shelves. You can processthe “data set” sequentially by strolling through the stacks, or access abook directly by looking it up in the index. Key-sequenced data sets canreside only on direct-access storage volumes. Figure 2.17 illustrates key-sequenced organization.


FIGURE 2.15 Partitioned orga-nization. The member, after beinglocated through the directory, isread sequentially.

Name 1

Name 2Directory

Name n

Member 1

Member 2

Member n

•••

•••

Records

FIGURE 2.16 Direct organiza-tion. Key is supplied to locate aspecific record. Data set canalso be read sequentially.

Record 1

Record 2

•••

Record 3

Key 2

Key n

Key 1

Key 3

Record n

2.4 DATA STORAGE

The two most used means of storing data are on direct-access storagedevices and on tape.

2.4.1 DIRECT-ACCESS STORAGE DEVICES

Direct-access storage devices (DASD), the most versatile I/O device, cancontain sequential, partitioned, direct, and VSAM data sets. Direct-accessstorage derives its name from the way data is accessed. Unlike tape, oneneed not read the first nine records to get to the tenth. Another advantagedirect-access storage has over tape is that, assuming fixed-length records,individual records can be updated in place whereas the entire data set mustbe copied for tape. Direct-access storage devices are like the hard disk on aPC, but much larger. A single DASD volume can contain as many as 9GB.

In addition to containing general data, direct-access storage devices areused for subroutine libraries and for storing complete programs in load-module form. Nonresident portions of the system are also stored on direct-access volumes. Table 10.4 in Chapter 10 shows the capacity and accesstime of various DASD units.

2.4.2 Magnetic Tapes

Magnetic tapes used for storing computer data are similar to those in cas-sette tape recorders, although the recording method and content are quite


FIGURE 2.17 Key-sequenced organization. Key is supplied to locate a spe-cific record through the index. Data set can also be read sequentially.

Record 1

Record 2

•••

Record 15

Record 16

Record 17

Key 15

Key

Key 30 Index

Key 45

•••

Record 30

Record 31

Record 32

•••

Record 45

different. A single tape cartridge can contain as many as 10GB, and an infi-nite amount of information can be stored using multiple cartridges. Tapescan contain only sequential data sets. If you make any change to a tape dataset, you must rewrite the entire data set. Several data sets can be stored ona single tape volume by separating them with file marks. Because tapes areupdated by copying the old tape and the changes onto a new tape, an auto-matic backup is obtained by keeping the old tape and a copy of the changes.

Tape makes excellent long-term storage because a tape volume is inex-pensive and can contain a great deal of information in a small storage space.The storage capacity of tape cartridges is roughly the same as a DASD vol-ume, and the data transfer rates are likewise comparable. Table 12.1 inChapter 12 shows the volume capacity for tape drives. Some tapes arestored singly in a storage area, requiring that an operator retrieve and mountthem before use. The installation may also have an automated tape librarysystem, a silo-type device containing tape cartridges, in which the hard-ware selects and mounts tapes for use in a few seconds. Tapes are veryportable and are often used for off-site storage and mailing data.


TEAMFLY

Team-Fly®

CHAPTER 3

JCL WITHIN A JOB

Essential

This chapter gives an overview of how you use JCL within a job. It goesrather fast to give the flavor of using JCL. Don’t worry about understandingall the details because we’ll cover them later.

3.1 JCL STATEMENTS

The complete set of JCL statements is as follows:

Essential

� The JOB statement marks the beginning of a job.� The EXEC (Execute) statements follow the JOB statement and name

the programs or procedures to execute. (A procedure is a collection ofJCL statements stored in a file.)

� The DD (Data Definition) statements describe each data set (a file ona direct-access storage device, tape, or printed output) and requestthe allocation of I/O devices.

� The Delimiter (/*) statement is the end-of-file statement for markingthe end of data that is included with JCL statements.

� The Comment (//*) statement contains comments in columns 4 to 80to document the JCL.

Sometimes Used

� The PROC statement begins a procedure, cataloged or instream, andassigns default values to symbolic parameters.

� The PEND statement marks the end of an in-stream procedure.

35

� The OUTPUT statement specifies processing of print data sets.� The IF/THEN/ELSE/ENDIF statement construct selectively executes

job steps within a job.� The INCLUDE statement copies JCL from a file into the job stream.� The JCLLIB statement names private libraries that contain cataloged

procedures and JCL statements copied into the input stream byINCLUDE statements.

� The SET statement assigns values to symbolic parameters in a proce-dure.

Rarely Used

� The COMMAND statement executes operator commands.� The CNTL statement marks the beginning of program control state-

ments in the input stream. An ENDCNTL statement marks the end ofthe program control statements.

� The Null (//) statement marks the end of a job.� The XMIT statement transmits data and jobs to another computer.

3.2 COMPUTER JOBS

The JCL statements take on meaning only when you can see them in opera-tion. Let’s examine how to use them to run a computer job.

3.2.1 The JOB Statement and the Job

A computer job is the basic independent unit of work. It begins as a groupof computer language statements (called source language statements) thatyou enter from a terminal and store on a direct-access volume to be submit-ted to the computer. Sets of source language statements that are executedtogether within a job constitute a program. You usually divide programsinto functional parts called modules, subroutines, functions, or procedures,so that the various parts can be tested and changed without affecting otherparts.

JCL statements direct the operating system on the processing to be doneon a job and describe all the I/O units required. Since these JCL statementsare numerous and complex, the statements for frequently used proceduresare kept on a direct-access volume (disk). The user invokes these catalogedprocedures by giving the system the name of the cataloged procedure ratherthan submitting all the JCL statements.


Each job must begin with a single JOB statement. (It, along with all otherJCL statements, is described in subsequent chapters.)

//RT452216 JOB (45992),'JONES',CLASS=A

This statement tells the operating system that a job named RT452216 ischarged to account 45992 and belongs to a programmer named Jones.

3.2.2 The EXEC Statement and the Job Step

By the classic definition, a computer is a device that reads some input,processes it, and writes some output. You specify the process part withEXEC statements that tell the computer what computer program to execute.Each program execution within a job is called a job step or simply a step,and a job may consist of several steps. A typical job might consist of a com-pile step to convert the source language statements into machine language,a linkage editor step to combine the compiled program with other programsin subroutine libraries, and an execution step to actually run the program.This entails the execution of three separate programs: the compiler andlinkage editor, which are system programs, and the user’s job. All are exe-cuted with JCL statements.

Each job step begins with a single EXEC statement that names a programor cataloged procedure.

//STEP1 EXEC PGM=COBCOMP//STEP2 EXEC COB2UCLG

STEP1 executes a program named COBCOMP. STEP2 requests a cata-loged procedure named COB2UCLG. The system executes steps within ajob sequentially, so that the output from one step can be input to a follow-ing step. For example, Figure 3.1 illustrates a job with three steps. STEP1performs some calculations, STEP2 sorts some data, and STEP3 producessome statistics.

The following example illustrates the difference between jobs and jobsteps.

//RUNA JOB 7233,'LINCOLN' <== First job//COMP EXEC PGM=FORTCOMP//LKED EXEC PGM=LINKEDIT//RUNB JOB 6221,'DOUGLAS' <== Second job//PL1 EXEC PGM=PL1COMP//LKED EXEC PGM=LINKEDIT

Two distinct jobs, RUNA and RUNB, are executed. The system executesthe steps within each job sequentially. However, the jobs may not runsequentially. RUNB might execute before RUNA, after RUNA, or both jobsmight run concurrently.

JCL WITHIN A JOB 37

3.2.3 The DD Statement and the Data

Each program that uses an I/O device must have a DD (Data Definition)statement telling the system which I/O device it needs. The system thencoordinates the use of the I/O devices with the programs. Figure 3.2 illus-trates this. Figure 3.3 shows the way a DD statement works.

You usually write JCL using a text editor, such as ISPF. The DD * state-ment lets you enter lines of data along with your JCL. (Your JCL and lines of


FIGURE 3.1 Three-step job.

Execute STATSprogram//LAST EXEC PGM-STATS

//TEXT #2 JOB (2237,4), ‘PHASE 1’, CLASS=A//STEP1 EXEC PGM-CALC

Execute CALCprogram

Execute SORTprogram//STEP2 EXEC PGM-SORT

FIGURE 3.2 Coordination of I/O devices.

Diskdrive

Displayterminal

Tapedrive

Computer Printer

data are termed the input stream.) The statement for this is shown here. The* means that the data immediately follows this JCL statement.

//ddname DD *

Figure 3.4 shows the flow of a typical job with the input and outputspecified by DD statements.

The JCL to process the transactions looks like this:

//TEST#2 JOB (2237,4),'PHASE1',CLASS=A <== JOB statement.//STEP1 EXEC PGM=CALC <== Executes the CALC program.

JCL WITHIN A JOB 39

FIGURE 3.3 The way a DD statement works.

The system sees that the programwants to write a data set whosesymbolic name is SYSPRINT.

This part of theDD statement

sends the file tothis printer.

This part of the DD statement is theddname; it ties this DD statement

to the data set the program is writing.

//SYSPRINT DD SYSOUT=A

The program writes an output data set.The program refers to the data set byan external name of SYSPRINT here.

FIGURE 3.4 Typical job flow.

Process transactionsand write theminto a new file

Process sortedtransactions

Sort thetransactions

Printedreport

Transactions Newtransactions

Sortedtransactions

//INPUT DD * <== Defines the input data.[Data placed here]//OUT DD many parameters <== Specifies where to write the

Output data.//STEP2 EXEC PGM=SORT <== Executes the SORT program.//INPUT DD *.STEP1.OUT,many parameters <== Describes input to the sort by

pointing to the OUT data writ-ten in the previous job step.

//OUT DD many parameters <== Specifies where to write thenew OUT data.

//LAST EXEC PGM=STATS <== Executes the STATS program.//INPUT DD *.STEP2.OUT,many parameters <== Describes the input to the

STATS program by pointing tothe OUT data from the previousjob step.

//OUT DD SYSOUT=A <== Tells the system to print theoutput data.

A DD statement must describe each data set used within a job step bytelling the system which I/O device to use, the volume serial number of anyspecific volumes needed, the data set name, whether old data is being reador new data generated, and the disposition of the data when the job stepcompletes. The following DD statement is representative.

//DATAIN DD DSN=MYDATA,DISP=(OLD,KEEP),UNIT=SYSDA,VOL=SER=PACK12

The DD statement is named DATAIN and requests a data set namedMYDATA, which is an OLD data set to KEEP after it is read. SYSDA is asymbolic name for direct-access storage, and a VOLume with a SERial num-ber of PACK12 is requested.

Data sets may also be cataloged by asking the system to record the dataset name, the type of I/O unit, and the volume serial number containing thedata set. This permits you to refer to the data set by name without specify-ing where the data set is stored. If you catalog the MYDATA data set, youcould write the preceding DD statement as

//DATAIN DD DSN=MYDATA,DISP=(OLD,KEEP)

The system records the data set name, type of I/O unit, and volume ser-ial number in the system’s catalog. The catalog is itself a data set that con-tains an entry for each cataloged data set. Don’t confuse a cataloged data setwith a cataloged procedure. A cataloged procedure is a named collection ofJCL kept in a data set whereas a cataloged data set is a data set that has itsname, type of I/O unit, and volume serial number recorded by the system.Thus, the special data set containing cataloged procedures may be cata-loged.


3.3 CREATING PROGRAMS

With this background, we are now ready to see how to turn language state-ments into an execution program.

3.3.1 Compilation

A group of source language statements is called a source module. A systemprogram called the compiler reads the source module and translates thelanguage statements into machine instructions. The output from the com-piler, which consists of these machine instructions, is called an object mod-ule. The compiler writes the object module on a direct-access volume forsubsequent execution.

3.3.2 Linkage Editor

The linkage editor must process an object module before it can be executed.The linkage editor is a service program that determines which subprogramscall other subprograms and resolves these external references (symbolscontained in one subprogram that are referred to in another). The linkageeditor also searches various subroutine libraries to gather additional sub-routines required to complete the job. A subroutine library is a partitioneddata set, a form of z/OS data set organization (described later in this chap-ter) that can contain several subroutines as members.

Public libraries, such as the COBOL or C/C++ libraries, are usuallysearched automatically. You may also create a private library containingyour own subroutines and instruct the linkage editor to search it by theinclusion of JCL statements.

The linkage editor combines these subroutines into a complete programcalled a load module and writes the load module onto a partitioned data seton a direct-access volume. The load module is a complete program ready tobe entered (loaded) into storage for execution.

3.3.3 Execution

After the program is link-edited, it is loaded into storage and executed. Thisstep is called the execute or go step. When the program is completed, youmay keep it on a direct-access volume in load module form, saving compileand link-edit costs. Only a fraction of a second is needed to begin executinga load module, whereas several seconds may be required to compile andlink-edit the same program. Figure 3.5 illustrates the entire compile, link-edit, and execute process.

JCL WITHIN A JOB 41

A job need not consist of a compile, link-edit, and execute step. Perhapsonly a single step is needed to compile source statements for error check-ing. Or perhaps several related execution steps are required, with each stepperforming an operation on some data and passing the results on to a sub-sequent step. For example, the first step of an automated address labelingsystem might update the names and addresses in a master file. The secondstep could select all names and addresses with a given zip code. The finalstep could then print these names and addresses for mailing labels.

3.4 SORT EXAMPLE

For an example of using JCL, we’ll write a step to execute a program namedSORT, which will sort some data in the input stream. Then, a second step


FIGURE 3.5 Compile, link-edit, execute process.

Object moduleon direct-access

storage

Sourcelanguage

statements

Subroutinelibraries on

direct-accessstorage

Load moduleon direct-access

storage

Direct-accessstorage

Printer

Compiler

Linkageeditor

Programexecution

Tape

will execute a program named REPORT, which will read the sorted file andprint a report. The JCL shown here is simplified from the actual JCL neededby the actual Sort/Merge utility described in Chapter 20. Every job beginswith a JOB statement.

//RT452216 JOB (45992,335),'SAMPLE JOB',CLASS=A

Then we need an EXEC statement to specify the following:

Stepname: STEP1Program: SORTRegion size: 256K

We write the EXEC statement as

//STEP1 EXEC PGM=SORT,REGION=256K

We need a DD statement so that this step can print some output. We dothis by giving it a ddname (data definition name) of SYSPRINT and assign-ing it to output class A. The output class usually tells the system whichprinter to use.


Next, we need a DD statement with a ddname of SYSIN to read linesfrom the input stream.

//SYSIN DD *

We’ll add some lines of data and a DD statement with a ddname ofSORTOUT to write the sorted output into a disk data set. Our job so far con-sists of

//RT452216 JOB (45992,335),'SAMPLE JOB',CLASS=A//STEP1 EXEC PGM=SORT,REGION=256K//SYSPRINT DD SYSOUT=A//SYSIN DD *[Lines of data]/*//SORTOUT DD DSN=&&OUT,DISP=(NEW,PASS),// UNIT=SYSDA,SPACE=(0,(20,10)),// RECFM=FB,LRECL=80

Let’s briefly explain the DD statement as a preview to later chapterswhere it is described in detail.

//SORTOUT DD DSN=&&OUT,DISP=(NEW,PASS),

DSN=&&OUT names the data set. The && makes it a temporary data set kept only for the duration of the job. The data set name is OUT.

JCL WITHIN A JOB 43

DISP=(NEW,PASS) gives the data set disposition. NEW tells the system tocreate it and then PASS it to a following step.

// UNIT=SYSDA,SPACE=(0,(20,10)),

UNIT=SYSDA specifies the type of device to write the data set on.SYSDA by convention is direct-access storage. SPACE=(0,(20,10)) specifiesthe amount of disk space to allocate to the data set.

// RECFM=FB,LRECL=80

This specifies the record format (RECFM) as fixed blocked (FB) and thelogical record length (LRECL) as 80. More on this later. Symbolically, ourstep looks like Figure 3.6.

The next EXEC statement executes a program named REPORT. We givethe step a stepname of STEP2 and provide it a region of 512K.

//STEP2 EXEC PGM=REPORT,REGION=512K

We’ll add a DD statement with a ddname of PRINT and assign it to classA to print the output.

//PRINT DD SYSOUT=A

We’ll assume that the REPORT program expects the input DD statementto have a ddname of INPUT. The ddname connects the name used inter-nally by the program to the DD statement describing the actual I/O device.This lets you change the I/O device without changing the program.

//INPUT DD DSN=&&OUT,DISP=(OLD,DELETE)

DSN=&&OUT names the data set—the same data set created in STEP1.DISP=(OLD,DELETE) gives the disposition of the data set. OLD means italready exists and DELETE deletes it at the end of the step. Symbolically,Figure 3.7 shows the way our job looks.


FIGURE 3.6 Sort step.

SORT program

Step 1SYSIN SYSPRINT

Lines of dataPrinted output

SORTOUT Sorted lines ofdata—passed toa following step

TEAMFLY

Team-Fly®

3.5 COMPILE, LINKAGE EDIT, EXECUTE EXAMPLE

Now let’s take a more complicated example that is equally typical—com-piling some computer language statements, link editing them to create aprogram, and loading and executing the program. We’ll go into the JCLparameters in more detail in this example. The example uses a simplifiedversion of the COBOL compiler.

3.5.1 Compile Step

The COBOL compiler is a system program named IGYCRCTL whichrequires three data sets: an input data set consisting of source languagestatements to compile, an output data set to print the compilation listing,and an output data set to contain the object module—that is, machine lan-guage instructions produced by the compiler. Figure 3.8 illustrates this.

The following JCL might execute this program:

//RT452216 JOB (45992),'SMITH',CLASS=A//COB2 EXEC PGM=IGYCRCTL,REGION=1024K//SYSPRINT DD SYSOUT=A//SYSLIN DD DISP=(NEW,PASS),UNIT=SYSDA,// AVGREC=U,SPACE=(0,(1000,500)//SYSIN DD *[Source language statements to compile]/*

JCL WITHIN A JOB 45

FIGURE 3.7 Sort and report steps.

SORT program

Step 1SYSIN SYSPRINT

Lines of data

REPORT program

Step 2PRINT

Printed output

Printed output

SORTOUT

INPUT

Sorted lines ofdata—passed toa following step

FIGURE 3.8 Compile step.

CompilerPGM=IGYCRCTL

COB2 stepSYSIN SYSPRINT

Source statementsCompilation listing

SYSLIN Compiled output(termed Object module)

Let’s examine each statement individually to see what it does.

//RT452216 JOB (45992),'SMITH',CLASS=A

JOB marks this as the start of a job. We’ve named the job RT452216,given it an account number of 45992, told the system that the programmer’sname is SMITH, and assigned the job to class A.

//COB2 EXEC PGM=IGYCRCTL,REGION=1024K

We named the step (the stepname) COB2. EXEC is the statement name.PGM=IGYCRCTL tells the system to execute a program named IGYCRCTLand REGION=1025K requests 1,024K bytes of central storage.


SYSPRINT is the ddname of the DD statement. The IGYCRCTL programmust internally define a data set with the ddname of SYSPRINT. When youwrite your own programs, you are free to choose the ddname; you mustknow the ddnames required by existing programs. SYSOUT=A defines aprint data set. Print data sets are used so often that the system provides aspecial abbreviation, SYSOUT. The SYSOUT keyword instructs the systemto queue the output on a direct-access volume. The general form isSYSOUT=class, where the class is defined by the installation. Traditionally,SYSOUT=A is a printer, but other classes may be established as needed forspecial forms, high-volume output, and so on.

//SYSLIN DD DISP=(NEW,PASS),UNIT=SYSDA,// AVGREC=U,SPACE=(0,(1000,500)

The //SYSLIN DD statement describes the data set to contain the objectmodule produced by the compiler. The DISP (disposition) keyword tells thesystem to create a NEW data set and PASS it on to the next job step.

The UNIT keyword specifies the I/O unit to use. (This is equivalent tothe way you specify the A diskette drive or the C hard drive on a PC.) Eachinstallation creates symbolic names that define the various I/O devices.SYSDA traditionally is the name for direct-access I/O devices.

The SPACE keyword allocates storage on the direct-access volume forthe data set. AVGREC=U tells the system that the SPACE parameter isrequesting space in units of records. Thus, the SPACE=(0,(1000,500)) tellsthe system that primary space is wanted for 1,000 records. If the data setexceeds that space, the system allocates secondary space for an additional500 records. (The system can allocate secondary space as many as 122times.) You must allocate space for all NEW data sets on direct-access vol-umes. Space allocation is unnecessary for data sets stored on tape.

//SYSIN DD *


The asterisk (*) is a special code telling the system that lines of dataimmediately follow the DD statement in the input stream. The end of thedata is indicated by the /* statement. The lines of JCL and data are termedthe input stream.

3.5.2 Linkage Editor Step

Next, the program must be link-edited to create an executable load module.The object module contains the machine language instructions for the pro-gram, but it does not include all the system routines that actually perform theI/O operations and various other standard functions. The object module mustbe link-edited to do this, and the result is a load module ready for execution.Assume that the linkage editor is a system program named IEWL requiringthree data sets: an input data set containing the object modules produced bythe compiler, an output data set for printing error messages, and an outputdata set to contain the load module produced. Figure 3.9 illustrates this.

Here are our statements so far with the linkage editor step added.

//RT452216 JOB (45992),'SMITH',CLASS=A//COB2 EXEC PGM=IGYCRCTL,REGION=1024K//SYSPRINT DD SYSOUT=A//SYSLIN DD DISP=(NEW,PASS),UNIT=SYSDA,// AVGREC=U,SPACE=(0,(1000,500)//SYSIN DD *[Source language statements to compile]/*//LKED EXEC PGM=IEWL,REGION=1024//SYSPRINT DD SYSOUT=A//SYSLIN DD DSN=*.COB2.SYSLIN,DISP=(OLD,DELETE)//SYSLMOD DD DSN=&&GOSET(GO),DISP=(NEW,PASS),// UNIT=SYSDA,AVGREC=K,SPACE=(0,(500,100,1))

JCL WITHIN A JOB 47

FIGURE 3.9 Compile and link-edit steps.


COB2 step

SYSINSYSPRINT

SYSPRINT

Source statements

Linkage editorPGM=IEWL

LKED step

Printed output

Compilation listing

Object moduleis passed tonext step

SYSLIN

SYSLIN

Compiled output(termed Object module)

SYSLMODLoad module(executable program)

Now examine the added statements in detail.

//LKED EXEC PGM=IEWL,REGION=1024K

This executes the IEWL program in a 1,024K region.


The //SYSPRINT DD statement defines a print data set.

//SYSLIN DD DSN=*.COB2.SYSLIN,DISP=(OLD,DELETE)

The //SYSLIN DD statement describes the input data set containingobject modules for the linkage editor—the data set created in the precedingjob step. DSN=*.COB2.SYSLIN tells the system that this is the same data setdescribed in the step named COB2 with a DD statement named SYSLIN.(The *.step.ddname parameter is called a referback parameter.) Since thedata set already exists, the current status is OLD. The data set is not neededafter this step, so we can DELETE it, releasing the space on the direct-accessvolume.

//SYSLMOD DD DSN=&&GOSET(GO),DISP=(NEW,PASS),// UNIT=SYSDA,AVGREC=K,SPACE=(0,(500,100,1))

This DD statement is similar to the //SYSLIN DD statement in the firststep except for the DSN (data set name) keyword parameter. You must placeload module output on a direct-access volume as a member of a partitioneddata set. A partitioned data set is a special data set that contains severalsequential data sets termed members. It is analogous to a file cabinet thatcontains several file drawers. We chose GO as the member name, andnamed the data set GOSET. The ampersands (&&) in front of the data setname mark it as temporary—to be deleted at the end of the job.

AVGREC=K tells the system that space is requested in units of K (1,024)records. Thus, SPACE=(0,(500,100.1) requests primary space for 500Krecords (500 × 1,024 = 512,000) and if that is exceeded, secondary space for100K records. The 1 reserves one block for storing the member names in thepartitioned data set.

3.5.3 Execution Step

The load module is now ready for execution. Figure 3.10 illustrates thecomplete job.

//RT452216 JOB (45992),'SMITH',CLASS=A//COB2 EXEC PGM=IGYCRCTL,REGION=1024K//SYSPRINT DD SYSOUT=A//SYSLIN DD DISP=(NEW,PASS),UNIT=SYSDA,// AVGREC=U,SPACE=(0,(1000,500)


//SYSIN DD *[Source language statements to compile]/*//LKED EXEC PGM=IEWL,REGION=1024K//SYSPRINT DD SYSOUT=A//SYSLIN DD DSN=*.COB2.SYSLIN,DISP=(OLD,DELETE)//SYSLMOD DD DSN=&&GOSET(GO),DISP=(NEW,PASS),// UNIT=SYSDA,AVGREC=K,SPACE=(0,(500,100,1))//GO EXEC PGM=*.LKED.SYSLMOD,REGION=228K//SYSPRINT DD SYSOUT=A

Let’s again examine the added statements in detail.

//GO EXEC PGM=*.LKED.SYSLMOD,REGION=228K

The referback parameter tells the system that the load module to exe-cute is described in the LKED step on the //SYSLMOD DD statement. Theprogram will execute in 228K of storage.


The //SYSPRINT DD statement defines a print data set. Output writtento the SYSPRINT ddname is printed.

Of course, you won’t actually write all these statements when you com-pile, link-edit, and execute a program. Instead, you invoke existing JCLstatements contained in a cataloged procedure.

JCL WITHIN A JOB 49

FIGURE 3.10 Compile, link-edit, and go steps.


COB2 step

SYSINSYSPRINT

SYSPRINT

Source statements

Linkage editorPGM=IEWL

LKED step

GO step

Printed output

Compilation listing

Object moduleis passed tonext step

This PGM parameterpoints to thisLoad module

SYSPRINT Printed outputfrom program

SYSLIN

SYSLIN

Compiled output(termed Object module)

SYSLMOD

PGM

Load module(executable program)

COBOL programtermed theGO step

3.6 CATALOGED PROCEDURE

You have seen all the JCL statements needed to compile, link-edit, and exe-cute the program, but there are a great number more of them. You shouldnow make them a cataloged procedure so that several people can use theJCL. You create a cataloged procedure by storing JCL statements on a direct-access volume as a member of a special partitioned data set. You choose aname, one to eight characters, for the cataloged procedure. COB2UCLGmight be an appropriate name for the COBOL compile, link-edit, and exe-cute procedure. The following statements constitute the procedure.

//COB2UCLG PROC

[The PROC statement, always the first statement, identifies this as acataloged procedure.]

//COB2 EXEC PGM=IGYCRCTL,REGION=1024K//SYSPRINT DD SYSOUT=A//SYSLIN DD DISP=(NEW,PASS),UNIT=SYSDA,// AVGREC=U,SPACE=(0,(1000,500)//LKED EXEC PGM=IEWL,REGION=1024K//SYSPRINT DD SYSOUT=A//SYSLIN DD DSN=*.COB2.SYSLIN,DISP=(OLD,DELETE)//SYSLMOD DD DSN=&&GOSET(GO),DISP=(NEW,PASS),// UNIT=SYSDA,AVGREC=K,SPACE=(0,(500,100,1))//GO EXEC PGM=*.LKED.SYSLMOD,REGION=228K//SYSPRINT DD SYSOUT=A

The JOB statement, //SYSIN DD * statement, the source language state-ments, and the /* statements are omitted. You include them when you sub-mit the job. You can now call forth the JCL statements by giving the name ofthe cataloged procedure on an EXEC statement.

//RT452216 JOB (45992),'SMITH',CLASS=A// EXEC COB2UCLG//COB2.SYSIN DD *[Source language statements]/*

The absence of a PGM= keyword on the EXEC statement indicates thata cataloged procedure is requested. The COB2. appended to the SYSINddname tells the system to temporarily add the DD statement added to thestep named COB2. Now the JCL has become manageable. We’ve covered theJCL statements very fast here to just give the feel for their use. The nextchapters go into them in detail.


CHAPTER 4

JCL STATEMENT FORMATS AND RULES

Essential

In this book, all JCL statements and parameters are capitalized. Fields con-taining uppercase or special characters such as PARM ( , / . and so forth arecoded exactly as shown. Names in lowercase italics indicate values thatyou select. For example, you might code TIME=minutes as TIME=10 torequest a time of 10 minutes. As a convention here, items stacked verticallyabove an underline indicate that you must choose one of the items. Anunderlined item indicates the default that is effective if you omit the param-eter entirely. For example,

NEW KEEPOLD DELETE

DISP=( , )

could be coded as DISP=(NEW,KEEP), DISP=(OLD,KEEP), and so on.DISP=(,DELETE) is equivalent to DISP=(NEW,DELETE) because NEW is thedefault. If both positional subparameters were optional, you could codeDISP=(,KEEP), DISP=OLD, and so on.

4.1 JCL STATEMENT FORMAT

All JCL statements (except for the /* statement) begin with a // in columns1 and 2, followed by a name, operation, operand, and comments field.

//name operation operand comments

The name field is optional for some statements and begins immediatelyafter the second slash. Separate the other fields from each other by one ormore blanks. Except for the comments, code the fields in columns 3 to 71.You can extend the comments field through column 80. (Long ago, data wasentered on punched cards that had 80 columns. Because of the danger of

51

dropping them, columns 72 to 80 were used for a sequence number so thatthe cards could be sorted back into the proper order. The need for this hasdisappeared, but the card format conventions still linger in old systems likeJCL.)

The name field, one to eight characters, identifies the statement so thatother statements or a computer program can refer to it. The first charactermust be in column 3 and be alphabetic (A to Z) or national (@ $ #). Theremaining characters can be alphanumeric (A to Z, 0 to 9) or national. ForJCL, @, $, and # are considered to be alphabetic characters, and you canwrite them wherever you can write an alphabetic character. Choose namesthat convey meaning in the JCL just as you would if you were writing anapplication program.

Correct Incorrect//A //1TEST First character not A–Z @ $ #//TEST#10 //SPACECRAFT More than 8 characters//PAYROLLS //TEST-6 Dash not legal

The operation field specifies the type of statement: JOB, EXEC, DD,PROC, PEND, CNTL, ENDCNTL, OUTPUT, COMMAND, IF/THEN/ELSE/ENDIF, INCLUDE, JCLLIB, SET, or an operator command.

//TEST20 JOB//STEP EXEC//PRINT DD

The operand field supplies the information in the form of parametersseparated by commas. Parameters are composites of prescribed words (key-words) and variables for which you select the information to enter. Theoperand field has no fixed length or column requirements as long as it doesnot extend beyond column 71, but it must be preceded and followed by atleast one blank.


Or


But not

//RT452216 JOB(45992),'SMITH',CLASS=A

The comments field, used for notes and comments, is optional. Separateit from the operand field by at least one blank, and you can code it only ifthere is an operand field.

//RT452216 JOB (45992),'SMITH',CLASS=A THIS IS A COMMENT


4.2 PARAMETERS IN THE OPERAND FIELD

The operand field is made up of two types of parameters: positional para-meters characterized by their position in the operand field in relation toother parameters, and keyword parameters positionally independent withrespect to others of their type and consisting of a keyword followed by anequal sign and variable information. The following example contains botha positional parameter (45992) and a keyword parameter (CLASS=A).

//RT452216 JOB 45992,CLASS=A

A positional parameter or the variable information in a keyword param-eter is sometimes a list of subparameters. Such a list may comprise bothpositional and keyword subparameters that follow the same rules andrestrictions as positional and keyword parameters. Enclose a subparameterlist in parentheses unless the list reduces to a single subparameter. The fol-lowing JOB statement illustrates positional subparameters:

//RT452216 JOB (45992,100,40),COND=(9,LT)

The (45992,100,40) is a positional parameter containing three positionalsubparameters. COND=(9,LT) is a keyword parameter containing two posi-tional subparameters. Subparameters can also be keywords. DCB=(RECFM=FB,LRECL=80) represents a keyword parameter consisting of two keywordsubparameters.

4.3 PARAMETER RULES

� Separate both positional and keyword parameters with commas.Blanks are not permitted.

Correct Incorrect6,CLASS=A,REGION=104K 6, CLASS=A,REGION=104K Blanks not allowed(6,106),CLASS=A (6,106)CLASS=A No commaCLASS=A,REGION=104K CLASS=A,REGION=104K, Extra comma

Misplaced blanks in JCL statements lead to errors. In the followingstatement, a blank is inadvertently left between two parameters. The,CLASS=A parameter is treated as a comment and is ignored.

//RT452216 JOB 45992 ,CLASS=A

� Code positional parameters in the specified order, before any key-word parameters in the operand field.

Correct: (6,106),CLASS=A

Incorrect: CLASS=A,(6,106)

JCL STATEMENT FORMATS AND RULES 53

� Indicate the absence of a positional parameter by coding a comma inits place. The second JOB statement here omits the second positionalsubparameter in the first JOB statement://RT452216 JOB (45992,100,40),'SMITH',CLASS=A//RT452216 JOB (45992,,40),'SMITH',CLASS=A

� If the absent positional parameter is the last parameter, or if all fol-lowing positional parameters are also absent, don’t code the subse-quent replacing commas.

Wrong: //RT452216 JOB (45992,,),'SMITH',CLASS=A

Correct: //RT452216 JOB (45992),'SMITH',CLASS=A

� You may omit the enclosing parentheses if a subparameter consists ofa single value.//RT452216 JOB (45992),'SMITH',CLASS=A

Or//RT452216 JOB 45992,'SMITH',CLASS=A

� You need code nothing if all positional parameters are absent.//RT452216 JOB CLASS=A

� You can code keyword parameters in any order in the operand field,as long as they follow any positional parameters.//RT452216 JOB (45992),'SMITH',MSGLEVEL=1,REGION=1040K,CLASS=A

Or//RT452216 JOB (45992),'SMITH',CLASS=A,MSGLEVEL=1,REGION=1040K

These rules appear complex, but a little practice makes their applica-tion automatic. The following example shows how to code the statement asyou omit the underlined parameters.

//A DD DCB=(LRECL=80,RECFM=F),SPACE=(TRK,(100,80,30),RLSE,CONTIG,ROUND)//A DD DCB=(LRECL=80,RECFM=F),SPACE=(TRK,(100,80,30),RLSE,,ROUND)//A DD DCB=(LRECL=80,RECFM=F),SPACE=(TRK,(100,,30),RLSE,,ROUND)//A DD DCB=LRECL=80,SPACE=(TRK,(100,,30),RLSE,,ROUND)//A DD DCB=LRECL=80,SPACE=(TRK,(100,,30),RLSE)//A DD DCB=LRECL=80,SPACE=(TRK,(100,,30))//A DD DCB=LRECL=80,SPACE=(TRK,100)//A DD SPACE=(TRK,100)//A DD SPACE=TRK

4.4 GENERAL JCL RULES

� Start all statements in column 1 with the appropriate // or /*.� Begin any entry you code in the name field (it is sometimes optional)

in column 3 and follow it with at least one blank.

//TEST JOB But not // TEST JOB or //TESTJOB


TEAMFLY

Team-Fly®

� Separate each field with at least one blank.

//STEP1 EXEC COB2UCLG But not //STEP1EXEC COB2UCLG

or //STEP1 EXECCOB2UCLG

� No embedded blanks are allowed within fields, and commas mustseparate parameters.

� To write comments on JCL statements that have an operand field,leave a blank between the operand and the comments.//STEP1 EXEC COB2UCLG THIS IS A COMMENT.

� Some parameters apply only to specific systems or hardware devices.The system ignores parameters if they are inappropriate for a featureor hardware device.

4.5 CONTINUING JCL STATEMENTS

Columns 1 to 71 contain the JCL information. If more than one line is neededor if you wish to place parameters on separate lines, interrupt the fields aftera complete parameter (including the comma that follows it) at or before col-umn 71, code // in columns 1 and 2 of the following line, and continue theinterrupted statement beginning anywhere in columns 4 through 16.

//RT452216 JOB (45992),'SMITH',CLASS=A,MSGLEVEL=1,// REGION=1040K

Or

//RT452216 JOB (45992),// 'SMITH',// CLASS=A,MSGLEVEL=1,// REGION=1040K

You can also break a statement after a complete subparameter:

//OUTFILE DD DSN=XR2832.TEST.DATA,DCB=(LRECL=120,RECFM=FB)

Or

//OUTFILE DD DSN=XR2832.TEST.DATA,DCB=(LRECL=120,// RECFM=FB)

Continuation is more complex if the value of a keyword parameter isenclosed in apostrophes. Code the parameter into column 71, and on thenext line code // in columns 1 to 2 and continue the parameter in column16 as shown in this example:

1 2 3 4 5 6 7123456789012345678901234567890123456787901234567890123456789012345678901//STEP10 EXEC PGM=STATUS,COND.STEP6=(4,LT),COND.STEP5=(4,LT),PARM='1000X// A*3345821'


Rather than remember this, break the statement before the parameterthat needs to be continued and code it on the next line.

//STEP10 EXEC PGM=STATUS,COND.STEP6=(4,LT),COND.STEP5=(4,LT),// PARM='1000XA*3345821'

4.6 COMMENTING JCL

Comment JCL as you would any programming language. The commentstatements contain //* in columns 1 to 3, with the remaining columns con-taining any desired comments. Place them before or after any JCL state-ments following the JOB statement to help document the JCL. Codecomments on any JCL statement by leaving a blank field after the operandfield.

//A DD UNIT=SYSDA, A DISK IS USED.//* THE FOLLOWING STATEMENTS REQUESTS THE//* SPECIFIC VOLUME TO USE.// VOL=SER=PACK12 PACK 12 IS USED.

The system lists the comments but ignores them when interpreting theJCL. The system interprets this statement as

//A DD UNIT=SYSDA,VOL=SER=PACK12

As an example of the use of comment statements, suppose you mustchange the JCL each time it is run. You could place comment statementsafter the JOB statement to remind yourself of the changes.

//RT452216 JOB (45992),'SMITH',CLASS=A//******** TAPE MOUNTS: 003845, 003900-WRITE ENABLE.//******** JCL CHANGES: LAST LINE IS RUN DATE.

[Note that you can’t continue a comment statement. Instead, youcode a second statement.]

Use comment statements as necessary throughout the job to describewhat the reader may need to know. A solid line of asterisks as commentstatements preceding each job step makes the start of the step easier tolocate.

//**********************************************************//******** SORT THE PAYROLL MASTER **//**********************************************************//STEP6 EXEC SORTD


4.7 STYLE IN WRITING JCL

Style in writing JCL is perhaps a contradiction in terms because JCL is nota stylish language. Nonetheless, while you cannot make JCL beautiful, youcan make it consistent. Your installation may have standards for JCL, andyou will undoubtedly develop those of your own. The following are somesuggestions:

� Begin each step with comment statements to highlight it in a listing://***************************************************************//* STEP1 VALIDATES THE DATA. **//***************************************************************//STEP1 EXEC PGM=VALID,REGION=512K

� Code the parameters for a statement in the order of their importanceand frequency of use. Since almost every DD statement has a DSNand DISP parameter and since these are the two most important DDparameters, write them first on all DD statements://OUT DD DSN=RI8275.A9456.DATA,DISP=(NEW,CATLG),

� Align the continuation of DD statements and code-related parameterson the same line. Since the UNIT and any VOL parameter are related,place them next://OUT DD DSN=RI8275.A9456.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,VOL=SER=PACK12,

But don’t indent beyond column 16 to align the statements. This canoften occur when you override DD statements in a cataloged proce-dure. The continuation can’t be spaced any further to the right in thenext statement because it would be beyond column 16://COBOL.PRINTOUT DD DSN=RI8275.A9456.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,

� Since the DCB subparameters tend to be rather long, place them on aline by themselves or following the UNIT://OUT DD DSN=RI8275.A9456.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,DCB=(RECFM=FB,LRECL=80),

� The AVGREC and SPACE parameter are related and tend to be long,so place them on a line by themselves://OUT DD DSN=RI8275.A9456.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,DCB=(RECFM=FB,LRECL=80),// AVGREC=K,SPACE=(0,(100,20),RLSE)

� Avoid writing comments at the end of JCL statements because thismakes the JCL statements difficult to read. Place the comments onseparate comment lines. The following is a typical set of commentedJCL.


//RT452216 JOB (45992),'SMITH',CLASS=A//**************************************************************//* WEEKLY PRODUCTION RUN TO VALIDATE DATA AND PRODUCE **//* STATUS REPORT. **//**************************************************************//**************************************************************//*//* STEP1 VALIDATES THE DATA. **//**************************************************************//STEP1 EXEC PGM=VALID,REGION=512K//* THE OUTPUT IS MADE NONTEMPORARY BECAUSE OTHER//* JOBS WILL READ THIS DATA.//OUT DD DSN=RI8275.A9456.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,DCB=(RECFM=FB,LRECL=80),// AVGREC=K,SPACE=(0,(100,20),RLSE)//**************************************************************//* STEP2 PRODUCES THE WEEKLY STATUS REPORT. **//**************************************************************//* THIS STEP IS BYPASSED IF ANY PREVIOUS STEP ISSUES//* A RETURN CODE GREATER THAN 4.//STEP2 EXEC PGM=REPORT,REGION=1024K,COND=(4,LT)//INPUT DD DSN=RI8275.A9456.DATA,DISP=(SHR,KEEP)//**************************************************************//* END OF JOB **//**************************************************************

� Break any of these rules and make up your own if they make your JCLeasier to read.

4.8 PLACEMENT OF JCL STATEMENTS

Many of the JCL statements have not yet been described, but their place-ment is described here for completeness. For quick reference, the order ofJCL (and JES) statement placement is as follows:

1. Any JES2 /*$command and /*PRIORITY statements or any JES3//*command statement or any XMIT JCL statement.

2. JOB statement.

3. Any JES2 statements other than /*$command and /*PRIORITY orany JES3 statement except the //*command statement or anyXMIT JCL statements.

4. Any JOBLIB statement.

5. Any JOBCAT or SYSCHK statements.

6. Any instream procedures.

7. Any OUTPUT or JCLLIB statements for the job.

8. The first EXEC statement.


9. Any STEPCAT or STEPLIB DD statements belonging to the step.This is a convention.

10. Any OUTPUT statements belonging to the job step. You can inter-mix DD and OUTPUT statements for a step in any order, but theconvention of placing them in this order simplifies overridingthem in cataloged procedures.

11. Any ordinary DD statements belonging to the step.

12. Any more EXEC statements and their associated DD and OUTPUTstatements.

13. Any // null statement.

In addition to these rules, you need to consider the following in placingJCL statements:

If DD statements in a step have the same ddname, the system uses thefirst statement and ignores any subsequent DD statements in thatstep with the same ddname.

The system concatenates data sets in the order of the DD statements.(When sequential data sets are concatenated, you can read them asif they were a single data set.)

Multiple //SYSOUT DD statements to the same output class are printedin the order of the DD statements.

DD statements overriding cataloged procedures must be in the sameorder as the statements within the procedure. Added DD statementsmust follow any overriding DD statements.

EXEC or DD statements with referback parameters must follow thestatement to which they refer.

The PROC statement must be the first statement in a cataloged orinstream procedure.

The PEND statement must follow the last JCL statement in an instreamprocedure.

Place any //* comment statements after the JOB statement. You can thenplace them before or after any other JCL statements.

Place Command statements before a JOB, EXEC, null, or other Com-mand statement.

That’s it for the general JCL rules. The next chapters describe the indi-vidual JCL statements.


CHAPTER 5

THE JOB STATEMENT

The JOB statement informs the operating system of the start of a job, givesthe necessary accounting information, and supplies run parameters. Begineach job with a single JOB statement. Installations usually establish a fixedJOB statement format that you must use, and some JOB statement parame-ters described in this chapter may be forbidden. The JOB statement has thefollowing form:

//jobname JOB (acct-no,acct-information),name,keyword-parameters

The jobname is a name you assign to the job.

The acct-no,acct-information is the account number to which the job ischarged and any additional accounting information that your instal-lation establishes.

The name is whatever you select to identify the run.

The keyword-parameters are the following:

Essential

CLASS specifies the job class, an input queue for holding jobs awaitingexecution.

COND specifies conditions for executing subsequent job steps if previ-ous steps fail.

REGION specifies region size to allocate to the job.

TIME imposes a CPU time limit on the job.

Sometimes Used

MSGCLASS specifies the job scheduler output class.

MSGLEVEL specifies whether to list all the JCL statements.

60

Rarely Used

ADDRSPC specifies that the job cannot be paged.

BYTES limits the number of bytes of printed output and tells what to doif this limit is exceeded.

CCSID converts data on ISO/ANSI version 4 tapes from or to codedcharacter set identifier.

GROUP allows users to share Resource Access Control Facility(RACF)–protected data sets.

LINES limits the number of lines of printed output and tells what to doif this limit is exceeded.

MEMLIMIT limits the total number of usable virtual pages above theline for a single address space.

NOTIFY notifies you at your terminal when the batch job is completed.

PAGES limits the number of pages of printed output and tells what todo if this limit is exceeded.

PASSWORD identifies a current Resource Access Control Facility(RACF) password or assigns a new password.

PERFORM assigns the job to a performance group for execution priority.

PRTY specifies the job’s priority in the input queue.

RD requests restart of a job step.

RESTART submits a job for restart.

SCHENV specified the name of a JES workload management schedulingenvironment.

SECLABEL specifies the security level for the job.

TYPRUN checks JCL or holds the job in the input queue.

USER specifies a RACF userid.

You can code COND, REGION, TIME and CCSID on both the JOB andEXEC statements. Since you usually code COND and REGION on the EXECstatement, they are described in the next chapter. Except for TYPRUN,which is described in this chapter, and CCISD, which is described in Chap-ter 12, the rarely used statements are described in Chapter 16.

The JOB statement defines the start of a job. The following is typical:

//RT452216 JOB (45992,522),'SMITH',CLASS=A

The system reads the entire job in and checks your JCL statements forsyntax errors. Then it stores the job on disk in a job queue to await execu-tion. The system keeps several queues, termed job classes. The CLASSparameter directs jobs into the job queues as illustrated in Figure 5.1.

THE JOB STATEMENT 61

Installations set up separate job classes for these reasons:

� To balance the running of jobs that do many calculations with jobsthat do lots of input/output.

� To set aside jobs that require a special setup, such as requiring a tapeto be mounted.

� To control when some jobs are run, such as overnight or on weekends.

The JOB statement is easy to code because your installation will specifywhat you must write. Figure 5.2 illustrates the usual JOB statement. Nowlet’s examine the parameters in detail.

5.1 JOBNAME: NAME OF JOB

Essential

The jobname identifies the job to the operating system. It can range from oneto eight alphanumeric (A to Z, 0 to 9) or national (@ $ #) characters. The firstcharacter must begin in column 3 and be alphabetic (A to Z) or national.Give each job a unique name because the system will not run jobs concur-


FIGURE 5.1 Job classes.

Job 4

CLASS=A

Job 3

Job 2

Job 1

CLASS=B

Jobs are selected on a first-in-first-out basis to be executed

Job 2

Job 1

CLASS=C

Job 2

Job 1

FIGURE 5.2 Typical JOB statement.

//name JOB (accounting-information), ‘name’, CLASS=letter

Often specifiedby installation

Often specifiedby installation

Always specifiedby installation

Always specifiedby installation

rently having the same name. It will hold up a job until any job having thesame jobname completes execution. Make the name unique by coding someunique characters as a part of the jobname, for example, initials, job number,or employee id. Many installations tell you what jobname you must use.

Correct Incorrect//GDB406 //6J First character not A to Z, @ $ #//A8463 //SUPERCOMP More than 8 characters.//B8750#12 // RUN#6 Does not begin in column 3.

5.2 ACCOUNTING INFORMATION

Essential

This parameter is easy. You code what your installation tells you. The form is

(acct-number,additional-acct-information)

The acct-number and additional-acct-information are defined by theinstallation. Separate all the subparameters with commas. If the accountnumber or additional accounting information contains any special charactersexcept a hyphen—blank . , / ’) (* & + =—enclose the subparameter in apos-trophes (’). The system does not pass the apostrophes as part of the informa-tion. Code a legitimate apostrophe as two consecutive apostrophes. Forexample, I’M is coded as ‘I’’M’. Code an ampersand as two ampersands (&&).

The usual rules of omitting commas and parentheses in lists of subparam-eters apply. If you omit the acct-number, indicate its absence with a comma:(,additional-acct-information). If there is no additional-acct-information, theparentheses around the account number may be omitted. You can continuethe accounting information onto another line after a complete subparameter,including the comma that follows it.

//jobname JOB 2011//jobname JOB (20746,30,// 6,94)//jobname JOB 3042,6 [Wrong! Parentheses are needed if there is more

than one positional parameter.]

The additional-acct-information can consist of several subparametersseparated by commas: (20746,30,6,94). If a subfield contains special char-acters, enclose it in apostrophes and make sure you write that parametercompletely on one line.

//jobname JOB (20746,30,'56+97/22',6,94)

If your installation has JES2, you will likely code acct-number andadditional-acct-information on the /*JOBPARM statement (see Chapter 13)


rather than on the JOB statement. If you specify the accounting informationon both the JOB statement and on the JES2 /*JOBPARM statement, that on/*JOBPARM overrides that on the JOB statement.

Likewise in JES3, you will likely code the accounting information onthe //*NETACCT statement described in Chapter 13. It, too, overrides thaton the JOB statement.

5.3 NAME: PROGRAMMER NAME

Essential

The name is a 1- to 20-character name identifying you or the job. Enclose it inapostrophes if it contains special characters other than a period or hyphen—blank . , / ’) (* $ + =. Rather than trying to remember all these rules, justenclose the name in apostrophes and forget about them. Code a legitimateapostrophe as two consecutive apostrophes; for example, code O’BRIAN as‘O’’BRIAN’. The installation can make the name parameter mandatory. Yourinstallation will likely specify what you must code for name.

//FIRST JOB (4562,200),SMITH//SECOND JOB ,SMITH

[If you don’t code the account number, indicate its absence with acomma.]

//THIRD JOB 6542,'O''REILLY'//FOURTH JOB 5642,AL GOLL

[Wrong! Need enclosing apostrophes if the name contains specialcharacters other than the period or hyphen.]

5.4 CLASS: JOB CLASS

Essential

CLASS=class specifies the job class. Your installation will specify which ofthe 36 possible job classes to use: A to Z, 0 to 9. The installation establishesa default job class that is in effect if you omit CLASS. Installations usuallyattempt to establish job classes that achieve a balance between I/O-boundjobs and CPU-bound jobs, between big jobs and little jobs, and so forth. Thejob class may depend on such things as the amount of CPU time required bythe job, tape mounts, and when the job is to run.

Job classes also determine the overall priority of a job, along with thePRTY parameter. (The PRTY parameter described in Chapter 16 changesthe priority for a job.) The operator can start and stop various job classes,thus controlling the time they are run. Jobs within the same job class are


TEAMFLY

Team-Fly®

queued together in the input queue to await execution. The installationmay assign priorities to jobs within the same class, based on such resourcerequirements as CPU time.

5.5 TIME: TIME LIMIT

Essential

The TIME parameter sets a CPU time limit for an entire job when you code iton the JOB statement. CPU time is not the same as clock time. CPU time, thetime a job is executing instructions, does not include wait time (when the jobis waiting for I/O actions to complete), system time, and time that other jobsin the multiprogramming environment are using the CPU. You can also codeTIME on the EXEC statement to set a CPU time limit for a specific step. Inpractice, though, you usually write it on the JOB statement. The forms are

TIME=minutesTIME=(minutes,seconds)TIME=NOLIMITTIME=MAXIMUM

The minutes may range from 1 to 357912 (248.55 days); seconds mustbe 0 to 59. If the total CPU time for the job exceeds the limit set on the JOBstatement, or if the elapsed CPU time within a step exceeds the time limitfor that step, the entire job is abnormally terminated with a 322 completioncode. (Coding TIME=0 gives unpredictable results when coded on the JOBstatement. On the EXEC statement, TIME=0 allows the step to use the unex-pired time from the preceding step. To simplify things, don’t code TIME=0.)

You estimate CPU time for several reasons:

� Your installation may require it. They may also limit you to certainjob classes based on the CPU time you estimate.

� If you are debugging a program and you think a bug in your programmay result in your program never reaching completion, you can cutthe job off after some length of time.

� You often code TIME during debugging to guard against wasting timeif the job goes into an endless loop.

� To obtain messages telling you how much time the job used.

When you estimate CPU time, be generous. Allow more time than youthink you need. For example, suppose you have a job you estimate will runfor five minutes of CPU time. If you estimate five minutes of CPU time andyour job runs a fraction over this (which always seems to happen), your jobABENDs (abnormally terminates) at the worst possible time—after youhave incurred all your run costs but before the job terminates and you getyour results. You have wasted five CPU minutes. If you estimate eight min-


utes of CPU time and your job goes into an endless loop, you have onlywasted three CPU minutes.

CPU time is computer-dependent because different computers mayhave different CPU speeds. This is especially important in JES2 or JES3where the system may select the CPU on which to run your job. Code TIMEfor the slowest CPU. The time is not exact. The system only checks the timefor jobs every few seconds of clock time. If your job were the only job run-ning, it could execute several seconds longer than what you specified in theTIME parameter. When the system does check the time, the time is accurateonly plus or minus half a second.

Code TIME=1440 or TIME=NOLIMIT to eliminate any CPU time limit.This is used for jobs that stay resident for long periods. You can also codeTIME=MAXIMUM to allow the job to run the maximum amount of time,which is 357,912 minutes. A default time limit set by the installation iseffective if you omit the TIME parameter.

5.5.1 TIME on the JOB Statement

TIME coded on the JOB statement sets the limit for the entire job. It does notoverride the limits set on EXEC statements—it is applied independent ofthem. Coding TIME=1440 or TIME=NOLIMIT on the JOB statement nulli-fies any TIME parameters on the EXEC statements.

//RT452216 JOB (45992),'SMITH',CLASS=A,TIME=(10,30)

[The time limit for the job is 10 minutes, 30 seconds. The systemwill terminate the job sooner if a time limit set on an EXEC state-ment within the job is exceeded.]

//RT452216 JOB (45992),'SMITH',CLASS=A,TIME=9

[The system abnormally terminates the job after nine minutes ofCPU time. You may omit the outer parentheses if you don’t code theseconds.]

5.5.2 TIME on EXEC Statements

Rarely Used

The TIME parameter on an EXEC statement applies to specific steps. Thefollowing sets the limit to seven minutes.

//STEP2 EXEC PGM=ONE,TIME=7

You can add or override parameters to any step of a cataloged orinstream procedure by appending the stepname to the keyword on theEXEC statement that invokes the procedure. Here is an example:


// EXEC COB2UCLG,TIME.GO=4

[The system adds the TIME parameter to the GO step of theCOB2UCLG procedure. Any TIME parameter already coded on theGO step in the procedure is overridden. Other parameters on that orother steps in the procedure are not affected.]

You can code each parameter as many times as there are steps in theprocedure. However, the parameters for each step must appear on the EXECstatement in the order the steps appear in the procedure. If the COB2UCLGprocedure had a COB2 step, a LKED step, and a GO step, in that order, youmight code the following. You don’t have to place the parameters for eachstep on a separate continuation line, but it does make it easier to see whichparameters apply to a particular step.

// EXEC COB2UCLG,TIME.LKED=(,15),// TIME.GO=1

[This sets the limit 15 seconds in the LKED step and 1 minute in theGO step of the COB2UCLG cataloged procedure.]

If you omit the stepname, the general rule is that the parameter appliesto all steps of a procedure. The TIME parameter sets the total time for theentire job, nullifying those on individual job steps. The effect is the same asif you had coded TIME on the JOB statement.

// EXEC COB2UCLG,TIME=10

[The system overrides the first step with TIME=10. It overrides thesecond step with TIME set to a value of 10 minus however muchtime the first step used, and so on.]

To nullify an existing parameter within a step in a procedure, code thekeyword and appended stepname with just an equal sign:

// EXEC COB2UCLG,TIME.COB2=,TIME.GO=

[The system nullifies the TIME parameter in the COB2 and the GOsteps.]

5.6 MSGCLASS: SYSTEM MESSAGES

5.6.1 The MSGCLASS Parameter

Sometimes Used

MSGCLASS=class specifies the job scheduler message output class. Thesystem first writes print output onto direct-access storage, and output


writer procedures later write the output onto printers. The output class is asingle character, A to Z, or 0 to 9. The installation sets the default if youomit MSGCLASS—usually MSGCLASS=A, the printer.

Job scheduler messages include all messages not printed by the actualjob steps being executed, that is, JCL statements and error messages, deviceallocations, data set dispositions, and accounting information. Since theoperator must start output writers to specific output classes, specify anactive output class or the system will not print your output.

Your installation may establish separate output classes for high-volumeoutput, for special forms, or to separate output (all output of a specific classis printed together). You should seldom need to use a special output writerfor job scheduler messages. Here is an example of a JOB statement with aMSGCLASS parameter.

//RT452216 JOB (45992),'SMITH',CLASS=A,MSGCLASS=V

5.6.2 JCL Output

JCL statements submitted in the input stream are listed as follows. Thecharacters display in columns 1 to 3:

// Normal JCL statement from the input streamXX JCL statement from a cataloged procedure++ JCL statement from an instream procedureX/ DD statement in the input stream overriding a cataloged

procedure statement+/ DD statement in the input stream overriding an instream

procedure statement//* JCL statement that ends up being treated as a comment

statement. Also any JES statements from the input stream*** Comment statements from the input streamXX* Comment statement from a cataloged procedure++* Comment statement from an instream procedure

The output from your job is divided into two categories:

� Job scheduler messages, which include your JCL statements, errormessages, device allocations, data set disposition, and accountinginformation

� The output generated by the programs you execute with your JCL

The job scheduler message output you receive differs with the versionof the operating system you’re using and installations often customize it, so


it may be a little different from that which follows. You first receive a gen-eral summary of the job execution, called a job log, such as this:

15.49.390 JOBnnnnn jobname STARTED - CLASS class

[This tells you the time your job started, the job number assigned tothe job internally, your jobname, and the job class.]

15.50.040 JOBnnnnn IEF233A M 562,942731,,jobname,stepname15.50.130 JOBnnnnn IEF234E K 562,942731,,jobname,stepname

[For tapes, the preceding M tells you that tape 942731 was mounted.The K means it was kept—dismounted—at 15.50.13.]

If your job abnormally terminates (ABENDs), you get a system codemessage.

15.49.390 JOB 1724 RT452216 STARTED - CLASS A15.50.040 JOB 1724 IEF233A M 562,942731,,RT452216,STEP115.50.130 JOB 1724 IEF234E K 562,942731,,RT452216,STEP115.50.200 JOB 1724 IEF450I RT452216 STEP2 - ABEND S322 U000015.50.230 JOB 1724 RT452216 ENDED

There are thousands of possible messages, but most of them rarelyoccur. A listing of your JCL follows the job log, including a listing of anycataloged procedures you use. This listing can go on for pages. Only a fewstatements are shown here.

// RT452216 JOB (45992),'SMITH',CLASS=A// EXEC COB2UCLG

[The JCL statements you actually write—the JCL statements in theinput stream—display with // in the first two columns.]

XXCOB2 EXEC PGM=IGYCRCTL,PARM='OBJECT',REGION=1024KXXSYSPRINT DD SYSOUT=A

[If you invoke a cataloged procedure, the system lists the JCL state-ments from the EXEC invoking it. You can tell the cataloged proce-dure statements because they display with XX in the first twocolumns.]

Following the JCL will be a list of all the symbolic parameter substitu-tion done within the step of the cataloged procedure. The output might looklike this:

STMT NO. MESSAGE4 IEF653I SUBSTITUTION JCL - TIME=35 IEF653I SUBSTITUTION JCL - DISP=SHR� � �


When you override a DD statement in a cataloged procedure, both theoverriding statement and the original statement are shown. The catalogedprocedure statement displays with an X/ in the first two columns:

//LKED.SYSLMOD DSN=Y0000.PGM.LIB(COMPUTE),DISP=(OLD,PASS)X/SYSLMOD DD DSN=&&GOSET(GO),DISP=(NEW,PASS),X/ UNIT=SYSDA,SPACE=(CYL,(1,1,1))

Notice that you don’t get a display of how the overridden step actuallyappears to the system. The //SYSLMOD DD statement will be treated as if itwere written as

//SYSLMOD DD DSN=Y0000.PGM.LIB(COMPUTE),DISP=(OLD,PASS),// UNIT=SYSDA,SPACE=(CYL,(1,1,1))

You must visualize how the statement will appear. The system doesn’tdisplay it this way. The system also lists comment statements differently ifthey come from the input stream than if they come from a cataloged proce-dure. A comment statement such as this:

//* THIS IS A COMMENT.

appears with asterisks in the first three columns if it comes from the inputstream.

*** THIS IS A COMMENT.

It appears with XX* in the first three columns if it comes from a cata-loged procedure:

XX* THIS IS A COMMENT.

Then you get the allocation messages for each data set in the step:

IEF236I ALLOC. FOR RT452216IEF237I 452 ALLOCATED TO STEPLIBIEF237I 450 ALLOCATED TO SYSLINIEF237I JES2 ALLOCATED TO SYSPRINT

� � �

The 450 and 452 are hardware device addresses. From this, you knowthat the data set specified with a ddname of SYSLIN was placed on hard-ware address 450, which is a specific disk drive. The JES2 in place of thehardware address for SYSPRINT means that the printed output wasspooled rather than written to a particular hardware device. Then you get aline telling you the condition code for the step, such as this:

IEF142I RT452216 COB2 - STEP WAS EXECUTED - COND CODE 0012


Following the COND CODE message, you get a disposition message foreach data set used in the step.

IEF2851 SYS1.PROCLIB KEPTIEF285I VOL SER NOS= SYSPGM.IEF285I JES2.JOB00258.S00102 SYSOUTIEF285I SYS85178.T085249.RA000.RT452216.LOADSET PASSEDIEF285I VOL SER NOS= PACK12.

From this you know that a data set named SYS1.PROCLIB on a volumenamed SYSPGM was kept. The

JES2.JOB00258.S00102 for SYSOUT

represents your spooled output. The

SYS85178.T085249.RA000.RT452216.LOADSET

is the data set name made up for a temporary data set when you wroteDSN=&&LOADSET. The system makes up names like this, incorporatingthe date, time, and jobname to ensure that the temporary data set name isunique. The LOADSET data set was stored on PACK12 and was passed.

And, finally, you get a message telling you when the step started, whenit ended, how much virtual storage you used, and how much storage thesystem needed to execute the step.

IEF373I RT452216 /COB2/ START 85178.1549IEF374I RT452216 /COB2/ STOP 85178.1553

CPU OMIN 01.79SEC SRB OMIN 00.13SECVIRT 256K SYS 240

From this, you can tell that your COB2 step used 1.79 seconds of CPUtime. You used a virtual region size of 256K. It is this number that deter-mines what you must specify in the REGION parameter. Unfortunately, youdon’t get this number until you execute the job step.

The final item printed for the step is usually the accounting informationfor the job step. This will differ for each installation. All of the informationis then repeated for each step:

A list of your JCL statements interspersed with any cataloged procedurestatements you invoked

The allocation message for each data set

The condition code for the job step

The disposition messages for the data sets

The elapsed time, CPU time, and region used

Any accounting information


After you wade through all the job scheduler messages for the entire job,you finally get to the output generated by your job. You’ll likely use ISPF,described in Chapter 21, to examine job output. It allows you to view thedifferent JCL messages separately and then decide which, if any, you wantprinted, saving a lot of paper.

5.7 MSGLEVEL: PRINTING JCL STATEMENTS

Sometimes Used

MSGLEVEL=(jcl,allocations) specifies the printing of JCL statements andallocation messages. Allocation messages, if requested, appear at the begin-ning of each job step to show the allocation of data sets to devices and at theend of the step to show the data set disposition. Default values set by theinstallation are in effect if you omit MSGLEVEL. The values for jcl and allo-cations are as follows:

JCL Meaning0 Print only the JOB statement.1 Print all JCL in the input stream and all the JCL in any

cataloged procedures invoked, including the internalrepresentation of statements after symbolic parametersubstitutions. Also print all JES control statements.

2 Print only the JCL in the input stream and any JEScontrol statements.

Allocations Meaning0 Print only JCL messages but no allocation, JES, or

operator messages unless the job abnormallyterminates.

1 Print all allocation, JES, SMS, and operator messages.

In the following example, all JCL is printed. No allocation messages areprinted.

//RT452216 JOB (45992),'SMITH',CLASS=A,MSGLEVEL=(1,0)

In the next example, only the JCL in the input stream is printed. Print-ing of allocation messages depends on the default.

//RT452216 JOB (45992),'SMITH',CLASS=A,MSGLEVEL=2

Printing of JCL statements in the next example depends on the default.Allocation messages are printed.


//RT452216 JOB (45992),'SMITH',CLASS=A,MSGLEVEL=(,1)

The MSGLEVEL parameter can save paper or paging through outputfrom a terminal. After you debug a job, there may be no need to print all theJCL and allocation messages each time you run it. To reduce printing to aminimum, code MSGLEVEL=(0,0).

5.8 TYPRUN: SPECIAL JOB PROCESSING

Rarely Used

TYPRUN tells the system to not execute the job, either to check the JCL orto hold it for later execution. The general form is as follows:

COPYJCLHOLDHOLDSCAN

TYPRUN=

SCAN checks the JCL for syntax errors and suppresses execution of thejob. This checking does not include checking for duplicate data sets on vol-umes, insufficient direct-access storage space, or an insufficient region sizefor the job steps. You can use this to check for JCL syntax errors withoutexecuting the job.

//RT452216 JOB (45992),'SMITH',CLASS=M,TYPRUN=SCAN

HOLD holds a job in the input queue until the operator releases it. Besure to tell the operator when to release the job or it will just sit in the inputqueue. Use TYPRUN=HOLD when one job must not be run until another jobcompletes or to ensure that all mountable volumes are located before thejob is released for execution. However, the system keeps the operators busy,and you should minimize operator intervention.

//RT452216 JOB (45992),'SMITH',CLASS=M,TYPRUN=HOLD

JCLHOLD (JES2 only) also holds the job until the operator releases it,but differs from TYPRUN=HOLD in that the JCL is not checked until theoperator releases the job. Perhaps the only use for JCLHOLD is if a preced-ing job updates a cataloged procedure.

//RT452216 JOB (45992),'SMITH',CLASS=M,TYPRUN=JCLHOLD

COPY (JES2 only) lists or duplicates the lines placed after the JOB state-ment. The system routes the output to the message class specified by the


MSGCLASS parameter. Class A is traditionally the printer. You can use thisto list your JCL statements, but it is far easier to just use a text editor, suchas ISPF, to list your JCL statements.

//RT452216 JOB (45992),'SMITH',CLASS=A,MSGCLASS=A,TYPRUN=COPY[Place lines to be printed here.]

EXERCISES

1. Find out your installation’s requirements for the JOB statement, includ-ing the following parameters:

Jobname.

Acct-number,acct-information.

Name.

CLASS. Find out all the permissible job classes and the requirementsfor assigning a job to a class. Note the default job class.

MSGCLASS. List all the output classes and their use. Note the default.

MSGLEVEL. Note the default.

2. Make up a JOB statement and run one of the following jobs. Pick thelanguage with which you are most comfortable. Code the MSGCLASSparameter to produce both JCL and allocation messages.

� COBOL:// JOB statement// EXEC COBUCLG//COB.SYSIN DD *

IDENTIFICATION DIVISION.PROGRAM-ID. JCLTEST.ENVIRONMENT DIVISION.CONFIGURATION SECTION.INPUT-OUTPUT SECTION.FILE-CONTROL.

SELECT IN-FILE ASSIGN TO IN.SELECT OUT-FILE ASSIGN TO OUT.

DATA DIVISION.FILE SECTION.FD IN-FILE

RECORD CONTAINS 80 CHARACTERSBLOCK CONTAINS 0 RECORDS.

01 IN-REC PIC X(80).FD OUT-FILE

RECORD CONTAINS 80 CHARACTERSBLOCK CONTAINS 0 RECORDS.

01 OUT-REC PIC X(80).


TEAMFLY

Team-Fly®

WORKING-STORAGE SECTION.01 IN-OUT-REC PIC X(80).01 SWITCH-OFF PIC 9(1) COMP-3 VALUE 0.01 EOF-IN PIC X(1).PROCEDURE DIVISION.

OPEN INPUT IN-FILEOPEN OUTPUT OUT-FILEMOVE "N" TO EOF-INPERFORM READ-LOOP UNTIL EOF-IN = "Y"CLOSE IN-FILECLOSE OUT-FILESTOP RUN.

READ-LOOP.READ IN-FILE INTO IN-OUT-RECAT END

MOVE "Y" TO EOF-INNOT AT END

WRITE OUT-REC FROM IN-OUT-REC.END-READ.

//GO.IN DD *LINE 1LINE 2

/*//GO.OUT DD SYSOUT=A,DCB=LRECL=80

� PL/I:

// JOB statement// EXEC IBMZCPLG//PLI.SYSIN DD *TEST: PROC OPTIONS(MAIN);

DCL IN_OUT_REC CHAR(80);DCL EOF_IN CHAR(1);DCL (IN, OUT) FILE RECORD ENV(FB);/* START OF PROGRAM. */OPEN FILE(IN) INPUT,

FILE(OUT) OUTPUT;ON ENDFILE(IN) EOF_IN = 'Y';EOF_IN = 'N';DO UNTIL(EOF_IN = 'Y');

READ FILE(IN) INTO (IN_OUT_REC);IF EOF_IN ¬= 'Y'

THEN WRITE FILE(OUT) FROM (IN_OUT_REC);END;CLOSE FILE(IN),

FILE(OUT);END TEST;




� FORTRAN:// JOB statement// EXEC VSFCLG//FORT.SYSIN DD *100 INTEGER*4 INOUT(20)200 READ (1,250,END=500) (INOUT(I),I=1,20)250 FORMAT(20A4)300 WRITE (2,250) (INOUT(I),I=1,20)400 GO TO 200500 STOP

//GO.FT01F001 DD *LINE 1LINE 2

/*//GO.FT02F001 DD SYSOUT=A,DCB=LRECL=80

� C/C++:// JOB statement// EXEC CBCCLG//C.SYSIN DD *#include <stdio.h>#include <stdlib.h>void main(){FILE *in_file, *out_file;char in_out_rec[80];/* START OF PROGRAM. */in_file = fopen("IN","r");out_file = fopen("OUT","w");eof_in = 'Y';for (;;){

fread(in_file,1,80,in_out_rec);if (feof(in_file)) break;fwrite(out_file,80,1,in_out_rec);

}fclose(in_file);fclose(out_file);exit(0);}



3. Have someone explain all the system messages and the accounting infor-mation produced by your installation. Be sure you can tell how much itcosts to run the job if your installation has a charge-back system.

4. Rerun the job setting the time limit to one second.


CHAPTER 6

THE EXEC STATEMENT

Begin each job step with an EXEC statement that either names the programto execute (compiler, linkage editor, applications program, utility, and soon) or invokes a cataloged procedure. A job can contain several EXEC state-ments. A cataloged procedure may also contain several job steps, eachbeginning with an EXEC statement naming a program to execute. Theremay be as many as 255 EXEC statements (job steps) in a job, each followedby DD statements defining the data sets required by the job step. The gen-eral form of the EXEC statement is as follows:

procedurePGM=programPGM=*.referback

//stepname EXEC ,keyword-parameters

The stepname is the name you choose for the job step.

The procedure names the cataloged procedure to use.

The program names the program to execute.

The referback names a previous DD statement describing the program toexecute.

The keyword-parameters are the following:

Essential

COND specifies conditions for executing job steps if previous steps fail.

PARM passes parameters to a job step.

REGION specifies the region size to allocate to a job step.

77

Rarely Used

ACCT provides accounting information for the job step.

ADDRSPC prevents the step from being paged. //MEMLIMIT limits thetotal number of usable virtual pages above the line for a singleaddress space.

CCSID converts data on ISO/ANSI version 4 tapes from or to codedcharacter set identifier.

DYNAMNBR gives the number of dynamically allocated data sets.

MEMLIMIT limits the total number of usable virtual pages above theline for a single address space.

PERFORM assigns the step to a performance group for execution priority.

RD specifies the step restart conditions.

TIME imposes a CPU time limit on the job step.

You can code COND, REGION, and TIME on both the EXEC and JOB state-ments. Since you usually code TIME on the JOB statement, it was describedin the previous chapter. ADDRSPC, DYNAMNBR, MEMLIMIT, PERFORM,and RD are discussed in Chapter 16. CCSID is described in Chapter 12.

6.1 STEPNAME: NAME OF JOB STEP

Essential

//stepname EXEC names the job step. The stepname is an optional one toeight alphanumeric (A to Z, 0 to 9) or national (@ $ #) character name youselect. It must begin in column 3 with an alphabetic or national (A to Z, @$ #) character. Stepnames within a job or cataloged procedure should beunique so that you can reference them in other JCL statements. A stepnameis required if subsequent JCL statements refer to the job step or if you wishto restart the job from the step. You should give all EXEC statements in cat-aloged procedures a stepname so that you can override the statements. Yourinstallation may also have standards for stepnames.

//STEP10 EXEC//COMPUT EXEC//(GO EXEC Wrong! First character not alphabetic.

6.2 PGM: NAME OF PROGRAM

Essential

//stepname EXEC PGM=program names the program to execute. Programscan reside in a system library named SYS1.LINKLIB, in temporary libraries,


and in private libraries. A program is a load module and must be a memberof a partitioned data set on a direct-access volume. If the program name can-not be found in the libraries, the system abnormally terminates the job withan 806 completion code that is then listed with the system messages in yourprinted output.

6.2.1 Programs in System Library

A system library named SYS1.LINKLIB contains all the IBM-supplied sys-tem programs, such as compilers, linkage editor, and service programs.Installations add their own programs to SYS1.LINKLIB, carefully control-ling who gets to do this. If you add a program to a partitioned data set withthe same name as an existing program, the system replaces the old program.You execute a system program in SYS1.LINKLIB by naming the program onthe EXEC statement.

//STEP1 EXEC PGM=IEFBR14

In the absence of other instructions, the system searches SYS1.LINKLIBfor the program. IBM programs have names such as SYS1.LINKLIB to de-crease the likelihood of someone duplicating the name.

6.2.2 Programs in Private Libraries

You create members of private program libraries by saving the output fromthe linkage editor as explained in Chapter 18. Programs within a librarymust have unique names; programs in separate libraries may have the samename. You execute a program in a private library by either including a spe-cial //JOBLIB DD statement immediately after the JOB statement or placinga //STEPLIB DD statement somewhere after the EXEC statement. DD state-ment parameters are fully described in later chapters.

//RT452216 JOB (45992),'SMITH',CLASS=A//JOBLIB DD DSN=A1000.COMPLIB.LOAD,DISP=SHR//GO EXEC PGM=COMP1

6.2.3 JOBLIB DD Statement

The previous //JOBLIB DD statement defines A1000.COMPLIB.LOAD as aprivate library that presumably contains the program COMP1. You placethe JOBLIB statement immediately after the JOB statement and it is effectivefor all the job steps. You cannot place JOBLIB in a cataloged procedure. Ifthe system does not find the program in the named library, it searchesSYS1.LINKLIB. Concatenate the libraries if you need to execute programsfrom different libraries. The system searches the libraries in the order inwhich you name them in the DD statements.

THE EXEC STATEMENT 79

//RT452216 JOB (45992),'SMITH',CLASS=A//JOBLIB DD DSN=A1000.COMPLIB.LOAD,DISP=SHR// DD DSN=A1000.PRINTLIB.LOAD,DISP=SHR

[You concatenate A1000.PRINTLIB.LOAD to A1000.COMPLIB.LOAD by omitting the ddname on the DD statement. The systemtreats A1000.COMPLIB.LOAD and A1000.PRINTLIB.LOAD as ifthey were one data set.]

//STEP1 EXEC PGM=COMP1

[COMP1 might be a program contained in A1000.COMPLIB.LOAD.]

//STEP2 EXEC PGM=PRINTX

[PRINTX could be contained in A1000.PRINTLIB.LOAD.]

//STEP3 EXEC PGM=IEA001

[IEA001 could be a system program contained in SYS1.LINKLIB.]

6.2.4 STEPLIB DD Statement

The //STEPLIB DD statement, similar in form and function to the JOBLIBstatement, is placed after an EXEC statement and is effective only for thatjob step. STEPLIB provides an alternative means of specifying a privatelibrary.

//RT452216 JOB (45992),'SMITH',CLASS=A//STEP1 EXEC PGM=COMP1//STEPLIB DD DSN=A1000.COMPLIB.LOAD,DISP=SHR//STEP2 EXEC PGM=PRINTX//STEPLIB DD DSN=A1000.PRINTLIB.LOAD,DISP=SHR

If //JOBLIB and //STEPLIB DD statements are both included in a job, the//STEPLIB DD statement overrides the //JOBLIB DD statement for the step.To negate the effect of the //JOBLIB DD statement for a particular step, nameSYS1.LINKLIB on the //STEPLIB DD statement.

Like the //JOBLIB DD statement, the //STEPLIB DD statement may beconcatenated. Unlike the //JOBLIB DD statement, the //STEPLIB DD state-ment can be placed in a cataloged procedure. The following example showsthe use of both //JOBLIB and //STEPLIB DD statements.

//RT452216 JOB (45992),'SMITH',CLASS=A//JOBLIB DD DSN=A1000.COMPLIB.LOAD,DISP=SHR// DD DSN=A1000.PRINTLIB.LOAD,DISP=SHR//STEP1 EXEC PGM=ONE//STEPLIB DD DSN=A1000.LIB1.LOAD,DISP=SHR

[The system searches A1000.LIB1.LOAD and SYS1.LINKLIB in thatorder for a program named ONE.]


//STEP2 EXEC PGM=TWO

[The system searches A1000.COMPLIB.LOAD, A1000.PRINTLIB.LOAD, and SYS1.LINKLIB in that order for a program named TWO.]

//STEP3 EXEC PGM=THREE//STEPLIB DD DSN=SYS1.LINKLIB,DISP=SHR

[The system searches SYS1.LINKLIB for a program named THREE.]

//STEP4 EXEC COB2UCLG//COB2.STEPLIB DD DSN=A0000.LIB2.LOAD,DISP=SHR// DD DSN=A0000.LIB3.LOAD,DISP=SHR

[COB2UCLG is a cataloged procedure. The system searchesA0000.LIB2.LOAD, A0000.LIB3.LOAD, and SYS1.LINKLIB in thatorder for the program requested in the COB2 step of the procedure.The system searches A1000.COMPLIB.LOAD, A1000.PRINTLIB.LOAD, and SYS1.LINKLIB in that order for programs requested inany remaining job steps in the procedure.]

If several steps execute programs from the same library, use a //JOBLIBDD statement. But if the steps execute programs from different libraries, use//STEPLIB DD statements. There is another advantage to //STEPLIB DDstatements. You will often use a text editor to piece together steps from dif-ferent jobs to create a new job. When you use //STEPLIB DD statements,each step stands by itself. But if you use //JOBLIB DD statements, you mustremember to also copy the //JOBLIB DD statement, which may be locatedfar away from the EXEC statement and is easy to overlook.

6.2.5 Programs in Temporary Libraries

Often the output from one job step becomes the program to execute in a sub-sequent step. You usually execute the linkage editor load modules in a fol-lowing step. If you need the load module output from the linkage editoronly for the duration of the job, place it in a temporary library. Then, ratherthan naming the program to execute, it is easier to refer back to the DD state-ment describing the data set containing the program. The step executing theprogram need not immediately follow the step creating the program.

//LINK EXEC PGM=IEWL//SYSLMOD DD DSN=&&TEMP(GO),DISP=(NEW,PASS),

[The && mark the data set as temporary.]

// UNIT=SYSDA,SPACE=(1024,(200,20,1))//STEP2 EXEC PGM=IEA001//STEP3 EXEC PGM=*.LINK.SYSLMOD


The backward reference (or referback) names the step and then theddname of a DD statement within the step. If you invoke a cataloged proce-dure, the referback must include the cataloged procedure stepname. Sup-pose the previous LINK step was part of a cataloged procedure namedLKED:

//LKED PROC//LINK EXEC PGM=IEWL//SYSLMOD DD DSN=&&TEMP(GO),DISP=(NEW,PASS),// UNIT=SYSDA,SPACE=(1024,(200,20,1))

If the LKED procedure were invoked in the following code, you wouldrefer back to the step with *.STEP1.LINK.SYSLMOD.

//STEP1 EXEC LKED//STEP2 EXEC PGM=IEA001//STEP3 EXEC PGM=*.STEP1.LINK.SYSLMOD

The referback parameter is not limited to temporary data sets. You canexecute a program from any library using the referback.

//STEP1 EXEC PGM=IEFBR14//PROGRAM DD DSN=A1000.COMPLIB.LOAD(RUN6),DISP=SHR//STEP2 EXEC PGM=*.STEP1.PROGRAM

STEP2 executes a program named RUN6 contained in the A1000.COM-PLIB.LOAD cataloged data set. The PGM=IEFBR14 is not arbitrary; it is anull program contained in SYS1.LINKLIB. The program executes a singleend-of-program statement and is useful in writing a null job step to providea place for DD statements. As shown in subsequent chapters, you may wantto allocate space to a data set on a direct-access volume or delete data setswithout executing a program. Or, as the previous example shows, you maydefine data sets for subsequent referbacks. (The previous program couldalso be executed using a //JOBLIB DD or //STEPLIB DD statement.)

6.3 PROCEDURE: NAME OF CATALOGED PROCEDURE

Essential

//stepname EXEC procedure names a cataloged or instream procedure touse. Chapter 14 explains how to create procedures.

//STEP1 EXEC PLIXCLG//STEPA EXEC FORTGCL// EXEC COB2UC


[The stepname is often omitted on the EXEC statement invoking aprocedure.]

// EXEC PROC=COB2UC

[You can also code PROC=procedure, but almost no one does.]

6.4 KEYWORD PARAMETERS

Essential

If you code the keyword parameters (PARM, TIME, and so on) on the EXECstatement following the program or procedure name, they apply only to thestep being executed. The PGM parameter looks like a keyword parameter,but it is actually a positional parameter and must appear first.

//STEP1 EXEC PGM=STUDY,TIME=4,PARM=LIST

[The TIME and PARM parameters apply to STEP1 only.]

Or:

//STEP1 EXEC PGM=STUDY,PARM=LIST,TIME=4

[You can code the keyword parameters in any order following thePGM parameter or procedure name.]

You can add, override, or nullify parameters in each step of a proce-dure. This chapter describes the nuances of the individual parameters, andChapter 14 contains a full description of using procedures.

6.5 REGION SIZE

Essential

The REGION parameter specifies the amount of central storage a job stepcan use. REGION on the EXEC statement sets the limit for a specific step;REGION coded on the JOB statement sets the limit for all steps, overridingany region size on EXEC statements. The system uses a default region size set by the installation if you omit the REGION parameter. You codeREGION as

nKmK

REGION=


nK is the number of 1,024-byte areas of storage to allocate. The n canhave value of 1 to 2096128. The system allocates storage in 4Kincrements—if n is not a multiple of four, the system rounds it up tothe next multiple. (REGION=65K is treated as REGION=68K.)

nM is the number of units of MB units (1,048,576 bytes) and can beeven or odd. The n can be 1 to 2047. REGION=1M is the same asREGION=1024K.

If a job step requires more storage than was specified by REGION, thejob is abnormally terminated with an 804 or 80A completion code. Remem-ber that the system dynamically allocates storage, and that a job’s require-ment may increase during execution. Thus, the system may terminate a jobfor exceeding its region size after the step has begun execution. For exam-ple, a COBOL job might fit nicely into its region, do some calculations, andthen open a data set. Since COBOL obtains storage dynamically for buffers,the program could then abnormally terminate. Opening all data sets firstcould solve the problem, but the simplest solution is to allow a safety mar-gin in estimating region size.

The REGION parameter specifies both the normal region size (the appli-cation address space) and an extended region size (the data space). The sys-tem allocates the data space given by the extended region size one or moretimes as separate address spaces in virtual storage. The following occurswhen you request various region sizes:

REGION=0K or REGION=0M. The system allocates all available stor-age, both above and below the 16MB line. The storage availabledepends on the amount of address space required by the operatingsystem, and the resulting region size is unpredictable. No extendedregion size is set.

REGION=1K to 16384K or 1M to 16M. The system allocates the stor-age you request below the 16MB line as the application addressspace. The extended region size defaults to 32M.

REGION=16385K to 32768K or 17M to 32M. The system allocates allavailable storage below the 16MB line (16MB less the address spaceused by the operating system) as the application address space andsets the extended region size to 32M.

REGION=32769K to 2096128K or 33M to 2047M. The system allo-cates all available storage below the 16MB line as the applicationaddress space and sets the extended region size to the REGIONvalue.


TEAMFLY

Team-Fly®

6.5.1 REGION on EXEC Statements

The REGION parameter on the EXEC statement requests storage for indi-vidual steps.

//STEPA EXEC PGM=ONE,REGION=64K

[This allocates STEPA 64K of storage.]

// EXEC COB2UCLG,REGION.LKED=128K,REGION.GO=64K

[This allocates the LKED step of the COB2UCLG procedure 128K ofstorage and the GO step 64K.]

// EXEC COB2UCLG,REGION=1920K

[This allocates each step in the COB2UCLG procedure 1,920K ofstorage.]

6.5.2 REGION on the JOB Statement

Rarely Used

The REGION parameter on the JOB statement must allow enough storage forthe maximum region required by any step. For example, a COBOL job mayrequire 1,020K to compile, 104K to link-edit, and 1,920K to execute. AREGION parameter on the JOB statement must allow enough storage for thelargest step (1,920K).

//RT452216 JOB (45992),'SMITH',CLASS=A,REGION=1920K

[This allocates all steps within the job 1,920K. The system ignoresany REGION parameters on EXEC statements within the job.]

6.6 COND: CONDITIONS FOR BYPASSING JOB STEPS

Essential

Each job step may pass a return code to the system when it reaches com-pletion. The COND parameter lets the execution of steps depend on thereturn code from previous steps. For example, if a compilation fails, thereis no need to attempt subsequent linkage editor or execution steps in thejob. If you omit the COND parameter, the system makes no tests and exe-cutes the steps normally. The system ignores a COND on the first EXEC stepof a job because there is no previous step to test.

Two different codes are returned in z/OS. An application program canreturn a code at the end of a step (termed a return code or a completioncode). Subsequent job steps can test the return code from a previous step by


use of the COND parameter. The operating system also returns a systemcompletion code at the end of the job.

6.6.1 System Completion Codes

The system code is a three-digit code prefixed with an S. The usual value is000, indicating normal completion. If the system or operator must termi-nate the job abnormally, the system completion code will indicate the rea-son. Table 6.1 shows the most common completion codes.


TABLE 6.1 Common System Completion Codes

Code Description/Solution

0C1 Invalid instruction. Usually caused by a wild branch into a data area of your programor by data clobbering the instruction area of the program.

0C4 Protection exception. Usually caused by an invalid index or subscript to an array. An0C4 means you tried to access storage belonging to another user. (The 0C5 followingmeans you tried to access storage that doesn’t exist on the computer.)

0C5 Invalid address. Usually caused by a wild branch or a wild index used with an array.

0C7 Invalid data. Usually caused by invalid alignment of data or packed decimal databeing clobbered.

122 Computer operator canceled the job. Most often, this is because the job requested anunavailable resource. The typical case is asking for a tape volume that can’t be found.

222 The TSO user (or sometimes the computer operator) canceled the job. Since you areusually the TSO user, you will know why.

322 Exceeded the CPU time limit. Make sure that the job isn’t in an endless loop and thenincrease the TIME parameter on the JOB or EXEC statement.

722 Output limit exceeded. Check that your program is not in a loop and that you want allthis output and then increase the limit parameter and rerun.

804 Exceeded the region size. Increase the REGION parameter for the step that ABENDed.

806 Couldn’t find the program to execute. Make sure that you used the proper JOBLIB orSTEPLIB statement and that the PGM keyword on the EXEC statement names the pro-gram you want.

80A Essentially the same as 804.

822 Region size requested not available. You asked for more space in your REGION param-eter than is available on the system.

B37 Disk volume is out of space. Request a different volume or request several volumes.

E37 Exceeded the direct-access storage space. Increase the amount of space in the SPACEparameter.

Look up additional codes in the IBM System Codes manual. An identi-fying number, such as IEF450I, also precedes each JCL error message. Youcan look this number up in the IBM System Messages manual for additionalinformation about the error.

The system completion code usually appears only if a step abnormallyterminates. The following is a typical message:

IEF450I jobname stepname - ABEND=Snnn Unnnn REASON=mmmmmm

6.6.2 Return Codes

The return code from a step shows up in your JCL listing as the nnnn in thismessage:

IEF142I jobname stepname - STEP WAS EXECUTED - COND CODE nnnn

Application programs can issue return codes as follows:

COBOL: MOVE return-code TO RETURN-CODE

FORTRAN: STOP return-codePL/I: CALL PLIRETC(return-code);

C/C++: exit(return-code);

Assembler-Language: Place the return code in general register 15.

Return codes range from 0 to 4,095. The IBM conventions for returncode values follow, and all the IBM compilers, linkage editors, and utilityprograms follow this convention, as do most application programmers.

0 No errors or warnings detected.4 Possible errors (warnings) detected but execution should be

successful.8 Serious errors detected; execution likely to fail.

12 Severe error; execution impossible.16 Fatal error; execution cannot continue.

6.6.3 Testing Return Codes

COND on an EXEC statement can test any or all return codes from previoussteps. If any test is satisfied, the system bypasses the step making the test.COND on the EXEC statement can also make step execution depend on theabnormal termination of previous steps.

The COND parameter is extremely difficult to code. Consequently, IBMhas provided a replacement in the form of the IF/THEN/ELSE/ENDIF state-ment construct. If you have the choice, use the IF/THEN/ELSE/ENDIF state-


ment construct because it is infinitely easier to code and far less errorprone. However, you still need to know about COND parameters even if youdon’t code them because they will appear in many JCL procedures.

6.6.4 COND on EXEC Statements

Code COND on the EXEC statement as

COND=((number,comparison),...,(number,comparison))

You can include one to eight return code tests. Each number (valuesfrom 0 to 4095) is compared against the return code from each prior step.The system bypasses the step if any comparison is true. (Remember this as“Don’t do if true.”) In the following example, the system bypasses STEP3 if4 is less than the return code of any previous step—STEP1 or STEP2. Youmay omit the outer parentheses if there is only one test.

//STEP1 EXEC PGM=ONE//STEP2 EXEC PGM=TWO//STEP3 EXEC PGM=THREE,COND=(4,LT)

The comparisons are

GT Greater than LE Less than or equalLT Less than EQ EqualGE Greater than or equal NE Not equal

For example, COND=(8,LT) is read “if 8 is less than the return code fromany previous step, bypass this step.” COND parameters are difficult to readand write because their written expression is the reverse of the way wethink. The COND may be easier to understand when stated in the reverse:“Execute the step if all the return codes from previous steps have values 0to 8.” Be careful writing COND. What you write often turns out to be theopposite of what you want.

To apply the test to the return code from a particular step, you code(number,comparison,stepname). In the following example, the system by-passes STEP3 if 4 is greater than the return code from STEP1.

//STEP1 EXEC PGM=ONE//STEP2 EXEC PGM=TWO//STEP3 EXEC PGM=THREE,COND=(4,GT,STEP1)

If you want to apply the test to the return code from a particular stepwithin a procedure, code (number,comparison,stepname.procstep). In thenext example, the system bypasses STEPD if 4 is less than the return codefrom the GO step of the COB2UCLG procedure executed by STEPC.


//STEPC EXEC COB2UCLG//STEPD EXEC PGM=REPORT,COND=(4,LT,STEPC.GO)

Now suppose you need to override a step within a procedure to specifythe COND parameter for it. Code COND.procstep=(number,comparison).

//STEPC EXEC COB2UCLG,COND.GO=(4,LT)

[The system overrides the GO step of the COB2UCLG cataloged pro-cedure and replaces it with COND=(8,LT). The system will nowbypass the GO step if 8 is less than the return code issued by anyprevious step.]

//STEPE EXEC COB2UCLG//STEPF EXEC COB2UCLG,COND.GO=(4,LT,STEPE.GO)

[The system overrides the GO step of the COB2UCLG cataloged pro-cedure invoked by STEPF and replaces it with COND=(4,LT,STEPE.GO). The system will now bypass the GO step of the COB2UCLGprocedure invoked by STEPF if 4 is less than the return code issuedby the GO step of the same COB2UCLG procedure invoked bySTEPE.]

//STEPA EXEC PGM=ONE//STEPB EXEC PGM=TWO//STEPC EXEC PGM=THREE,COND=((1,EQ,STEPA),(4,EQ,STEPB))

[The system bypasses STEPC if 1 equals the return code issued bySTEPA or if 4 equals the return code issued by STEPB.]

//STEPD EXEC COB2UCLG,COND.GO=((12,GE),// (8,EQ,STEPB),(4,EQ,STEPA))

[The system bypasses the GO step of the COB2UCLG procedure if 12is greater than or equal to the return code of any previous step, if 8is equal to the return code of STEPB, or if 4 is equal to the returncode of STEPA. You can continue the COND parameter onto a newline after a complete test, including the comma that follows it.]

//STEPE EXEC COB2UCLG,COND=(4,NE,STEPD.GO)

[Any step in the COB2UCLG procedure is bypassed if 4 is not equalto the return code of the GO step in the COB2UCLG cataloged pro-cedure invoked by STEPD.]

//STEPF EXEC PGM=FOUR,COND=(4095,LT)

[STEPF executes regardless of the return codes. Return codes can-not exceed 4,095 so the condition can never be met.]

//STEPG EXEC PGM=FIVE,COND=(0,LE)

[The system bypasses STEPG regardless of the return codes. Returncodes cannot be less than zero and so the condition is always met.]


If the system does not execute a step, it does not issue a return code. Ifa subsequent step tries to test the return code from a bypassed step, the sys-tem does not perform the test. If the job has a JCL error, the system will notattempt to execute it. If a step abnormally terminates, the system does notissue a return code and proceeds to bypass all subsequent steps unless youcode the EVEN or ONLY subparameters. COND=EVEN executes the stepeven if previous steps abnormally terminate. COND=ONLY executes thestep only if previous steps abnormally terminate.

You can code EVEN or ONLY with up to seven other return code tests inthe same step, but not with each other because EVEN and ONLY are mutuallyexclusive. The step making the test COND=((EVEN,(8,EQ),(7,LT,STEPA)) isbypassed if 8 equals the return code from any previous step or if 7 is less thanthe return code from STEPA; if not, it is executed even if previous stepsabnormally terminate. The order in which you code the individual tests doesnot matter. COND=((2,EQ),EVEN) and COND=(EVEN,(2,EQ)) are equivalent.

The system makes the test for EVEN or ONLY only if the job and the stepon which they are coded go into execution. JCL errors, the inability to allo-cate space on I/O devices, operator cancellation, or expiration of time allcause the system to bypass the remaining job steps regardless of the CONDparameters. In this example, the system executes the LKED step of theCOB2UCLG procedure EVEN if a previous step abnormally terminates. Thesystem bypasses the GO step if 4 equals the return code of the LKED step; itthen executes the step ONLY if a previous step has abnormally terminated.

//STEPA EXEC PGM=ONE//STEPB EXEC COB2UCLG,COND.LKED=EVEN,// COND.GO=((ONLY,(4,EQ,STEPB.LKED))

For most steps that depend on the successful execution of a program, areturn code of 4 or less means that a previous step has executed success-fully, perhaps with only some warning messages. For this usual case, youcode the COND parameter as

//stepname EXEC PGM=program,COND=(4,LT)

[The system bypasses the step if 4 is less than the return code fromall previous steps. This executes the step if no previous step hasissued a return code of greater than 4. You could also write this asCOND=(5,LE).]

As an example of the use of the COND parameter, we’ll code the equiv-alent of IF/THEN/ELSE/ENDIF logic for executing job steps. In the follow-ing example, STEPA is executed. Then if the return code is 0 to 4, STEPB isexecuted; otherwise, STEPC is executed. In either case, execution resumeswith STEPD. The logic is shown in Figure 6.1.


//STEPA EXEC PGM=UPDATE� � �

//STEPB EXEC PGM=CLEANUP,COND.STEPA=(4,LT)

[The system bypasses this step if the return code from STEPA isgreater than 4. That is, it executes this step if the return code fromSTEPA is 0 to 4. The step might produce a report or clean up afterthe successful completion of STEPA.]

//STEPC EXEC PGM=ERROR,COND.STEPA=(4,GE)

[The system bypasses this step if the return code from STEPA is 4 orless. That is, it executes the step if the return code from STEPA isgreater than 4. The step might perform some error analysis or printdebugging information if STEPA doesn’t execute properly.]

//STEPD EXEC PGM=WHATEVER

[The system executes this step after it executes either STEPB orSTEPC.]

There is a further example of the use of the COND parameter to selec-tively control the execution of job steps in Chapter 14.

6.6.5 COND on the JOB Statement

Rarely Used

When you code the COND parameter on the JOB statement, the systemapplies the tests to each job step, and if any test is true, it bypasses all subse-quent steps. The system performs the tests for the COND parameters on theJOB statement before any COND parameters on EXEC statements. You rarelyuse the COND parameter on the JOB statement because you usually want towrite it for individual job steps. You code COND on the JOB statement as

COND=((number,comparison),...,(number,comparison)).


FIGURE 6.1 IF/THEN/ELSE logic in job steps.

Step A

Step A

Step CStep B

Return code > 4Return code <= 4

You cannot append a stepname to COND or code EVEN or ONLY. Thesystem makes the tests at the end of each step against the return code issuedby the step. If any test is satisfied, it bypasses all the remaining steps. Thecomparisons are the same as for the EXEC statement, and you can code asmany as eight tests.

//RT452216 JOB (45992),'SMITH',CLASS=A,COND=((4,GT),(6,LT))

[Terminate the job if 4 is greater than a return code or if 6 is less thana return code (that is, terminate the job unless the return code equals4, 5, or 6).]

//RT452216 JOB (45992),'SMITH',CLASS=A,// COND=((4,EQ),(5,EQ),(6,EQ))

[Terminate the job if a return code equals 4, 5, or 6. This is just theopposite of the previous JOB statement.]

6.7 IF/THEN/ELSE/ENDIF STATEMENT CONSTRUCT

Essential

The IF/THEN/ELSE/ENDIF statement construct provides a simple means ofselectively executing job steps and eliminates the need to struggle with theCOND parameter. You code the construct as follows:

// IF (relational-expression) THEN

[JCL statements to execute if the relational expression is true.]

// ELSE

[JCL statements to execute if the relational expression is false.]

// ENDIF

The THEN and ENDIF are always required. The ELSE is optional. Youcan therefore code the following:

// IF (relational-expression) THEN

[JCL statements to execute if the relational-expression is true.]

// ENDIF

Place the IF before any EXEC statement (except the first EXEC). Both theTHEN and ELSE can be null, but not both. If not null, the THEN (and ELSEif one is coded) must always contain at least one EXEC statement. You canplace as many statements as needed following a THEN or ELSE. JOB,


JCLLIB, JOBCAT, JOBLIB, SYSCHK, and XMIT JCL statements can’t followTHEN or ELSE. PROC, PEND, JES2 and JES3 statements, JCL commandstatements, //* comment statements, INCLUDE statements, /* delimiterstatements, // null statements, and SET statements can be placed in a THENor ELSE, but they are executed unconditionally.

You code the relational-expression as

(RC comparison number)

[The system compares the highest return code (RC) from any previ-ous executed step to the number, which can be 0 to 4095.]

(stepname.RC comparison number)

[The system compares the return code from the step named to thenumber. You can also code stepname.procstep to specify a stepwithin a procedure.]

Table 6.2 shows the comparison operations.NOT has the highest priority, the comparisons the second highest, and

AND and OR have the lowest. The system evaluates the relational expres-sion to yield a true or false value. Here is an example:

// IF (STEPA.RC GE 4 AND STEPA.RC LE 6) THEN

[JCL statements to execute if the return code (RC) from STEPA is 4, 5, or 6.]

// ELSE

[JCL statements to execute if the return code from STEPA is not 4, 5, or 6.]

// ENDIF


TABLE 6.2 IF/THEN/ELSE/ENDIF Comparison Operations

Mnemonic Operator Character Operator Description

NOT ¬ Logical notEQ = Equal toNE ¬= Not equal toGT > Greater thanLT < Less thanGE >= Greater than or equalNL ¬< Not greater than. Same as GELE <= Less than or equalNG ¬> Not greater than. Same as LEAND & Logical andOR | Logical or

You can write operations in mnemonic or character form: (RC GT 4) or(RC>4). Notice that if you use the mnemonic, you must leave blanks beforeand after it. Blanks are not needed for the character form. (The & (AND) and| (OR) are exceptions and must also be set off by blanks. To simplify things,set all logical operators off with blanks.) You can use parentheses to specifythe hierarchy:

// IF ((RC GE 1 AND RC LE 4) OR (RC GE 12 AND RC LE 14)) THEN

[JCL statements to execute if the return code is 1, 2, 3, 4, 12, 13, or 14.]

The NOT operator can be coded outside of parentheses to reverse thetrue/false result.

//IF NOT ((RC GE 1 AND RC LE 4) OR (RC GE 12 AND RC LE 14)) THEN

[JCL statements to execute if the return code is anything except 1, 2,3, 4, 12, 13, or 14.]

To continue the IF/THEN statement, break the line wherever a blankcan be coded, code // on the next line and continue somewhere in columns4 through 16. Here is an example:

// IF ((STEPA.RC GE 1 AND STEPA.RC LE 4) OR (STEPA.RC GE 12// AND STEPA.RC LE 14)) THEN

The relational expression can contain any or all of the following:

(RC comparison value)

[Test the highest return code from all previous steps.]

(stepname.RC comparison value)

[Test return code of a particular previous step.]

(stepname.procstepname.RC comparison value)

[Test return code of a particular previous step in a cataloged proce-dure.]

ABEND

[Test if an ABEND occurred in any previous step.]

stepname.ABEND

[Test if an ABEND occurred in a particular previous step.]

stepname.procstepname.ABEND

[Test if an ABEND occurred in a particular previous step in a cata-loged procedure.]

You can code either ABEND or ABEND=TRUE. For the reverse, to testthat an ABEND didn’t occur, code ¬ABEND or ABEND=FALSE.


TEAMFLY

Team-Fly®

ABENDCC=SxxxABENDCC=Uxxxx

[Test the most recent system completion code (Sxxx), such asABENDCC=S80A or the most recent user ABEND completion code(Uxxxx).]

stepname.ABENDCC=Sxxxstepname.ABENDCC=Uxxxx

[Test the system or user completion code for a particular previousstep.]

stepname.procstepname.ABENDCC=Sxxxstepname.procstepname.ABENDCC=Uxxxx

[Test the system or user completion code for a particular previousstep in a cataloged procedure.]

stepname.RUN

[Test that a particular previous step executed.]

stepname.procstepname.RUN

[Test that a particular previous step in a cataloged procedure exe-cuted.]

You can code either RUN or RUN=TRUE. For the reverse, to test that astep did not execute, code ¬RUN or RUN=FALSE. The following exampleillustrates how you might use RUN.

// IF (STEPA.RUN) THEN//STEP1 EXEC PGM=ONE// ENDIF// IF (STEP1.RUN=FALSE) THEN//STEP2 EXEC PGM=TWO// ENDIF

Same as coding:

// IF (STEPA.RUN) THEN//STEP1 EXEC PGM=ONE// ELSE//STEP2 EXEC PGM=TWO// ENDIF

When the system tries to compare the return code of particular previousstep, it yields a value of false if the step didn’t execute.

The following example uses the IF/THEN/ELSE/ENDIF construct toexecute the same steps as the example given for the COND parameter illus-trated in Figure 6.1. First, STEPA is executed. Then if the return code is 0 to


4, the system executes STEPB; otherwise, it executes STEPC. In either case,execution resumes with STEPD. Notice how much simpler this is to codethan using COND.

//STEPA EXEC PGM=UPDATE� � �

// IF (STEPA.RC LE 4) THEN//STEPB EXEC PGM=CLEANUP

[The system executes this step for return codes of 0 to 4.]

// ELSE//STEPC EXEC PGM=ERROR// ENDIF//STEPD EXEC PGM=WHATEVER

[The system executes this step after it executes either STEPB orSTEPC.]

The EXEC statements within the IF/THEN/ELSE/ENDIF construct mayalso contain COND parameters. The system examines the COND parameterto determine whether to execute the step only if flow reaches the EXECstatement. The following example illustrates this:

// IF (STEP6.RUN=TRUE)// THEN//STEP10 EXEC PGM=TEN,COND=(4,NE,STEP7)// ENDIF

[The system executes STEP10 only if STEP6 executed and if STEP7issued a return code of 4.]

One final note. You can nest IF/THEN/ELSE/ENDIF statements up to 15levels. For example:

// IF (STEP6.RC GE 4 AND STEP6.RC LE 10) THEN//STEP10 EXEC PGM=TEN

[Execute if return code from STEP6 is 4 to 10.]

// IF (STEP6.RC EQ 8) THEN//STEP11 EXEC PGM=ELF

[Execute if return code from STEP6 is 8.]

// ENDIF

[This ends the IF preceding STEP11. There is no ELSE.]

// ELSE//STEP12 EXEC PGM=ZWOLF

[The system executes STEP12 if it did not execute STEP10.]


// ENDIF

[This ends the IF preceding STEP10.]

You can nest either the THEN or ELSE. Just be careful to close off eachnested IF/THEN/ELSE with an ENDIF.

6.8 PARM: PASS PARAMETERS TO JOB STEPS

Essential

PARM=value passes control information to the job step when the step is ini-tiated. This can be extremely useful for passing run-time information to anapplication program. For example, you might design the program withbuilt-in debugging statements, and then pass a switch to the program withthe PARM parameter to turn the debugging on and off so that the debuggingstatements can be left in a production program.

//STEP1 EXEC PGM=ONE,PARM=DEBUG

There may be 1 to 100 characters of data in the PARM. If the value con-sists of several subvalues separated by commas, or if it contains specialcharacters such as blank , . / ‘) (* & + − =, enclose the value in apostrophes.(For simplicity, enclose the value in apostrophes.) Code a legitimate apos-trophe as two consecutive apostrophes:

PARM='O''CLOCK,XREF,SIZE=100'.

You can use parentheses to enclose several subvalues. You must encloseany subvalues containing special characters in apostrophes:

PARM=('O''CLOCK',XREF,'SIZE=100')

Code an ampersand as two consecutive ampersands unless it designatesa symbolic parameter in a procedure. If you must continue a parameter ontothe next line, enclose the subvalues in apostrophes and interrupt the linefollowing a complete subvalue and its comma but before column 72. Thencontinue on the next line:

//STEP1 EXEC PGM=ONE,PARM=('K=6',// FIVE,'I=3','J=4',SEVEN)

[K=6, FIVE, I=3, J=4, and SEVEN are passed to the step.]

//STEP2 EXEC COB2UCLG,PARM=STOP

[The system passes STOP to the first step of the procedure. It thennullifies any PARM values in subsequent steps within the proce-dure.]


//STEP3 EXEC COB2UCLG,PARM.LKED=MAP,PARM.GO=LIST

[The system passes MAP to the LKED step and LIST to the GO stepof the procedure.]

You must know what values the processing program expects to bepassed to it. If you omit PARM, no values are passed. Programs supplied byIBM, such as the compilers and linkage editor, expect the value to representvarious run options. Programs written in COBOL, C/C++, PL/I, and Assem-bler Language can accept PARM values as follows:

COBOL//STEP1 EXEC IGYWCLG,PARM.GO='string'

� � �

LINKAGE SECTION.01 PARM05 LNGTH PIC S9(4) BINARY.05 VAL PIC X(100).PROCEDURE DIVISION USING PARM.

The length of the string is stored in LNGTH, and the string is storedin VAL. You can use any valid data names in place of PARM,LNGTH, and VAL.

PL/I//STEP1 EXEC IBMZCPLG,PARM.GO='/string'name: PROC(PARM) OPTIONS(MAIN);DCL PARM CHAR(100) VAR;

The system stores the string in PARM and sets the PARM length tothe length of the string. You can use any valid data name in place ofPARM.

C/C++//STEP1 EXEC CBCCLG,CPARM='NOARAGPARSE or

ARGPARSE',,PARM.GO='string'

[CBCCLG is for C++. For C, the procedure name is EDCCPLG.]int main(int argc, char *argv[] [[]]) {

� argc contains the number of arguments stored in the argv stringarray. The string may be untokenized or tokenized.

� NOARGPARSE (Untokenized): argc always contains 2, argv con-tains a pointer to the entire string.

� ARGPARSE (Tokenized): argc contains the number of string ele-ments stored in argv, argv contains a pointer to the command linethat invoked the program, argv[][1[]] to argv[][argc-1[]] containthe strings. The system breaks the string into separate substrings(tokenized) when it encounters special characters, such as blanksand parentheses.

Assembler Language//STEP1 EXEC ASMHCLG,PARM.GO='string'


When the system gives control to the program, general register 1points to a full word containing the address of an area in storage.The first half word of this area contains the number of characters inthe string; the remainder of the area contains the string itself.

IBM processing programs may have three levels of values: default val-ues generated into the system, PARM values in cataloged procedures thatoverride the defaults, and PARM values coded on EXEC statements invok-ing the procedures. If you override a single PARM value in a procedurestep, the system nullifies all PARM subparameters in the procedure stepand reestablishes the default values. For example, a COBOL II compile pro-cedure might contain:

//IGYWCLG PROC//COBOL EXEC PGM=IGYCRCTL,PARM='LIST,MAP',REGION=1024K

If you override the PARM in the procedure, the system overrides all thePARM subparameters:

// EXEC IGYWCLG,PARM.COBOL='OBJECT'

The system replaces the LIST and MAP subparameters with OBJECT,and the COBOL step appears in the run as

//COBOL EXEC PGM=IGYCRCTL,PARM='OBJECT'

6.9 ACCT: JOB STEP ACCOUNTING INFORMATION

Rarely Used

Your installation will tell you if accounting information is needed for jobsteps. To supply step accounting information, you write ACCT=(acct-information), where the accounting information may be one or more sub-parameters separated by commas: ACCT=(2645,30,17). You may omit theouter parentheses if there is only one subparameter: ACCT=2645. If subpa-rameters contain any special characters except hyphens—blank , . / ’) (* &+ =—enclose the subparameters in apostrophes. (For simplicity, enclose thesubparameter in apostrophes.) Code a legitimate apostrophe as two consec-utive apostrophes: ACCT=(2645,‘O’’CLOCK’,‘T=7’).

//STEP1 EXEC PGM=ONE,ACCT=(24,53// 45,'A=17')

[You can continue accounting information onto another line byinterrupting it after a complete subparameter, including the commathat follows it.]


// EXEC COB2UCLG,ACCT=2647

[The accounting information applies to each step of the COB2UCLGprocedure.]

// EXEC COB2UCLG,ACCT.COB2=('T=7','K=9'),ACCT.GO=('T=9')

[T=7 and K=9 are supplied to the COB2 step; T=9 is supplied to theGO step of the COB2UCLG procedure.]

6.10 SYSUDUMP, SYSABEND, SYSMDUMP: ABNORMAL TERMINATION DUMPS

Rarely Used

Sometimes it is difficult to find the source of an error when a program abnor-mally terminates. (This is called an ABEND, and means abnormal end.)

� The //SYSUDUMP DD statement provides a formatted dump of theprogram area in hexadecimal, including the contents of registers, atraceback of subroutines called, and information about all the datasets used.

� The //SYSABEND DD statement additionally dumps the systemnucleus—the resident portion of the operating system.

If you want a storage dump, use SYSUDUMP unless you have a partic-ular reason for examining the nucleus. A storage dump can be extremelyvaluable when you need it, but wastes paper and printer time if you do not need it. You should never need to use SYSUDUMP and rarely needSYSABEND.

Place either the //SYSUDUMP or //SYSABEND DD statement after eachEXEC statement in a step in which a dump is wanted. If both SYSUDUMPand SYSABEND appear in one step, the last to appear is effective. A dumpresults only if the step abnormally terminates.

//STEP1 EXEC PGM=ONE//SYSUDUMP DD SYSOUT=A//STEP2 EXEC PGM=TWO//SYSABEND DD SYSOUT=A

For cataloged procedures, append the name of the step for which adump is wanted. See Chapter 8 for a complete description of adding DDstatements to procedures.


// EXEC COB2UCLG� � �

//GO.SYSUDUMP DD SYSOUT=A

[The //SYSUDUMP DD statement is effective for the GO step of theCOB2UCLG procedure.]

SYSUDUMP and SYSABEND are both DD statements whose parametersare described in later chapters. Although many special parameters may becoded on the DD statement if the dump is to be saved on disk or placed ontape, SYSOUT=A usually suffices if the dump is to be printed. On a 3800printer, you can request the dump to be printed in high-density format (204characters per line) by coding CHARS=DUMP on the DD statement: Print 10lines per inch by coding FCB=STD3.

//SYSUDUMP DD SYSOUT=A,CHARS=DUMP,FCB=STD3

There is also a //SYSMDUMP DD statement of use mainly for systemprogrammers that dumps the system nucleus and program area but doesn’tformat it. You must write it to disk or tape. A computer program can thenread the dump, but you can’t print the dump.

//SYSMDUMP DD DSN=A1000.SAVE.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,SPACE=(TRK,(20,5))

EXERCISES

Execute the compile, link-edit, and go procedure from Chapter 5 twicewithin the same job. This will require the following JCL statements:

//JOB statement//STEP1 EXEC procedure//stepname.SYSIN DD *[Source statements]/*//GO.OUT DD//GO.IN DD ...[Lines of data]//STEP2 EXEC procedure//stepname.SYSIN DD *[Some source statements]/*//GO.OUT DD ...//GO.IN DD ...[Lines of data]/*


Before you run the job, modify the JCL to do the following:

� In STEP1 set the PARM values of the LKED step to be XREF and LIST.� Include a //SYSUDUMP DD statement in STEP1 for the GO step.� Override all the steps in STEP2 to execute even if a STEP1 step

abnormally terminates.� Set the region size of STEP1.GO to 480K and of STEP2.GO to 482K.


CHAPTER 7

THE DD STATEMENT

7.1 OVERVIEW OF DATA SETS

Essential

DD statements describe data sets. Before explaining how to code a DD state-ment, you need some overview of the different types of data sets in z/OS.z/OS provides a variety of data sets that are evolving, with new featuresadded and older forms retained for compatibility. Many of the new featurescome about through SMS. For some, SMS need be active only at your instal-lation. Others are available only for an SMS-managed data set. Your instal-lation will tell you whether SMS is active at your installation. When SMSis active, your installation can set various defaults for non-SMS-manageddata sets that are normally associated with SMS-managed data sets. ForSMS-managed data sets, your installation will tell you the different storage,management, and data classes available and what options apply to each.For reference, Table 7.1 shows the various types of data sets, what they canbe stored on, how you specify them, the maximum number of volumes onwhich they can reside, and whether they must be SMS-managed.

In addition, you can compress data in the following types of data sets.Compressing data reduces the storage requirements and the I/O processingtime by a factor of roughly three at some expense in CPU time to do thecompression and decompression.

Extended sequential by selecting the appropriate DATACLAS.

Tapes on mountable volumes contained in an automatic tape librarydataserver by coding TRTCH=COMP. (An installation can makecompaction the default for such tapes.)

VSAM data sets with extended format KSDS.

Selecting the type of data set appears intimidating, but it is actuallyquite simple.

103

� The choice of whether data sets should be SMS-managed is usuallymade by your installation. You make data sets be SMS-managedwhen you create them by coding the STORCLAS DD parameterdescribed in Chapter 11.

� Choose extended sequential for sequential data sets. If you write totape, the system will write it as a normal sequential data set, so don’tworry.

� Choose PDSE for program libraries.� Use VSAM for data sets requiring random access.� HFS and PIPE are for UNIX-type files.� VIO is convenient for temporary data sets.

The remainder of this chapter focuses on non-SMS-managed data sets,but much of the information is also needed for SMS-managed data sets. Youdescribe each data set used in a step by placing a DD (data definition) state-ment after the EXEC statement for each data set. The DD statement namesthe data set, gives the data set disposition, requests an I/O unit, and perhapsasks for a specific volume. The system ensures that requested I/O devicesare available for the job before it allows execution to begin. You are permit-ted a maximum of 3,273 DD statements (or fewer, depending on the instal-lation) per step.

The DD statement may also give the system various information aboutthe data set, such as its organization, record length, blocking, and so on. Ifyou create a new data set on a direct-access volume, you must specify theamount of storage to allocate on the DD statement with a SPACE parameter.Likewise, you also request the specific file on a multiple-file tape with theDD statement.

A great deal of information must be supplied to read or write a data set,including the data set organization, record type, record length, and block


TABLE 7.1 Data Set Types and Their Characteristics

Data set type Storage Specified by SMS-managed

Sequential Disk DSORG=PS OptionalTape DSORG=PS Optional

Extended Seq Disk DSNTYPE=EXTENDED YesPDS Disk SPACE=(,(,,n)) OptionalPDSE Disk DSNTYPE=LIBRARY YesVSAM Disk RECORG OptionalPIPE Disk DSNTYPE=PIPE YesHFS Disk DSNTYPE=HFS YesVIO Disk UNIT No

TEAMFLY

Team-Fly®

length. Supplying this information is one of the things that makes JCL diffi-cult. The information may come from three sources: the data control block(DCB) in the application program, a DD statement, and the data set label.

7.2 DATA CONTROL BLOCK

Essential

A data control block (DCB) is a table of data in storage that describes eachdata set used by the program. You can accept any default values suppliedby the language compiler or code language statements in COBOL, PL/I,C/C++, and Assembler Language to specify them.

When the system opens a data set, it takes information from the DDstatement and merges it into fields of the data control block left blank by theapplication program. The system then reads the data set label (if it is anexisting data set with a label) and merges any data from it into any remain-ing blank fields of the data control block. The hierarchy is

1. Data control block from application program first

2. DD statement second

3. Data set label third

For example, the language compiler need not specify the record formatin the data control block; allowing it to be supplied on a DD statementmakes the program more flexible. You usually omit the record length andblocking when you write your program, even if the language has statementsto specify them. This allows you to supply the DCB the information on theDD statement. That way, if the I/O device is changed, the program need notbe changed and recompiled. You can make the change on the DD statement.If the program reads a data set, you let it obtain the DCB information fromthe data set label rather than specifying the information with the compilerlanguage statements. You must know which data control block fields thecompilers leave blank so that you can supply them on the DD statement.(The information on how the compiler language statements supply theinformation included in the DCB is in the programmer’s guide for the lan-guage.)

Since there may be several data control blocks, one for each data set aprogram uses, you assign a data definition name (ddname) to each. Youmust then include a DD statement with a corresponding ddname for eachdata set used. The ddname forms the connection between the program andthe data set. The system may then read the data set label for further infor-mation.

THE DD STATEMENT 105

7.3 DD STATEMENT FORMAT

Essential

The format of the DD statement is as follows:

//ddname DD optional-parameters

The ddname is the name given to the DD statement that associates itwith a DCB within a program. The optional parameters consist of threepositional parameters (DUMMY, DATA, and *) and several keyword pa-rameters.

� * (asterisk) indicates that lines of data immediately follow the DDstatement. (Described in Chapter 9.)

� DUMMY gives the data set a dummy status. (Described in Chapter 8.)� DATA indicates that lines of data with // in columns 1 and 2 imme-

diately follow the DD statement. (Described in Chapter 9.)

The remainder of the parameters are keyword parameters that you maycode in any order following the positional parameters. The following pa-rameters are most often used and are described in this chapter.

DCB specifies data control block parameters.

DISP specifies the data set disposition.

DSN names the data set.

LRECL specifies the logical record length.

RECFM specifies the record format.

UNIT specifies the I/O device.

VOL specifies the volume and provides volume information.

Two parameters for direct-access storage are described in Chapter 10.

SPACE requests the amount of direct-access space to allocate.

VIO requests a virtual I/O temporary data set.

The following input stream and printed output parameters aredescribed in Chapter 9.

BURST bursts the continuous form output on the 3800 printer, tearingthe paper apart at the perforations.

CHARS specifies a character set for the 3800 printer.

COPIES requests copies of an output data set.


DEST routes output to a specified destination.

DLM specifies an alternative delimiter.

FCB specifies forms control image for a 3800 printer.

FLASH specifies a forms overlay for the 3800 printer.

FREE deallocates a data set when it is closed rather than at the end of ajob step.

HOLD holds the output data set in a queue.

MODIFY modifies print lines on the 3800 printer.

OUTLIM limits the lines of printed output.

OUTPUT associates a DD statement with an OUTPUT statement tospecify special output processing.

SEGMENT prints a portion of a data set while the job is still runningand producing output.

SPIN prints an output data set at the end of a step or at the end of a job.

SYSOUT routes a data set to the system output stream.

The SMS parameters are described in Chapter 11.

AVGREC requests space in units of number of records rather than innumber of blocks.

DATACLAS assumes various DD parameters for a class of data set.

DSNTYPE specifies partitioned data set extended (PDSE) and extendedsequential data sets.

LIKE copies DD information from an existing cataloged data set on disk.

MGMTCLAS assigns a management class to a new data set, which theinstallation can then use for backing up and migrating data sets.

REFDD copies DD information from a previous tape or disk DD state-ment.

SECMODEL requests password protection for SMS-managed data sets.

STORCLAS assumes UNIT and VOL information for new data sets.

The VSAM parameters are described in Chapter 17.

AMP provides information for VSAM data sets.

KEYOFF specifies the offset of the keys in a VSAM KSDS data set whencreated through JCL.

LGSTREAM specifies a prefix for the log stream used to record changes.


RECORG specifies the VSAM data set organization when creating aVSAM data set with JCL.

RLS specifies the level of record sharing for a VSAM data set in SMS.

The hierarchical file system (HFS) files are described in Chapter 24.

FILEDATA tells whether a hierarchical file contains binary or text data.

PATH gives the pathname of an HFS file.

PATHDISP specifies the disposition of an HFS file.

PATHMODE specifies the file access attributes when you create an HFSfile.

PATHOPTS specifies the access and status for an HFS file.

The remaining parameters are less often used.

ACCODE requests an access code for ANSI tapes. (Described in Chapter12.)

CHKPT requests checkpoints and end of volume. (Described in Chapter16.)

CNTL executes subsystem control statements. (Described in Chapter16.)

DDNAME postpones definition of a data set. (Described in Chapter 14.)

EXPDT specifies an expiration date for the data set. (Described in Chap-ter 16.)

LABEL provides label information and data set protection. (Describedin Chapter 12.)

PROTECT requests password protection for data sets. (Described inChapter 16.)

QNAME defines a data set for TCAM messages. (Described in Chapter16.)

RETPD specifies a retention period for the data set. (Described in Chap-ter 16.)

SUBSYS requests a subsystem to process a data set. (Described in Chap-ter 16.)

TERM sends or receives a data set from a time-sharing terminal.(Described in Chapter 16.)

Although there are many DD statement parameters, you’ll likely useonly eight on a regular basis: DCB, DISP, DSN, LABEL, SPACE, SYSOUT,UNIT, and VOL.


7.4 DDNAME: DATA DEFINITION NAME

Essential

The ddname is one to eight alphanumeric or national (A to Z, 0 to 9, @ $ #)characters. The first character must be alphabetic or national (A to Z, @ $ #).Make each ddname within a step unique. If duplicate ddnames exist withina step, the system makes device and space allocations for each statement,but directs all references to the first statement. The required ddnames varywith each language processor as shown in Table 7.2.

Don’t choose the following as ddnames because they all have specialmeaning to the operating system.

J3JBINFO J3SCINFO JCBIN JCBLOCK JCBTAB JESInnnnJESJCL JESJCLIN JESMSGLG JESYSMSG JOBCAT JOBLIBJOURNAL JS3CATLG JST STCINRDR STEPCAT STEPLIBSYSABEND SYSCHK SYSCKEOV SYSIN SYSMDUMP SYSMSGSYSUDUMP TSOINRDR

7.5 REFERBACK: REFERBACK PARAMETER

Essential

The referback parameter, similar to the // EXEC PGM=*.referback in Chap-ter 6, is also used on DD statements to copy information from a previous DDstatement. The following example illustrates how to copy data controlblock information from a previous DD statement with a referback.


TABLE 7.2 Required ddnames for the Language Processors

Language Data set requested by JCL ddnames

Assembler DCB DDNAME=ddname //ddname DD . . .COBOL Sequential VSAM files: //ddname DD . . .

SELECT file ASSIGN TO AS-ddnameAll other files:

SELECT file ASSIGN TO ddname.FORTRAN FORTRAN UNIT nn //FTnnF001 DD . . .

OPEN (UNIT=n, FILE=‘ddname’) //ddname DD . . .PL/I DECLARE ddname //ddname DD . . .C/C++ fopen(“dd:ddname”); //ddname DD . . .

//COMP PROC//STEP1 EXEC PGM=ONE//DD1 DD DCB=RECFM=FB,...//DD2 DD DCB=*.DD1,...

[To refer back to a DD statement in the same step, code *.ddname.]

//STEP2 EXEC PGM=TWO//DD3 DD DCB=*.STEP1.DD1,...

[To refer back to a DD statement in a previous step, code *.stepname.ddname.]

To refer back to a DD statement within a procedure, refer first to thestepname invoking the procedure, next to the stepname within the proce-dure, and then to the ddname. If you invoke the preceding COMP catalogedprocedure, you could code the following:

//STEP3 EXEC COMP//STEP4 EXEC PGM=FOUR//DD4 DD DCB=*.STEP3.STEP1.DD1,...

The referback can be to any DD statement except a DD * or DD DATAstatement.

7.6 DCB: DATA CONTROL BLOCK PARAMETER

Essential

Using JCL, you often specify two attributes for the records in the data set:

� RECFM is the record format. It tells what type of record it is.� LRECL is the logical record length. That is, the length of a record of

data.

A third attribute, BLKSIZE to specify the block size, is also required forall data sets. For efficiency, the system usually places several recordstogether in a block, and BLKSIZE specifies the size of the block. In the past,you usually had to code BLKSIZE on the JCL, but since an efficient blocksize depends on the type of I/O device, this led to massive JCL changeswhenever IBM introduced a new disk drive. Today, the system calculates anoptimum block size for data sets, taking into consideration the device type,when you omit the BLKSIZE subparameter. There is almost no need to codeBLKSIZE anymore. In fact, you shouldn’t code it because the system canselect a better block size than you can. Remove any BLKSIZE subparame-ters on old JCL statements.


You specify the RECFM and LRECL with a DCB parameter on a DDstatement. The following is typical:

//OUT DD DCB=(RECFM=FB,LRECL=80),...

DCB stands for data control block. The DCB parameter is coded asDCB=subparameter or DCB=(subparameter, . . . ,subparameter). Several ofthe most frequently used subparameters are described here. You may codeany DCB subparameter as a parameter, leaving off the DCB=, or as a DCBsubparameter. The following are equivalent:

//OUT DD DCB=(RECFM=FB,LRECL=80,KEYLEN=16,BLKSIZE=4096),...//OUT DD RECFM=FB,LRECL=80,KEYLEN=16,BLKSIZE=4096,...

Just don’t code any parameter twice:

//OUT DD DCB=(RECFM=FB,LRECL=80,BLKSIZE=4096),RECFM=FB,...

Your installation may set a standard as to whether you code items asparameters or DCB subparameters. Older JCL will always have them as sub-parameters because the ability to code them as parameters was introducedlater. If you have a choice, code them as parameters because this is simplerand individual parameters are easier to override in cataloged procedures.

7.6.1 DSORG: Data Set Organization

Essential to Know but Rarely Used

Code DSORG=organization to specify the type of organization. The defaultis DSORG=PS, but most application programs specify the DSORG for theDCB, and so you rarely need to code DSORG. The following organizationtypes are the most common.

PS Physical sequential.PO Partitioned organization.DA Direct access. (This is described in Chapter 24. It is supported

but obsolete. Use a VSAM file instead.)

//OUT DD DCB=DSORG=PS

The various languages set the DSORG as follows:

COBOLRELATIVE DYNAMICINDEXED RANDOMSEQUENTIAL SEQUENTIAL

SELECT filename ORGANIZATION IS ACCESS IS .


FORTRAN: OPEN(ACCESS=SEQUENTIAL or DIRECT)

PL/IVSAM

TRANSIENT REGIONAL(n)DIRECT INDEXEDSEQUENTIAL CONSECUTIVE

DCL filename FILE RECORD ENV( );

C/C++: The open() function supplies the needed information.

Assembler Language: DCB DSORG=format macro.

7.6.2 RECFM: Record Format

Essential

Code RECFM=format to specify the record format. Figure 7.1 shows the dif-ferent record formats.

Records contain data and text. Computer data, as shown here, is often offixed length. That is, each record has the same length:

Data: (from 1980 Census)

City Country PopulationSao Paulo Brazil 12,578,045Shanghai China 11,000,000Mexico City Mexico 9,200,000Calcutta India 9,165,650Rio de Janeiro Brazil 9,011,981

Text, such as that on this page, usually varies in length. That is, eachrecord may have a different line length. You specify fixed- or variable-length records with the DCB RECFM subparameter. The form is

Fixed-length: Variable-length://OUT DD DCB=(RECFM=FB,... //OUT DD DCB=(RECFM=VB,...

Or Or//OUT DD RECFM=FB,... //OUT DD RECFM=VB,...

There is a third type of record format occasionally used, the undefinedformat, specified with RECFM=U. The system must read the record to deter-mine its length. For undefined records, you omit the LRECL and specify theBLKSIZE as that of the largest block. You use the undefined record formatto read input from a comma-delimited file, from a terminal device, and forload modules.

DCB=(RECFM=U,BLKSIZE=120)


FIGURE 7.1 Record formats.

Record 1

LRECL

LRECL, the record length, is the same for all records.IBG, interblock gap.

RECFM=F Fixed-length records

RECFM=FB Blocked fixed-length records

IBG Record 2

IBG Record 3 …

IBG

Record 1

BLKSIZE

BLKSIZE must be equal to or greater than the maximum record length in the data set.

IBG Record 2

IBG Record 3 Record 4 …

IBG

IBG

LRECL

Record 1 Record 2 Record 3

BLKSIZE

BLKSIZE, the block size, is a multiple of LRECL.

RECFM=V Variable-length records

IBG Record 4 Record 5 Record 6

IBG …

m n

4 Bytes

4 ≤ m ≤ 32,756

RECFM=VB Blocked variable-length records

IBGRecord 1 Record 2 Record 3 …

m Bytes

n Bytes

BLKSIZE

m n

LRECL

IBG m n

IBG

m n

8 ≤ m ≤ 32,760BLKSIZE must be equal to or greater than the maximum record length in the data set.RECFM=U Undefined-length records

Record 1 Record 2 Record 3 …n

BLKSIZE

IBG m n

IBG

m Bytes

113

RECFM=format can be one or more of the following characters.

� First character (only one permitted):

U: Undefined-length records. Don’t code LRECL. BLKSIZE must begreater than or equal to the largest record.

V: Variable-length records. LRECL is the length of the longest recordplus four bytes. BLKSIZE must be at least as large as LRECL+4.The four bytes describing the length of the block are called theblock descriptor word.

F: Fixed-length records. BLKSIZE is a multiple of LRECL for blockedrecords.

D: Variable-length ISO/ANSI records.� Next characters:

B: Blocked records. (FB and VB are permitted; UB is not.)

S: Spanned records. Used when the record length is greater than theblock size. For V format records—logical records are spannedover more than one block. For VS or VBS, the BLKSIZE is inde-pendent of the LRECL. For F format records—no truncated blocksor unfilled tracks within the data set. You cannot code S with Uor D. Spanned records are described in Chapter 16.

A: ISD/ANSI device control character is the first byte of data. Used tocontrol the printer. You cannot code A with M.

M: Machine code control character used to control the printer is thefirst byte of data. You cannot code M with D or A.

//OUT1 DD DCB=(DSORG=PS,RECFM=FB,LRECL=80)//OUT2 DD RECFM=FBSA

The various languages set the RECFM as follows:

COBOLFD filename RECORD CONTAINS n or n TO m CHARACTERSFD filename BLOCK CONTAINS n TO m CHARACTERS.

FORTRAN: Defaults to VB.

PL/I: DCL filename ENV(U/VB/V/FB/F);


Assembler Language: DCB RECFM=format macro.

7.6.3 LRECL: Logical Record Length

Essential

LRECL=length specifies the length of the logical record in bytes for fixed- orvariable-length records. The LRECL value is 1 to 32760 for non-VSAM data


TEAMFLY

Team-Fly®

sets and 1 to 32761 for VSAM data sets. Omit the LRECL for undefined-length records. The LRECL is determined differently for fixed-length andvariable-length records.

� Fixed-length records. LRECL is the length of the record. (Eachrecord has the same length.)

� Variable-length records. LRECL is the length of the longest recordplus four. That is, if the longest record were 96, you would specifyLRECL=100. The extra four bytes describing the length of the recordare called the record descriptor word. The record length is stored inthe extra four bytes.

//OUT DD DCB=(RECFM=FB,LRECL=80)

Why use variable-length records at all? Why not just use fixed-lengthrecords with a length large enough to contain the longest line? The reasonis that it would waste a lot of file storage space on the computer. With fixed-length data in a fixed-length record, there is no wasted space. Figure 7.2illustrates variable-length data stored in a fixed-length record. Space iswasted. Figure 7.3 shows how variable-length records prevent space frombeing wasted.

How about the other way around? Why not make all records variable-length? Why have fixed-length records at all? The system can process fixed-length records slightly faster than variable-length records, but the realreason is that fixed-length records are actually an anachronism left over


FIGURE 7.2 Variable-length data stored in a fixed-length record.

Mr. John Q. Smith

The Ajax Company

14 Oak Street

Norogrudo, Byelorussian Soviet Socialist Republic

FIGURE 7.3 Variable-lengthdata stored in a variable-lengthrecord.

Mr. John Q. Smith

The Ajax Company

14 Oak Street

Norogrudo, Byelorussian Soviet Socialist Republic

from the early days of computing when most input was on punched cards,which were fixed-length, 80-character records.

The various languages set the LRECL as follows:

COBOL: FD filename RECORD CONTAINS n or n TO m CHARACTERS.

FORTRAN: Record length depends on the length of the record written.

PL/I: DCL filename ENV(RECSIZE(length));


Assembler Language: DCB LRECL=length macro.

7.6.4 BLKSIZE: Block Size

Essential to Know but Rarely Used

Blocking determines how the system transmits and stores records on an I/Odevice. When records are physically stored on disk and tape, the systemleaves a gap between the records so that the hardware can tell where onerecord ends and the next one begins, as shown in Figure 7.4. This inter-record gap can take up as much and even more space than the record itself.On a typical disk, the interrecord gap occupies 185 bytes; on tape, it occu-pies 230 bytes.

To regain some of the space used for interrecord gaps, you can block therecords. That is, you can put several records together in a block. Instead ofthe records stored as they are in Figure 7.4, you can block them as shown inFigure 7.5.

Blocking can save a tremendous amount of data set storage space. Butthere is another, equally important reason for blocking. The system can readand write blocked records much faster than unblocked records, signifi-cantly reducing run costs. The computer can transmit (read or write) agroup of records in a block far more efficiently than transmitting them oneat a time. This is comparable to the efficiency gained by filling an airlinerwith passengers and flying them as a group rather than flying one passen-


FIGURE 7.4 Interblock gaps (IBGs).

Record 1 IBG Record 2 IBG Record 3 IBG Record 4

FIGURE 7.5 Blocked records.

Record 1 Record 2 Record 3 Record 4 IBG

ger per plane. The basic cost of the pilot and fuel do not change that muchwith each passenger added. Similarly, with the computer, the big cost oflocating the start of a block in a data set and getting things going doesn’tchange much with each additional record placed in the block.

For fixed blocked records, the block size must be an even multiple ofthe record length. It is more complicated for variable-length records inwhich the record length must be at least as long as the longest record plusfour, and the block size must be at least as long as the longest record pluseight.

The actual record length and block length are stored within those extrafour and eight bytes. By storing the record length in each record, the oper-ating system always knows how long each record is.

Of course, the block size can also be inefficient if it is too big. The basicunit of storage on disk is a track, like that on a CD. On a typical disk unit,the IBM 3390, a track can contain 56,664 bytes. If you have 80-byte recordsand choose a block size of 32,000 bytes, only one block will fit on a track,as shown in Figure 7.6. This wastes approximately 24,000 bytes on eachtrack because the block size is too large.

Choosing an appropriate block size is very important—and very com-plicated. In the past, you had to choose a block size. Today, you omit theBLKSIZE subparameter and the system supplies an optimum block size forthe device. You should never code BLKSIZE unless you have to becauseyou might select an inefficient block size. And even if you select an effi-cient one, your installation may install a new I/O device that results in yourblock size suddenly becoming inefficient. About the only time you mightneed to code BLKSIZE is when you are reading an unlabeled tape.

Should you somehow need to code BLKSIZE, the following simplerules of thumb should suffice. Choose a block size of 4,096 bytes or as closeas you can get. This is big enough to be efficient but not too big. It also fitsnicely onto the tracks of most models of disk units. The suggested recordlengths for data and text are as follows:

� Input stream data records: RECFM=FB,LRECL=80,BLKSIZE=4080. Ifthe LRECL isn’t 80, choose a block size that is an even multiple thatis close to 4,096.

� Text records: RECFM=VB,LRECL=255,BLKSIZE=4096.


FIGURE 7.6 One block stored on a 3390 track.

32,000-byte block

—56,664-byte track—

24,664 wasted bytes

You specify the block size in bytes by coding the following.

n [bytes: n is 18-2147483648 bytes]nK [Kilobytes: n is 1-2097152x103 bytes]nM [Megabytes: n is 1-2048x106 bytes]nG [Gigabytes: n is 1-2x109 bytes]

BLKSIZE=__

The block size must be a multiple of the LRECL for fixed-length records;for variable-length records, it must be equal to or greater than LRECL plusfour. That is, it must be equal to or greater than the longest record plus eight.For undefined-length records, the block size must be as large as the longestblock. The block size can range from 18 (the smallest block size allowed fortape) to 2 gigabytes. Normally the block size should not exceed the track sizeof a direct-access volume.

//OUT DD DCB=(DSORG=PS,LRECL=80,// BLKSIZE=4080)

[Continue a DCB parameter by breaking it after a complete subpa-rameter, including the comma following it.]

The various languages set the BLKSIZE as follows:

COBOL: FD filename BLOCK CONTAINS n TO m CHARACTERS.

FORTRAN: The BLKSIZE is built-in.

PL/I: DCL filename ENV(BLKSIZE(length));

C/C++: The open () function supplies the needed information.

Assembler Language: DCB BLKSIZE=length macro.

7.6.5 BUFNO: Number of Buffers

Rarely Used

BUFNO=n specifies the number of buffers to allocate for the data set. Theinstallation establishes a default, usually five, if you omit BUFNO, and thisis usually sufficient. The maximum is 255.

//OUT DD DCB=(RECFM=FB,LRECL=80,BUFNO=2)

7.6.6 DCB Information from Data Set Labels

Essential

The system creates a data set label for nontemporary data sets. It records theDCB subparameters DSORG, RECFM, BLKSIZE, and LRECL in the label and


they become part of the data set. The system also stores the OPTCD,KEYLEN, RKP, and TRTCH DCB subparameters; the EXPDT or RETPD pa-rameters; and the volume sequence number in the label. (These subpa-rameters are described later.) You need not specify the parameters stored inthe label when referring to an old data set. The system retrieves them fromthe data set label. If all required DCB information is contained in the datacontrol block or in the data set label, you may omit the DCB parameter fromthe DD statement.

Several DD parameters, some not yet explained, are either stored in thecatalog when the data set is cataloged, stored in the data set label, or areretained by the system when the data set is passed. Except for DSN, youneed not code these parameters to retrieve the data set. For reference, Table7.3 shows the DD parameters that the system retains.


TABLE 7.3 Retained DD Parameters

Retained Retained Retainedin catalog in label if passed

DSN Yes* Yes* Yes*UNIT Yes No YesVOL=SER Yes Yes* YesVolume seq # Yes Yes YesDCB=BLKSIZE No Yes Yes†

DCB=DEN No Yes No†

DCB=DSORG No No Yes†

DCB=KEYLEN No Yes Yes†

DCB=LRECL No Yes Yes†

DCB=OPTCD No Yes Yes†

DCB=RECFM No Yes Yes†

DCB=RKP No Yes Yes†

DCB=TRTCH No Yes Yes†

Creation date No Yes NoGeneration # Yes Yes YesEXPDT No Yes NoRETPD No Yes NoLABEL=PASSWORD No Yes NoLABEL=NOPWREAD No Yes NoLABEL file # Yes Yes* YesLABEL type No No YesSPACE=(u,(p,s)) No Yes No

* Although retained, you must still specify it.† For tape, only for standard labels.

7.6.7 Copying DCB Values

Sometimes Used

Often you would like to create a data set with the same DCB subparametersas an existing data set. You do this by either naming the other data set or byreferring back to a DD statement containing the desired DCB subparameters.

DCB=(data-set-name,subparameter,...,subparameter)DCB=(*.referback,subparameter,...,subparameter)

If you code a data-set-name, the system copies the DCB information(DSORG, RECFM, BLKSIZE, LRECL, OPTCD, KEYLEN, and RKP) from thenamed data set, which must be a cataloged data set on a direct-access stor-age device. The system copies the volume sequence number and retentiondate along with the DCB subparameter unless you code them on the DDstatement.

If you code a referback, the system copies the DCB subparameters codedon the previous DD statement. Note that the system copies the DCB subpa-rameters from the DD statement, not from the data set label of the data setdescribed by the DD statement. You can code subparameters following the DCB=data-set-name or DCB=*.referback to override or augment thosecopied.

//INPUT DD DCB=SYS1.LINKLIB,...

[The system copies DCB subparameters from SYS1.LINKLIB.]

//INPUT DD DCB=*.DDONE,...

[The system copies DCB subparameters from the //DDONE DD state-ment. DDONE must be a previous statement in this same step.]

//INPUT DD DCB=(*.STEP1.DDTWO,LRECL=80,BUFNO=3),...

[The system copies DCB subparameters from the //DDTWO DDstatement in STEP1. STEP1 must be a previous step. Any LRECL orBUFNO subparameter in the copied DCB is overridden.]

7.7 DSN: DATA SET NAME

Essential

The DSN (short for DSNAME) parameter names the data set. Data sets areeither temporary or nontemporary. A temporary data set is created anddeleted within the job; whereas the system can retain nontemporary datasets after the job completes. Nontemporary data sets are usually cataloged.All nontemporary data sets must be given names; the name is optional for


temporary data sets. If the data set is new, DSN assigns a name to it; if old,DSN gives its existing name.

7.7.1 Temporary Data Sets

Temporary data sets are used for storage needed only for the duration of thejob. If the DISP parameter does not delete the data set by the end of the job,the system deletes it. Deleting a tape data set dismounts the tape, whereasdeleting a data set on a direct-access volume releases the storage.

You mark a data set as temporary by either omitting the DSN parameteror by coding DSN=&&name. The system assigns a unique name to the dataset when you omit the DSN parameter, and any subsequent steps using thedata set must refer back to the DD statement. (You can use the DSN=*.refer-back parameter to refer back to any data set, temporary or nontemporary.)

//STEP1 EXEC PGM=ONE//DATA1 DD UNIT=SYSSQ,DISP=(NEW,PASS),...

[Since no name is given, the system creates a temporary data set.]

//STEP2 EXEC PGM=TWO//DATA2 DD DSN=*.STEP.DATA1,DISP=(OLD,PASS)

[The data set is retrieved by referring back to the DD statement creating it.]

A temporary data set can be assigned a name by coding DSN=&&name;the ampersands mark it as temporary. The name is a one- to eight-charactername beginning with an alphabetic or national (A to Z, @ $ #) character. Theremaining characters may be alphanumeric or national: A to Z, 0 to 9, @ $#), or the hyphen (-). You can later refer to the temporary data set by codingeither DSN=&&name or DSN=*.referback.

//STEP1 EXEC PGM=ONE//DATA1 DD DSN=&&STUFF,DISP=(NEW,PASS),...

[The system creates a temporary data set with the name STUFF.]

//STEP2 EXEC PGM=TWO//DATA2 DD DSN=&&STUFF,DISP=(OLD,DELETE),...

[We retrieve the temporary data set by referring to the name we giveit when we created it.]

Or

//DATA2 DD DSN=*.STEP1.DATA1,DISP=(OLD,DELETE),...

[We retrieve the temporary data set by referring back to the DD state-ment creating it.]


7.7.2 Nontemporary Data Sets

The system can retain nontemporary data sets after the completion of thejob. A data set label created and stored along with the data set contains thedata-set-name and DCB subparameters. You can also catalog the data set sothat the system records the unit and volume on which the data set resides,along with the file number if the data set is on tape. Although you may cre-ate and delete a nontemporary data set in the same step, it is wasteful; cre-ate a temporary data set instead. (But use a nontemporary data set if youneed to save the data set for a restart.)

A nontemporary data set is denoted by coding DSN=data-set-namewhere data-set-name is one or more one- to eight-character names, eachseparated by periods. Never use NULLFILE as a name because it gives thedata set a dummy status. Don’t begin names with JES or SYS1 because z/OSuses these names. The first character must be alphabetic or national (A to Z,@ $ #), and the remaining characters can be either alphanumeric ornational: A to Z, 0 to 9, @ $ #), or the hyphen (-).

//STEP1 EXEC PGM=CREATE//A DD DSN=OMNIBUS,DISP=(NEW,CATLG)...

[The system creates a nontemporary data set named OMNIBUS.]

//STEP2 EXEC PGM=READ//B DD DSN=OMNIBUS,DISP=OLD,...

[We retrieve the data set by its name.]

Or

//B DD DSN=*.STEP1.A,DISP=OLD,...

[We retrieve the data set by referencing the DD statement creating it.The referback refers back to DD statements so that if the data setname is changed, only one DD statement is affected.]

Don’t use special characters in data set names. SMS doesn’t permitthem. A data set name can contain one of the special characters blank , . / ’)(* & + = under the following circumstances.

� You enclose the name in apostrophes and code a legitimate apostro-phe as two consecutive apostrophes: ‘O’’CLOCK’. The data set name,including apostrophes, cannot exceed 44 characters.

� The data set name must not refer to a partitioned or generation datagroup.

� You cannot catalog the data set.


� You cannot use the name in a referback.� You cannot code DSN=&&data-set-name.� You cannot qualify the data set name.� The data set cannot be SMS-managed.

You usually extend or qualify nontemporary data set names, especiallyon direct-access storage devices, by concatenating names. Each level ofname, called an index, must conform to the preceding naming conventionsand you must separate them from other names with a period. For example,A.B.Z. Qualified names can contain up to 44 characters including periods(35 characters if it is a generation data group name), and so 22 levels ofqualification are possible. (For tape data sets, the system looks at only theleftmost 17 characters, including periods, of the data set name.)

You can use qualified names to group data sets or to ensure uniquenames. For example, DATA.A27.B74276 is likely to be a unique name, andthe data sets named SMITH.SOURCE, SMITH.DATA, and SMITH.REPORTcould all belong to Smith. (Qualified names serve somewhat the same func-tion as a directory on a PC or in UNIX. However, there are differences.)

//INPUT DD DSN=JONES.N2267.TEST6,...//OUT DD DSN=LAX.UNITED.FT767.SEAT32,...

Figure 7.7 illustrates how the different levels of names group data sets.Note that the use of levels makes it easy to identify all the data sets belong-ing to RT452216.


FIGURE 7.7 Levels of data set names.

PROD TEST

RT452216

DSN=RT452216.PROD.CNTLDSN-RT452216.PROD.COBOLDSN-RT452216.TEST.COBOL

Three data sets:

CNTL COBOL COBOL

As with all names in computer systems, you should assign meaningfulnames to your data sets. Installations usually impose naming conventionsfor nontemporary data sets. Check with your installation for its conven-tions. In TSO and ISPF (the text editor used in many z/OS installations),data set names often have three levels as follows: project.name.type

project identifies the project or person owning the data set. It is often auserid.

name names the data set itself.

type is the generic type of the data set. Typical generic types are as fol-lows:

ASM Assembler Language sourceC C/C++ language sourceCLIST TSO command proceduresCNTL JCLCOBOL COBOL language sourceDATA Text data (uppercase)EXEC TSO/E commands and REXX instructionsFORT FORTRAN language sourceH C/C++ header filesLINKLIST Output listing from linkage editorLIST ListingsLOAD Load modulesLOADLIST Output listing from loaderOBJ Object modulesOUTLIST Output listing from OUTPUT commandPASCAL PASCAL language sourcePLI PL/I language sourceTESTLIST Output listing from TEST commandTEXT Text (upper- and lowercase)VSBASIC VSBASIC statements

For example, a typical data set name might be X0225.TEST.CNTL,which might be some JCL given a name of TEST and belonging to X0225.Most data sets you see will have at least three levels of qualification. How-ever, to simplify the examples in this book and to save space, some data setnames will be one level.

7.7.3 Other Data Sets

The DSN parameter for partitioned data sets must include the membername to refer to an individual member within the data set. For this, you


TEAMFLY

Team-Fly®

enclose the member name in parentheses and place it following the data setname:

DSN=data-set-name(member) For nontemporary data sets

DSN=&&data-set-name(member) For temporary data sets

For example, DSN=HOLD(IT) requests member IT in the data set HOLD.The DSN parameter is also slightly different for generation data sets,

which are described in Chapter 15. The general form is as follows:

DSN=data-set-name(n) For nontemporary data sets

DSN=&&data-set-name(n) For temporary data sets

To refer to a particular generation data group, code DSN=data-set-name(n), giving the relative generation number—zero, or a signed integer(such as +1, −1, and so forth); for example, DSN=TAX(−1) refers to relativegeneration −1 of data group TAX.

7.8 DISP: DATA SET DISPOSITION

Essential

The DISP parameter describes the status of the data set (old, new, or to bemodified) and directs the system on the disposition of the data set (pass,keep, catalog, uncatalog, or delete) either at the end of the step or if the stepabnormally terminates. DISP is always required unless you create and deletethe data set in the same step. The general form of the DISP parameter is

DISP=(status,normal-disp,abnormal-disp)

The various options are

KEEPMOD DELETE KEEPOLD PASS DELETESHR CATLG CATLGNEW UNCATLG UNCATLG

DISP=( , , )

7.8.1 Status

The status, NEW, MOD, OLD, or SHR, is the status of the data set at thebeginning of the step. If the data set is new, the system creates a data setlabel; if it is old, the system locates the data set and reads its label.


Except for SHR, the system gives a program exclusive use of a data set.(In multiprogramming environments, several jobs have the potential of con-currently reading the same data set on a direct-access volume.) The systemwill hold programs in the input queue until another program that has exclu-sive access to the data set terminates. Several programs can read a data setat the same time if they all have a DISP of SHR.

NEW: New Data SetsDISP=(NEW,...) creates a data set. Unless you code the SMS STORCLASparameter, the UNIT parameter is required, the VOL parameter can be usedto place the data set on a specific volume, and the SPACE parameter isrequired for data sets on direct-access volumes. The step abnormally termi-nates if a data set with the same name already exists on the same direct-access volume.

NEW is default if you code nothing. For example, DISP=(,KEEP) is thesame as DISP=(NEW,KEEP). If you omit DISP entirely, the system alsoassumes NEW. Of course, NEW implies sole access to a data set.

OLD: Old Data SetsDISP=(OLD,...) designates an existing data set; it can be an input data set toread or an output data set to rewrite. The system gives the step sole accessto the data set.

If the old data set is cataloged or passed from a previous step, the DSNparameter is usually the only other DD parameter needed. (The LABELparameter may also be needed for tapes.) If the old data set is not catalogedor passed from a previous step, UNIT and VOL parameters are required.

OLD operates differently for partitioned data sets when you code amember name: DSN=data-set-name(member)

� If the member does not already exist, the system adds the new mem-ber.

� If the member already exists, the system replaces it with the newmember.

SHR: Sharing Input Data SetsDISP=(SHR,...) permits old data sets to be shared. SHR is identical to OLDexcept that several jobs may read the data set concurrently in multipro-gramming environments. Use SHR only for input data sets; use OLD orMOD if you write the data set. Sharing data sets is necessary because pub-lic libraries such as SYS1.LINKLIB or the subroutine libraries should beavailable to every job in the system. Generally, you should use SHR for allinput data sets. (If another job is modifying the data, that job will have a dis-position of NEW, MOD, or OLD to prevent the data set being shared.)


//STEP1 EXEC PGM=FIRST//A DD DSN=RECORDS,DISP=(NEW,PASS),UNIT=SYSDA,SPACE=(4096,100)

[The system creates a data set named RECORDS. Since it now exists,any later usage of it must be with the disposition, MOD, SHR, orOLD.]

//STEP2 EXEC PGM=SECOND//B DD DSN=BOOKS,DISP=(MOD,CATLG),UNIT=SYSDA,SPACE=(4096,100)

[If the system does not find data set BOOKS in the catalog, itassumes the data set does not exist and creates it. If the system findsit, it writes any new data following the last record in the data set.]

//C DD DSN=LIBRARY,DISP=(MOD,CATLG),UNIT=SYSDA,VOL=SER=PACK12

[Because of the VOL, LIBRARY must be an existing data set. Thesystem places any data written into it following the last record inthe data set.]

//STEP3 EXEC PGM=THIRD//D DD DSN=SYS1.FORTLIB,DISP=OLD

[SYS1.FORTLIB must be an existing data set, and the system givesthe step sole use of it. If the system cannot locate the data set in thecatalog, it terminates the step.]

//E DD DSN=SYS1.FORTLIB,DISP=SHR

[The only difference between D and E is that E permits other jobs toread SYS1.FORTLIB concurrently.]

For a partitioned data set, if you code the data set name and the mem-ber name, then the system accesses that member. For a PDSE only, you cancode SHR to add a member to the data set. This way, the system can add themember while allowing other members of the same partitioned data set tobe shared.

Note that if any step requests exclusive control of a data set (MOD, OLD,or NEW), the system ignores any SHR in another step and gives exclusivecontrol for the entire job. This means that you cannot write to a data set inone step and then share it in a later step.

MOD: Modifying Data SetsYou use MOD either to extend an existing sequential data set or to create thedata set if it does not exist. When you code DISP=(MOD, . . .) with an exist-ing sequential data set, the system, when it opens the data set, positions theread/write mechanism of the I/O device to the point immediately followingthe last record in the data set. Figure 7.8 illustrates this. This provides aconvenient means of adding data at the end of a sequential data set. MODalways gives sole access to the data set.


If you use DISP=(MOD, . . .) when the data set does not exist, the systemtreats MOD as if it were NEW. However, it does this only if you have notrequested a specific volume. The system determines whether to extend orcreate by the following process:

1. If you pass or catalog the data set, it exists and the system extendsthe data set.

2. If you code VOL=SER to refer to a specific volume (or codeVOL=REF to refer to a DD statement containing a VOL=SER request-ing a specific volume), the system assumes that the data set existson that volume and attempts to extend it. If the data set doesn’texist, the system terminates your job.

3. In all other cases, the system assumes that the data set does not existand treats MOD as NEW. Unless supplied by SMS parameters, youmust code all the necessary DD parameters needed to create a newdata set, such as UNIT, SPACE, and DCB.

A new data set does not contain an end-of-data-set marker until the sys-tem opens it for output and then closes it. You often allocate space on adirect-access volume with the expectation that subsequent jobs will adddata to it with a disposition of MOD. An attempt to read the data set yieldsunpredictable results unless you have opened and closed the data set foroutput to write an end-of-data-set marker.

You can use MOD to add to a data set that extends onto several volumes.This is the usual way of extending data sets onto several direct-access vol-umes. Always specify a disposition of CATLG with MOD for cataloged datasets, even if they are already cataloged, so that the system will record anyadditional volume serial numbers in the catalog. For tape, if the volumes ontowhich the data set extends are not already mounted, specify either a volumecount with the VOL parameter or deferred mounting with the UNIT parame-ter so that the system will request dismounting and mounting of volumes.

MOD works differently for a partitioned data set than it does for sequen-tial. If you don’t code a member name, MOD positions to the end of the par-


FIGURE 7.8 Disposition of MOD.

Old data

OLD positions here.You write over

the data set.

Existing data set

EOF

Available space

MOD positions here.You add to the end of

the data set.

titioned data set and the system makes no directory entry. When you codea member name for a partitioned data set, MOD adds new members only ifthey do not already exist according to the following rules:

� If the member already exists, the system terminates the job.� If the member doesn’t exist, the system treats MOD as NEW and adds

the new member at the end of the data set. Note that this is slightlydifferent from OLD, which adds if the member isn’t there andreplaces if it is.

7.8.2 Normal Disposition

Normal disposition, the second term in the DISP parameter, indicates thedisposition of the data set when the data set is closed or when the job terminates normally. The normal disposition can be omitted if the data set’sstatus is not to change from what it was at the start of the step—existing datasets (MOD, OLD, or SHR) continue to exist; NEW data sets are deleted.

Disposition for data sets on direct-access and tape volumes differs. Thesystem keeps space on direct-access volumes intact if you keep the data set,and it releases the space for other use if you delete the data set. When youkeep or delete a tape data set, the system rewinds and unloads the tape.The system then tells the computer operator whether to keep the tape or delete it. Presumably the operator will reserve a kept tape and put adeleted tape back into circulation, but nothing actually happens to the dataon the tape.

The system retains data set on a direct access volume that you passbetween job steps. Passing a tape data set rewinds the tape to the start of thedata set between steps but does not dismount it. Under the following spe-cial circumstances, disposition is not performed, leaving data sets as theywere prior to the job step:

� The system does not initiate the step because of JCL errors or JCLchecking.

� If the system bypasses the step because of the COND parameter on JOBor EXEC statements or the IF/THEN/ELSE/ENDIF statement construct.

� If the step does not open the data set for which the DD statementmade a nonspecific request for a tape (VOL=SER not coded).

� If the system terminates the step abnormally after allocating I/Odevices but before the step begins execution because space on adirect-access volume cannot be obtained. Existing data sets (OLD,MOD, and SHR) continue to exist; NEW data sets are deleted.

� If the device, such as a printer, cannot contain data sets.� If DUMMY or DSN=NULLFILE are coded on the DD statement.


PASS: Pass Data SetsDISP=(..,PASS,..) passes the data set on to subsequent job steps, and eachstep can use the data set once. PASS saves time because the system retainsthe data set location and volume information in memory and does not haveto read the catalog or volume table of contents on a disk volume to locatethe data set.

PASS is especially useful for tape because it repositions the tape to thestart of the data set and keeps the tape mounted between job steps. You canpass both temporary and nontemporary data sets. Table 7.2 lists all the DDparameters passed with the data set. Disposition for a passed data set occursas follows:

� If you execute a subsequent step with a DD statement referring to thedata set, disposition depends on the DISP parameter on the step’s DDstatement referencing the passed data set. The disposition can beDELETE, KEEP, CATLG, or PASS. The system passes the data set onto subsequent steps only if you code PASS. Note that if a step has aDD statement referring to the passed data set, but that step isn’t exe-cuted, it has no effect on the passed data set.

� If a data set continues to be passed at the end of the job (because nostep retrieved it or the last step to retrieve it passed it), the systemassumes a disposition to keep the data set’s status as it was at the startof a job. The system assumes DELETE for all NEW data sets, tempo-rary or nontemporary. (As a nuance, if you create a data set, KEEP orCATLG it, and then refer to it in a later step and PASS it, the systemassumes KEEP, not DELETE.) KEEP is assumed for preexisting (MOD,OLD, or SHR) nontemporary data sets.

� For tape, PASS passes the file number and label type. The systemdoes not pass the tape density.

Subsequent steps can refer to a passed data set by name or by referback.Don’t code the UNIT and VOL parameters because the system passes thisinformation with the data set.

//STEP1 EXEC PGM=ONE//A DD DSN=&&IT,DISP=(NEW,PASS),// UNIT=SYSDA,VOL=SER=PACK10,SPACE=(4096,100)//STEP2 EXEC PGM=TWO//B DD DSN=&&IT,DISP=(OLD,PASS)

Or

//B DD DSN=*.STEP1.A,DISP=(OLD,PASS)

You can pass several data sets having identical names in successivesteps. DD statements referring to these identically named passed data sets


retrieve them in the order they were passed. But give each data set a differ-ent name so you don’t have to worry about this.

For SMS-managed data sets, the system treats PASS as KEEP for non-temporary data sets.

KEEP: Keep Data SetsDISP=(..,KEEP,..) keeps nontemporary data sets. The system retains a dataset residing on a direct-access volume. It rewinds and dismounts a tapecontaining a kept data set and then it issues a keep message to the operator.If you attempt KEEP for a temporary data set, the system changes the dis-position to PASS. (The system deletes the data set if the DD statement hasno DSN parameter and you code DEFER in the UNIT parameter.) If you codeKEEP for a NEW data set, the system creates a data set label for the data set.

//READ DD DSN=LEDGER,DISP(NEW,KEEP),// UNIT=SYSDA,VOL=SER=PACK10,SPACE=(4096,100)

[LEDGER is created and is kept after the step terminates. SinceLEDGER is not passed or cataloged, any later use of the data set,either in a subsequent step or in a later job, must supply the volumeand unit.]

//LATER DD DSN=LEDGER,DISP=(OLD,KEEP),UNIT=SYSDA,VOL=SER=PACK10

[The system locates LEDGER on the volume and unit specified. Youmust use OLD, MOD, or SHR to refer to an existing data set. If NEWhas been used instead of OLD, the system would terminate the stepbecause a data set with the same name already exists on the volume.]

You use KEEP mainly when reading existing data sets. The systemtreats KEEP as CATLG for new SMS-managed data sets (described in Chap-ter 11) because you must catalog all SMS-managed data sets. For SMS-managed VSAM data sets, all dispositions are valid. For VSAM data setsnot managed by SMS, only KEEP is valid.

DELETE: Delete Data SetsDISP=(..,DELETE,..) deletes data sets. Storage on a direct-access volume isreleased; a tape is rewound and unloaded, and the operator is told that thetape data set is deleted (nothing actually happens to the data on tape). If thedata set is located through the catalog (UNIT and VOL not coded), the dataset is also uncataloged. If the retention period (specified by the RETPD orEXPDT parameters described in Chapter 16) of a data set on a direct-accessvolume has not expired, the data set is not deleted.

The system deletes NEW data sets that have a disposition of DELETE inthe same step regardless of any retention period. Note that the system doesnot overwrite disk storage when it deletes a data set unless RACF or anothersecurity system specifies it for the data set.


CATLG: Catalog Data SetsDISP=(..,CATLG,..) catalogs a nontemporary data set. CATLG is similar toKEEP except that the system records the unit and volume of the data set inthe catalog, along with the data set name. It also records the file number ofa tape data set in the catalog, but not the type of tape label or the tape den-sity. (The system assumes standard labels, and so you need to code theLABEL parameter only for nonstandard labels.)

If the data set is already cataloged, CATLG is the same as PASS. If youcode CATLG for a temporary data set, the system changes the disposition toPASS. (It deletes the data set if you didn’t code the DSN parameter andspecified DEFER in the UNIT parameter.) The system records all volumes ofa multivolume data set in the catalog. If a multivolume data set is beingexpanded onto more volumes, DISP=(MOD,CATLG) records the additionalvolumes in the catalog.

//CARDS DD DSN=BALANCE,DISP=(NEW,CATLG),UNIT=TAPE,VOL=SER=000500

[BALANCE is created and cataloged. A later DD statement can referto the data set by its name, omitting the unit and volume.]

//LATER DD DSN=BALANCE,DISP=(OLD,CATLG)

Or

//LATER DD DSN=BALANCE,DISP=(OLD,KEEP)

[CATLG and KEEP are equivalent if the data set is already cataloged.However, if a multivolume data set is expanded onto more volumes,use CATLG to record the additional volumes in the catalog.]

//SAVE DD DSN=BUDGET,DISP=(OLD,CATLG),UNIT=TAPE,VOL=SER=000300

[You can also catalog an existing data set.]

CATLG is used at most installations when creating or modifying allnontemporary data sets on direct-access storage devices, and, if tape datasets are cataloged at the installation, all tape data sets.

The system catalogs SMS-managed data sets when it creates them, notat the end of the job step as it does for other data sets. Also, the system cat-alogs all SMS-managed data sets—even temporary data sets. This meansthat an SMS-managed temporary data set has more overhead than if it werenot SMS-managed.

UNCATLG: Uncatalog Data Sets

Rarely Used

DISP=(..,UNCATLG,..) uncatalogs a data set. UNCATLG is the same as KEEPexcept that the system removes the data set name from the catalog. If the


data set was not cataloged, UNCATLG is equivalent to KEEP. The systemalso treats UNCATLG as KEEP for an SMS-managed data set.

//RID DD DSN=BALANCE,DISP=(OLD,UNCATLG)

[We remove BALANCE from the catalog. If BALANCE were not cat-aloged, the system could not locate the data set and would termi-nate the step.]

//A DD DSN=DT,DISP=(OLD,UNCATLG),UNIT=SYSDA,VOL=SER=PACK06

[We remove DT from the catalog. If DT was not cataloged, the sys-tem treats UNCATLG as KEEP.]

7.8.3 Abnormal Disposition

Essential

The abnormal dispositions, effective only if the step abnormally termi-nates, are the same as normal dispositions except that PASS is not allowed.KEEP, CATLG, UNCATLG, and DELETE are all permitted: DISP=(NEW,PASS,DELETE), DISP=(OLD,DELETE,CATLG), and so forth.

If an abnormal disposition is not specified and the step terminatesabnormally, the normal disposition is assumed; for example, DISP=(OLD,KEEP) is equivalent to DISP=(OLD,KEEP,KEEP); DISP=(OLD,PASS) isequivalent to DISP=(OLD,PASS,KEEP). The abnormal termination disposi-tion for temporary data sets is always DELETE, regardless of what you code.

A passed data set assumes the conditional disposition specified the lasttime it was passed if a step abnormally terminates. If you don’t specify aconditional disposition, the system deletes the data set if it was new whenfirst passed; otherwise, it keeps it. The following example illustrates the useof the abnormal disposition.

//STEP1 EXEC PGM=CREATE//OUT DD DSN=JUNK,DISP=(NEW,KEEP),// UNIT=SYSDA,VOL=SER=PACK02,SPACE=(4096,100)

If STEP1 abnormally terminates, the system keeps the data set namedJUNK. If you correct the program and resubmit the job with the same JCL, thesystem will abnormally terminate the job again—this time because the data set JUNK already exists on the volume. You must change the dispo-sition of the //OUT DD statement to DISP=(OLD,KEEP). You can avoid thisinconvenience by deleting the data set if the step abnormally terminates.

//STEP1 EXEC PGM=CREATE//OUT DD DSN=JUNK,DISP=(NEW,KEEP,DELETE),// UNIT=SYSDA,VOL=SER=PACK02,SPACE=(4096,100)


Now if STEP1 abnormally terminates, the system deletes JUNK and youneed not change the disposition to OLD when you resubmit the job. Theabnormal disposition is very useful for data sets on direct-access volumesbecause, as the preceding example illustrates, subsequent runs may dependon the disposition of the data sets in previous runs. The abnormal disposi-tion, in addition to deleting unwanted data sets, can also retain informationabout the data set. Here’s how:

//STEP1 EXEC PGM=ONE//A DD DSN=SAVEIT,DISP=(NEW,PASS),UNIT=SYSDA,SPACE=(4096,100)

[If STEP1 abnormally terminates, the system deletes SAVEITbecause PASS is assumed, and passed nontemporary data setsassume their original disposition if the step abnormally terminates.]

//STEP2 EXEC PGM=TWICE//B DD DSN=SAVEIT,DISP=(OLD,DELETE,CATLG)

[If STEP2 abnormally terminates, the system catalogs SAVEIT,retaining the unit and volume information in the catalog. If you usethe checkpoint/restart feature described in Chapter 16 to restart thejob from STEP2, you needn’t change the //B DD statement.]

The status, normal disposition, and abnormal disposition are alloptional. The following examples show the actual dispositions in effect ifparameters are omitted.

//A DD UNIT=3390,SPACE=(4096,100)

[DISP=(NEW,DELETE,DELETE) is assumed. NEW defaults if thestarting status is not specified. If you specify no disposition, the sys-tem assumes one that will leave the data set in the same status it wasat the start of the job step. Since a new data set doesn’t exist at thestart of the step, it assumes DELETE to delete it.]

//B DD DISP=NEW,UNIT=SYSDA,SPACE=(4096,100)

[DISP=(NEW,DELETE,DELETE) is assumed. The system assumesDELETE to revert the new data set to its status at the start of the jobstep.]

//C DD DSN=LIB,DISP=SHR

[DISP=(SHR,KEEP,KEEP) is assumed. The system assumes KEEP asthe disposition because the data set existed at the start of the step.]

//D DD DSN=TURNON,DISP=MOD,UNIT=SYSDA,SPACE=(4096,100)

[DISP=(OLD,KEEP,KEEP) is assumed if TURNON is cataloged orpassed from a previous step. DISP=(NEW,DELETE,DELETE) isassumed if TURNON does not exist.]


TEAMFLY

Team-Fly®

//E DD DSN=IT,DISP=(,KEEP,DELETE),UNIT=SYSDA,SPACE=(4096,100)

[DISP=(NEW,KEEP,DELETE) is assumed. The system assumes NEWif you specify no status.]

//F DD DSN=&&IT,DISP=(OLD,PASS,KEEP)

[DISP=(OLD,PASS,DELETE) is assumed. You can’t keep temporarydata sets, so the system assumes DELETE.]

//G DD DSN=IT,DISP=(OLD,,CATLG),UNIT=SYSDA,VOL=SER=PACK02

[DISP=(OLD,KEEP,CATLG) is assumed. The system assumes KEEPbecause the data set existed at the start of the job step.]

//H DD DSN=&&IT,DISP=(,KEEP),UNIT=SYSDA,SPACE=(4096,100)

[DISP=(NEW,PASS,DELETE) is assumed. The system assumes NEWif you don’t specify a status. You can’t keep temporary data sets, sothe system assumes PASS. The system assumes DELETE as theabnormal disposition because the data set didn’t exist at the start ofthe step.]

7.9 UNIT: I/O UNIT

Essential

An I/O unit is a particular type of I/O device: a 3390 disk, 3490 tape, 3800printer, and so forth. Don’t confuse the I/O unit requested with the UNITparameter with the volume. A volume is a specific storage container: a tapereel or cartridge or a disk volume. Thus, a volume is mounted on an I/Ounit. You request specific volumes with the VOL parameter described laterin this chapter. For an SMS-managed data set, you usually code the STOR-CLAS DD parameter described in Chapter 11 in place of UNIT.

UNIT requests an I/O unit by hardware address, device type, or groupname—or by requesting the unit used by another data set in the same step.Other UNIT subparameters request the system to mount multiple volumesin parallel and that volume mounting be deferred until the data set isopened. UNIT is generally required unless you pass or catalog the data set.The following list gives other circumstances in which the UNIT is notneeded:

SMS is active at your installation and you code the STORCLAS DDparameter or one defaults.

SYSOUT appears on the DD statement. The system ignores UNIT whenyou code SYSOUT.

DUMMY or DSN=NULLFILE appears on the DD statement. The systemignores UNIT when you code them.


The data set already exists, either as a cataloged data set or as a data setpassed from a previous job step, and the VOL=SER parameter is notcoded.

The data set is assigned volumes used by an earlier data set in the samejob with the VOL=REF parameter. The system obtains UNIT infor-mation from the previous DD statement.

To request an I/O unit, code UNIT=address, UNIT=type, or UNIT=group.The address is the hardware address, the type is the numeric model type,and the group is a name assigned by the installation to a group of units.

7.9.1 Group

Essential

Your installation will have several disk volumes and will assign them itsown volume serial numbers. The volumes shown in Figure 7.9 are typical.Someone, either you or the system, has to decide on which volume to writeyour data set. Installations use UNIT names to specify groups of one ormore disks. For example, an installation might use these unit names:

SYSTEM For system data sets—volumes SYSSQE and SYSRES.SYSDA For storage of permanent data sets—volumes PERM01

to PERM04.TEMP For storage of temporary data sets—volumes TEMP01 to

TEMP04.SYALLDA For storage on any direct-access volume. This name is

built into the system.SYS3480R For storage on 3480, 3480X, and 3490 tape units.SYS348XR For storage on 3480X and 3490 tape units.

Figure 7.10 shows how the unit name can group volumes. Your instal-lation will tell you what UNIT values you can use. If you don’t request aspecific volume, the system selects a volume on which to store your dataset, which is usually best.

UNIT=TEMP: The system selects TEMP01, TEMP02, TEMP03, or TEMP04.UNIT=SYSDA: The system selects PERM01, PERM02, PERM03, or PERM04.


FIGURE 7.9 Typical disk volumes.

SYSSQE

SYSRES

TEMP01

PERM01

TEMP02

PERM02

TEMP03

PERM03

TEMP04

PERM04

Code UNIT=group to request one of several I/O devices grouped by theinstallation. UNIT=SYSDA is traditionally defined to be direct-access stor-age devices, and UNIT=SYSSQ is traditionally units, such as tape and disk,that can contain sequential data sets. An installation can define one groupfor temporary and another for nontemporary storage on direct-access vol-umes. Both groups might include different devices. The following exam-ples show the distinction between hardware addresses, type, and group.

Available devices 3390#1 3390#2 3380#1 3380#2Address 130 131 230 231Type 3390 3390 3380 3380Group SYSDA SYSDA SYSDA SYSDA

SCRATCH SCRATCH SCRATCH

UNIT=130 selects 3390#1 only, UNIT=3390 requests either 3390#1 or3390#2, or UNIT=SYSDA allows any of the four devices to be selected.Either 3390#1, 3390#2, or 3380#1 is selected if you code UNIT=SCRATCH.

7.9.2 Type

Rarely Used

UNIT=type requests an I/O device by the IBM model number. For example,UNIT=3390 requests an available 3390 disk. Generally, you shouldn’t usethe type because your installation will replace old types with new typesfrom time to time.

7.9.3 Hardware Address

Rarely Used

UNIT=address requests a specific I/O unit by giving the three-digit hard-ware address of the device, set when the computer is installed. For exam-


FIGURE 7.10 Typical UNIT names.

SYSSQE

SYSTEM

SYSRES

TEMP01

TEMP

PERM01

TEMP02

PERM02

TEMP03

PERM03

TEMP04

PERM04

SYSDA

ple, if a specific tape unit is on 0C4, code UNIT=0C4. Don’t use hardwareaddresses unless you want a specific hardware unit; the system mayalready have allocated the device to another job. It is better to ask for one ofa group of devices and let the system select one that is available. There areseveral other optional subparameters of UNIT described later that applyonly to tape.

7.9.4 AFF: Unit Affinity

Rarely Used

Use AFF only for tape. UNIT=AFF=ddname assigns data sets to the sametape unit used by a previous DD statement in the same step as identified bythe ddname. Unit affinity conserves I/O units by forcing data sets onto thesame physical device. The unit is used sequentially; that is, you must closeeach data set before opening the next data set. Unit affinity implies deferredmounting—the system does not request the volume to be mounted until itopens the data set.

//STEP1 EXEC PGM=ONE//A DD UNIT=TAPE,...//B DD UNIT=AFF=A,...//C DD UNIT=AFF=D,...

[Wrong! Must refer to a previous DD statement.]

//D DD UNIT=DISK,...

If the ddname refers to a dummy DD statement (DUMMY or DSN=NULLFILE), the system also assigns a dummy status to the requesting DDstatement.

7.9.5 Special Options

You specify multiple volumes and deferred mounting with the UNITparameter.

type Pgroup n

UNIT=( , ,DEFER)

Volume Count n

Sometimes Used

The n tells the system how many devices the data set will need (1 to 59) andmust not exceed the number of drives available. The system assumes oneunit if you omit n. For disk, n becomes the default number of volumes on


which the system can write the data set. (For an SMS-managed data set, thisdefault number is set by the DATACLAS you select.)

//A DD UNIT=(3390,2),...

[The system would write the data set on two volumes, if necessary.]

For tape, the system allocates the number of tape drives to the data set,allowing the system to mount the volumes of a multiple-volume data set inparallel. This might save time by eliminating the need for the operator orsystem to dismount and mount volumes on a single drive as they areneeded, but it also denies the use of these units to other jobs. Don’t do par-allel volume mounting for tape.

P: Mounting Volumes in Parallel

Rarely Used

Code P is only for tape to mount the volumes of a multiple-volume data setin parallel. You use it rather than volumes when you pass or catalog thedata set, or when the VOL parameter indicates the number of volumes. Thesystem then obtains the number of volumes from the catalog, from thepassed data set, or from the VOL parameter. Omit the device type or groupfor cataloged or passed data sets because the system also obtains this infor-mation from the catalog or passes it with the data set.

//B DD UNIT=(,P),...

[The system mounts all volumes containing the cataloged or passeddata sets in parallel.]

//C DD UNIT=(TAPE,P),VOL=SER=(000200,000300),...

[The system mounts two volumes (000200 and 000300) in parallel.]

DEFER: Deferred Volume Mounting

Sometimes Used

For tape you can defer volume mounting until an existing data set is openedby coding UNIT=(device,,DEFER). (DEFER is ignored if it coded for a newdata set.) The system will not mount the volume until the data set isopened. DEFER prevents the needless mounting of a volume that a particu-lar run does not require. Mounting and dismounting tapes takes time.DEFER is ignored if the volume is already mounted.

//A DD UNIT=(TAPE,,DEFER),...//B DD UNIT=(,P,DEFER),...


A volume might be deferred when a tape volume is not immediatelyrequired, when successive volumes must be mounted on the same unit, orwhen several files are to be read in succession from the same tape volume.

7.10 VOL: VOLUME PARAMETER

Essential

You use the VOL parameter primarily for tape data sets, although you canuse it for disk. The VOL parameter requests a specific volume, multiple vol-umes, and specific volumes of a multivolume cataloged data set. A volumeis the portion of a storage device served by one read/write mechanism, suchas a tape reel or cartridge or disk volume. You generally need to code theVOL parameter only when you create a data set or when you retrieve a non-cataloged data set. For SMS-managed data sets, coding the STORCLASparameter usually eliminates the need to code VOL.

Each volume can have a label. There are two types of labels (excludingany external label pasted on a tape reel or cartridge): a volume label and adata set label. Both the volume and data set labels are contained in the vol-ume itself as data. The volume label contains the volume serial number andthe system reads it to ensure that an expected volume is actually mounted.Most installations use standard labels for both disk and tape.

Volumes can be permanently mounted, mounted by the operator, ormounted because your job requires them. Disk volumes are all permanentlymounted and tape volumes are all mountable volumes.

Volumes are private or public. The space on public volumes is suballo-cated to many users. The system assigns private volumes to a single user.Only one user at a time can use tapes, and they are always private. Disk vol-umes are always public.

For the two types of volumes, there are two types of requests, specificand nonspecific. You make a nonspecific request, which you can only makefor new data sets, by not requesting a specific volume with the VOL param-eter and by requesting an appropriate UNIT name or coding the SMS STOR-CLAS parameter. Installation must define which UNIT names may benonspecific. For example, UNIT=SYSDA might be nonspecific, in whichcase the VOL parameter could be omitted. UNIT=PRIV might be specific,requiring the VOL parameter to be coded. Check with your installation tofind out which UNIT names are specific and nonspecific.

A nonspecific request is satisfied either by the system selecting an on-line volume or requesting the operator to select and mount a mountable vol-ume. The DISP parameter tells the operator what to do with the volume.KEEP or CATLG tell the operator to assign the volume to the user; DELETEtells the operator that the volume is available for reuse.


7.10.1 SER, REF: Request a Specific Volume

To request specific volumes, code VOL=SER=volume for one volume orVOL=SER=(volume,...,volume) if several volumes (up to 255) are needed.The volume serial numbers are one to six alphanumeric (A to Z, 0 to 9) ornational (@ $ #) characters, or the hyphen (-). You can also use the specialcharacters blank , . / ’ ) ( * & + = by enclosing the volume in apostrophes.Code a legitimate apostrophe as two consecutive apostrophes. If the volumeis less than six characters, the system pads it on the right with blanks to sixcharacters. (Don’t use SCRTCH, PRIVAT, Lnnnnn, or MIGRAT as a volumeserial number because they are reserved for the system.) The followingexample requests tape XT4321. If the tape is not mounted, the system willrequest the operator to mount it.

//A DD DSN=SAVE,DISP=(NEW,CATLG),UNIT=TAPE,VOL=SER=XT4321

The next example requests the system to mount three tape volumes inparallel: volumes TP1, TP2, and TP3. You can continue a DD statementrequesting multiple volumes by breaking the statement following a com-plete serial number, including the comma following it.

//B DD DSN=MANY,DISP=(OLD,KEEP),VOL=SER=(TP1,// TP2,TP3),UNIT=(TAPE,3)

Rather than specifying volume serial numbers, you can request thesame volumes used by another data set. If the other data set is cataloged orpassed from a previous step, code VOL=REF=data-set-name to name thedata set. (Enclose the data set name in apostrophes if it contains specialcharacters.) If the data set is not cataloged, passed, or assigned a temporaryname, code VOL=REF=*.referback to refer back to a previous DD statementdescribing the data set. If the earlier data set resides on multiple volumes,the system assigns only the last for tapes; it assigns all volumes assigned fordirect-access storage. If a DD statement makes a referback to a DD statementdefining a dummy data set, the system also assigns the DD statement mak-ing the referback a dummy status. Don’t refer back to DD*, DD DATA, or DDSYSOUT statements.

//STEP1 EXEC PGM=START//A DD DSN=HOLDUP,DISP=(NEW,PASS),// UNIT=SYSDA,VOL=SER=PACK02,SPACE=(4096,100)//B DD DSN=REPORT,DISP=(NEW,PASS),// VOL=REF=*.A,SPACE=(4096,100)

[The system allocates the space for REPORT on disk volumePACK02. The DD statement doesn’t need a UNIT parameter becausethe system already knows to which unit the volume is assigned.]


//STEP2 EXEC PGM=FINISH//C DD DSN=MORE,DISP=(NEW,CATLG),VOL=REF=*.STEP1.A,SPACE=(4096,100)

Or

//C DD DSN=MORE,DISP=(NEW,CATLG),VOL=REF=HOLDUP,SPACE=(4096,100)

[Space for the data set named MORE is allocated on PACK02.]

7.10.2 Special Options

The following special options are all for mountable volumes, and sinceonly tapes are mountable today, they apply only to them. The options letyou request private volumes, keep private volumes mounted between steps,request multiple volumes, and request a specific volume of a multivolumedata set. All subparameters are optional and you can code them in any com-bination. Code commas to omit any positional subparameters.

SER=...REF=...

VOL=(PRIVATE,RETAIN,start,no-vols, )

PRIVATE: Private Volumes

Rarely Used

VOL=(PRIVATE,...) gives exclusive use of a mountable volume to a particu-lar data set during a step. The system will not assign other data sets to thevolume, and it dismounts the volume after its last use in the step. Onlytapes are mountable, and because they are all PRIVATE anyway, there is noneed to code PRIVATE.

RETAIN: Retain Private Volumes

Sometimes Used

VOL=(,RETAIN,...) keeps a volume mounted between steps. The systemdoes not reposition the volume, but keeps it mounted until it is used in asubsequent step or until the end of the job. (Actually, the operators canforce it to be dismounted—which they will do if the tape drive beingunavailable for other jobs becomes a bottleneck.) Only the last volume of amultivolume data set is kept mounted. Use RETAIN to minimize mountinga tape used in several job steps.

//A DD DSN=A1000.TAPEFILE.DATA,DISP=(NEW,CATLG),UNIT=TAPE,// VOL=(,RETAIN,SER=004527)

[The system won’t dismount volume 004527 at the end of the step.]


The PASS disposition also keeps the volume mounted between steps.Use RETAIN when you cannot use PASS, as for example when you codeCATLG or when a subsequent step retrieves a different file from a tape volume.

If you don’t code RETAIN or pass the data set, the system dismountsmountable volumes at the end of the step. Then if a subsequent steprequests the volume, the operator may have to mount it on another I/O unit.They don’t like doing this. (The CLOSE statement in several languages hasprecedence over DD statement parameters and may specify a different dis-position.)

Sequence

Rarely Used

When you catalog a multivolume data set, the system records all volumeserial numbers in the catalog. To begin processing at other than the first vol-ume, code VOL=(..,..,start,...), where start is the starting sequence number(1 to 255). If you omit start, processing begins with the first volume.

//A DD DSN=A1000.MULT.DATA,DISP=OLD,VOL=(,RETAIN,2)

[Processing begins with volume 2 of the A1000.MULT.DATA data-set. The volume serial numbers and I/O unit are omitted becausethey are contained in the catalog.]

//B DD DSN=A1000.IRS.DATA,DISP=OLD,VOL=(,,3)

[Processing begins with volume 3 of the cataloged A1000.IRS.DATAdata set.]

Volumes

Sometimes Used

If you want a data set to extend onto more than one specific volume, youcan list the volume serial numbers with the SER subparameter to identifythe volumes. If you want a tape data set to extend onto nonspecific vol-umes, you specify the number of volumes in the VOL parameter. The sys-tem ignores no-vols for disk and instead uses the UNIT count. Specify thenumber of tape volumes by coding:

VOL=(..,..,..,no-vols,...)

Give the number (1 to 255 for tape data sets) of volumes needed.VOL=(,,,5) is default, so you need specify this only if you want six or morevolumes. If you omit no-vols or code 1 to 4, it defaults to 5. You can alsogive the number of volumes for a cataloged or passed data set to indicate


that additional volumes may be required. The following requests the oper-ator to assign and mount a maximum of six tapes.

//A DD DSN=A1000.IRS.DATA,DISP=(NEW,CATLG),UNIT=TAPE,VOL=(,,,6)

If you create or extend a multivolume data set and you don’t know thenumber of volumes the data set requires, you can specify a maximum num-ber. If no-vols is less than the number of volumes you list, the systemignores it; if more, the system assigns the additional volumes needed. Here,the system assigns tape volumes 000100 and 000200 to the data set. Sincewe requested a maximum of six volumes, the system may assign up to fouradditional volumes if they are needed. The system records the volume ser-ial numbers of all the volumes used in the catalog.

//A DD DSN=A1000.FILE.DATA,DISP=(NEW,CATLG),// UNIT=TAPE,VOL=(,,,6,SER=(000100,000200))

Alternatively, you can use deferred mounting.

//A DD DSN=A1000.FILE.DATA,DISP=(NEW,CATLG),// UNIT=(TAPE,,DEFER),VOL=SER=(000100,000200)

[The effect of this statement is the same as the preceding one exceptthat the data set is not limited in the number of volumes onto whichit can extend. If more than the two volumes are required, the DEFERrequests the operator to assign additional volumes as needed. Thesystem then catalogs the assigned volumes.]

Now consider two special problems. Suppose you wish to write a dataset on a tape, but you do not know the volume serial number. Code the fol-lowing on the DD statement.

DISP=(MOD,...),UNIT=(unit,,DEFER)

For example, suppose the external label pasted on a tape is lost and youdon’t know the volume serial number. The following job opens the data setfor output and catalogs the tape. The system then lists the volume serialnumber in the data disposition messages and records it in the catalog.

//STEP1 EXEC PGM=OPEN

[Assume that OPEN is a program that opens the data set.]

//A DD DSN=A1000.WHAT.DATA,DISP=(MOD,CATLG),UNIT=(TAPE,,DEFER)

Next, suppose that a program uses a data set twice in the same step; per-haps it first opens it for output, closes it, and then opens it for input. Nor-


TEAMFLY

Team-Fly®

mally one DD statement would suffice, but the program might be coded torequire two DD statements. The second DD statement must contain the fol-lowing:

DSN=*.ddname,DISP=(OLD,...),VOL=REF=*.ddname

The following example illustrates a program that uses a data set twice inthe same step.

//STEP1 EXEC PGM=INOUT//A DD UNIT=SYSDA,SPACE=(4096,100)

[DD statement A creates a temporary data set. (No DISP parametermeans it must be temporary.)]

//B DD DSN=*.A,DISP=OLD,VOL=REF=*.A

[DD statement B refers to the temporary data set.]

EXERCISES

1. Find out your installation’s conventions for disk and tape data setnames.

2. Make a list of the type and group names for all the I/O devices at yourinstallation. Note which ones require specific volume requests, andwhich permit nonspecific requests.

3. Make a list of all the public disk volumes at your installation.

4. Find out how you obtain private tape volumes and how you requestthem to be mounted. Then find out if your installation has any publictape volumes for temporary data sets.


CHAPTER 8

MORE ON THE DD STATEMENT

Essential

With the basics of the DD statement in hand from the preceding chapter,you are ready to read about concatenated data sets, dummy data sets, over-riding the DD statement in procedures, and the placement of DD state-ments.

8.1 SEQUENTIAL AND PARTITIONED DATA SETS

Sequential data sets consist of records that are ordered sequentially, onerecord following another in the order they are entered. A partitioned dataset is composed of several sequential data sets grouped together. Eachsequential data set is called a member of the partitioned data set. Eachmember has a unique name. The entire partitioned data set also has a name.An example of a partitioned data set name is

Y2222.STUDENTS.DATA

The following analogy further illustrates sequential and partitioneddata sets. Suppose there is a four-drawer file cabinet, with a drawer for eachclass—freshmen, sophomores, juniors, and seniors. Each piece of paper inthe file represents a record. A single file drawer represents a sequential dataset as shown in Figure 8.1.

The file drawer (sequential data set) is named Y2222.FRESHMEN.DATA. There is a record for each student. Figure 8.2 represents a parti-tioned data set as a file cabinet. The file cabinet (partitioned data set) isnamed Y2222.STUDENTS.DATA. The file drawers (members) are namedFRESHMEN, SOPHS, JUNIORS, and SENIORS. Each member contains arecord for each student in that class. Partitioned data sets are often used forprogram libraries. The load module created by the linkage editor must bestored in a partitioned data set.

146

MORE ON THE DD STATEMENT 147

There are two types of partitioned data sets—partitioned data sets(PDS), and partitioned data sets extended (PDSE). They are described inChapter 11.

8.2 DUMMY, NULLFILE: DUMMY DATA SETS

You can assign a sequential data set a dummy status in which all I/O oper-ations are bypassed, and device allocation, space allocation, and data setdisposition are ignored. An attempt to read a dummy data set results in animmediate end-of-file exit: the system ignores a write request. You canassign only sequential and VSAM data sets a dummy status.

You can use dummy data sets to test program flow without actually pro-cessing data. Unwanted output (listings, data sets, and so forth) may also besuppressed by giving the output data sets a dummy status.

A data set is assigned a dummy status by coding either DUMMY as thefirst parameter in the DD statement or DSN=NULLFILE. You may also codeother parameters on the DD statement as they would be for a real data set,but except for the DCB parameter, the system ignores them. The systemalways requires a BLKSIZE for dummy data sets so that the OPEN canobtain buffers. The system computes an optimum BLKSIZE for an I/Odevice when you don’t specify the BLKSIZE, but DUMMY data sets have noI/O device, and so the system can’t determine a BLKSIZE. Code BLKSIZEfor all DUMMY data sets if the program does not supply it. The followingexamples illustrate the use of dummy data sets:

FIGURE 8.1 A sequential data set as a file drawer.

ZEND

…

ARTEMUS

ANDERSON

ABLE

AARON

Y2222.FRESHMEN.DATA


//SYSPRINT DD DUMMY

[The system suppresses any output produced by SYSPRINT.]

//SYSIN DD DUMMY

[Any attempt to read data from SYSIN results in an immediate endof file.]

//OUT DD DSN=NULLFILE,DISP=(NEW,CATLG),UNIT=SYSDA,// VOL=SER=PACK12,SPACE=(4096,100),BLKSIZE=4096

[The requested volume is not mounted, no space is allocated, andthe data set is not cataloged. OUT must describe a sequential dataset because only sequential data sets can be given a dummy status.]

//OUT DD DUMMY,DSN=REAL,DISP=(NEW,CATLG),UNIT=SYSDA,// VOL=SER=PACK12,SPACE=(4096,100),BLKSIZE=4096

[This statement is equivalent to the preceding statement.]

A sequence of concatenated data sets is broken by an intervening dummydata set. In the following example, the system reads only the first data set.

FIGURE 8.2 A partitioned dataset as a file cabinet.

Seniors

Juniors

Sophs

Y2222.STUDENTS.DATA

Freshmen


//DD1 DD DSN=ONE,DISP=SHR// DD DUMMY// DD DSN=TWO,DISP=SHR

8.3 CONCATENATING DATA SETS

You can read several input data sets in sequence as if they were a singledata set by concatenating them. Concatenating data sets consists of treatingtwo or more data sets as if they were placed end to end to form one longsequential data set. Suppose you had three separate sequential data sets asshown in Figure 8.3.

To generate a quarterly report, you would need all three data sets. Youwant the system to see them as shown in Figure 8.4.

To concatenate data sets, you write a normal DD statement for the firstdata set, and then add a DD statement without a ddname for each data setto be concatenated. Suppose you want to concatenate these three data sets:

JAN.DATAFEB.DATAMAR.DATA

The following JCL concatenates them. JAN.DATA will be read first, thenFEB.DATA, and last MAR.DATA.

//IN DD DSN=JAN.DATA,DISP=SHR// DD DSN=FEB.DATA,DISP=SHR// DD DSN=MAR.DATA,DISP=SHR

Concatenate data sets by coding a DD statement for each data set in theorder you want them read. Code a ddname on the first DD statement only.NAMES, ADDRESS, PHONES, and the lines of data in the input stream areread sequentially in the following example:

//DATAIN DD DSN=NAMES,DISP=SHR// DD DSN=ADDRESS,DISP=SHR// DD DSN=PHONES,DISP=SHR// DD *

FIGURE 8.3 Three sequential data sets.

JAN.DATA FEB.DATA MAR.DATA


[You need not align the DD statements as shown, but aligning themmakes the statements easier to read.]

[Lines of data]/*

The data sets being concatenated must have the same RECFM. TheLRECL must also be the same for fixed-length records. You can concatenatedata in the input stream with other data sets if the other data sets have aLRECL of 80. You can also concatenate partitioned data sets. You might dothis for program libraries to have the system search in several libraries for amember:

// EXEC PGM=CREATE//STEPLIB DD DSN=A1000.LIB1.LOAD,DISP=SHR// DD DSN=A1000.LIB2.LOAD,DISP=SHR

The //STEPLIB DD statement tells the system which library containsthe program you want to execute. Here, the system will first search theA1000.LIB1.LOAD partitioned data set to find the CREATE program. If itdoesn’t find it, it then searches the A1000.LIB2.LOAD data set.

You can also concatenate the individual members of a partitioned dataset. It will appear to the system as if they were one long sequential data setas shown in the following example. Figure 8.5 shows how the data set istreated.

// EXEC PGM=REGISTER//IN DD DSN=A1000.STUDENTS.DATA(FRESHMEN),DISP=SHR// DD DSN=A1000.STUDENTS.DATA(SOPHS),DISP=SHR// DD DSN=A1000.STUDENTS.DATA(JUNIORS),DISP=SHR// DD DSN=A1000.STUDENTS.DATA(SENIORS),DISP=SHR

FIGURE 8.4 Three concatenated data sets.

JAN.DATA

FEB.DATA

MAR.DATA


The next example concatenates sequential data sets with a member of apartitioned data set. The system reads member ONE in A1000.TEST.COBOLfirst, then the lines of data, and finally the sequential data set A1000.NAMES.COBOL.

//DATAIN DD DSN=A1000.TEST.COBOL(ONE),DISP=SHR// DD *[Lines of data]/*// DD DSN=A1000.NAMES.COBOL,DISP=SHR

You must supply a member name for any partitioned data set concate-nated with a sequential data set. In the following example, an I/O erroroccurs when the system reads DATAIN because A1000.TEST.COBOL is apartitioned data set.

//DATAIN DD DSN=A1000.NAMES.COBOL,DISP=SHR// DD DSN=A1000.TEST.COBOL,DISP=SHR

To read a partitioned data set in its entirety, concatenate each member.The following rules apply to concatenating data sets:

� You can’t concatenate VSAM data sets.� The concatenated data sets can reside on different devices.� You can concatenate as many as 114 partitioned data sets as parti-

tioned data sets. There is no concatenation limit on the number ofpartitioned data set members or of sequential data sets.

� The LRECL must be the same for fixed-length records. It need not bethe same for variable-length records as long as you place the data setwith the longest LRECL on the first DD statement. If the data set it

FIGURE 8.5 Concatenating data sets.

Directory

The partitioned data setthat looks like this:STUDENTS.DATA

FRESHMEN

SOPHS

JUNIORS

SENIORS

Is treated by thesystem as if it were:

FRESHMEN

SOPHS

JUNIORS

SENIORS

describes doesn’t have the longest LRECL, code the LRECL parameteron the DD statement. The system will use the LRECL stored in thedata set’s label to actually determine the length of the records in thedata set.

� The BLKSIZE need not be the same. (In the rare case where the dataset is not partitioned or sequential and is not on disk or tape, youmust specify the largest block size in the first DD statement. Unlessthe data set described by the first DD statement is the largest, code aBLKSIZE parameter specifying the largest size. Assuming the con-catenated data sets have standard labels, the system will use the BLK-SIZE on the DD statement for allocating buffers, but use the BLKSIZEin the data set label in determining how the data set is actuallyblocked.)

EXERCISES

Execute the program from Chapter 5 twice in succession within the samejob. Name the first EXEC statement STEP1 and the second EXEC statementSTEP2. Override STEP1 as follows:

//GO.OUT DD DISP=(NEW,PASS),UNIT=public-disk,// RECFM=FB,LRECL=80,SPACE=(4096,(1,1))

Override STEP2 to concatenate its stream input to the end of the tem-porary data set from STEP1. Verify that the job is correct by checking theoutput printed from STEP2.


CHAPTER 9

DD STATEMENTS FOR INPUTSTREAM AND PRINT DATA SETS

This chapter discusses the DD statements required to read and write data forinput and output stream data sets. Since you can control the printed outputwith the DD SYSOUT statement, with the JCL OUTPUT statement, and withthe JES2/*OUTPUT statement, they are all described in this chapter, as arethe parameters on the JCL JOB and JES statements that control printing.

9.1 *,DATA: INPUT STREAM DATA SETS

Essential

Data in the form of 80-byte lines is perhaps the most common type of input.The 80-byte length is an accident of history. Punched cards had 80columns. To include lines of data in the input stream, code the following:

//ddname DD *[Lines of data]/*

SYSIN is the ddname for lines of data in the input stream. The /* marksthe end of the lines. The lines of data cannot contain // or /* in columns 1and 2 when DD * is used. If the lines contain // in columns 1 and 2, as itwould if the data included JCL, code DATA in place of *.

//ddname DD DATA[Lines of data which may contain // in columns 1 and 2.]/*

DATA is the same as * except that lines with // in columns 1 and 2 maybe included. Both * and DATA are positional parameters and must be codedbefore any other parameters on the DD statement. You cannot place DD * orDATA in cataloged procedures because they must immediately precede thelines of data in the input stream.

153

There may be several DD * or DATA statements with different ddnamesbecause input is queued on a direct-access volume before the job is executed.If the system encounters lines of data (any lines not having // or /* incolumns 1 and 2) not preceded by a DD * or DATA statement, it automaticallyprovides a DD * statement with a ddname of SYSIN. If a cataloged procedureis invoked, the generated //SYSIN DD statement applies to the first step of theprocedure. If DD * is specified or assumed and the /* statement is omitted,the system assumes a /* when the next statement with a // in columns 1 and2 is encountered. This means that you can usually omit the /*.

//STEP1 EXEC PGM=PRIMERO[Lines of data]//STEP2 EXEC PGM=SEGUNDO

These steps are equivalent to the following:

//STEP1 EXEC PGM=PRIMERO//SYSIN DD *[Lines of data]/*//STEP2 EXEC PGM=SEGUNDO

Note that the /* delimiter is required for a DD DATA statement becauseDD DATA treats lines containing // in columns 1 and 2 as data.

9.1.1 DLM: Delimiter Parameter

Rarely Used

If the data itself contains /* in columns 1 and 2, which could occur if thedata consisted of JCL statements, code the DLM=‘cc’ parameter on the DDstatement to specify any two characters as the delimiter. If the delimiter con-tains an ampersand or apostrophe, code it as two consecutive characters:

DLM=‘&&’ ” specifies the delimiter characters as &’. DLM can be codedon either a DD * or DATA statement.

//SYSIN DD *,DLM='ZZ'[Lines of data which may contain /* in columns 1 and 2.]ZZ

9.1.2 DCB Subparameters

Rarely Used

The system blocks input stream data automatically. The DCB=BUFNO sub-parameter specifies the number of buffers, and the DCB=LRECL subparam-


TEAMFLY

Team-Fly®

eter specifies the logical record length if you don’t want 80. The followingprovides two buffers for reading the input.

//SYSIN DD DATA,DCB=BUFNO=2

9.1.3 DSN Parameter

Rarely Used

You can assign a name to the input data set if you wish. About the only rea-son for this might be to make it easier to identify the allocation messages inyour JCL listing. You can’t use the data set name and it doesn’t do anything.To assign a name, code DSN=&&name, where name is a normal one- toeight-character name.

//SYSIN DD *,DSN=&&TEMP

The system now gives the output stream data set the following name onthe output listing:

userid.jobname.jobid.Ddsnumber.TEMP

9.2 SYSOUT: OUTPUT STREAM DATA SETS

Essential

The DD statement SYSOUT parameter routes output to a printer. Forprinted output, you code the DD statement as

//ddname DD SYSOUT=class

The class can be any alphanumeric (A to Z, 0 to 9) character or the aster-isk (*). An installation may define separate output classes for special forms,high-volume output, high-priority output, and so forth. SYSOUT=A is tra-ditionally the printer.


The asterisk specifies the same class as specified on the MSGCLASSparameter on the JOB statement.

//RT452216 JOB (45992),'SMITH',CLASS=A,MSGCLASS=E� � �

//SYSPRINT DD SYSOUT=*

[Same as SYSOUT=E.]

DD STATEMENTS FOR INPUT STREAM AND PRINT DATA SETS 155

Output is queued onto a direct-access volume, and system output writ-ers later write the output onto the appropriate I/O device. A computer oper-ator must start an output writer to a specific printer, and each writer maywrite several classes of output. Use an active output class or the output willremain queued on the direct-access volume. If you write several data sets tothe same output class, the system prints each data set separately in theorder of the DD statements.

You can also code the CLASS parameter on the OUTPUT statementdescribed later in this chapter. However, CLASS on a DD statement over-rides CLASS on the OUTPUT statement, so if you want to specify the classon an OUTPUT statement, you must write a null class on the SYSOUT DDstatement:

//OUT DD SYSOUT=(,),OUTPUT=*.TEST1

You can code the following parameters only on the DD SYSOUT state-ment. There are more parameters that you can also code on other statementsdescribed later in this chapter. SYSOUT data sets cannot be SMS-managed.

9.2.1 DCB Subparameters

Rarely Used

You can code LRECL for any output stream device. RECFM describes therecord format (F, V, U) and printer control characters (A for ASA controlcharacters and M for machine code control characters).

9.2.2 DSN Parameter

Rarely Used

You can assign a name to the SYSOUT data set, but the only reason for thismight be to make it easier to identify the allocation messages in your JCLlisting. You can’t use the data set name and it doesn’t do anything. To assigna name, code DSN=&&name, where name is a normal one- to eight-character name.

//SYSOUT DD *,DSN=&&TEMP

The system now gives the output stream data set the following name:

userid.jobname.jobid.Ddsnumber.TEMP

9.2.3 HOLD Parameter to Hold the Output

Sometimes Used

For TSO or ISPF on-line usage, HOLD=YES holds the output in the outputqueue rather than printing it. This allows you to retrieve the output from


the queue and display it on a terminal rather than waiting for it to beprinted.

//SYSPRINT DD SYSOUT=A,HOLD=YES

The system holds the output until you free it or until the operatorreleases it. You can tell the operator whether to print or purge the outputwith the JES2 /*MESSAGE or the JES3 //*OPERATOR statement. OmittingHOLD or coding HOLD=NO requests the system to process the output nor-mally. Coding HOLD on a DD statement overrides any HOLD coded on anOUTPUT statement.

9.2.4 Parameters to Control when Printing Starts

Rarely Used

Start Data Set Printing Immediately: SEGMENT (JES2 Only)The SEGMENT parameter starts a data set printing while the job step is running, even if the program is still writing output to the data set. CodeSEGMENT as

//ddname DD SYSOUT=class,SEGMENT=pages

The pages is the number of pages to write in the data set before printingbegins. The data set must have RECFM=A or RECFM=M, which almost allSYSOUT data sets do.

You might use SEGMENT for jobs producing large amounts of output tooverlap printing with execution of the job step to complete the printingsooner. SEGMENT can also start multiple copies of the output printingsimultaneously on multiple printers.

//SYSPRINT DD SYSOUT=A,SEGMENT=80

[Each time you generate 80 pages in the data set, the systemreleases them for printing. If the installation had multiple printers,the different 80-page segments might print concurrently on differ-ent printers.]

Begin Printing when Data Set Is Deallocated: SPINThe SPIN parameter starts a data set printing when the system deallocatesthe data set rather than at the end of the job as is normal. This overlaps theprinting with execution of subsequent job steps to complete the printingsooner. Code SPIN as

//ddname DD SYSOUT=class,SPIN=UNALLOC

The default is SPIN=NO, which prints the data set at the end of the job.If you code both SEGMENT and SPIN, SEGMENT overrides SPIN.


Deallocate Data Set when It Is Closed: FREEFREE deallocates a data set when it is closed rather than at the end of a step.Use FREE in combination with SPIN to print a data set when the data set isclosed rather than at the end of the job step. Code FREE as

//ddname DD SYSOUT=class,SPIN=UNALLOC,FREE=CLOSE

The default is FREE=END, which deallocates the data set at the end ofthe job step.

9.2.5 Generating JCL within a Program and Submitting It

Rarely Used

For sophisticated applications, you may want to write a program that gen-erates JCL as output and then submit this output to the input stream as ajob. You can easily do this by coding the SYSOUT DD statement as

//ddname DD SYSOUT=(class,INTRDR)

This sends the output you write to the SYSOUT data set directly to theinput stream, as if you had submitted it as a job. If the JOB statement of the generated JCL has no MSGCLASS parameters, the system assumes theSYSOUT class. In addition to writing the JCL, you can also intersperse the following statements:

/*EOF: This marks the end of the generated JCL and tells the systemthat the job is ready for submission.

/*DEL: This cancels the job, and you get the normal JCL listing for acanceled job.

/*PURGE: (JES2 only). This cancels the job and produces no output.

/*SCAN: (JES2 only). This tells JES2 to scan the data set for JCL errorsbut not execute it.

9.3 THE OUTPUT JCL STATEMENT AND OUTPUT DD PARAMETER

Essential

The OUTPUT JCL statement, along with the OUTPUT parameter on the DDstatement, lets you specify special processing for SYSOUT data sets.

9.3.1 The OUTPUT Statement

The OUTPUT statement has many of the same parameters as those onSYSOUT DD statements, plus several additional ones. You code parameters


on the OUTPUT statement rather than on individual DD statements for tworeasons:

� To specify identical SYSOUT parameters for several DD statementswith a single OUTPUT statement.

� To print the output from a single DD statement several times, eachwith different SYSOUT parameters or perhaps on different printers.

For example, suppose you wanted all the SYSOUT DD statements tohave the following parameters:

//SYSPRINT DD SYSOUT=A,BURST=Y,COPIES=2,DEST=RMT001,// CHARS=XYZ,MODIFY=LOGO,FLASH=FM1

Rather than code them all on each SYSOUT DD statement, you can codethem once on a single OUTPUT statement and place it between the JOBstatement and the first EXEC statement. The SYSOUT parameters on theOUTPUT statement then apply to every SYSOUT DD statement in the job,saving coding and making it easy to change the print options.

//RT452216 JOB (45992),'SMITH',CLASS=A//FORMS1 OUTPUT DEFAULT=YES,BURST=Y,COPIES=2,DEST=RMT001,// CHARS=XYZ,MODIFY=LOGO,FLASH=FM1

[The DEFAULT=YES parameter tells the system that the OUTPUTstatement is to be applied to all SYSOUT DD statements in the job.]

//STEP1 EXEC PGM=PRINTIT//SYSPRINT DD SYSOUT=A

[The system treats this SYSOUT DD statement and any otherSYSOUT DD statements in the job as if all the options on the OUT-PUT statement were coded on them.]

To apply the OUTPUT statement to just one step in the job rather thanthe entire job, place it after the EXEC statement for the step but before anySYSPRINT statements to which it is to apply.

//RT452216 JOB (45992),'SMITH',CLASS=A//FORMS1 OUTPUT DEFAULT=YES,// BURST=Y,COPIES=2,DEST=RMT001,// CHARS=XYZ,MODIFY=LOGO,FLASH=FM1

� � �

//STEP6 EXEC PGM=PRINTTHE//PRINTOUT DD SYSOUT=A

[The system uses the FORM1 OUTPUT statement parameters forthis DD statement because it hasn’t encountered the FORMS2 OUT-PUT statement yet.]


//FORMS2 OUTPUT DEFAULT=YES,// BURST=N,COPIES=1,DEST=RMT005,// CHARS=XYZ,MODIFY=LOGO,FLASH=FM1

[Must be placed after the EXEC, but before any SYSOUT DD state-ments to which it is to apply.]


[The system uses the FORMS2 OUTPUT statement parameters forthis SYSOUT DD statement.]

To summarize:

Place the OUTPUT statement between the JOB and the first EXEC toapply to the entire job.

Place the OUTPUT statement following an EXEC statement to apply toany SYSPRINT statements following it in that step.

Placing the OUTPUT statement after the JOB or EXEC statement makesit available for use within the job or step. Place the OUTPUT statements fora step before the DD statements.

You write the OUTPUT statement as

//outname OUTPUT parameter,parameter,...,parameter

Choose an outname that is unique within the job. The outname is one toeight alphanumeric or national characters; the first character must be alpha-betic or national. The parameters are described in the following section.

9.3.2 Implicit Referencing

DEFAULT=YES tells the system that the OUTPUT applies to all theSYSOUT DD statements for which it is active (all SYSOUT DD statementsif placed after the JOB and before the first EXEC, or to all SYSOUT DD state-ments following it in a step when placed after the EXEC). This is calledimplicit referencing.

//jobname JOB ...//outname OUTPUT DEFAULT=YES,parameter,parameter,...,parameter

The system now automatically applies the parameters coded on thisOUTPUT statement to all SYSOUT DD statements in the job.

DEFAULT=NO tells the system that the OUTPUT statement applies onlywhen it is explicitly referenced. If the OUTPUT statement is implicit at boththe job level and for a step, only the step values are used. For example,


//RT452216 JOB (45992),'SMITH',CLASS=A//FORM1 OUTPUT DEFAULT=YES,COPIES=2

[COPIES=2 implicit for the job.]

//STEP1 EXEC PGM=ONE//FORM2 OUTPUT COPIES=3

[COPIES=3 implicit for the step, overriding the implicit value forthe job.]

9.3.3 Explicit Referencing with the OUTPUT Parameter

Essential

Explicit referencing applies the OUTPUT parameters to only thoseSYSOUT DD statements that call for it. For explicit referencing, code anOUTPUT parameter on a SYSOUT DD statement to reference the OUTPUTstatement to use. (The JES2/*OUTPUT statement, the OUTPUT statement,and the OUTPUT parameter on the OUTPUT statement are different thingsand easy to confuse.) If you code the OUTPUT parameter on a DD statementnot containing SYSOUT, the system checks it for syntax and then ignores it.You code the OUTPUT parameter as

//ddname DD SYSOUT=A,OUTPUT=*.referback,...

[The system uses the parameters from both the OUTPUT statementand the SYSOUT DD statement. If the same parameter appears inboth places, the system uses the one on the SYSOUT DD statement.]

The referback refers back to the OUTPUT statement to use. You cancode the referback as

//DD1 DD OUTPUT=*.outname,...

[Refers back to an OUTPUT statement that is either placed in thisstep or placed following the JOB statement. The system first checksfor an OUTPUT statement in the current step, and then for one fol-lowing the JOB statement. Note that it checks within the step onlyback up to the EXEC.]

//DD2 DD OUTPUT=*.stepname.outname,...

[Refers back to the OUTPUT statement in the step named.]

//DD3 DD OUTPUT=*.stepname.procstepname.outname,...

[Refers back to the OUTPUT statement in a cataloged procedure.]

You usually omit the DEFAULT parameter or code DEFAULT=NO onthe OUTPUT statement being referenced. This way, the system will not


implicitly apply the parameters on it to all the other SYSOUT DD state-ments. Omitting the DEFAULT=YES on the OUTPUT statement or codingDEFAULT=NO tells the system to not apply the OUTPUT parameters toother SYSOUT DD statements.

//RT452216 JOB (45992),'SMITH',CLASS=A//STEP1 EXEC PGM=ONE//FORM2 OUTPUT COPIES=2

� � �

//STEP3 EXEC PGM=THREE//SYSPRINT DD SYSOUT=A,OUTPUT=*.STEP1.FORM2

[The OUTPUT parameter here refers back to the FORM2 OUTPUTstatement.]

The OUTPUT parameter on a DD statement can refer to more than oneOUTPUT statement.

//ddname DD SYSOUT=class,OUTPUT=(*.referback,...,*.referback),...

Each OUTPUT DD parameter can refer to as many as 128 OUTPUTstatements. The system then prints the output as directed by each OUTPUTstatement, allowing you to print the output several times, perhaps at differ-ent locations or on different print forms. Here is an example:

//STEP1 EXEC PGM=ONE//FORM1 OUTPUT COPIES=2,DEST=CORP//FORM2 OUTPUT COPIES=3,DEST=MFG

� � �

//STEP4 EXEC PGM=FOUR//SYSPRINT DD SYSOUT=A,OUTPUT=(*.STEP1.FORM1,*.STEP1.FORM2)

[The system prints two copies as directed by FORM1 and threecopies as directed by FORM2.]

Explicit references have precedence over implicit references. The fol-lowing example illustrates this:

//RT452216 JOB (45992),'SMITH',CLASS=A//STEP1 EXEC PGM=PRINTIT//FORMS1 OUTPUT DEFAULT=YES,// BURST=Y,COPIES=2,DEST=RMT001,// CHARS=XYZ,MODIFY=LOGO,FLASH=FM1//SYSPRINT DD SYSOUT=A//STEP6 EXEC PGM=PRINTTHE//PRINTOUT DD SYSOUT=A

[The system uses the FORMS1 OUTPUT statement parameters forthis DD statement because it hasn’t encountered the FORMS2 OUT-PUT statement yet.]


//FORMS2 OUTPUT DEFAULT=YES,// BURST=N,COPIES=1,DEST=RMT005,// CHARS=XYZ,MODIFY=LOGO,FLASH=FM1

[Must be placed after the EXEC, but before any SYSOUT DD state-ments to which it is to apply.]


[The system uses the FORMS2 OUTPUT statement parameters forthis DD statement.]

//PRINTIT DD OUTPUT=*.STEP6.FORMS1

[The system uses the FORMS1 OUTPUT parameters.]

The order of precedence of SYSOUT processing, from highest to low-est, is

1. Parameters coded on a SYSOUT DD statement have highest priority.

2. Explicit parameters (OUTPUT=*.referback).

3. Step level implicit OUTPUT statements.

4. Job level implicit OUTPUT statements have lowest priority.

You can place OUTPUT statements in a cataloged procedure, as long asyou place them after the first EXEC statement in the procedure. (You can’toverride an OUTPUT statement in a cataloged procedure, however.) Placeany OUTPUT statements in front of the DD statements for a step. An OUT-PUT parameter in the input stream can refer back to an OUTPUT statementin a cataloged procedure. However, the reverse isn’t true. An OUTPUTparameter within a cataloged procedure can’t refer to an OUTPUT state-ment in the input stream.

9.3.4 OUTPUT JCL Statement Parameters

The following options are unique to the OUTPUT statement:

Essential

DEFAULT=YES tells the system that the OUTPUT statement is implicitand applies to all SYSOUT DD statements in its range that do notcontain an OUTPUT parameter specifically referencing anotherOUTPUT statement. The default is DEFAULT=NO, meaning that theOUTPUT statement parameters on it are applied only when anOUTPUT parameter refers back to this OUTPUT statement.


Sometimes Used

CLASS=class specifies the SYSOUT class. Code CLASS=* to use theMSGCLASS parameter on the JOB statement. Although CLASSspecifies the output class, you still need to code SYSOUT on the DDstatement to make it a SYSOUT data set. Write a null SYSOUT classon the DD statement://OUT DD SYSOUT=(,),OUTPUT=*.TEST1.

JESDS=which specifies whether the JCL listing and job log apply to thisOUTPUT statement. The options for which are as follows:� ALL requests JCL, LOG, and MSG.� JCL requests just the JCL listing.� LOG requests just the job’s hard-copy log.� MSG requests just the system messages for the job.

Since the JESDS parameter applies to the entire job, place any OUT-PUT statement on which you code JESDS between the JOB and firstEXEC statement.

NOTIFY=node.userid sends a message to the userid at the node whenthe printing on a Print Services Facility printer completes. You canomit node (NOTIFY=userid) if the userid is at the node were the jobwas submitted. You can also notify as many as four users by coding:NOTIFY=(node.userid,node.userid,node.userid,node.userid)

OUTBIN=n requests the output be placed in printer output bin n (1 to65535).

OUTDISP=(normal-disposition,abnormal-disposition) (JES2 only)controls the output disposition for normal and abnormal job termi-nation. You may code the following dispositions for both normaland abnormal termination:� WRITE prints the output and then deletes it.� HOLD holds the output data set until you or an operator release it.� KEEP prints the output and then changes the disposition to

LEAVE.� LEAVE changes the disposition to KEEP after you or the operator

release the output.� PURGE deletes the output without printing it.

The HOLD parameter on a DD statement overrides the OUTDISPparameter. If you don’t code OUTDISP, the system uses the installa-tion default. If you don’t specify a normal disposition, the systemassumes WRITE. If you don’t specify an abnormal disposition, thesystem assumes the normal disposition.


TEAMFLY

Team-Fly®

PRTY=priority specifies the priority (0 to 255) of the printing in theoutput queue. Zero is lowest.

Rarely Used

COLORMAP=resource specifies the AFP (Advanced Function Presen-tation) Resource used by PSF for data sets that contain color trans-lation information. Your installation must tell you the resourcenames to use.

COMSETUP=resource names a microfile setup resource containingsetup information.

DATACK=block tells the system how to handle print-positioning errors(when the designated print position is off the page) and invalid-character data-check errors (when an unrecognizable character isprinted). The block options are as follows:� BLOCK ignores errors and continues. It is usually the default, but

an installation can change this.� UNBLOCK reports all errors to Print Services Facility (PSF).� BLKCHAR ignores invalid-character errors but reports the print-

positioning errors to PSF.� BLKPOS ignores print-positioning errors but reports invalid char-

acter errors to PSF.

DPAGELBL=YES prints a security label on each page of printed output.The installation sets the security label through RACF to includesecurity levels and categories. DPAGELBL=NO suppresses the secu-rity label. The installation sets the default.

DUPLEX overrides the FORMDEF in effect to specify whether to printon one or both sides of the paper. DUPLEX=NO prints on one sideonly, DUPLEX=NORMAL prints on both sides with the page rotatedon the y axis (long edge of sheet) to allow binding on the long edge,and DUPLEX=TUMBLE prints on both sides with the page rotatedon the x axis (short edge of sheet) to allow binding on the short edge.

FORMDEF=member names a library member that contains statementsto tell Print Services Facility (PSF) how to print the data set on apage-mode printer, such as the IBM 3800 Model 3. The statementsin the member may specify overlay forms, location on the page ofthe forms, and when to suppress the form for certain page formats.

FORMLEN sets the length of the page for printing without reconfiguringthe printer. Code FORMLEN=nIN or n.dIN or nCM or n.dCM tospecify the form length in inches (IN) or centimeters (CM). The n


can be 1-2 digits and the optional .d can be 1-3 digits. For example,FORMLEN=4.5IN

GROUPID=group (JES2 only) specifies that the SYSOUT data set belongsto an output group.

OFFSETXB, OFFSETXF, OFFSETYB, and OFFSETYF=value overridethe default set for the FORMDEF to set the offset in the X or Y direc-tions, and the page origin for the Front or Back side of the page. Thevalue can be n or n.d, where n is 1-2 digits and .d 1-3 digits. Followthis with IN for units in inches, CM for centimeters, MM for millimeters, PELS for pels (picture elements or pixels), or POINTSfor points. For example, OFFSETXB=1IN, OFFSETXF=1.5IN, OFFSETYB=16CM

OVERLAYB and OVERLAYF=ovlyname specify an overlay to place onthe Back or Front side of each sheet printed. Your installation willtell you the overlay names to use.

PAGEDEF=member is identical to the FORMDEF parameter exceptPAGEDEF member statements specify page formatting, such as sizeand fonts. It is applicable only to a page-mode printer, such as theIBM 3800 Model 3.

PIMSG=YES is the default and requests that the Print Services Facilitymessages be printed with the output listing following the SYSOUTdata set. PIMSG=NO suppresses the messages. You can code YES(n)or NO(n) to tell the system to cancel printing after n (0 to 999) errors.PIMSG=YES(0) or NO(0) specify no canceling.

PORTNO=n specifies the port number at which the functional subsys-tem connects to the printer. Your installation must provide thenumber to use.

PRMODE=LINE or PAGE or mode specifies the process mode for theSYSOUT data set. LINE schedules the data set on a line-modeprinter. PAGE schedules the data set on a page-mode printer. Themode is a one to eight alphanumeric character mode.

PRTERROR=action tells what to do when an error occurs that preventsprinting a data set. PRTERROR=DEFAULT restores the defaultaction, PRTERROR=QUIT releases the data set as if it had been suc-cessfully printed, and PRTERROR=HOLD holds the data set foroperator action.

PRTOPTNS=’name’ names an entity that contains additional printoptions to use for a data set using a functional subsystem that canperform Internet Protocol transmission. Your installation must tellyou the names to use.


PRTQUEUE=‘name’ names the print queue on a remote host systemthat is to receive the print data set that uses a functional subsystemthat can perform Internet Protocol transmission. Your installationmust tell you the queue names to use.

RETAIN tells how long to retain transmitted data sets processed by a func-tional subsystem (FSS) performing Internet Protocol (IP) transmis-sion. RETAINS=’hhhh:mm:ss’ retains successfully transmitted datasets and RETAINF=’hhhh:mm:ss’ failed data sets. The single quotesare required around the time. Code FOREVER to retain the data setforever. For example, RETAINS=’0004:00:00’, RETAINF=FOREVER

RETRYL=times specifies the maximum times to attempt to transmit a dataset processed by a functional subsystem performing Internet Protocol(IP) transmission, and RETRYT=’hhhh:mm:ss’ specifies the time towait between transmission attempts. The single quotes are requiredaround the time. For example, RETRYL=5, RETRYT=’0000:10:00’

RESFMT=P240 or P300 sets the resolution for 240 or 300 pels/inch (pic-ture elements/inch, same as dots or pixels per inch on the PC).

SYSAREA=YES reserves an area on each page of printed output and isusually coded in combination with DPAGELBL=YES. SYSAREA=NOreserves no area. The installation establishes the default if you don’tcode SYSAREA.

USERDATA=(value,value, . . . ,value) specifies 1 to 16 values definedby an installation for its own use. Each value is 1 to 60 EBCDIC char-acters. Enclose a value in apostrophes if it contains any specialcharacters.

USERLIB=(data-set-name,data-set-name, . . . ,data-set-name) names1 to 8 library data sets containing information such as fonts, pagesegments, overlays, and page definitions, used by Print ServicesFacility to process the data set.

The following parameters supply fields to print on the separator pagesof the output. The fields may contain 1 to 60 characters with any apostro-phe coded as two apostrophes:

//PRINTIT OUTPUT NAME='HENRY O''BRIAN'

Sometimes Used

ADDRESS=(‘delivery-address, . . . ,delivery-address’) prints one to fourdelivery address lines to help the operators distribute the output.

BUILDING=‘building-name’ prints one line for the building name.


DEPT=‘department-name’ prints one line for the department name.

NAME=‘name-of-person’ prints one line for your name.

ROOM=‘room-name’ prints one line for the room name.

TITLE=‘output-description’ prints one line to describe the output.

You can code the remaining OUTPUT parameters on several statementsas described at the end of this chapter.

9.4 THE JES2/*OUTPUT STATEMENT

Rarely Used

The JES2/*OUTPUT statement specifies parameters for one or more of thejob’s SYSOUT data sets. It is completely redundant to the JCL OUTPUTstatement, which IBM recommends you use instead. Parameters on the/*OUTPUT statement override those on OUTPUT statements. You code theJES2/*OUTPUT statement as

/*OUTPUT code parameter,parameter,...,parameter

The code consists of 1 to 4 alphanumeric characters that identify theSYSOUT statements to which this /*OUTPUT statement is to apply andbegin in column 10. The system uses the /*OUTPUT parameters for allSYSOUT statements in which code matches the third subparameter of theSYSOUT parameter:

SYSOUT=(class,program,code)

The parameters are described as follows. Here is an example of theJES2/*OUTPUT statement.

//RT452216 JOB (45992),'SMITH',CLASS=A/*OUTPUT LTR DEST=HOUSTON,LINECT=55//STEP1 EXEC PGM=ONE//PRINTIT DD SYSOUT=(A,,LTR)

[Same as if DEST=HOUSTON and LINECT=55 had been coded onthis DD statement.]

//STEP2 EXEC PGM=TWO//OUTPUT DD SYSOUT=(A,,LTR),DEST=ATLANTA,COPIES=2

[Same as if DEST=HOUSTON, LINECT=55, and COPIES=2 had beencoded on this DD statement. Note that DEST=HOUSTON on the/*OUTPUT statement overrides DEST=ATLANTA on the SYSOUTDD statement.]


To continue the /*OUTPUT statement, end the statement after a com-plete parameter and its comma, code /* in columns 1 and 2 and an * (aster-isk) in column 10 and continue the parameters in column 11:

/*OUTPUT LTR DEST=HOUSTON,/* *LINECT=55

9.5 THE JES3//*FORMAT PR STATEMENT

Rarely Used

The //*FORMAT PR statement also specifies parameters for SYSOUT datasets. It is redundant to the JCL OUTPUT statement, which IBM recom-mends you use instead. The //*FORMAT PR parameters override those onthe OUTPUT statements. Code the //*FORMAT PR statement as

//*FORMAT PR,DDNAME=ddname,parameter,parameter,...,parameter

The ddname identifies the DD statement describing the data set towhich the parameters apply. You can also write the ddname as SYSMSG to specify system messages, as JESJCL to specify the JCL messages, or asJESMSG to specify the JES3 and operator messages. The parameters aredescribed as follows. Here is an example of the JES3 //*FORMAT PR state-ment.

//RT452216 JOB (45992),'SMITH',CLASS=A//*FORMAT PR,DDNAME=PRINTIT,//* DEST=HOUSTON

[Continue //*FORMAT PR statements as you would JCL state-ments.]

//STEP1 EXEC PGM=ONE//PRINTIT DD SYSOUT=A

[Same as if DEST=HOUSTON had been coded on this DD state-ment.]

//STEP2 EXEC PGM=TWO//OUTPUT DD SYSOUT=A,DEST=ATLANTA,COPIES=2

[Same as if DEST=HOUSTON and COPIES=2 had been coded onthis DD statement. Note that DEST=HOUSTON on the //*FORMATPR statement overrides DEST=ATLANTA on the SYSOUT DD state-ment.]


9.6 PARAMETERS CODED ON SEVERAL STATEMENTS

Essential

Coding a parameter on a statement higher in the hierarchy shown here over-rides the same parameter on a statement below it.

1. JES2 /*OUTPUT statement parameters (highest)

2. JES3 //*FORMAT PR statement parameters

3. JCL SYSOUT DD statement parameters

4. JCL explicit OUTPUT statement parameters (OUTPUT=*.referback)

5. JCL step level implicit OUTPUT statement parameters

6. JCL job level implicit OUTPUT statement parameters

7. JCL JOB statement

8. JES2 /*JOBPARM statement

9. JES3 //*MAIN statement (lowest)

Use the following guidelines to determine where you should code aparameter.

If your installation has standards, follow them.

Code the parameter at the highest level you can. That is, if the parame-ter applies to all the DD statements in a job and you can code it onthe JOB statement, code it there.

Code parameters that apply to a specific DD statement on the DD state-ment.

Code parameters for output on the JCL OUTPUT statement whereveryou can.

Don’t code the JES2/*OUTPUT or the JES3//*FORMAT PR statements.

Code parameters on the JES2/*JOBPARM or the JES3//*MAIN state-ment only if you cannot code them on other statements.

9.6.1 Multiple Copies: COPIES

Sometimes Used

Request multiple copies by coding the COPIES parameter on the followingstatements.

JES2 /*OUTPUT code COPIES=nJES3 //*FORMAT PR DDNAME=ddname,COPIES=nJCL //ddname DD SYSOUT=class,COPIES=nJCL //outname OUTPUT COPIES=nJES2 /*JOBPARM COPIES=n


The n is the number of copies (1 to 255) of the output to produce. Thedefault is one copy. Note that the number of copies requested by the JES2/*JOBPARM statement includes any DD, OUTPUT, or /*OUTPUT copies.The following prints six copies of SYSPRINT.

/*JOBPARM COPIES=2//STEP1 EXEC PGM=ONE//SYSPRINT DD SYSOUT=A,COPIES=3

For the 3800 printer only, you can request several groups to be placed ina separate output bin of the 3800 printer, with each group containing a dif-ferent number of copies. You code: COPIES=(n,(group,group, . . . ,group))

The n defaults to 1 if omitted. It specifies the number of times to printthe data set, including each group listed. The group is the number of copiesto print for each group. You can code eight groups as long as the total of allthe groups does not exceed 255. The following example prints three groups;each stored in a separate output bin. The first group contains two copies,the second one copy, and the third group four copies, so that seven totalcopies of each page result.

//SYSOUT DD SYSOUT=A,COPIES=(,(2,1,4))

The COPYG parameter on the JES2/*OUTPUT statement is an alterna-tive to coding COPIES=(,(group,group, . . . ,group)).

JES2 /*OUTPUT code COPYG=(group,group,…,group)

9.6.2 Limiting the Amount of Output

Sometimes Used

Limit the lines of output by coding a parameter on one of the followingstatements:

JCL //ddname DD SYSOUT=class,OUTLIM=linesJCL //jobname JOB …,LINES=thsndlinesJES2 /*JOBPARM LINES=thsndlinesJES3 //*MAIN LINES=thsndlines

lines is the number of lines for an individual data set and can range from 1to 16777215. thsndlines is the number of thousands of lines for all printdata sets in the job and can range from 0 to 999999 in JES2 and 0 to 9999 inJES3.


In the following example, the system terminates the job if SYSPRINTproduces more than 20,000 lines.

//SYSPRINT DD SYSOUT=A,OUTLIM=20000

You can also specify the system action if the number of lines isexceeded.

JCL //jobname JOB …,LINES=(thsndlines,action)JES2 //*MAIN LINES=(thsndlines,action)

The action is one of the following:

DUMP cancels the job and requests a storage dump.

CANCEL cancels the job with no dump.

WARNING displays a message to the operator and continues.

To limit the printed output by the number of bytes produced rather thanlines, you can code:

JCL //jobname JOB …,BYTES=bytesJES2 /*JOBPARM BYTES=bytesJES3 //*MAIN BYTES=bytes

The bytes estimates the maximum output in thousands of bytes. If theoutput exceeds this, the system sends the operator a message, who then hasthe option of canceling the job. You can also specify the same action to takeas with LINES if the limit is exceeded.

JCL //jobname JOB …,BYTES=(bytes,action)JES3 //*MAIN BYTES=(bytes,action)

Finally, you can also limit the output by the number of printed pagesproduced by a job by coding the following. The n is 1 to 99999999 for JCLand JES2 and 1 to 16777215 for JES3.

JCL //jobname JOB …,PAGES=nJES2 /*JOBPARM PAGES=nJES3 //*MAIN PAGES=n

In addition, you can also specify the action.

JCL //jobname JOB …,PAGES=(n,action)JES3 //*MAIN PAGES=(n,action)


9.6.3 Routing the Output: DEST

Sometimes Used

Route the output to some destination by coding the DEST parameter on oneof the following statements. Note that the JES2/*OUTPUT statement canroute the output to four destinations.

JES2 /*OUTPUT code DEST=dest OrJES2 /*OUTPUT code DEST=(dest,dest,dest,dest)JES3 //*FORMAT PR DDNAME=ddname,DEST=destJCL //ddname DD SYSOUT=class,DEST=destJCL //outname OUTPUT DEST=dest

The dest is

DEST=LOCAL or ANYLOCAL routes the output to a local device.

DEST=RMTs routes the output to remote workstation s as defined bythe installation. R0 is equivalent to LOCAL.

DEST=Ut gives special routing to local terminal t as defined by theinstallation.

DEST=name routes the output to the symbolic name of the destinationas defined by the installation.

DEST=Nn or NnRs routes the output to node n and remote workstations as established by the installation. Coding DEST=NnR0 is equiva-lent to LOCAL at node n.

DEST=userid routes the output to the userid at the local node.

DEST=nodename.userid (/*OUTPUT and OUTPUT only) routes theoutput to a TSO or VM userid at node n as assigned by the installa-tion.

DEST=(nodename.userid) (DD only) routes the output to a TSO or VMuserid at node n as assigned by the installation.

9.6.4 Checkpointing Printed Output

Sometimes Used

You can specify when to checkpoint printed output by coding one of thefollowing.

JES2 /*OUTPUT code CKPTLNS=lines,CKPTPGS=pagesJCL //outname OUTPUT CKPTLINE=lines,CKPTPAGE=pages,CKPTSEC=seconds


lines is the maximum number (0 to 32767) of lines contained in a logicalpage of the data set being printed. The system uses this to count pages forcheckpoints. pages is the number (0 to 32767) of logical pages to printbefore the system takes the next checkpoint for the data set being printed.seconds is the number (1 to 32767) of seconds to elapse between check-points of the data set being printed.

9.6.5 Specifying a Program to Write the Output

Rarely Used

Specify a special program to write the output with one of the following.

JES3 //*FORMAT PR,DDNAME=ddname,EXTWTR=writerJCL //ddname DD SYSOUT=(class,writer)JCL //outname OUTPUT WRITER=writer

The writer names a program contained in SYS1.LINKLIB that is to writethe output. In the next example, the system loads the MYPRINT programand passes control to it so that it can print the output.

//PRINT DD SYSOUT=(A,MYPRINT)

9.6.6 Specifying Special Output Forms: FORMS

Rarely Used

To print the output on a special output form as defined by the installation,code one of the following.

JES2 /*OUTPUT code FORMS=formJES3 //*FORMAT PR,DDNAME=ddname,FORMS=formJCL //ddname DD SYSOUT=(class,writer,form)JCL //outname OUTPUT FORMS=formJES2 /*JOBPARM FORMS=form

The form specifies the print form to use for the job. STD is the installa-tion standard. The system requests the operator to mount the special formjust before the data set is printed and requests the original form to beremounted when printing is complete. In this example, the system requeststhat the operator mount form 1001 before the output is printed.

//PRINT DD SYSOUT=(A,,1001)


TEAMFLY

Team-Fly®

9.6.7 Specifying the Forms Control Buffer: FCB

Rarely Used

The FCB parameter specifies the forms control image for the 3800, 4245,and 4249 printers that have the forms control buffer feature. The FCB con-trols the lines per inch and page length on the printer. Code FCB on one ofthe following statements.

JES2 /*OUTPUT code FCB=image-idJES3 //*FORMAT PR,DDNAME=ddname,FCB=image-idJCL //ddname DD SYSOUT=A,FCB=image-idJCL //outname OUTPUT FCB=image-id

The image-id identifies the FCB image to be loaded into the formsbuffer. Coding STD as the image-id requests the installation’s standardforms control buffer.

9.6.8 Burst the Output: BURST (3800 Printer Only)

Rarely Used

Code BURST=YES to burst fanfold output into separate sheets. BURST=NOprints the output in normal continuous fanfold mode. BURST=NO isdefault, but installations can make BURST=YES the default for a particularSYSOUT class. You can code BURST on the following statements:

JES2 /*OUTPUT code BURST=YJES3 //*FORMAT PR,DDNAME=ddname,STACKER=S

[Code STACKER=S in JES3. STACKER=C requests continuous formsstacker and STANDARD requests the installation’s standard.]

JCL //ddname DD SYSOUT=class,BURST=YJCL //outname OUTPUT BURST=YESJES2 /*JOBPARM BURST=YES

9.6.9 Specify a Character Set: CHARS (3800 Printer Only)

Rarely Used

Coding CHARS=(table, . . . ,table) lists from one to four table names thatspecify the 3800 printer’s character sets. You can code CHARS on the fol-lowing statements:


JES2 /*OUTPUT code CHARS=(table,…,table),MODTRC=n

[MODTRC=n specifies the table, where n has values of 0 to 3.]

JES3 //*FORMAT PR,DDNAME=ddname,CHARS=(table,…,table)JCL //ddname DD SYSOUT=class,CHARS=(table,…,table),DCB=OPTCD=J

[The DCB=OPTCD=J indicates that the second byte of each line, thebyte following the printer control character, is a single numericcharacter (0 to 3) that selects the table for the print lines based onthe order in which you list the tables in the CHARS parameter.]

JCL //outname OUTPUT CHARS=(table,…,table),TRC=YES

[TRC=YES (only with the Print Services Facility) accomplishes thesame as DCB=OPTCD=J.]

Coding CHARS=DUMP or CHARS=(DUMP,table,DUMP,table, . . .) on a//SYSUDUMP or //SYSABEND DD statement prints storage dumps as 204-character print lines. To print 8 lines per inch on an 11-inch form, addFCB=STD:

//SYSUDUMP DD SYSOUT=A,FCB=STD3,CHARS=DUMP

9.6.10 Modify Print Lines with a Program: MODIFY (3800 Printer Only)

Rarely Used

MODIFY names a module supplied by the installation that replaces blanksor data in the print lines to print legends and column headings. Code MOD-IFY on the following statements.

JES2 /*OUTPUT code MODIFY=(module-name,n)JES3 //*FORMAT PR,DDNAME=ddname,MODIFY=(module-name,n)JCL //ddname DD SYOUT=class,MODIFY=(module-name,n)JCL //outname OUTPUT MODIFY=(module-name,n)

module-name names a module supplied by the installation thatreplaces blanks or data in the print lines. You use this feature toprint legends and column headings.

n is a number (0 to 3) that corresponds to the character arrangementtable specified by the CHARS parameter. n is optional and defaultsto 0.


In the following example, the system invokes module HDR1 to replacedata in the print lines and prints the lines with the CYRL character set.

//OUT DD SYSOUT=A,CHARS=(ALPH,CYRL),MODIFY=(HDR1,1)

9.6.11 Specify a Forms Overlay: FLASH (3800 Printer Only)

Rarely Used

The FLASH parameter overlays an installation-defined form over the pageof printed output. Code FLASH on the following statements.

JES2 /*OUTPUT code FLASH=(overlay-name,n)JES3 //*FORMAT PR,DDNAME=ddname,FLASH=(overlay-name,n)JCL //ddname DD SYSOUT=class,FLASH=(overlay-name,n)JCL //outname OUTPUT FLASH=(overlay-name,n)

The overlay-name names an overlay form designated by the installa-tion. The system requests the operator to mount this form on theprinter and then projects the form on each page of the output. Cod-ing NONE eliminates the forms overlay and is the default.

The n prints the forms overlay on only the first n (0 to 255) copies whenyou print multiple copies with the COPIES parameter. An n value of0 prints the forms overlay on all copies. The n defaults to 255 if youomit it.

In the following example, the system prints the forms overlay specifiedby FRM1 on the first three copies.

//OUT DD SYSOUT=A,COPIES=6,FLASH=(FRM1,3)

The JES2/*OUTPUT statement also lets you specify the flash count ona FLASHC parameter:

JES2 /*OUTPUT code FLASH=overlay-name,FLASHC=n

9.6.12 Compact the Output: COMPACT

Rarely Used

To compress the output when sending SYSOUT output to an SNA remoteterminal, code the COMPACT parameter on the following statements:


JES2 /*OUTPUT code COMPACT=nJES3 //*FORMAT PR,DDNAME=ddname,COMPACT=compaction-table-nameJCL //outname OUTPUT COMPACT=compaction-table-name

The n is a number identifying the compaction table.

The compaction-table-name names the compaction table.

9.6.13 Change the Line Spacing: CONTROL

Sometimes Used

You can control the line spacing with the following:

JES3 //*FORMAT PR,DDNAME=ddname,CONTROL=linesJCL //outname OUTPUT CONTROL=lines

The lines specifies the line spacing for the printer. You code lines as

PROGRAM if the first character of a record is control character.

SINGLE to force single spacing.

DOUBLE to force double spacing.

TRIPLE to force triple spacing.

JCL //ddname DD SYSOUT=class,DCB=PRTSP=n

[DCB=PRTSP=n sets the printer spacing (0 to 3, PRTSP=1 isdefault).]

9.6.14 Change the Page Size and Margins (JES2 Only)

Sometimes Used

To specify the size of the physical and logical page, you code the followingstatements:

JES2 /*OUTPUT code LINECT=lpageJCL //outname OUTPUT LINECT=lpageJES2 /*JOBPARM LINECT=lpage

The lpage is the number of lines (0 to 255) to print on each physical page.

JES2 /*OUTPUT code CKPTLNS=linesJCL //outname OUTPUT CKPTLINE=lines


The lines is the maximum number (0 to 32767) of lines contained ineach logical page.

Set the left margin with the following:

JES2 /*OUTPUT code INDEX=nJCL //outname OUTPUT INDEX=n

The n is the left margin (1 to 31 from the left) for the 3211 printer withthe indexing feature. INDEX=1 is flush left.

Set the right margin with the following. (You can set only the left orright but not both.)

JES2 /*OUTPUT code LINDEX=nJCL //outname OUTPUT LINDEX=n

The n specifies the right margin (1 to 31 from the right) for the 3211printer with the indexing feature. LINDEX=1 is flush right.

9.6.15 Check for Forms Overflow: OVFL (JES3 Only)

Rarely Used

OVFL=ON tells the system to check for forms overflow and ejecting to anew page when it occurs. OFVL=OFF is the default.

JES3 //*FORMAT PR,OVFL=ONJCL //outname OUTPUT OVFL=ON

9.6.16 Limit SYSOUT Records: THRESHLD (JES3 Only)

Rarely Used

To specify the maximum number of records (1 to 99999999) allowed for anyone SYSOUT data set, code the following:

JES3 //*FORMAT PR,DDNAME=ddname,THRESHLD=limitJCL //outname OUTPUT THRESHLD=limit

9.6.17 Set Priority for Printing: PRTY (JES3 Only)

Rarely Used

To set the priority (0 to 255) for printing in the output queue, code the fol-lowing:


JES3 //*FORMAT PR,DDNAME=ddname,PRTY=priority

9.6.18 Other JES3 Parameters

The last option is used for workstations. To specify the number of recordsto be sent from an SNA workstation, code CHNSIZE=n. Code CHNSIZE=DSto send the data as a single SNA chain.

JES3 //*FORMAT PR,DDNAME=ddname,CHNSIZE=n


CHAPTER 10

DIRECT-ACCESS STORAGE DEVICES

10.1 DIRECT-ACCESS HARDWARE DEVICES

Essential

Direct access, the most versatile storage device, can contain sequential, par-titioned, direct, and VSAM data sets. Direct-access storage derives its namefrom the way you access the data. Unlike tape, you can read each recordindependently of the previous record. Today, direct-access storage devicesare all disk units.

A disk device consists of a stack of rotating recording surfaces. Eachdisk surface contains many concentric tracks radiating inward toward thecenter, each containing the same amount of data. A set of electronicread/write heads positioned between each disk surface is connected to anaccess arm as shown in Figure 10.1. To read or write a specific track, thesystem moves the access arm to position the read/write head over thetrack, a movement called a seek. The read/write head looks for a specialmarker on the rotating track to tell it where the track begins. Thus, thereare two physical delays in accessing a specific track: a seek delay whichdepends on how far the access arm must be moved, and a rotational orlatency delay which averages one-half revolution. These mechanicalmovements are the Achilles heel of computing. Since System/360 wasintroduced in 1964, the CPU speed, central storage, I/O data rates, andstorage capacity have all increased by a factor of several hundred times; the seek and rotational delays have decreased by less than a factorof 10.

Since there is a read/write head for each disk surface, the system canread several tracks without arm movement. The tracks that lie one on top ofthe other form an imaginary cylinder in which all the tracks are accessiblewithout arm movement. Access arm movement is required if data resideson different cylinders. Thus, the system can read and write data much

181

faster if it resides all on the same cylinder. Table 10.1 summarizes the speedand capacity of the various IBM direct-access volumes.

The system maintains a volume table of contents (VTOC) on eachdirect-access volume as a directory to existing data sets and free space. Thefirst track on the volume contains the volume label and points to the VTOC.


FIGURE 10.1 Direct-access storage device. (Reprinted by permission fromIntroduction to IBM Direct-Access Storage Devices and Organization Meth-ods 1974, International Business Machines Corporation.)

Track

Disks

Read/write heads

Access arms

Comb-typeaccess assembly

Cylinder

TABLE 10.1 Direct-Access Storage Device Characteristics

Rotational Seek Data rate VolumeDASD device delay (ms) time (ms) (MB/sec) capacity (GB)

3380-D,J 8.3 15.0 3.0 0.633380-E 8.3 17.0 3.0 1.253380-K 8.3 16.0 3.0 1.893390-1 7.1 9.5 4.2 0.953390-2 7.1 12.5 4.2 1.893390-3 7.1 15.0 4.2 2.843390-9 22.8 22.5 3.9 8.519345-1 5.6 10.0 4.4 1.009345-2 5.6 11.0 4.4 1.50RAMAC-1 5.6 9.5 5.0 2.10RAMAC-2 4.2 8.0 9.6 4.50RAMAC-3 4.2 8.5 15.4 9.10Internal Disk 4.2 8.0 10.0 9.10

10.2 SPACE ALLOCATION

Essential

Space allocation is unique in z/OS. While you never have to reserve diskspace ahead of time on a PC, z/OS requires that you specify the amount ofspace for each data set created. This is inconvenient, but with improve-ments in the operating system, it is now relatively simple.

You must allocate space to all new data sets on direct-access volumes.The system allocates space on direct-access volumes in units of tracks, andthe minimum space it can allocate is one track. (Space allocation for VSAMdata sets is done differently and is described in Chapter 17.)

When you request space, the system looks in the VTOC to see if it isavailable and allocates the space by updating VTOC. The system attemptsto allocate space in contiguous tracks (tracks on the same cylinder) andadjacent cylinders. If contiguous space is unavailable, the system will sat-isfy the request with noncontiguous blocks of storage. Each block of storageis termed an extent.

If the system still can’t find enough space and if you haven’t requesteda specific volume, the system looks for space on other appropriate volumes.The system terminates the step with one of the following system codes if itcannot find space:

B37 indicates that not enough space was available on the volume to sat-isfy a space request.

E37 indicates that all the extents have been allocated on a volume, butmore space is required, and the data set cannot be extended ontoother volumes.

You request space as both a primary and a secondary amount. The sys-tem allocates the primary amount when it opens the data set with a dispo-sition of NEW or MOD. It allocates the secondary amount if the data setoverflows the primary amount, even if this is in a later job step or job. Thesecondary amounts offer the following advantages:

� The primary amount can be conservative, while the secondary amountprovides a reserve.

� The secondary amount provides for data set growth over time.� The system can allocate the secondary amount on a different volume.

The data set size is not limited to the space available on a singlevolume.

Space allocation is complicated. Here are the rules the operating systemfollows in allocating space:

DIRECT-ACCESS STORAGE DEVICES 183

1. The system allocates space in extents, that is, contiguous blocks oftracks on the same cylinder and adjacent cylinders.

2. It allocates the entire primary amount on one volume.

3. If the data set overflows the primary amount, the system then beginsallocating the secondary amount.

4. If the data set exceeds the number of secondary or the volume runsout of space, the system then tries to find space on another vol-ume. For an SMS-managed data set, the DATACLAS parametersets the number of volumes onto which your data set can extend.For a non-SMS-managed data set, you set the number by codingUNIT=(device,n).

5. This continues until the system has used all the volumes allowed it.If you use up all extents on all volumes, the system terminates thejob with an E37 system code. If there isn’t enough space on a vol-ume to fulfill the request, the system terminates the job with a B37system code.

The allocation of an extended sequential data set is slightly different.The system divides the primary space by the number of volumes, roundingup, and allocates this amount as the primary on each volume. When a pri-mary area on any volume becomes filled, the system divides the secondaryamount by the number of volumes, rounding up, and allocates this amountof secondary space on the volume.

Although the system allocates storage on direct-access volumes in non-contiguous blocks and across different volumes, the system reads andwrites it as if it were one large block. It can read or write data faster if it allresides on the same cylinder because it must use a relatively slow mechan-ical movement to position the access arm between noncontiguous blocks.In a busy multiprogramming environment where hundreds of other peopleare concurrently running jobs, this doesn’t matter. Occasionally, though,you might consider allocating high-activity data sets contiguous space onthe same cylinders.

The number of extents, counting the primary space amount, that thesystem will permit a data set and the number of volumes on which the dataset can reside is shown in Table 10.2.


TABLE 10.2 Permitted Extents and Volumes for Data Sets

Type of data set Maximum volumes Extents per volume

Sequential 59 16Extended sequential 16 123PDS 1 16PDSE 1 123

TEAMFLY

Team-Fly®

The sequential and PDS are older file formats that are being replaced bythe newer extended sequential and PDSE, both of which require that SMSbe active.

For an SMS-managed data set, you can select a STORCLAS that has theguaranteed space attribute. This attribute allocates space as follows:

1. The system allocates the primary amount of space on all the vol-umes.

2. The system writes the data set into the primary amount of the firstvolume.

3. If this primary is filled, the system allocates a secondary amount onthat volume.

4. If all the secondary amounts allowed are used or the volume runsout of space, the system moves to the second volume and beginswriting into the primary space already allocated.

5. The system repeats steps 3 and 4 for the second volumes. It thenmoves on to the next volume until it runs out of volumes.

When STORCLAS sets the guaranteed space attribute for extended se-quential, the system operates somewhat differently. The system allocates theprimary amount on all the volumes. If all the primary amounts are filled, thesystem then allocates a secondary amount on all the volumes. If all the sec-ondary amounts are filled, the system allocates a second secondary amount onall the volumes. This continues until all the secondary amounts are used up.

For disk data sets, you can specify all the usual DD parameters as needed:

//ddname DD DSN=data-set-name,DISP=(status,normal-disp,abnormal-disp),// UNIT=device,VOL=SER=volume,

[For non-SMS-managed data sets.]

// DATACLAS=data-class,STORCLAS=storage-class,

[For SMS-managed data sets.]

// RECFM=type,LRECL=length

You seldom need to use the VOL parameter with direct-access devices.One more parameter is also needed, the SPACE parameter, to specify theamount of disk space.

10.3 THE SPACE PARAMETER

Essential

You request a quantity of space and let the system select the appropriatetracks. You may request space in units of cylinders, tracks, block size, or


record length. The maximum size per volume is 65,535 tracks. The systemignores the SPACE parameter for tape.

CYLTRKblksizereclength

SPACE=( ,(primary,secondary,directory))

The reclength, blksize, TRK, or CYL requests that space be allocated in units of number of bytes per record, bytes per block, tracks, orcylinders.

The primary is the number of units (records, blocks, tracks, or cylin-ders) to allocate for the primary allocation. The system always allo-cates it on a single volume. For example, SPACE=(80,2000) requests2,000 blocks of 80 bytes each, and SPACE=(CYL,20) requests 20cylinders.

The secondary is the number of units to allocate as the secondary allo-cation if you exceed the primary allocation. The primary allocationtakes up one extent, and the remaining (15 or 122) are allocated asneeded for secondary amounts. Each subsequent volume can havethe full complement of 16 or 123 secondary extents. You can storesequential data sets on more than one volume, but partitioned andHFS data sets must reside on a single volume. The number of vol-umes on which the data set can reside is determined by the DATA-CLAS parameter for an SMS-managed file and the UNIT=(device,n)parameter for non-SMS-managed data sets. Both the primary andsecondary must be large enough to contain the largest block written.The secondary amount is optional, and if omitted, no secondaryallocation is given.

The directory reserves space for the names of members of partitioneddata sets and you code it only for partitioned data sets.

If a SPACE parameter is written as SPACE=(TRK,(10,2)), space is allo-cated as shown in Figure 10.2.


FIGURE 10.2 Space allocation for SPACE=(TRK,(10,2)).

10 tracks

Primary

2 tracks

1st secondary

2 tracks

2d secondary

2 tracks…

15th or 122dsecondary

10.3.1 Space Units

Reclength: Requesting Space for Records

Essential—If SMS Is Active

If SMS is active at your installation, simplify the SPACE parameter by cod-ing the AVGREC parameter on the DD statement to indicate that you arecoding the reclength, the average record length (LRECL) of the data. Other-wise, the system will think you are coding the blksize. (The average recordlength cannot exceed 65,535 bytes.) Both the primary and secondary thenbecome the number of records to store. You code AVGREC as

AVGREC=U for primary and secondary in units of one record.

AVGREC=K for primary and secondary in units of K (1,024) records.

AVGREC=M for primary and secondary in units of M (1,048,576) records.

//OUTPUT DD DSN=A0000.TEST.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,RECFM=VB,LRECL=255,// AVGREC=U,SPACE=(60,(1000,500))

[The system allocates primary space for 1,000 records that have anaverage length of 60 bytes. Each secondary space allocation is for500 records.]

To determine the number of tracks to allocate for both the primary andsecondary, the system computes how many blocks will fit on a track. Forthis, it obtains the block length as follows:

1. First, it tries to use the DCB information for the data set.

2. Failing that, it tries to calculate an appropriate block size for the I/Odevice.

3. Failing that, it uses a value of 4,096.

If you use AVGREC, you can ignore the other methods of allocatingspace: blksize, TRK, and CYL.

Blksize: Requesting Blocks of Space

Essential

If your system doesn’t have SMS active, you generally request space inunits of blksize, the average blocksize (BLKSIZE) of the data. (The averageblock length cannot exceed 65,535 bytes.) You will often find this form ofallocating space on old JCL written before SMS.

//OUTPUT DD DSN=A0000.TEST.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,RECFM=VB,LRECL=255,// SPACE=(4096,(1000,500))


[The system allocates primary space for 1,000 blocks having anaverage block length of 4,096 bytes. Each secondary space alloca-tion is for 500 blocks.]

The problem with this is that you must know how many records onaverage will fit in a block to determine how many records you can store. Forexample, if you coded SPACE=(4096,(1000,500)) and the average block con-tains 10 records, the primary area could hold 10 × 1,000 = 10,000 records,and each secondary could hold 10 × 500 = 5,000 records. (This is why youshould use AVGREC if it is available.)

Rather than specifying the average block size, you can code a value of 0and let the system supply the block size, which it does as follows:

1. First, it tries to use the DCB information for the data set.

2. Failing that, it tries to calculate an appropriate block size for the I/Odevice.

3. Failing that, it uses a value of 4,096.

//OUTPUT DD DSN=A0000.TEST.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,RECFM=VB,LRECL=255,// SPACE=(0,(1000,500))

[Since we specify no blksize, the system decides on an appropriateblock size to use for the I/O device and then allocates 1,000 units ofthis for the primary and 500 units for each secondary.]

This is simpler to code, but now you have no way of knowing howmany records can be stored because you don’t know the block size and howmany records might be stored per block. You must make a guess and do thebest you can.

Even with its failings, blksize is better than TRK or CYL because youcan at least guess how many records there are in a block, which enables youto calculate how many blocks you need independent of the particulardevice type on which the data set is stored. The system computes the actualnumber of tracks to allocate based on the number of blocks that fit on atrack. (Table 10.4 describes the capacity of the direct-access volumes.) Forexample, SPACE=(1000,100) allocates three 3390 tracks because thirty-four1,000-byte blocks fit on a track. Although SPACE=(10000,10) requests thesame total storage (100,000 bytes), two 3390 tracks are allocated becausefive 10,000-byte blocks fit on a track. The system always rounds space up toa whole number of tracks.

The system makes a secondary allocation only as needed. For this, itmultiplies secondary times the actual block size of the data set rather thanblksize in the SPACE parameter to compute the number of tracks.


For variable length or undefined format records, blksize is the averagelength. For direct data sets having keys, code KEYLEN=keysize as a DCB sub-parameter so that the system can include space for the keys in its calculation.

TRK: Requesting Tracks

Sometimes Used

Since the system always allocates space in units of whole tracks, TRKallows you to request an exact amount of space. TRK is device-dependent.SPACE=(TRK,1) results in 56,664 bytes on a 3390 disk and 47,476 bytes ona 3380 disk.

You might sometimes use TRK for quick and dirty runs, allocating a num-ber of tracks that you know is enough and let it go at that. The problem withallocating space in units of tracks is that the number of records that can fit ona track depends upon the BLKSIZE, the LRECL, and the type of disk unit. Inother words, you need to know what your DCB subparameters are, what thetrack size of your disk unit is, and how many records you have to store. If youdon’t have a feel for how many tracks to allocate, allocate in units of block size.

CYL: Requesting Cylinders

Rarely Used

CYL requests complete cylinders, resulting in faster access by eliminating theneed for access arm movement. CYL is also device-dependent. SPACE=(CYL,1) obtains 849,960 bytes on a 3390 disk and 712,140 bytes on a 3380disk. You will occasionally see CYL on old JCL, but the only time you mightcode CYL is when you want a large amount of space and access time is criti-cal. You must compute (or estimate) the amount of space needed if you wantto use TRK or CYL. See the following section on estimating storage space.

When you request space in units of TRK or CYL, don’t use a UNITparameter with a group name defining more than one type of device. Forexample, if SYSDA defines both 3390 and 3380 disks, UNIT=SYSDA,SPACE=(TRK,1) yields 56,664 bytes if a 3390 is selected and 47,476 bytes ifa 3380 is selected; you would not know which.

If you must allocate in cylinders, request space in reclength or blksizeand use the ROUND parameter described in the following to allocate thespace in whole cylinders.

10.3.2 Secondary: Secondary Allocation

Essential

If you code secondary and the primary space allocation is exceeded, thesystem allocates a secondary amount computed as secondary times the


units. The system allocates a maximum of 15 or 122 secondary amounts onthe first volume and 16 (for sequential and PDS) or 123 (for extendedsequential or PDSE) secondary amounts on any additional volumes. If thedata set needs more space, the system terminates the step with an E37 sys-tem code. As an example, for SPACE=(4096,(10,20)), the system allocatesprimary space for 10 blocks of 4,096 bytes each. Then as needed, the systemallocates each secondary amount for 20 blocks of 4,096 bytes. The maxi-mum space that could be allocated on a single volume is then 10 + 20(15) =310 blocks of 4,096 bytes for sequential or PDS, and 10 + 20(122) = 2,450blocks for extended sequential or PDSE.

Extents are usually not contiguous, and so the access time increases asextents are allocated. (This is usually insignificant in large systems inwhich many programs are running at the same time.) For very high usagedata sets, you might not want to have secondary extents, but this would beextremely rare.

If you created a data set without requesting a secondary in the SPACEparameter, you can code another SPACE parameter on the DD statementadding to the data set to specify a secondary. If you created the data set witha secondary, you can code a new SPACE parameter to specify a differentamount. In both cases the new secondary is effective only for the durationof the step and does not change the original secondary or the 16/123-extentlimit. For example, you might create a data set with

//A DD DSN=A1000.HOLDIT.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,SPACE=(100,(10,20))

Later you might add to it and wish to increase the size of the secondary:

//ADD DD DSN=A1000.HOLDIT.DATA,DISP=(MOD,KEEP),// SPACE=(100,(0,200))

[The system gives each extent that it allocates in this step 200 blocksof 100 bytes. Later runs will revert to an extent size of 20 blocks of100 bytes.]

Be careful when you override a DD statement in a cataloged procedurecontaining a SPACE parameter. If the overriding statement describes anexisting data set, you would usually not code a SPACE parameter. However,if a secondary allocation is required, the SPACE parameter on the over-ridden statement specifies the secondary, which is not necessarily the secondary specified when the data set was created. Code SPACE= on theoverriding DD statement to nullify the SPACE parameter and avoid thisproblem. The following example illustrates this frequent need. The linkageeditor step of a COBOL cataloged procedure contains this DD statement todescribe the load module output:


//SYSLMOD DD DSN=&&GOSET(GO),DISP=(NEW,PASS),// UNIT=SYSDA,SPACE=(CYL,(1,1,1))

The SPACE parameters are appropriate for a single job, but if you werecreating a subroutine library, you might want to override the statement toallocate more space, give the library a name, and catalog it:

// EXEC COB2UCL//LKED.SYSLMOD DD DSN=A1000.COBOL.LOAD(SUB1),DISP=(NEW,CATLG),// SPACE=(CYL,(10,5,50))

Then subsequent compile, link-edit runs might add new members:

// EXEC COB2UCL//LKED.SYSLMOD DD DSN=A1000.COBOL.LOAD(SUB2),DISP=OLD

[The secondary amount is one cylinder as specified in the original//SYSLMOD DD statement because the system gives priority to anyvalue in a SPACE parameter over that stored in the data set labelwhen the data set was created.]

// EXEC COB2UCL//LKED.SYSLMOD DD DSN=A1000.COBOL.LOAD(SUB2),DISP=OLD,SPACE=

[The secondary amount is now five cylinders; the amount specifiedwhen the data set was created. The SPACE= nullifies the SPACEparameter in the cataloged procedure DD statement.]

10.3.3 Directory: Directory Space

Essential

A partitioned data set must fit on a single volume. For a PDSE, code theDSNTYPE=LIBRARY parameter described in Chapter 11 to tell the systemthat you are creating a PDSE. The system doesn’t reserve space for the mem-ber names and so it doesn’t need an estimate of the number of directoryblocks, although you might still code an estimate in case you ever need toconvert the PDSE to a PDS. The directory space does not come out of theprimary space you allocate. The system adds extra space for the directory.Here is an example of a PDSE:

//OUT DD DSN=A0000.COBOL.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,RECFM=VB,LRECL=255,// DSNTYPE=LIBRARY,SPACE=(0,(100,50,10)

[The DSNTYPE=LIBRARY marks it as a PDSE. The 10 directoryblocks are coded only for compatibility in the event the PDSE isever converted to a PDS.]


You must use the old PDS type of partitioned data set if SMS is notactive and you must request the number of directory blocks for the systemto use to store the name, any aliases, and location of each member. The sys-tem allocates the directory in units of 256-byte blocks and each block canconservatively contain five member names. To estimate the number ofdirectory blocks, estimate the number of members, divide by 5, and roundup to the nearest integer. For example, if a PDS has 32 members, allocate32/5 or 7 directory blocks: SPACE=(4096,(20,100,7)).

Allow a liberal margin for adding new members when creating a PDSbecause you cannot extend the directory later. If it fills up, you must copythe data set and allocate more space. (The IEBCOPY utility described inChapter 19 does this.) The directory must fit on the first extent of the dataset. If you request space in units of reclength or blksize, the system calcu-lates the directory space required and adds this to the primary spaceamount. If you code TRK or CYL, the system obtains the directory spacefrom the primary allocation and you must take this into account in estimat-ing the total space required.

10.3.4 Special Space Options

Other options of the SPACE parameter let you release unused space andallocate space for faster access.

CYL ALXTRK MXIGblocksize CONTIG

SPACE=( ,(primary,secondary,directory),RLSE, ,ROUND)

RLSE: Releasing Space

Essential

RLSE releases all unused space when you close a data set after you haveopened it for output and written into it. It permits you to allocate morespace than perhaps is needed without wasting space. For example, ifSPACE=(4096,20,RLSE) is coded and only four blocks are written, the sys-tem releases the space for the remaining 16 blocks. If the system allocatesan extent that the data set only partially uses, the system releases theremainder of the extent. If you request space in cylinders, the system re-leases only excess cylinders; otherwise, it releases excess tracks. The sys-tem does not release space if the step ABENDs. (For a multivolume data set,the system releases space only on the current volume.)

The system releases space only if the data set is not empty and you closethe data set after opening it for output and writing into it. You can also useRLSE to release space in an existing data set. Code SPACE=(,,RLSE) on a DDstatement referring to the data set to release any excess space when you


close the data set. (Code SPACE=(units,(,secondary),RLSE) if the existingdata set requires secondary allocation.)

// EXEC COB2UCL//LKED.SYSLMOD DD DSN=A1000.COBOL.LOAD(SUB3),DISP=OLD,// SPACE=(CYL,(10,5,50),RLSE)

At first glance, it appears that you should always use RLSE, but thereare some drawbacks. RLSE requires I/O time to release the space, althoughthe amount isn’t significant. Then the system must place any data added ina subsequent step in a new extent, with the resultant slower processingtime. RLSE can also use up the 16 or 123 extents allowed on a volume. Beespecially careful of this with a PDS because you must allocate it on a sin-gle volume and it can only have 16 extents total. Don’t code RLSE if youplan to add later to the data set and wish to reserve space.

If you override a DD statement in a cataloged procedure with a DD state-ment defining an existing data set, be sure to code SPACE= to nullify anySPACE parameter on the overridden DD statement. If you don’t, and theSPACE parameter on the overridden statement contains the RLSE subpara-meter, the system releases excess space in the data set when you close it.

CONTIG, MXIG, ALX: Minimizing Access Time

Rarely Used

CONTIG, MXIG, and ALX are mutually exclusive positional parametersthat allocate contiguous space. Since contiguous space minimizes accessarm movement, the access time is decreased.

CONTIG allocates all the primary space on contiguous tracks and cylin-ders; that is, all tracks on a cylinder are contiguous, and if more thanone cylinder is needed, the cylinders are also contiguous. Since thesystem allocates each extent on contiguous anyway, CONTIG forcesthe primary space to be allocated in a single extent. The system ter-minates the job if contiguous space is unavailable.

MXIG allocates the primary space as the largest contiguous free area on avolume, but only if that area is as large or larger than the amountrequested. The system might allocate considerably more space thanyou requested (anywhere from the amount requested to the entire vol-ume). Use MXIG, if at all, only for large data sets as an alternative torequesting secondary allocation. (RLSE can release the excess space.)

ALX allocates the primary area by building up a list of the five largestcontiguous, free areas on the volume and allocates all of these areasthat are as large or larger than the space you request. You mightobtain a single area as large as the entire volume or five areas all


much larger than requested. Since ALX can also allocate much morespace than you requested, use it, if at all, only for very large data setsas an alternative to requesting secondary allocation. (RLSE can re-lease the excess space.)

SPACE=(100,(20,10),,CONTIG)

[The system allocates space only if it is contiguous.]

SPACE=(100,(1000,5),RLSE,ALX)

[The system allocates somewhere between 100,000 bytes and theentire volume in up to five areas whose minimum size is 100,000bytes. It releases excess space.]

SPACE=(100,(1000,10),,MXIG)

[The system allocates anywhere between 100,000 bytes and theentire volume in contiguous space.]

ROUND: Rounding Up to Cylinders

Sometimes Used

ROUND lets you request space in units of trksize or blksize, but allocate thespace on cylinder boundaries—as if you had coded CYL. Thus, ROUND isa device-independent way of allocating space in cylinders. The systemcomputes the space the data set needs, rounds up to the nearest cylinder,and allocates complete cylinders so that the space begins on the first trackof a cylinder and ends on the last track. Code CONTIG if you want contigu-ous cylinders. ROUND places the data on the minimum number of cylin-ders possible by starting on a cylinder boundary. This decreases access timeby minimizing the access arm movement.

SPACE=(1000,800,,,ROUND),UNIT=3390

[The system allocates two 3390 cylinders. The cylinders might notbe contiguous.]

SPACE=(1000,(800,10),RLSE,CONTIG,ROUND),UNIT=3390

[The system allocates two 3390 cylinders. The cylinders are con-tiguous, secondary allocation is permitted, and excess cylinders arereleased.]

10.4 DCB PARAMETERS

Essential

The RECFM and LRECL parameters are required for new data sets on direct-access volumes unless the program supplies them. The block size must not


TEAMFLY

Team-Fly®

exceed the 32,760-byte limitation of the standard access methods. If the log-ical record length exceeds the track size, spanned records, described inChapter 16, must be requested by coding RECFM=VS or VBS.

The most efficient block size in terms of I/O count, storage space, andCPU time is an even fraction of a full track. The system allocates bufferswithin a region to contain the blocks as they are read or written. Table 10.3illustrates the efficiency of an unblocked data set, efficient block sizes, andan inefficient block size. A larger block size requires more storage forbuffers but less I/O operations. Whether less disk storage is needed dependson whether the blocks fit nicely on a track.

The system assumes five buffers for the file. The CPU times are notshown because they vary with the computer model and system versions.Each I/O requires some CPU time, and the fewer I/Os, the less CPU timeused. Table 10.3 shows that it is not enough to just block, you must block toan even fraction of the track size to avoid wasting space. Increasing theblock size from 27,920 to 30,000 increased the 3390 disk storage requiredfrom 14 to 27 tracks. On a different disk device, this might reduce the stor-age required.

All of this is to show that you should omit the BLKSIZE parameter andlet the system select an optimum size. It knows the type of device on whichit is writing your data set. If a new disk is installed, your program will stillselect the optimum size.

10.5 VIRTUAL I/O (VIO) TEMPORARY DATA SETS

Sometimes Used

Virtual input/output (VIO) lets you store temporary data sets in virtual stor-age so that the system reads or writes them using the fast-paging hardware.VIO is simple to code because you do not need to code the SPACE parame-ter. The system allocates a default amount of space. The system allocatesVIO data set outside your own address space, which is important if you are


TABLE 10.3 Efficiency of Block Sizes on a 3390

I/O count to read 3390 disk Bytes of storage10,000-record storage required for

Blocking BLKSIZE data set required buffer spacer

Unblocked 80 10,000 129 400Normal 6,160 130 17 30,800Half track 27,920 29 14 139,600Inefficient 30,000 27 27 150,000

reaching the limit of address space. The following rules apply to VIO datasets:

� They cannot be VSAM, PDSE, or extended sequential data sets.� You can allocate them only on a single volume.� The maximum size is 65,535 tracks.� They cannot be SMS-managed.

Your installation must either generate the system with UNIT or STOR-CLAS names for VIO data sets. You then specify one of these unit nameswith a UNIT or STORCLAS parameter. In specifying VIO data sets, the fol-lowing DD parameters and defaults apply.

DSN is optional, as it is for any temporary data set. Code it as DSN=&&name, if you code it at all.

DISP=CATLG or KEEP cannot be coded.

UNIT or STORCLAS must specify a VIO name. If you code UNIT, thesystem ignores any unit count.

VOL=SER cannot be coded. The unit name selects a group of eligiblevolumes.

SPACE is optional. If omitted, the system assumes SPACE=(8192,(4,24)).VIO data sets can have 15 secondary extents. (The system calculatesthe total space and allocates them as a single primary area.)

DCB is coded normally as needed.

The following example illustrates a VIO data set.

//STEP1 EXEC PGM=ONE//DD1 DD DISP=(NEW,PASS),UNIT=VIO,DCB=(RECFM=VB,LRECL=255)

[The system assumes SPACE=(8192,(4,24)).]

//STEP2 EXEC PGM=TWO//DD2 DD DSN=*.STEP1.DD1,DISP=(OLD,DELETE)

If a DD statement describes a temporary data set and you code VOL=REFto refer back to a VIO data set, the DD statement making the referback alsobecomes a VIO data set.

10.6 ESTIMATING SPACE

Essential

When you allocate disk space, it is much better to allocate a bit too muchthan too little. If you allocate too little, you write the data set and incur mostof the run cost before the data set overflows, wasting the entire run. If you


allocate too much, you only waste some disk space. There are two basicways to allocate space for a disk data set.

� By estimating the number of records you will be storing.� By feel, experience, judgment, or seat of the pants. You usually allo-

cate space in tracks when you do it this way.

10.6.1 Calculating the Space Required

If SMS is active at your installation, code the AVGREC parameter and spec-ify the estimate of the number of records directly in the SPACE parameter.If SMS is not active and you cannot code AVGREC, you must calculate thenumber of blocks needed by dividing the estimated number of records bythe average number of records per block. The following equation showshow. For variable-length records, the LRECL is the average record length.

n = estimated number of records

blocks needed = n/(BLKSIZE/LRECL)

rounded up to integer.If you let the system select the BLKSIZE, as you generally should, use

4,096 as the estimate. If we have a data set containing 10,000 fixed blockedrecords with LRECL=100, the calculation is

blocks needed = 10,000/(4096/100) = 244.1

rounded up to 245.There are several problems with allocating space in units of blocks. You

may be unable to estimate the number of records. It’s like guessing thelength of a book. You can tell at a glance whether a book is large or small,but you would probably have no idea how many lines there are in itbecause you’re not used to quantifying a book’s size by the number of lines.Also, for variable blocked records, you must estimate the average recordlength to estimate the number of records per block. If you let the systemselect the BLKSIZE, it probably won’t exactly equal the estimate of 4,096.And, finally, if you can’t code AVGREC, you must still do some arithmetic(when the computer is supposed to be the one to do the math). For thesereasons, you may occasionally allocate space in tracks.

10.6.2 Estimating Tracks

In computing the amount of tracks required, you must know the devicetype, track capacity, block size, key length, and device overhead. Table 10.4lists the capacity of direct-access volumes. RAMAC-1, 2, 3, and the internaldisk usually emulate a 3390.


Space is required for device overhead for each block stored on a trackand is used for hardware data, such as address markers and interblock gaps.Device overhead varies with each device. To compute the actual space adata set needs when you code TRK or CYL, calculate the blocks per trackwith one of the following formulas. These formulas are approximations andassume records without keys. BLKSIZE is an actual or estimated block size.For variable-length records, it is the average block size.

� 3350:blocks/track = 1 + (19,254−(185+BLKSIZE))/(185+BLKSIZE)

truncated to integer.� 3380:

d = (BLKSIZE + 12)/32

rounded up to integer.

blocks/track = 1499/(15 + d)

truncated to integer.� 3390:

dn = (BLKSIZE + 6)/232


d = 9 + [[BLKSIZE + 6 + (6*dn)]/34]


space = 10 + dblocks/track = 1729/space

truncated to integer.


TABLE 10.4 DASD Storage Capacity

DASD Bytes per Tracks per Cylinders perdevice track cylinder volume

3350 19,069 30 5553380-D,J 47,476 15 8853380-E 47,476 15 1,7703380-K 47,476 15 2,6553390-1 56,664 15 1,1133390-2 56,664 15 2,2263390-3 56,664 15 3,3393390-9 56,664 15 10,0179345-1 46,456 15 1,4409345-2 46,456 15 2,156

� 9345:dn = (BLKSIZE + 6)/232


d = [BLKSIZE + 6 +(6*dn)]/34


space = 18 + dblocks/track = 1420/space

truncated to integer.

From the blocks/track, you can compute the number of tracks neededas the following:

tracks needed = blocks needed/blocks per trackrounded up to integer.

You round up because the system allocates in units of full tracks. Thetracks needed is device-dependent.

Now calculate how many tracks your 10,000 record data set would takeon a 3390 disk. The data set has an average record length of 100 bytes, andyou used 4,096 as the estimate of the block size. The calculation for blocksper track is

dn = (4096 + 6)/232 = 17.7

rounded up to 18

d = 9 + [4096 + 6 + (6*18)]/34 = 132.8

rounded up to 133

space = 10 + 133 = 143

blocks/track = 1729/143 = 12.09

truncated to 12

blocks needed = 10,000/(4096/100) = 244.1

rounded up to 245

tracks needed = blocks needed/blocks per track = 245/12 = 20.4

rounded up to 20

Calculating the SPACE parameter using the blocksize results inSPACE=(4096,245). Calculating using tracks resulted in SPACE=(TRK,20).The two SPACE parameters are equivalent for a 3390 disk. Neither methodis very easy.


But you usually don’t allocate space in tracks by calculating it. Afteryou gain some experience, you will get a feel for how many tracks it takesto store your data sets. If you don’t know how many records you have, thisis the most painless method.

10.6.3 Estimating Cylinders

If you want to calculate the number of cylinders required, the formula is

cylinders = tracks/tracks-per-cylinder


Table 10.4 shows the tracks per cylinder for the various devices. For thisexample, the number of cylinders required is

cylinders = 20/15 = 1.3

which rounds up to 2.

10.7 THE LABEL PARAMETER: DATA SET LABELS

Rarely Used

You rarely need to use the LABEL parameter for disk. You must code it ifthe data set on a direct-access volume has user labels in addition to thestandard labels. To specify user labels, code LABEL=(,SUL). You might usethe LABEL parameter for data set protection (Chapter 16) and for magnetictape labels (Chapter 12). Since user labels are rare, a full description ofLABEL is deferred until these chapters.

10.8 MULTIVOLUME DATA SETS

Sometimes Used

For an SMS-managed data set, the DATACLAS you select determines thedefault number of volumes on which you can store your data set. For anon-SMS-managed data set, the UNIT=(device,n) parameter sets the num-ber of volumes. To store a sequential data set on specific volumes, specifythe volume count and the volume serial numbers with the VOL parameter.The system ignores the volume count if it is less than the number of vol-umes you specify. If you specify more, the system selects additional vol-umes. (The system ignores the volume count for an existing SMS-manageddata set.)


VOL=(,,,,SER=(PACK10,PACK11))

[The system will store the data set only on these two volumes.]

VOL=(,,,3,SER=(PACK10,PACK11)

[The system will store the data set on the two specified volumes.The system will assign another volume if needed.]

The system always makes the primary space allocation on the first vol-ume, and it can also allocate 15 or 122 extents on the same volume. The sec-ond and subsequent volumes can each contain 16 or 123 secondary amounts.A disposition of MOD will allow you to extend a data set in a subsequent jobstep. Code DISP=(MOD,CATLG) when extending multivolume cataloged datasets, even if the data set is already cataloged. CATLG records new volume ser-ial numbers in the catalog as you extend the data set.

When writing, the system switches volumes when space is exceeded onthe volume. During reading, volume switching occurs when an extent isread that resides on another volume. The next example illustrates the cre-ation, extension, and retrieval of a multivolume data set:

//STEP1 EXEC PGM=CREATE//A DD DSN=A1000.MULT.DATA,DISP=(NEW,CATLG),// UNIT=(SYSDA,3),// SPACE=(TRK,(4000,1000))

[The system creates a data set that it can write onto three nonspe-cific volumes.]

//STEP2 EXEC PGM=EXTEND//B DD DSN=A1000.MULT.DATA,DISP=(MOD,CATLG)

[The system extends the data set onto volumes as needed.]

//STEP3 EXEC PGM=RETRIEVE//C DD DSN=A1000.MULT.DATA,DISP=OLD

[The data set is read.]

10.9 USING DATA SETS ON DIRECT-ACCESS VOLUMES

Essential

To create a data set on a direct-access volume, allocate space with the SPACEparameter. Always code the UNIT/STORCLAS, DSN, and DISP parameters,except in the rare circumstances when it is apparent that they are not needed;for example, UNIT/STORCLAS are not needed if you code VOL=REF. Codethe VOL parameter to place the data set on a specific volume or on severalnonspecific volumes. Code DCB subparameters as required: RECFM andLRECL are the most common.


To retrieve an existing data set, code DSN and DISP. (Code UNIT andVOL only if the data set is not cataloged or passed—which is rare.) The DCBsubparameters are not required. The following examples show how to cre-ate and retrieve temporary and nontemporary data sets:

//STEP1 EXEC PGM=WON//DD1 DD DSN=&&PASSIT,DISP=(NEW,PASS),// UNIT=SYSDA,// RECFM=FB,LRECL=100,// SPACE=(4100,(10,5))

[The system creates a temporary data set and passes it to a subse-quent step.]

//DD2 DD DSN=A1000.SAVEIT.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,// RECFM=FB,LRECL=100,// SPACE=(4100,(20,10)),RLSE)

[The system creates a nontemporary data set and catalogs it for lateruse.]

//DD3 DD DSN=KEEPIT,DISP=(NEW,KEEP),// UNIT=SYSDA,VOL=SER=PACK01,// RECFM=U,LRECL=256,// SPACE=(TRK,100)

[The system creates a nontemporary data set but does not catalog it.]

//STEP2 EXEC PGM=DOS//DD4 DD DSN=&&PASSIT,DISP=(OLD,DELETE)

[The system retrieves the passed data set.]

//DD5 DD DSN=A1000.SAVEIT.DATA,DISP=SHR

[The system retrieves the cataloged data set.]

//DD6 DD DSN=KEEPIT,DISP=(OLD,DELETE),UNIT=SYSDA,VOL=SER=PACK01

[The kept data set is retrieved and deleted.]

In the next example, suppose that you need to store a data set con-taining 575,000 records on 3390 volumes. Each fixed-length record is1,500 bytes. You expect high usage, so you will try to minimize accesstime by allocating cylinders. Let the system select an appropriate blocksize.

First, assume that the system selects a block size somewhere around4,096. If the data set had fixed-length records, the block size would have tobe a multiple of 1,500, so assume the system will use a block size of 4,500.If you allocate a primary space large enough for all the records, will it fit onone 3390 volume?


dn = (4500 + 6)/232 = 19.4

rounded up to 20.

d = 9 + [4500 + 6 + (6*20)]/34 = 145.1

rounded up to 146.

space = 10 + 146 = 156

blocks/track = 1729/156 = 11.1

truncated to 11.Eleven blocks will fit on a track. The number of records in a block is

4,500/1,500 = 3. Thus, a track can contain 11 × 3 = 33 records. You will thenneed 575,000/33 = 17,425 tracks. From Table 10.4, you can see that a 3390has 15 tracks per cylinder and, depending on the 3390 model, 1,113, 2,226,or 3,339 cylinders per volume. This data set requires 17,425/15 = 1,162cylinders. So it will fit on a 3390-2 and 3390-3, but not on a 3390-1. Mostinstallations will not have a 3390 volume sitting empty, so you will likelyneed to store this data set over several volumes, regardless of 3390 model.To be conservative, assume 3390-1 volumes in which each volume has atleast 25 percent free space. Assume that each volume can contain 1,113 ×25% = 278 cylinders free per volume. You will then need 1,162/278 = 4.1,rounded up to 5 volumes. Now code the DD statement:

//ddname DD DSN=data-set-name,DISP=(NEW,CATLG),// UNIT=(3390,5),// RECFM=FB,LRECL=1500,// SPACE=(4500,(45870,4587),RLSE,,ROUND)

[11 blocks/track × 15 tracks/cylinder = 165 blocks/cylinder. 165blocks/cylinder × 278 cylinders = 45,870 blocks per volume. Youhave allocated a secondary equal to 10 percent of this.]

Now do this for an SMS-managed data set:

//ddname DD DSN=data-set-name,DISP=(NEW,CATLG),// STORCLAS=storage-class,DATACLAS=data-class,// RECFM=FB,LRECL=1500,// AVGREC=U,SPACE=(0,(115000,11500),RLSE,,ROUND)

[You’re allocating 575,000/5 = 115,000 records on each volume witha secondary equal to 10 percent of this.]

All this points out that it is not easy to allocate space for very large datasets. In practice, you would probably ask the operators which volumes haveavailable space and which ones you might use. You might also need per-mission to create a data set this large. Then you might preallocate the space


using the IEFBR14 dummy program, described later, or preallocate thespace using ISPF for quick trial and error turnaround as you try to findenough available space on the volumes for the data set.

Take special care in production jobs to set up the JCL to reduce the riskof termination because disk storage is not available. Make sure you canrestart the job if it does terminate. If a job creates temporary data sets in onestep and terminates in a subsequent step, the system deletes the temporarydata sets. You must then restart the job from the step that created the tem-porary data sets. This can be expensive. Make such temporary data setsnontemporary and delete them when you no longer need them for restart.

The system does not reserve space for secondary allocations before thedata set needs them, so that if you’ve used up all your available volumesand the current volume is full, the system must terminate the step becausethe space is unavailable. This problem is common in multiprogrammingsystems where several jobs may concurrently request space on a public vol-ume and the system does not guarantee that space will be available. Forthese situations, you might consider using the guaranteed space feature ofSMS by selecting the appropriate STORCLAS parameter as provided byyour installation.

Another way to ensure that there is enough space for all steps within ajob is to use the IEFBR14 null program to allocate all the space in the firststep:

//stepname EXEC PGM=IEFBR14//any-ddname DD all-parameters-to-create-the-file

Include a DD statement for each data set for which you want space allo-cated. The following example allocates space for a PAYROLL data set.

//RT452216 JOB (45992),'SMITH',CLASS=A//STEP1 EXEC PGM=IEFBR14//A DD DSN=A1000.PAYROLL.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,RECFM=FB,LRECL=80,// SPACE=(4096,(200,50))

Subsequent steps can now write the PAYROLL data set by coding a DDstatement as follows:

//ddname DD DSN=A1000.PAYROLL.DATA,DISP=OLD

Delete all nonpermanent direct-access data sets in the last step in whichthey are needed to free up space for subsequent steps and for other jobs. Ifa production job has difficulty obtaining space, you might permanentlyallocate space for all the data sets, even temporary ones. Although this re-duces the disk space available to the installation, it guarantees that the sys-tem will not terminate this job for lack of direct-access space.


TEAMFLY

Team-Fly®

Data sets on direct-access volumes also cause problems when jobs arererun if data sets already exist that are to be created in the job. For example,assume the previous job was run creating the PAYROLL data set. Supposethat for some reason the job must be rerun. If we rerun the job withoutchanging the JCL, the system will terminate it in STEP1 because you cannotcreate a data set if it already exists on the same direct-access volume. (Thereis no DISP parameter to tell the system to create a new data set, wiping outthe old data set if it should exist.) You can make the appropriate JCLchanges (DISP=NEW to DISP=OLD), but this is error prone and leads tofrustration. You might include the following IEFBR14 null program step todelete the data set:

//STEP1 EXEC PGM=IEFBR14//A DD DSN=data-set-name,DISP=(OLD,DELETE)

However, if the data set is not there to delete, the system will terminatethe job with a JCL error. Instead, you can use MOD because the system willaccept MOD whether or not the data set exists. You could code

//STEP1 EXEC PGM=IEFBR14//A DD DSN=data-set-name,DISP=(MOD,DELETE),// UNIT=device,SPACE=(TRK,0)

[The UNIT and SPACE are needed to allocate the data set in theevent the data set is not there. If the data set is not there, allocateand delete it in the same step. If it is there, the system deletes it.Notice that you can specify zero tracks. To allocate space on direct-access storage, you must code the SPACE parameter. However, youcan specify zero tracks.]

The following deletes the PAYROLL data set:

//RT452216 JOB (45992),'SMITH',CLASS=A//STEP1 EXEC PGM=IEFBR14//A DD DSN=A1000.PAYROLL.DATA,DISP=(OLD,DELETE),// UNIT=SYSDA,SPACE=(TRK,0)

This method works only if the data set is cataloged; another reason foralways cataloging nontemporary data sets.

10.10 ABSTR: REQUESTING SPECIFIC TRACKS

Rarely Used

ABASTR allocates a given number of tracks at a starting track address. Thisalways gives contiguous space, but you should use it only for location-


dependent data sets. The data set cannot be moved, and systems program-mers often need to move data sets around to balance both available space onthe disk volumes and the I/O done on a channel. Conceivably, you mightuse ABSTR for very high usage data sets to place them near the VTOC. Thesystem allocates the space only if all the tracks are available. To requestabsolute tracks, code the following:

SPACE=(ABSTR,(quantity,address,directory))

The quantity is the number of tracks desired and address is the relativetrack address of the first track wanted. (The address of the first track on avolume is zero, but it cannot be allocated because it contains a pointer tothe table of contents.) For a partitioned data set, directory requests directoryspace.

SPACE=(ABSTR,(200,2400))

[We request 200 tracks, starting at relative track address 2,400.]

EXERCISES

1. Use the program in Chapter 5, but modify the //GO.OUT DD statementto write the lines into a data set named userid.THING.CNTL on disk.(Use your installation standards for actually naming the data set.) Makeuserid.THING.CNTL a cataloged data set.

2. Now rerun the same program, but modify the JCL to add the followingthree lines to the end of userid.THING.CNTL.LINE 3LINE 4LINE 5

3. Run the job again to read userid.THING.CNTL and print the lines, veri-fying that the three lines were added.

4. Again, change the JCL to place only the following lines in userid.THING.CNTL:LINE 6LINE 7LINE 8

5. Do this twice, once by overwriting userid.THING.CNTL, and once bydeleting userid.THING.CNTL and recreating it.

6. Suppose that you pick up an old job that contains the following DDstatement://ONE DD DSN=userid.THING.CNTL,DISP=(,CATLG),// UNIT=3350,// DCB=(RECFM=FB,BLKSIZE=80,LRECL=80).// SPACE=(90,100000)


Suppose that you also know that the program writes 100,000 records,runs in 500K of storage, consumes 100 CPU seconds, and is run duringthe prime shift. Using your installation’s cost equation and assumingthat the CPU time and region size remain constant, how much run costcould you save per run if you set the block size to 4,096? How manytracks of disk storage space would you save with this new block size? Ifyour installation charges for disk storage, calculate the cost of storingthe data set for a year. Finally, what are your conclusions about using aBLKSIZE of 80 for a disk data set?


CHAPTER 11

SMS: STORAGE MANAGEMENTSUBSYSTEM

Essential—If SMS Active at Your Installation

SMS (Storage Management Subsystem) is an optional feature of the operat-ing system that manages user disk data sets. If your installation doesn’thave it, you can skip this chapter. SMS manages disk data sets by providingDD parameters to classify the data sets that allow them to be migrated backand forth to tape for long-term storage based on criteria such as usage andimportance. An administrator establishes classes of disk data sets with sim-ilar characteristics. You can then create a data set and name the class towhich it should belong. SMS also consolidates fragmented disk space andmoves data sets around on the disk volumes to balance usage. As a fortu-nate side effect, SMS made it easier to write JCL.

The SMS parameters apply only to new data sets, and the systemignores them for existing data sets, DD * and DD DATA data sets, JOBCATand JOBLIB DD statements, and SYSOUT data sets. You can create SMS-managed data sets on disks and on tapes contained in an automatic tapelibrary dataserver. Data sets created by SMS are termed SMS-managed datasets, and installations can set various DD parameters for them. Data setsbecome SMS-managed in two ways:

� You code the STORCLAS parameter on the DD statement creating thedata set, which assigns it to a storage class.

� The installation establishes a default storage class that the systemapplies if you omit STORCLAS.

The system determines the status of an SMS-managed data set and itsSMS attributes when it creates the data sets. It stores this information in thecatalog and catalogs the data set when it creates it rather than at the end ofthe job step as it does for non-SMS-managed data sets.

If SMS is activated, your installation can establish various defaults to beset for non-SMS-managed data sets. In addition, an activated SMS lets you

208

use the AVGREC, LIKE, REFDD, DATACLAS, SECMODEL, RECORG, andKEYOFF parameters or all data sets. Only the STORCLAS and DATACLASparameters are limited to SMS-managed data sets.

11.1 THE AVGREC PARAMETER

Essential

The AVGREC parameter operates with the SPACE parameter as described inChapter 10. Installations can establish AVGREC values for different dataclasses or as the default if you don’t specify a class. If SMS is active, you canuse AVGREC for both SMS- and non-SMS-managed data sets.

11.2 THE DATACLAS, STORCLAS, MGMTCLAS, AND SECMODEL PARAMETERS

Essential

These four parameters let installations establish various default values forcataloged disk data sets. An administrator assigns a name to each group ofdefault values, and then you reference this name on your DD statements touse the values. Installations can also establish default classes for each of thesefour parameters to be effective when you don’t code them. The concept ofclasses allows an installation to more closely control its disk space. It canalso make it easier to code JCL for disk data sets. However, keeping track ofall the classes and knowing what attributes they provide can be confusing.

11.2.1 STORCLAS

You code the STORCLAS parameter when you create a data set to make itan SMS-managed data set. STORCLAS can replace the UNIT and VOL pa-rameters for creating new data sets, temporary or nontemporary. Installa-tions establish the STORCLAS names and assign the name to appropriateunits and volumes. Then you can code STORCLAS=class on your DD state-ment rather than the UNIT and VOL parameters.

For example, suppose that the installation had set up a STORCLASname of PDSLIB. You could code your JCL as follows:

//PDS DD DSN=A1000.LIB.COBOL,DISP=(NEW,CATLG),// STORCLAS=PDSLIB

The STORCLAS parameter denotes a new data set (temporary or non-temporary) as an SMS-managed data set. That is, a data set is an SMS-

SMS: STORAGE MANAGEMENT SUBSYSTEM 209

managed data set if STORCLAS is coded or assumed for it when the systemcreates it. If you create a data set using VOL=REF on the DD statement torefer back to an SMS-managed data set, the new data set assumes the STOR-CLAS of the SMS-managed data set and you needn’t code STORCLAS. Thesystem ignores any UNIT and VOL on the DD statement when it appliesSTORCLAS. (You can code the VOL DD parameter to override the STOR-CLAS volumes for an SMS-managed data set if the administrator has speci-fied the guaranteed space option described in Chapter 10.)

Most installations already have UNIT group names that act much thesame as the STORCLAS parameter. However, STORCLAS is much moreflexible because new values can be set at any time or old values changed,whereas UNIT group names are set at SYSGEN time.

Note that temporary data sets can be SMS-managed data sets and sinceall SMS-managed data sets must be cataloged, the system catalogs tempo-rary SMS-managed data sets when it creates them and uncatalogs themwhen it deletes them.

11.2.2 DATACLAS

The DATACLAS parameter may define any or all of the following DD pa-rameters:

RECFMLRECLAVGREC and SPACEvolume count on the VOL parameterRETPD or EXPDTDSNTYPE for partitioned or extended sequential data setsKEYLEN for direct data setsRECORG, KEYOFF, IMBED, REPLICATE, CISIZE, FREESPACE, and

SHAROPTIONS for VSAMCompression of the data, if necessary, for extended sequential data sets.

Installations set up these values for a class of data sets. Then you namethis class on your DD statement with the DATACLAS=class parameter andomit the assumed parameters for the class in writing the DD statement. Forexample, suppose that a class named COBOL was established for COBOLsource libraries with the following parameters:

RECFM=VB

LRECL=255

AVGREC=U,SPACE=(0,(200,100,20))


You could then code the following on your JCL:

//PDS DD DSN=A1000.LIB.COBOL,DISP=(NEW,CATLG),// STORCLAS=DASDTWO,DATACLAS=COBOL

The system treats this statement as if you had coded the following:

//PDS DD DSN=A1000.LIB.COBOL,DISP=(NEW,CATLG),// STORCLAS=DASDTWO,RECFM=VB,LRECL=255,// AVGREC=U,SPACE=(0,(200,100,20))

You can override any of the DATACLAS values by coding them on yourJCL. For example, if you wanted 50 directory blocks for the precedinglibrary, you could code

//PDS DD DSN=A1000.LIB.COBOL,DISP=(NEW,CATLG),// STORCLAS=DASDTWO,SPACE=(,(,,50)),DATACLAS=COBOL

[You can code SPACE this way to override just the number of blocksof directory space. When overriding, you just need to write the indi-vidual subparameters you want to override.]

To use DATACLAS, you need to know the names of the data classes setup at your installation and the attributes assigned to each class. DATACLASworks well for standard data sets, such as the following combinations:

Text files: RECFM=VB,LRECL=255

Data files: RECFM=FB,LRECL=80

Partitioned data sets: SPACE parameter

Sequential data sets: SPACE parameter

AVGREC=U is often specified for all classes, although installations canset what they want. Beyond these standard values, the number of possibili-ties quickly rises.

You can use DATACLAS for tape data sets and for non-SMS-manageddata sets. Any attributes obtained with the MGMTCLAS, REFDD, or LIKEparameters override the corresponding DATACLAS attributes.

11.2.3 MGMTCLAS

The MGMTCLAS parameter doesn’t replace any DD parameters. It assigns amanagement class to a new data set that the installation can then use as itwishes and can be used only for SMS-managed data sets. The followinguses are typical:

� To migrate inactive data sets to archival storage� To determine how often to back up the data set


� To determine how often to compress partitioned data sets� To do cost accounting on data sets� To release unused space in a data set� To delete data sets whose retention period has expired

Installations must provide the names for the MGMTCLAS parameter,and you code it as MGMTCLAS=class. If a management class namedACTIVE were defined, you could code the following:

//PDS DD DSN=A1000.LIB.COBOL,DISP=(NEW,CATLG),// STORCLAS=PDSLIB,DATACLAS=COBOL,MGMTCLAS=ACTIVE

You can code MGMTCLAS with DATACLAS or STORCLAS, althoughthis isn’t necessary. MGMTCLAS attributes override those from a DATA-CLAS parameter.

11.2.4 SECMODEL

The SECMODEL parameter replaces the PROTECT DD parameter describedin Chapter 16. SECMODEL overrides any PROTECT parameter and can beused for both SMS- and non-SMS-managed data sets. The system ignoresany PASSWORD or NOPWREAD subparameters in the LABEL parameterwhen you code SECMODEL. SECMODEL assigns an RACF (ResourceAccess Control Facility) profile name to a new data set for security. Youcode the following to name the profile assigned by the installation belong-ing to a discrete data set profile:

SECMODEL=profile

Add GENERIC if the profile belongs to a discrete data set profile.

SECMODEL=(profile,GENERIC)

The generic data set profile can include the following:

OWNER to name the user or group that owns the data set

ID to name the access list of users or groups who can access the data set

UACC to assign universal access authority to the data set

AUDIT/GLOBALAUDIT to tell which access attempts to log

ERASE to erase the disk storage when you delete the data set

LEVEL to specify the installation-defined level indicator

DATA to include installation-defined information


WARNING to cause RACF to issue a warning message but allow unau-thorized access to the data set

SECLEVEL to name the installation-defined security level

11.3 THE LIKE AND REFDD PARAMETERS

Sometimes Used

The LIKE parameter copies DD information from an existing cataloged dataset on disk, and REFDD copies DD information from a previous DD state-ment in the job—tape or disk. LIKE and REFDD also copy any SMS attri-butes coded or assumed for the referenced data set or DD statement. Notethat SMS must be active to use LIKE and REFDD, but neither of the data setsinvolved—the data set being copied from or the data set for which theattributes are being copied to—need be SMS-managed. You code LIKE andREFDD as

LIKE=data-set-name

[Name the data set from which to copy the attributes.]

REFDD=*.referback

[Refer back to a DD statement containing attributes to copy. Notethat REFDD copies information from the DD statement, not from thedata set described by the DD statement.]

The priority for attributes copied by REFDD or LIKE are

1. Parameters on the DD statement containing REFDD or LIKE

2. Parameters on the DD statement referred to by REFDD or the data setnamed by LIKE

3. Parameters from the data class of the DD statement referred to or thenamed data set

LIKE does the same thing as naming a data set with the DCB parameter(DCB=data-set-name), and REFDD does the same thing as naming a DDstatement with a referback (DCB=*.referback), except that LIKE and REFDDcan also copy SPACE parameter information. Note that any attributesobtained by LIKE or REFDD override the corresponding attributes on aDATACLAS parameter.

The system copies the following information if you don’t supply it onthe DD statement:

RECFM for normal data sets; RECORG for VSAM data sets.

LRECL.


SPACE and any AVGREC. (When you code LIKE, the system allocatesprimary space equal to the first three extents of the data set.)

DSNTYPE for partitioned or extended sequential data sets.

KEYLEN for normal direct data sets; KEYOFF for VSAM KSDS datasets.

In this example, the system copies the DCB and SPACE informationfrom the data set named A1000.TEST.DATA.

//STEP1 EXEC PGM=ONE//DD1 DD DSN=A1000.TEST.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,RECFM=VB,LRECL=255,// SPACE=(TRK,(30,10),RLSE)//STEP2 EXEC PGM=TWO//DD2 DD DSN=A1000.RUN.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,LIKE=A1000.TEST.DATA

Next, the DCB and SPACE information are copied from the //DD1 DDstatement in STEP1.

//STEP3 PGM=THREE//DD3 DD DSN=A1000.PROD.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,REFDD=*.STEP1.DD1

Any parameters you code on the DD statement override those copiedfrom the data set. In this example, the system copies the DCB and SPACEinformation from A1000.TEST.DATA, except for the LRECL, which is 500.

//STEP4 EXEC PGM=FOUR//DD4 DD DSN=A1000.RUN.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,LRECL=500,LIKE=A1000.TEST.DATA

Don’t use LIKE or REFDD to copy information from a temporary dataset, a member of a partitioned data set, or a generation data group in whicha relative generation number is used.

11.4 RECORG AND KEYOFF FOR VSAM DATA SETS

Essential—For VSAM Data Sets

You can create VSAM data sets with JCL by coding the RECORG parameterto specify the VSAM data set organization and the KEYOFF parameter tospecify the offset of the keys in a KSDS data set. These parameters aredescribed with VSAM in Chapter 17.


TEAMFLY

Team-Fly®

11.5 DSNTYPE PARAMETER FOR PARTITIONED AND EXTENDED SEQUENTIAL DATA SETS

Essential

The DSNTYPE parameter lets you specify a PDSE, partitioned data setextended. A PDSE is like a PDS except for the following:

A PDSE must be SMS-managed.

A PDSE never needs to be compressed. When you delete a member, thesystem makes its space available for reuse.

No directory space needs to be set aside for member names. Any PDSEcan contain as many as 524,286 members, assuming there is enoughspace to store them.

A PDSE is faster to access.

The system can concurrently update individual members in a PDSE.This allows members of system data sets to be updated withoutdenying access to the members of the data set not being updated.

To create a PDSE, code DSNTYPE=LIBRARY on the DD statement. Codethe SPACE parameter with the number of directory blocks as with a PDS,although the system ignores the estimate for a PDSE.

To specify an extended sequential data set, code DSNTYPE=EXTENDED.z/OS has two types of sequential data sets: normal sequential and extendedsequential. Extended sequential data sets must be SMS-managed. The sys-tem writes extended sequential data sets across several individual RAMACdisks in a round-robin manner. That is, it writes a track on the first volume,then on the second, and so on to the last volume. This is termed striping.Then the system begins writing the second track on the first volume and soon. This lets the tracks across the multiple volumes act as cylinders in whichthe entire cylinder is read or written concurrently. Since each volume has itsown read/write head, the system can read the tracks across all the volumesconcurrently. You can also specify extended sequential data sets for tape,and the data sets are striped across the tracks of a tape when read and writ-ten for faster processing.

Aside from processing speed, extended sequential data sets offer twoadditional benefits. The system can allocate 123 secondary allocations pervolume rather than 16 for normal sequential data sets, as described in Chap-ter 10. In addition, the data in extended sequential data sets can be com-pressed on disk or tape to reduce the storage requirement and processingtime by roughly a factor of three. For tape, you code the TRTCH=COMPparameter to request compaction. For disk, you specify compaction throughthe DATACLAS parameter. The one disadvantage of compressed data on


disk is that you cannot update records in place. (This is not a disadvantagefor tape because you cannot update tape in place anyway.)

Although the way extended sequential data sets are stored is differentfrom that of normal data sets, there is no difference in the way you processthem. Once you create an extended sequential data set by codingDSNTYPE=EXTENDED, the hardware handles all the differences.

The full DSNTYPE parameter is

LIBRARYPDSEXTENDEDHFSPIPE

DSNTYPE=

LIBRARY specifies a PDSE.

PDS is the default for the old-type partitioned data set if you don’t codeDSNTYPE.

Whether it is an SMS-managed data set depends on the STORCLASparameter.

EXTENDED specifies an extended sequential data set and makes it anSMS-managed data set.

HFS specifies a hierarchical file system data set as described in Chapter16 and makes it an SMS-managed data set.

PIPE specifies a FIFO special file as described in Chapter 16 and makesit an SMS-managed data set.

You may code DSNTYPE with other SMS subparameters, too. The fol-lowing is typical:

//OUT DD DSN=A1000.LIB.COBOL,DISP=(NEW,CATLG),// DATACLAS=COBOL,STORCLAS=PDSLIB,DSNTYPE=LIBRARY,// AVGREC=U,SPACE=(0,(100,10,20))


CHAPTER 12

MAGNETIC TAPES

12.1 DESCRIPTION OF TAPE

Essential

12.1.1 Tape Hardware

Disk devices on mainframe computers are large, expensive, fragile, and notportable. By contrast, tape reels and cartridges are relatively inexpensive(costing as little as $15), they can hold vast amounts of data, they can sur-vive the postal service, and you can carry them around in a briefcase. Tapeis an inherently sequential I/O device that can contain only sequential datasets. However, for backup and sending from one site to another, you canunload most nonsequential data sets to tape and then load them back ontodirect-access storage. You just can’t use them directly while they are storedon tape. For example, you can only use partitioned data sets on direct-access storage, but you can load and unloaded them to tape for backup or tosend to another installation.

Tapes used for storing computer data consist of either a reel or cartridgeof magnetic tape. A tape reel consists of 2,400 feet of 1⁄2-inch wide tape. Atape cartridge is enclosed in a 4 × 5 inch case. They require separate tapedrives. Tape reels began being supplanted by cartridges in the late 1980s.However, many tape reels still exist, and installations usually keep one ormore tape drives around to read them. A typical tape reel might contain170MB whereas tape cartridges can contain as much as 20GB (60GB if com-pressed). On a 3590 Tape Unit, the data rate is 13.5 Mb/second. Table 12.1shows the various capacities of tape units. For tape cartridges, both thecapacity and data transfer rate increase by roughly a factor of three whenthe data is compressed.

A byte of data is stored in a row across the width of the tape; the positionof each of the eight bits across the width forms a column that is called atrack. The density is the distance between successive bits along the length of

217

the tape. For tape reels, a density of 6,250 bits per inch (bpi) is standardtoday. In the past, tape drives with 200, 556, 800, and 1,600 bpi were com-mon. Even today, PC tape drives are usually 1,600 bpi. Tape reels have ninetracks—eight bits for storing a byte and one bit for parity. This enables thetape drive to detect when a bit is lost. The tape drives have additional paritychecks that enable them to detect and correct all single-bit errors and mostdouble-bit errors. Before System/360, tapes were 7-track and had even orodd parity, and after a third of a century, there are few of these tapes around.

Tape cartridges, such as that for the 3590, are roughly 5 inches squareand have 128 tracks, allowing much more data to be stored with faster read-ing and writing. Multiple tape cartridges are often stored in a silo, essen-tially a library of tape cartridges, where they are automatically selected,mounted, and readied in a few seconds without operator intervention.Although tape cartridges are considerably different in design than tapereels, they are the same from the programming standpoint.

A tape drive reads and writes tapes by passing the tape past a read/writehead, similar to the way cassette tape recorders operate. The hardwareerases any old data on the tape as it writes the tape. Tapes can be file-protected, a hardware feature that physically prevents a tape from beingwritten on. For tape reels, the computer operator must insert a small write-enable ring (also termed the file-protect ring) into the circular groove pro-vided for it on the tape reel before anyone can write on the tape. When theoperator removes the ring, the tape can be read, but it is fully protectedagainst being written on accidentally. Tape cartridges have a write-protecttab. Some installations set all tapes to be write-enabled and use othermeans, such as a tape management system and an expiration date, to pro-tect the tape. One advantage of this is that no operator intervention isrequired to write a tape. Other installations use the write-protection featureof the hardware, requiring that you notify the operator when you wish towrite a tape.

The system terminates a data set on tape by writing a file or tape markas shown in Figure 12.1. Several data sets can be contained on a single tapevolume. The last file on tape is marked with an end-of-volume marker thatconsists of two tape marks as shown in Figure 12.2.


TABLE 12.1 Tape Capacity

Tape model Reel/Cartridge capacity

1600 bpi 9-track 26MB6250 bpi 9-track 170MB3480 200MB3575 5GB3590 20GB

The hardware reads tapes by moving the tape past the read head totransmit the data into contiguous ascending storage locations. If the hard-ware detects an error, the system attempts to reread the block several timesbefore pronouncing an I/O error. Your program is notified when the filemark is read. Tapes, as long as they do not have variable-length records, canalso be read backward by moving the tape in the opposite direction, placingthe data in descending order of addresses in storage—interesting but notterribly useful.

The hardware writes a tape by transmitting data in storage in increasingorder of addresses onto the tape as it passes the write head. It immediatelyreads the data back as it passes the read head to ensure that it was recordedcorrectly. For standard labeled tapes, the system stores a block count in thetrailer record as shown in Table 12.4. This gives additional protection toensure the integrity of tape data. Tapes can also be backspaced and forward-spaced over blocks or files, rewound to the load point, and unloaded.

12.1.2 Using Tape Storage

Individual tape volumes are usually stored separately in a fireproof vault,requiring a computer operator to retrieve the volume and mount it on a tapedrive when you want to use it. Tape cartridges may also be contained inTape Library, a silo device that holds many cartridges and automaticallymounts them. Tape storage is ideal for the following:

Storing large amounts of sequential data.

Long-term storage of inactive data sets. If you aren’t going to use datasets for some time, you can copy them to tape and free up scarcedisk storage.

Sending large data sets from one installation to another. You can copythe data sets to tape and mail or carry the tape.

MAGNETIC TAPES 219

FIGURE 12.1 Tape file mark.��Data set

Tape file File mark

TM

FIGURE 12.2 Several files stored on tape.��Data set 1

Loadpoint

File 2

TM Data set 2 T

M Data set 3 TM … T

MTM

File 3 End ofvolume

File 1

Making backup copies of critical data sets on tape. (Your installationwill back up the disk volumes onto tape on a regular basis.)

Off-site storage. Many catastrophes that might destroy data on the com-puter, such as fire, flood, and earthquake, have the potential of alsodestroying all on-site backups. Installations must keep copies ofcritical data sets off-site.

To use an individual tape volume, you must tell the computer operatorwhich volume you want. Tape cartridges stored in a tape library areselected and mounted by the hardware. The system selects an availabletape drive for mounting the tape. When the job is finished with the tape, thesystem rewinds the tape. For an individual tape volume, it notifies theoperator to dismount the volume. For a cartridge in a tape library, it auto-matically removes the cartridge and returns it to its silo storage. The tapedrive then becomes available for mounting other tapes. Normally, no oneelse can use a tape drive while the system has it assigned to you. (There isa concurrent copy feature that allows the system to copy or back up a tapewhile it is assigned to you, but you are not affected by this.)

Installations usually assign tape volumes in one of two ways.

� Some installations assign tapes when you run your job. You leave offthe VOL parameter, and the operator assigns a new tape when the jobrequests one. These installations usually require that you catalog tapedata sets by specifying a DISP of CATLG. This way the system savesthe volume serial number in the catalog, along with the data set name.

� Other installations assign tapes before you run your job. The opera-tors assign you the tape and tell you the volume serial number, whichyou then specify in your JCL with the VOL parameter. Often theseinstallations do not catalog tape data sets, although they can.

If tape data sets are cataloged at your installation, as they will usuallybe, you can let the system keep track of the volume serial numbers for you.However, if your tape is not in a tape library, your installation may requireyou to inform the operators of the tape volumes that your job needs so thatthe operators can retrieve the volume from storage before releasing your jobto run.

12.2 LABEL: TAPE LABELS

Essential

The LABEL parameter tells the type of label, the relative file number on thetape, and whether to protect the data set for input or output. The complete


LABEL parameter is coded as

RETPD=nnnnNOPWREAD IN EXPDT=yydddPASSWORD OUT EXPDT=yyyy/ddd

LABEL=(file,type, , , )

PASSWORD, NOPWREAD, EXPDT, and RETPD specify data set protec-tion and are explained in Chapter 16. The usual form of the LABEL param-eter for tape is

LABEL=(file,type)

12.2.1 FILE: Relative File Number

Essential

Data sets are stored on tape in what are termed files. The hardware writesthe data sequentially onto tape, followed by a file mark that marks the endof the file or data set. You can place several data sets on the same tape vol-ume.

Unless the data set is the first file on the tape, file must give the filenumber to position the tape properly. The file is a sequence number (1 to9999) indicating the data set’s position on the volume. (File one is the firstfile on the tape.) If you omit the file or code zero, the system assumes one.(The tape is spaced to the end of volume if the file is higher than the num-ber of data sets on the volume.) For labeled tapes, the file continues con-secutively over multiple volumes. For unlabeled tapes, the file starts withone with each volume.

The system records the file in the catalog if you catalog the data set. Italso passes it with the data set, so that if a DD statement refers to a passeddata set, it does not need to supply the file number. Here’s an example of apassed data set on tape.

//STEP1 EXEC PGM=WON//DD1 DD DSN=ALL,DISP=(OLD,PASS),// UNIT=TAPE,VOL=SER=000421,LABEL=2//STEP2 EXEC PGM=TOO//DD2 DD DSN=*.STEP1.DD1,DISP=(OLD,KEEP)

12.2.2 TYPE: Label Type

Sometimes Used

Tapes are usually labeled, in which case the tape contains both volume anddata set labels, either standard as provided by IBM, nonstandard as devised

MAGNETIC TAPES 221

by the installation, a combination of both, or they can contain ASCII labels.Most installations use standard labels.

A tape volume label is a block written on the tape by the system beforethe tape is used, and the label is not changed thereafter. (The one- to six-character label is pasted on the tape volume to help the operator locate thetape. Newer tape cartridges also use bar codes that the hardware reads.) Thevolume label is not separated from the first data set on the tape by a tapemark. Table 12.2 describes the standard IBM volume label.

Figure 12.3 illustrates a data set on a standard labeled tape. For a dataset, the tape contains a header block, a tape mark, the data set itself, a tapemark, and a trailer block. The system writes two tape marks after the lastfile on the tape to denote the end of volume. The header block contains thedescription of the data set: record format, record size, block size, and dataset name. The trailer block contains the same information as the headerblock so that the tape can be read backward. Table 12.3 illustrates theheader block format and Table 12.4 the trailer block. Figure 12.4 illustratesa multivolume file.

The system creates data set labels when the data set is created with stan-dard labels. If you request no label, the system creates no volume or data setlabel. The tape would then contain the first data set, a tape mark, the next


TABLE 12.2 VOL1 Record Format

Byte position Number of bytes Contents

1 4 Characters ‘VOL1’5 6 Volume serial number, left justified, padded on right with

blanks11 70 Reserved characters

FIGURE 12.3 IBM standard labels, single volume, multiple files.�

VOL 1 Dataset 1

HDR1/HDR2

Load pointreflective strip

Tape mark

TM

EOF1/EOF2

TM

TM

Dataset 2

HDR1/HDR2

TM

EOF1/EOF2

TM

TM

TM

Volumelabel

Second tape markmarks end of volume

MAGNETIC TAPES 223

FIGURE 12.4 IBM standard labels, multivolume file.��VOL 1 Data set 1 (first part)

Volume 1

HDR1/HDR2

TM

EOV1/EOV2

TM

�VOL 1 Data set 1 (second part)

Volume 2

HDR1/HDR2

TM

EOF1/EOF2

TM

TM

TABLE 12.3 HDR1/EOV1/EOF1 Record Formats

Byte position Number of bytes Contents (80-byte records)

1 4 Characters ‘HDR1’ or ‘EOV1’ or ‘EOF1’5 17 Data set name. Rightmost 17 characters, left justified,

padded on right with blanks22 6 Volume serial number. Right justified, padded on left with

blanks. For multivolume file, serial number of first file28 4 Volume sequence number (0001–9999) of a multivolume

file; 0001 for single volume file32 4 File number (0001–9999) of file on tape36 4 Generation numbe (0001–9999) for generation data group40 2 Version number (00–99) for generation data group42 6 Creation date: ‘cyyddd’. c is code for first two digits of

year: blank–19, 0–20, 1–2148 6 Expiration date: ‘cyyddd’54 1 Data set security: 0–no protection, 1–PASSWORD

protection, 3–NOPWREAD protection55 6 6 low-order digits of block count. Zero in HDR161 13 System code, such as ‘IBM OS/VS 370’74 3 Reserved77 4 4 high-order digits of block count in byte position 55

data set, a tape mark, and so on, as shown in Figure 12.5. The system writestwo tape marks after the last data set on the tape. The system does not storethe label in the catalog, but does pass it with the data set between steps.

You may specify the following types of labels.

SL: Standard Labels (assumed if type is omitted).

BLP: Bypass Label Processing.

NL: No Labels.

NSL: Nonstandard Labels.

SUL: Both SL and User Labels.

LTM: Leading Tape Mark on an unlabeled tape.

AL: ISO/ANSI version 1, ISO/ANSI/FIPS version 3, and ISO/ANSI ver-sion 4 Labels. The format for these tapes is the same as for SL, asshown in Figures 12.3 and 12.4.

AUL: Both AL and User Labels.


TABLE 12.4 HDR2/EOV2/EOF2 Record Formats

Byte position Number of bytes Contents (80-byte records)

1 4 Characters ‘HDR2’ or ‘EOV2’ or ‘EOF2’5 17 Record format: F-fixed, V-variable, U-undefined length6 5 BLKSIZE

11 5 LRECL16 1 DEN17 1 Data set position: 1 if volume switch has occurred;

otherwise 018 17 ‘job-name/job-step’ that created file35 2 TRTCH for 7-track tape. Pb for compressed cartridge37 1 Control character. A-ASCII, M-machine, blank-none38 1 Reserved39 1 Blocking of records: B-blocked, S-spanned, R-blocked and

spanned, blank-unblocked40 2 Reserved43 6 Device serial number of tape drive that wrote tape48 1 ‘C’ if file contains checkpoint data set. Blank otherwise49 32 Reserved

FIGURE 12.5 Tape with no labels.

��Data set

Loadpoint

File number 1

TM Data set T

MTM

File number 2

TEAMFLY

Team-Fly®

Sometimes Used

The only label type you are likely to use is SL. BLP and NL are occasionallyused.

SL: Standard LabelsIf you code SL or omit the type, the system assumes standard labels andreads in the first file to see whether it contains a valid label. It then checksthe volume serial number in the label with that stored in the catalog or sup-plied in the VOL=SER parameter. If they do not check, the system tells theoperator to mount the proper volume.

Most installations require you to use tapes with standard labels. If thetape does not have a standard label and a specific volume is not requestedwith VOL=SER, the system (or the operator) supplies the label informationand writes a volume label on the tape. If the label being read is of a differ-ent density than that specified or assumed on the DD statement, and if thetape is mounted on a multiple-density drive, the density is changed and thesystem attempts to read the label again.

When the serial numbers check, the system positions the tape to theproper file. If you are writing the tape, the system writes the data set namegiven by DSN into a data set label. (It writes only the 17 rightmost charac-ters.) If you read the tape, the system checks the DSN parameter against thename in the data set label and terminates the program if the names do notcheck. You must supply the file number and data set name for each non-temporary data set created.

The system writes a trailer label on the current volume if it encountersan end-of-volume condition while writing a tape, and it continues process-ing on the next volume.

BLP: Bypass Label ProcessingBLP positions the tape to the specified file without checking for volume ordata set labels. The system does not create data set labels when you write adata set with BLP. Consequently, the system cannot obtain DCB informationfrom the label when the data set is read. It must be coded in the program orin the DCB parameter of the DD statement. BLP is used to read or writeunlabeled tapes when NL (explained next) cannot be used.

If you write on a tape containing standard labels with BLP, the volumelabel is overwritten. If a tape with standard labels is read with BLP, the firstfile contains the volume label and the header block for the first data set, thesecond file contains the data set, and the third file contains the trailer block.The formula for computing the BLP file number for a standard labeled tapeis given by

BLP file number = ((SL file number - 1) x 3) + 2

MAGNETIC TAPES 225

BLP is especially useful when the file type or data set name isunknown. For example, LABEL=(1,BLP) would let you read the tape labeland data set name of the first file of a tape having standard labels.LABEL=(2,BLP) would let you read the first file of a tape having standardlabels in which you did not know the data set name. Remember that to reada nonlabeled tape, you must supply all the necessary DCB informationbecause the system cannot obtain it from the data set label.

Always dismount unlabeled tapes at the end of the last step in whichthey are needed by coding DISP=(..,KEEP) so that the system will not usethem for scratch. BLP is an installation option. If the BLP option is notenabled, the system treats BLP as NL.

NL: No LabelsNL is identical to BLP except that NL won’t let you read or write a labeledtape. To ensure that the tape is not labeled, NL reads in the first file on thetape and verifies that it is not a volume label. Nonlabeled tapes are oftenused for sending tapes to another installation. That way, you don’t have toworry about the tape label corresponding to the standards at the otherinstallation or of accidentally matching the volume serial number of anexisting tape at that installation. NL tapes are not supported in SMS.

NL can produce some unexpected results. Because new tapes do notcontain a tape mark, the system reads to the end of volume. If the tape con-tains previous data of a different parity, track, or density, the result is an I/Oerror and the system abnormally terminates the step. You must know whatis on a tape to use NL—if you do not know, use BLP. If the tape does nothave the proper label and a specific volume is not requested withVOL=SER, the operator is requested to supply label information, and a vol-ume label is then written on the tape. If the tape originally contained a stan-dard label, the system writes a new label only if any retention data hasexpired and if the tape does not contain password-protected data sets.

To process ASCII data sets on unlabeled (NL) tapes, you must code theDCB=OPTCD=Q parameter. OPTCD=Q converts from ASCII to EBCDICwhen a tape is read and the reverse when the tape is written.

NSL: Nonstandard LabelsNSL gives control to installation-written routines for label processing.

SUL: Standard and User LabelsSUL is identical to SL except that installation-provided routines processthe user data set labels.

LTM: Leading Tape MarkLTM is identical to BLP except that if the tape has a leading tape mark, thesystem ignores it. LTM reads and writes disk operating system (DOS/VS)files.


AL: American National Standard LabelsISO/ANSI version 1, ISO/ANSI/FIPS version 3, and ISO/ANSI version 4labels are industry standard labels. The BLKSIZE must be 18 to 2,048 bytes.

AUL: ANS and User LabelsAUL is identical to AL, except that installation-provided routines processuser data set labels.

Specifying Label TypesThe following examples illustrate ways to code the LABEL parameter tospecify labels.

//A DD UNIT=TAPE,LABEL=(,BLP)

[The system positions the tape to file one without checking the label.]

//B DD DSN=MYDATA,DISP=OLD,UNIT=TAPE,VOL=SER=000300,LABEL=2

[The system positions the tape to file two and assumes standardlabels.]

//C DD UNIT=TAPE,LABEL=(3,NL)

[The system positions the tape to file three. The tape must not havea label.]

//D DD DSN=IT,UNIT=TAPE,LABEL=(1,SL)//E DD DSN=IT,UNIT=TAPE

[D and E are equivalent since the LABEL parameters in D areassumed if you omit LABEL.]

12.2.3 IN/OUT: Input or Output Protection

Essential (in FORTRAN Only)

Coding IN protects the file from being opened for output, and OUT protectsit from being opened for input. The system abnormally terminates the stepif you open the data set incorrectly. The IN and OUT LABEL subparametersare almost exclusively used for FORTRAN programs. FORTRAN opens datasets for INOUT or OUTIN, depending on whether the first use of the data setis a READ or WRITE. Since this opens data sets for both output and input,the tape must be write-enabled even if the tape is only read, negating theprotection afforded by file protecting a tape. Likewise, operator interven-tion is required for reading data sets that have retention checks. CodingLABEL=(,,,IN) opens the data set for input only, allowing the tape to bewrite-protected and retention protected data sets to be read without opera-tor intervention.

//A DD LABEL=(2,SL,,IN),...

[The data set can only be read.]

MAGNETIC TAPES 227

12.3 DCB SUBPARAMETERS

Essential

Specify the usual DCB subparameters RECFM and LRECL as needed fortapes. Fixed, variable, and undefined record formats are all permitted. Themaximum block size is 32,760 bytes.

Rarely Used

The DEN subparameter is used only for tape reels, not cartridges, to specifya nonstandard tape density. You rarely need to write the DEN because thedefault is the highest density for the tape drive, which you should alwayswant. The following list gives the various values of DEN:

DEN 9-track density (bpi)2 8003 1,6004 6,250

DEN is required only if you want to write a tape at the lower density ona dual-density tape drive. (Higher density stores more data on the tape andis more reliable.) The system ignores DEN for input—it reads the tape labelto determine the density. If you are writing the first file of a tape with stan-dard labels and the tape label is of a different density, the system willrewrite the label to agree with the density of the data set you are writing.

12.4 USING TAPES

Essential

The system needs to know the following things to write a tape:

RECFM—Record format. It is usually F or FB (fixed length or fixed-length blocked), V or VB (variable length or variable-lengthblocked), or U (Undefined).

LRECL—Logical record length. This is in bytes.

BLKSIZE—Block size. This is in bytes. The system assumes an opti-mum value for this if you don’t specify it.

type—The label type. SL is the usual, while BLP and NL are occasion-ally used.

file—The relative file number.


For a labeled tape, all these except the file number are stored in the dataset label on the tape itself. Here is a typical DD statement to write a noncat-aloged data set onto tape in which the volume serial number was preas-signed:

//OUT DD DSN=TEST,DISP=(NEW,KEEP),// UNIT=TAPE,VOL=SER=970216,// RECFM=FB,LRECL=80

Here is the same thing for a cataloged data set in which the operatorsassign a tape to the job.

//OUT DD DSN=A1000.TEST.DATA,DISP=(NEW,CATLG),// UNIT=TAPE,RECFM=FB,LRECL=80

A single data set can be stored across several tape volumes so that anunlimited amount of information can actually be stored. Several data setscan be stored on a single tape volume by separating them with tape marks.The following example writes onto file three of a tape. This requires thatfiles one and two already exist on the tape, and is illustrated in Figure 12.6.

//INFILE DD DSN=PAYROLL,DISP=(NEW,KEEP),// UNIT=TAPE,VOL=SER=004435,LABEL=3

If you rewrite any file, all subsequent files on that volume aredestroyed. Thus, if a tape contains three files and you rewrite the secondfile, the first file is unchanged, but the third file is destroyed.

Tapes may be rewritten as many times, and any old data on a tape iserased as the tape is written. You update tapes by reading the old master fileand applying the transactions to produce a new tape. You get an automaticbackup by keeping the old tape and the transactions.

Tape makes excellent long-term storage because a volume of tape is inex-pensive and can contain a great deal of information in a small storage space.Tapes may be faster or slower than direct-access storage devices dependingon the particular device. Tapes must be mounted, by either the hardware oran operator, so this may increase the turnaround time of the job.

MAGNETIC TAPES 229

FIGURE 12.6 Writing onto a tape.��Tape no. Header File 1

You startwriting here

TM Header T

MTrailer TM

TM File 2 Trailer T

MTM

TM

When tape is mounted, the system positions it to the load point. Someprogramming languages also have a REWIND command to rewind the tape.This also positions it to the load point as illustrated in Figure 12.7.

A disposition of NEW in a DD statement for a tape data set positions thetape to the start of a file. A disposition of MOD positions the tape to thebeginning (if the data set doesn’t already exist on tape) or the end of a tapefile (if it already exists). Figure 12.8 shows this for a labeled tape. Note thatyou can only extend a data set on tape if you pass or catalog it. This isbecause a specific volume reference (VOL=SER=volume) with MOD causesMOD to act as if OLD were coded. You can code VOL=SER=SCRTCH withMOD to make a nonspecific volume request.

A disposition of KEEP rewinds the tape to the load point and unloadsit. A disposition of PASS rewinds the tape to the start of the data set andkeeps the tape mounted. Coding VOL=(,RETAIN,..) also keeps the tapemounted between job steps. Minimize operator intervention by not unload-ing tapes between job steps if they are used again within the job. (If youPASS a data set, you don’t need to code RETAIN.)

To create a data set on tape, always code the DSN and DISP parametersexcept in those rare circumstances when it is apparent that they are notrequired. For example, DSN is not required for temporary data sets. CodeUNIT unless you code STORCLAS. You need VOL if you want a specificvolume and the data set is not cataloged. Code DCB subparameters asneeded. RECFM and LRECL are the most common. You need LABEL unlessthe data set is on the first file of a standard-labeled tape. DEN is requiredonly if you have dual-density tape drives and don’t want to write the tapeat the higher density.

To access an old data set on tape, code DSN and DISP. If the data set isnot cataloged or passed, code UNIT and VOL. Code LABEL as needed. Thesystem can obtain DCB information from the data set label only if the tapehas standard labels. If the data set is not cataloged or passed or is not on thefirst file, LABEL must give the file number. The following example showsseveral uses of tapes.

//STEP1 EXEC PGM=ENA//A DD UNIT=TAPE

[This places a scratch data set on file one of a standard-labeled tape.]


FIGURE 12.7 Rewinding a tape.��Volume

serial no.Headerrecord

Firstfile

If you werepositioned here

TM

Headerrecord

TM

Trailerrecord

TM

TM

Secondfile

Trailerrecord

TM

TM

TM

REWIND wouldposition you

back here

//B DD DSN=SALARY,DISP=(NEW,PASS),// UNIT=TAPE,VOL=SER=000250,LABEL=(2,BLP),DEN=3

[This creates a data set on file two of an unlabeled tape and passesit. The system writes the tape at 1,600 bpi.]

//C DD DSN=A1000.TENURE.DATA,DISP=(NEW,CATLG),// UNIT=TAPE,VOL=(,RETAIN,SER=000451),LABEL=2

[This creates a data set on file two of a tape and catalogs it. The tapeis kept mounted at the end of the step.]

//STEP2 EXEC PGM=DIA//D DD DSN=*.STEP1.B,DISP=(MOD,KEEP),// LABEL=(2,BLP)

[This retrieves the data set on the 1,600-bpi tape. Note that DEN=3is not needed to read the tape.]

//E DD DSN=A1000.TENURE.DATA,DISP=OLD

[This retrieves the cataloged data set on tape.]

12.5 COMPRESSING DATA ON TAPE

Sometimes Used

You can compact data sets on tape cartridges, not on tape reels, if yourinstallation has established a data class for this. You specify compaction bycoding the DCB subparameter TRTCH=COMP to compress the data on tapeby roughly a factor of three:

//TAPEOUT DD DSN=A0000.TEST.DATA,DISP=(NEW,CATLG),// STORCLAS=COMPTAPE,// LABEL=(1,SL),TRTCH=COMP,

The data set does not need to be SMS-managed, but the STORCLAS you request must allow compaction. The default may or may not be

MAGNETIC TAPES 231

FIGURE 12.8 DISP=MOD for a labeled tape.

��Volumeserial no.

Headerrecord

Firstfile

NEW positions hereDISP=(NEW,KEEP)

MOD positions hereDISP=(MOD,KEEP)

TM

Headerrecord

TM

Trailerrecord

TM

TM

Secondfile

Trailerrecord

TM

TM

TM

TRTCH=COMP. Code TRTCH=NOCOMP for no compaction. You specifycompaction only for file one of a tape. The system ignores compactionrequests for files other than one and sets them to the compaction of file one.ISO/ANSI/FIPS tapes cannot be compacted.

The system automatically uncompacts the data set when it reads it, soyou need to specify compaction only when writing. Compaction not onlyreduces the required storage by a factor of roughly three, it reduces the I/Otime by the same amount.

12.6 MULTIVOLUME TAPE DATA SETS

Sometimes Used

You can extend data sets that are too large to be contained on one tape vol-ume onto another volume, up to a maximum of 255 volumes. Tape car-tridges have such high capacity that multivolume tapes are rather unusualtoday. The VOL parameter may request specific volumes or a maximumnumber of nonspecific volumes. A maximum of five nonspecific volumes isdefault. The UNIT parameter can mount volumes in parallel or defermounting until the volumes are needed, but you should never need to doparallel mounting. You defer mounting so as not to monopolize the tapeunits, especially if volume processing is slow. It also saves the operatorshaving to mount a tape that might not be opened by the job. If there aremore volumes than tape units, you must defer mounting.

Use a disposition of DISP=(MOD,CATLG) when extending multivolumecataloged data sets, even if the data set is already cataloged. CATLG recordsnew volume serial numbers in the catalog as you extend the data set.

Volume switching during writing occurs when the end-of-volumemarker is reached on tape volumes. During reading, volume switchingoccurs when an end of volume is encountered on tape. The following exam-ple shows the creation, extension, and retrieval of multivolume tape datasets.

//STEP1 EXEC PGM=CREATE//A DD DSN=A1000.MULTI.DATA,DISP=(NEW,CATLG),// UNIT=TAPE,VOL=SER=(000100,000200)

[We create a tape data set on volumes 100 and 200 and record all thevolume serial numbers in the catalog.]

//STEP2 EXEC PGM=EXTEND//C DD DSN=A1000.MULTI.DATA,DISP=(MOD,CATLG),// UNIT=(,,DEFER),VOL=(,,,7)

[If more volumes are required, the operator must assign and mountthem. The system enters any new volume serial numbers into thecatalog. The data set can be stored on as many as seven tapes.]


//STEP3 EXEC PGM=RETRIEVE//E DD DSN=A1000.MULTI.DATA,DISP=OLD,UNIT=(,,DEFER)

[The volumes are mounted one at a time as required.]

12.7 READING TAPES FROM ANOTHER INSTALLATION

Sometimes Used

If someone sends you a tape from another installation, you may have prob-lems getting your system to accept it. If the tape is labeled, it is unlikely thatthe volume serial will be acceptable at your installation. Consequently, it iscommon to write unlabeled tapes when sending them to another installa-tion. Assuming your system allows you to code BLP, you can use it to readan unlabeled tape.

If the tape is labeled, you cannot rewrite the label to conform to thestandards at your installation. If you rewrote the label, you would destroythe first file on the tape. You may be able to hand the tape to the operatorand have him mount it for you. However, the software security of your oper-ating system may reject the tape. Often the only way to read a labeled tapethat does not conform to your installation’s standards is to read it as BLP.(You can’t read it as NL because the system will detect that there is a labeland fail the job.) When you read a tape as BLP, you must supply the RECFM,LRECL, and BLKSIZE in the JCL because the system cannot obtain thisinformation from the tape label. Be sure to ask for this information if some-one sends you a tape. But what if your system does not permit you to codeBLP? In this case, you need to talk to the systems programmers.

Assuming you are able to read the tape, you will not be able to catalogit because the volume serial number won’t match the standards at yourinstallation. It might even be the same as that of an existing tape. If you planto use the tape more than once, copy the files on it to one of your installa-tion’s tapes to eliminate all of the preceding problems.

12.8 ISO/ANSI/FIPS VERSION 3 AND ISO/ANSI VERSION 4 LABELS

Sometimes Used

ISO/ANSI/FIPS version 3 and ISO/ANSI version 4 tape labels are industry-standard labels for ASCII data, and you indicate them by codingLABEL=AL. (Version 4 has the same characters as version 3, plus the under-score.) When you read such a tape, z/OS converts the ASCII characters toEBCDIC and does the reverse when writing. (Note that you can also codeOPTCD=Q for any data set to cause the system to convert ASCII to EBCDICwhile reading and the reverse while writing.)

MAGNETIC TAPES 233

Code RECFM=F for fixed-length records, but for variable-lengthrecords, code RECFM=D. Code the usual RECFM=S for spanned records. Ifthe records contain ASCII device control characters, code RECFM=A. Forvariable-length spanned records processed by the Data Facility Product,you must code LRECL=nK, where n is 1 to 16383 and indicates multiples of1,024 bytes. You can code DISP=MOD only if the installation has providedfor it.

12.8.1 The ACCODE Parameter

ISO/ANSI/FIPS Version 3 and ISO/ANSI Version 4 tapes can be protectedagainst change by an access code. Your installation will tell you the accesscodes to use. For an output data set, specify the access code with

//ddname DD ACCODE=code,...

12.8.2 ASCII to EBCDIC Conversion

All ASCII characters convert to the corresponding EBCDIC charactersexcept those shown in Table 12.5.

12.8.3 EBCDIC to ASCII Conversion Problems

All EBCDIC characters convert to the corresponding ASCII charactersexcept the following as shown in Table 12.6.

In addition, the EBCDIC hex codes 05, 06, 08–0A, 14–15, 17, 1B, 20–24,28–2C, 30–31, 33, 38–3B, 3E–3F, 41–49, 62–69, 70–78, 80, 8A–90, 9A–A0,


TABLE 12.5 ASCII to EBCDIC Conversion Problems

ASCII Character Hex code Converted to EBCDIC Hex code

! X’21’ | X’4F’[ X’5B’ ¢ X’4A’] X’5D’ ! X’5A’^ X’5E’ ¬ X’5F’

X’80’–X’FF’ SUB X’3F’

TABLE 12.6 EBCDIC to ASCII Conversion Problems

EBCDIC character Hex code Converted to ASCII Hex code

¢ X’4A’ [ X’5B’¬ X’5F’ ^ X’5E’

TEAMFLY

Team-Fly®

AA–BF, CA–CF, DA–DF, E1, EA–EF, and FA–FF all convert to the ASCIIRNL character (X’1A’).

12.8.4 Converting to and from Coded Character Set: CCSID

When reading or writing ISO/ANSI Version 4 tapes with AL or ALU labels,you can convert from and to specified coded character sets (such as GreekASCII or Spanish EBCDIC) by coding the CCSID=id parameter. If reading,the conversion is to the CCSID on the JOB or EXEC statement from theCCSID on the DD statement. If writing, the conversion is the opposite—from the CCSID on the JOB or EXEC to the CCSID on the DD statement. (ACCSID on an EXEC overrides any CCSID on the JOB statement.) If CCSID isnot coded, the conversion is from/to 7-bit ASCII. Your installation can pro-vide the list of coded character set identifiers. The following converts datafrom USA PC-data to USA EBCDIC data.

//STEP1 EXEC PGM=READ,CCSID=437//INPUT DD DSN=PC.DATA,DISP=OLD,LABEL=(1,AL),CCSID=437

CCSID=65535 is a special value to suppress conversion.

EXERCISES

1. Modify the //GO.OUT DD statement in the program from Chapter 5 towrite the lines onto a tape file. Write them as file one of a standardlabeled tape.

2. The tape generated by exercise 1 now contains three physical files, avolume label and header label, the data set, and a trailer label. Modifythe JCL in the program from Chapter 5 to read the tape records and printthem. Read each of the three physical files on the tape. (They all have80-byte records, and so the program can read them.) Verify that the vol-ume label, header label, data set, and trailer label contain the correctinformation.

MAGNETIC TAPES 235

CHAPTER 13

JES2 AND JES3

Essential

13.1 JOB ENTRY SUBSYSTEMS

IBM provides two Job Entry Subsystems (JES2 or JES3) for submitting jobscontrolled by JCL in a multicomputer network. JES2 and JES3 provide sim-ilar functions for installations with several computers that are linked to-gether. They schedule jobs through a central input queue and route theoutput to the appropriate devices. You submit jobs through your terminal toa remote computer and either hold your output to view it at the terminal orroute it to a printer.

Although JES2 and JES3 provide similar functions, they are separateproducts with different statements. JES2 is by far the most widely used. Itallows each processor (computer) to operate independently, selecting jobsas needed from the central queue. By contrast, JES3 exercises central con-trol over several processors and assigns jobs to them from the central jobqueue.

13.2 JES2

In JES2, the computers are connected in a network, each computer termeda node. JES2 is a decentralized system, in which each computer runs inde-pendently, selecting jobs from the single job queue as it sees fit. Usuallyeach computer has its own computer operators. JES2 statements direct thejob to a computer in a network or route the output to some destination. Youcan specify some of the same parameters with JES2 that you specify throughyour JCL.

Two statements, the JES command and /*PRIORITY, are placed in frontof the JOB statement. Place the remaining statements following the JOBstatement. You cannot place JES2 statements in a cataloged procedure. JES2

236

statements have the same rules for coding as JCL statements with theseexceptions:

� Code /* in columns 1 to 2 rather than //.� You cannot code comments on JES2 statements. Use a JCL comment

statement instead.� Except for the /*OUTPUT statement, no JES2 statements may be con-

tinued. Write multiple statements instead.� If you write the same parameter more than once on a JES2 statement,

JES2 uses the last instance.

The following are the JES2 statements. In addition, the /*OUTPUT state-ment is described in Chapter 9, the /*PRIORITY, /*MESSAGE, /*XMIT, and/*$command statements are described in Chapter 16, and the /*NOTIFYstatement is described in Chapter 22.

13.2.1 The /*ROUTE Statement

The /*ROUTE statement routes a job or its output to a specific node.

XEQPRINT

/*ROUTE node

XEQ routes the job for execution.

PRINT routes the output for printing.

node is the destination.

//RT452216 JOB (45992),'SMITH',CLASS=A/*ROUTE XEQ HOUSTON/*ROUTE PRINT LA

13.2.2 The /*XEQ Statement

The /*XEQ statement routes the job to a node for execution. It is equivalent(and redundant) to the /*ROUTE XEQ statement. You code it as

/*XEQ node

13.2.3 The /*NETACCT Statement

The /*NETACCT statement specifies an account number for the job. Yourinstallation will tell you what is required.

JES2 AND JES3 237

/*NETACCT account-number

For example:

//RT452216 JOB (45992),'SMITH',CLASS=A/*NETACCT 22385

13.2.4 The /*JOBPARM Statement

The /*JOBPARM statement specifies processing and output parameters foran entire job. You write it as

/*JOBPARM option,option,...,option

The BURST, BYTES, COPIES, FORMS, LINECT, LINES, and PAGESoptions apply to printed output and are described in Chapter 9. The remain-ing options are as follows:

NOLOG suppresses printing of the JES2 job log.

PROCLIB=ddname names the ddname of the cataloged procedure li-brary to use for this job.

RESTART=YES restarts the job from the start of the job if restart is nec-essary and if the job cannot be restarted from a step or checkpoint.RESTART=NO, the default, requests that the system take no specialaction.

ROOM=room specifies one to four alphanumeric characters to identifythe room or location where the job output is to be sent.

SYSAFF=(cccc,cccc, . . . ,cccc) specifies one to seven systems (cccc) thatcan process this job, depending on the installation. Code cccc asANY to request any system.

TIME=minutes estimates the job execution time in minutes (0 to 9999).The estimate is clock time, not CPU time. Perhaps the only use forthis is if your job might go into the wait state for some reason andyou want it canceled.

Here is an example of the JOBPARM statement:

//RT452216 JOB (45992),'SMITH',CLASS=A/*JOBPARM PROCLIB=TEMPLIB,ROOM=322,TIME=40

13.2.5 The /*SETUP Statement

The /*SETUP statement lists tape volumes that must be mounted for a job./*SETUP displays an operator message and places the job on hold until the


operator mounts the tapes and releases the job. The volume must begin incolumn 11 or beyond, and you cannot extend into column 72.

1 2 3 4 512345678901234567890123456789012345678901234567890 <== Columns/*SETUP volume,volume,...,volume

For example:

/*SETUP 002215,003716

13.2.6 The /*SIGNON and /*SIGNOFF Statements

The /*SIGNON statement begins a remote job session by connecting the jobto a workstation. The RMTs must begin in column 16, password1 begins incolumn 25, any new-password begins in column 35, and password2 beginsin column 73.

RMTsNnRsdest-name

/*SIGNON password1 new-password password2

1 2 3 4 7 81234567890123456789012345678901234567890 ... ...34567890 <== Columns

The s is the identification number of the remote station.

The n is the node.

The password1 is the password for a nondedicated connection andbegins in column 25.

The new-password assigns a new password (1 to 8 characters) to the work-station and begins in column 35.

The password2 is the password for a remote job entry station that issigning on and begins in column 73.

The /*SIGNOFF statement terminates a remote job and disconnects thestation.

/*SIGNOFF

13.3 JES3

In JES3, several computers are connected closely together, and all thescheduling is done by a single computer, termed the global processor. All

JES2 AND JES3 239

the jobs are placed in a single job queue. The global processor then sched-ules the jobs, either to itself or to the other computers connected to it(termed the local processors). The global and local processors together aretermed the main processors. JES3 is a highly centralized network, with onecomputer and one group of operators controlling all the other computers.

The global processor and the computers connected to it are not really anetwork. They are more like a single computer with multiple CPUs. JES3 canalso operate in a network that consists of separate computers operating rela-tively independently, connected by some form of communications. A node ina JES3 network consists of the main processors—the global processor and itslocal processors. The network can also contain other JES3 and JES2 nodes.

JES3 also lets you submit several jobs in a group and make the execu-tion of a job depend on the successful or unsuccessful execution of otherjobs. This gives you some of the flexibility for jobs that the COND parame-ter gives to job steps.

JES3 consists of a set of statements that specify information on how torun the job. JES3 statements look like JCL statements and have the samerules for coding. They begin with //* in columns 1 to 3 and the commandbegins in column 4:

//*command options

All JES3 statements except the command statement are placed follow-ing the JOB statement. You cannot place JES3 statements in a cataloged procedure. To continue a JES3 statement, end the statement after a comma,code a //* on the next line, and continue in column 4.

//*MAIN SYSTEM=(CPU1,CPU4),EXPDTCHK=YES,//*HOLD=YES

Many of the parameters specified on the JES3 statements are the sameas those written on JCL statements. You have the option of specifying thesame information either on the JCL statements or on JES3 statements. Param-eters specified on JES3 statements take precedence over the same param-eters on the JCL statements.

The following are the JES3 statements. In addition, the //*OPERATOR,//*XMIT, and //*COMMAND statements are described in Chapter 16 andthe //*FORMAT statement is described in Chapter 9.

13.3.1 The //*NETACCT Statement

The //*NETACCT statement specifies an account number for the job at anode in the network. It may also supply information to identify you andyour location. Each installation specifies what is required for this parame-


ter. The //*NETACCT statement must immediately follow the first JOBstatement and precede any //*ROUTE statement.

//*NETACCT option,option,...,option

The options are as follows:

PNAME=name gives your name, 1 to 20 characters.

ACCT=account gives the account number.

USERID=userid gives your userid.

DEPT=department gives your department, 1 to 8 characters.

BLDG=building gives your building address, 1 to 8 characters.

ROOM=room gives your room number, 1 to 8 characters.

//RT452216 JOB (45992),'SMITH',CLASS=A//*NETACCT PNAME=SMITH,ACCT=22385

13.3.2 The //*ROUTE XEQ Statement

The //*ROUTE XEQ statement specifies the destination of the job for exe-cution if you do not want JES3 to decide where to run the job.

//*ROUTE XEQ node//*ROUTE XEQ node.vmuserid

[The .vmuserid is needed only if the job is sent to a VM node.]

Place the //*ROUTE statement after any JOB statement for the submit-ting location and after any //*NETACCT statement. Any JOB statement forthe destination location must follow the //*ROUTE statement.

//jobname JOB ... <== For submitting location.//*NETACCT PNAME=SMITH,ACCT=22385//*ROUTE XEQ DALLAS//jobname JOB ... <== For destination location.

13.3.3 The //*MAIN Statement

The //*MAIN statement specifies the processor requirements for the job.

//*MAIN option,option,...,option

The following options specify the processor on which the job is to berun and where the output is to be sent.

SYSTEM=main-name names the processor (computer) on which torun this job. Special names are ANY for any system (the default),

JES2 AND JES3 241

JGLOBAL for running on the global processor only, and JLOCAL forlocal processors only. To specify several main processors on whichthe job can run, list the names in parentheses. If you want to list theprocessors on which the job is not to run, place a slash (/) in frontof the names.//*MAIN SYSTEM=(CPU1,CPU4) (Job could run on CPU1 or CPU4.)//*MAIN SYSTEM=/(CPU1,CPU4) (Job could run on any processor

except CPU1 or CPU4.)

ACMAIN=main-name identifies the job with a specific processordespite the job not being submitted from or processed by it. Thisallows the SYSOUT data sets to be sent to a computer in the networkother than the one the job was submitted from or processed on.

ORG=name treats the job as if it were submitted from this group ornode name despite being submitted from somewhere else. Thisdirects the output back to this device rather than to the device fromwhich the job was submitted.

SPART=partition-name names a JES3 spool partition that is to allocatespool space for the job.

USER=userid identifies the job with a TSO user despite that user notsubmitting the job, so that the TSO user can inquire about the job’sstatus, cancel the job, or retrieve the output.

The next set of options tell how the job is to be run.

CLASS=class specifies the job class and overrides the CLASS parame-ter on the JOB statement.

DEADLINE=(time,type) tells when the job is to be scheduled. The timecan be minutesM (0M–1440M) or hoursH (0H–24H) to indicate howsoon to start the job. Or you can write a time of day as four digitsbased on a 24-hour clock. DEADLINE=(1300,A) requests the job to bestarted by 1 p.m. The type is a single character defined by the instal-lation that allows the job to run. You can also add a date: DEAD-LINE=(time,type,mm/dd/yyyy), where mm is the month (01–12), ddis the day (01–31), and yyyy is the year. Finally, you can specify thecycle on which to run the job as DEADLINE=(time,type,when,cycle).The cycle can be WEEKLY, MONTHLY, or YEARLY. The when spec-ifies when in the cycle to run the job. For WEEKLY, when is the dayof the week (1–7, 1 is Sunday). For MONTHLY, when is the day of themonth (1–31, with 29, 30, and 31 treated as the last day of themonth). For YEARLY, when is the day of year (1–366).

EXPDTCHK=NO requests the expiration date to not be checked forscratch SL output tapes. EXPDTCHK=YES is the default to check forexpiration dates.


JES2 AND JES3 243

FAILURE=RESTART or CANCEL or HOLD or PRINT specifies therecovery in case the job fails. RESTART restarts the job, CANCELcancels it, HOLD holds the job for operator intervention, and PRINTprints the job and holds it for restart.

FETCH=ALL or NONE or SETUP or ddname or /ddname overrides theinstallation-defined FETCH parameter and determines which fetchmessages are issued to the operator for disk and tape mounts.� ALL issues fetch messages for all mountable volumes requested

in the JCL.� NONE issues no fetch messages.� SETUP gives fetch messages for only the volumes in DD state-

ments specified in the SETUP parameter on this MAIN statement.� You can also code one or more ddnames of volumes requested in

the DD statements to fetch. Enclose the ddnames in parenthesesand separate them with commas. To instead specify the ddnames ofthe data sets not to fetch, precede the ddnames with a slash (/). Youcan’t continue the FETCH statement. If you need more ddnamesthan will fit on one line, just write another FETCH statement.

HOLD=YES holds the job until the operator releases it and is the sameas the TYPRUN=HOLD parameter on the JOB statement. HOLD=NOis the default and does not hold the job.

JOURNAL=YES or NO tells whether to keep a job journal for the job.

RINGCHK=YES or NO tells whether to check for the write-enable ringfor tape mounts; RINGCHK=YES is default.

SETUP=setup specifies the availability of I/O devices before the job isreleased for execution. The setup options are as follows:� JOB specifies that all devices for the entire job must be available.� HWS specifies that the minimum tape and disk devices required

by any one step are sufficient to start the job.� THWS specifies that the minimum tape devices for a step are suf-

ficient to start the job, but all the disk devices for all steps mustbe present.

� DHWS is the opposite of THWS.� ddname is the fully qualified ddname of a DD statement whose

device must be available. Name several ddnames by enclosingthem in parentheses and separating them with commas.

� /ddname specifies that all ddnames except this one must be avail-able for the job to be initiated. Name several ddnames by enclos-ing them in parentheses and separating them with commas.

Here is an example of the //*MAIN statement.

//RT452216 JOB (45992),'SMITH',CLASS=A//*MAIN SYSTEM=ZIP,SETUP=(DDA,DDB)

The next set of options give estimates for the job.

IORATE=MED or HIGH or LOW specifies the I/O to CPU ratio for thejob to assist in job scheduling.

LREGION=nK estimates the largest region needed by the job in kilo-bytes (1 to 1024) and is used to improve scheduling.

THWSSEP=IGNORE or PREFER or REQUIRE tells whether scratchtapes and specific tape volumes can be mounted on the same tapedrives in determining the tape drives required by the job. IGNOREmeans they can be allocated on the same tape drive; PREFER meansthat it is preferable that they be mounted on different tape drives;REQUIRE means they must be placed on separate tape drives.

TRKGRPS=(primary,secondary) specifies the number of primary andsecondary track groups to assign to the job for spooling. A trackgroup represents a number of spool space units.

There are also BYTES, LINES, and PAGES options for printed outputdescribed in Chapter 9. Here is another example of the //*MAIN statement.

//*MAIN SYSTEM=ZIP,LINES=(8000,W)

The last set of options give information about the cataloged procedurelibraries.

PROC=xx identifies any private library to search for the cataloged pro-cedures. The xx are the last two characters of the ddname of any procedurelibrary to search in place of the standard procedure libraries. Write ST oromit the PROC parameter to search only the standard procedure libraries.

UPDATE=data-set-name names the data set containing the procedurelibrary updated by this run.

13.3.4 The //*NET Statement

The //*NET statement specifies dependencies between jobs. The generalform is

//*NET ID=net-id,option,option,...,option

ID=net-id gives a one- to eight-character name that identifies this jobwith a collection of dependent jobs. All the jobs with the same net-id are apart of the collection, termed a job net.


TEAMFLY

Team-Fly®

JES2 AND JES3 245


NHOLD=n gives the number (0 to 32767) of previous jobs that mustcomplete before releasing this job. NHOLD=0, the default, allowsthe job to be scheduled immediately.

RELEASE=(jobname,jobname, . . . ,jobname) gives the names (1 to 50)of jobs in the job net that are to follow this job.

NETREL=(net-id,jobname) specifies that this job is a predecessor to ajob in another job net. The jobname names the following job in theother net.

NORMAL=D or F or R requests the action to take for this job when aprevious job terminates normally. D decrements the NHOLD countby one. The job is scheduled to be run only if the count goes to zero.F flushes the job and any jobs following it from the system. Any out-put generated by previous jobs is printed. R (default) retains the jobwithout decrementing the NHOLD count. The job and any followingjobs are suspended until the preceding job is resubmitted or theoperator decreases the NHOLD count.

ABNORMAL=D or F or R is the same as NORMAL, except it specifiesthe action when a previous job abnormally terminates. The defaultis D.

ABCMP=KEEP or NOKP specifies the action to take if the job abnor-mally terminates. KEEP keeps the job net in the system until eitherthe job is resubmitted and completes normally or the operator forcesthe net from the system. NOKP, the default, purges the job net if thejob that abnormally terminated has not been resubmitted by thetime the other jobs in the job net have completed and there are nomissing following jobs or subnets.

DEVPOOL=ANY or NET specifies the devices to be dedicated to thisdependent job net. Write it for the first job of the job net—it isignored if it is not on the first job. ANY, the default, lets jobs in thenet use any device. NET means that jobs can use only devices dedicated to the net. You can also code (ANY,device-name,n) or(ALL,device-name,n) to list as many device-names and the numberof named devices. A device-name is either a UNIT name of a DDstatement or an installation-defined name.

DEVRELSE=YES releases all devices dedicated to the dependent jobcontrol net at the end of this job. You can write DEVRELSE on morethan one job in the net and the devices are released by the first com-pleting job with DEVRELSE=YES. The default is DEVRELSE=NO,which releases the devices when the last job in the net terminates.

NRCMP=HOLD or NOHO or FLSH indicates that this job has completednormally and is being resubmitted. The job does not enter the jobnet and all references to the job net are erased. HOLD, the default,holds the job to be released by the operator. NOHO schedules thejob as system resources become available. FLSH flushes the job fromthe system without executing it.

OPHOLD=YES holds the job until released by the operator. NO is thedefault to not hold it.

RELSCHCT=n tells when to begin the setup for the job, that is, when tobegin allocating devices. Setup begins when the NHOLD countbecomes less than or equal to n (0 to 32767). RELSCHCT=0 is thedefault and means that there is no early setup of dependent jobs.

Here is an example:

//RT452216 JOB (45992),'SMITH',CLASS=A//*NET ID=TEST,NHOLD=3,DEVPOOL=(ANY,3390,2)

13.3.5 The //*DATASET and //*ENDDATASET Statements

The //*DATASET statement specifies the beginning of an additional inputstream data set that can contain JCL or data. You write it as

//*DATASET DDNAME=ddname,option,option,...,option

DDNAME=ddname assigns a ddname to the spooled data set entered inthe input stream following this statement. This should match the ddnameof a DD statement in the job that is to read the data set. If necessary, theddname should be qualified by the stepname and any cataloged procedurename. The options are as follows:

CLASS=NO, MSGCLASS, or class specifies the class to use for JES3 jobprocessing. NO means that the system is to assign a default class.CLASS=MSGCLASS gives the data set the MSGCLASS of the job.CLASS=class specifies a particular class.

J=NO or YES specifies how the data set is terminated. NO, the default,terminates the data set when a JOB statement is encountered. YESterminates the data set when an ENDDATASET statement isencountered. Code YES if the data set contains a JOB statement.

//RT452216 JOB (45992),'SMITH',CLASS=A//STEP1 EXEC COB2UCLG//READIT DD ...//*DATASET DDNAME=STEP1.COB2UCLG.READIT,J=YES[Lines of data]//*ENDDATASET


The //*ENDDATASET statement marks the end of a JES3 input streamthat was begun by a //*DATASET statement.

13.3.6 The //*PROCESS and //*ENDPROCESS Statements

The //*PROCESS statement lets you bypass the standard JES3 job flow. Youmight want to do this to check only JCL errors or bypass output processingso that the operator can check whether the job reaches completion. You canwrite a single processing option on a //*PROCESS statement. Request sev-eral processing options by writing several //*PROCESS statements. Markthe end with an //*ENDPROCESS statement. There are many processes andmany have optional parameters.

//*PROCESS process//*PROCESS process//*ENDPROCESS

13.3.7 The /*SIGNON, /*SIGNOFF Statements

The /*SIGNON statement begins a remote job session by connecting the jobto a workstation. Note that it begins with a single slash.

1 2 3 4 512345678901234567890123456789012345678901234567890 <== Columns/*SIGNON work AR password1 password2new-password

The work names the remote workstation and begins in column 16.

A, coded in column 22, indicates an automatic reader.

R, coded in column 23, suspends printing if the printer is not ready.

The password1 is the password for the remote job processing line andbegins in column 25.

The password2 is the password for the remote job workstation and beginsin column 35.

The new-password assigns a new password (1 to 8 characters) to theworkstation and begins in column 44.

The /*SIGNOFF statement ends a remote job stream processing session.

/*SIGNOFF

JES2 AND JES3 247

CHAPTER 14

CATALOGED AND INSTREAMPROCEDURES

Essential

Coding the numerous JCL statements required for a job is difficult andprone to error. Consequently, JCL statements that have potential use by sev-eral users are usually placed in a cataloged procedure, letting you invokethe JCL in the cataloged procedure with a single EXEC statement. Catalogedprocedures are stored as members in partitioned data sets established bythe installation.

Instream procedures are identical to cataloged procedures except thatyou place them right along with the job in the input stream, immediatelyfollowing the JOB statement, rather than as members of partitioned datasets. You might use instream procedures to test JCL before placing it in acataloged procedure. You might also use them as your own procedurelibrary without the bother of placing them in a partitioned data set.

You can change procedures in two ways: by overriding them (EXEC, DD,and OUTPUT statements only) or by assigning values to symbolic parame-ters on either the EXEC or SET statement. For example, a procedure to copya disk data set onto tape might use a symbolic parameter for the disk data setname and the tape volume serial number. These values would likely changeeach time you invoke the procedure, and it would be nice to make it easy tochange the JCL. Symbolic parameters do this. You give a value a symbolicname, you can set default values within the procedure, and you can supplya different value when you code the EXEC statement invoking the proce-dure. Symbolic parameters provide a means of generalizing JCL; another rea-son for creating procedures. The INCLUDE statement provides furthergenerality when placed in a cataloged procedure by naming a member of apartitioned data set containing statements to copy in where the INCLUDEstatement is placed.

Procedures may be composed of multiple job steps containing any ofthe following JCL statements:

248

EXEC statement

IF/THEN/ELSE/ENDIF statement construct

DD statement. (But not DD * or DD DATA)

OUTPUT statement

SET statement

INCLUDE statement

Comments statements (//*)

No other JCL statements and no JES statements are allowed within aprocedure. You can code symbolic parameters on any of the statements butoverride only EXEC, DD, and OUTPUT statements.

14.1 MODIFYING STATEMENTS IN CATALOGED PROCEDURES

Essential

Of the JCL statements in a procedure, you can override or nullify parame-ters on the EXEC, DD, and OUTPUT statements. You can add only DD andOUTPUT statements. To simplify overriding procedures, the convention isto place statements in the following order within a procedure:

� EXEC statements first. This isn’t a convention—it is required.� The OUTPUT statements that apply to the step follow. This is also

mandatory if the OUTPUT statements affect the following DD state-ments.

� Then the DD statements that apply to the step follow.

14.1.2 Overriding the EXEC Statement

You can add parameters to any step of a cataloged or instream procedure byappending the stepname to the keyword on the EXEC statement that in-vokes the procedure. (You cannot override the PGM parameter.) In the fol-lowing example, the system adds the REGION=1048K parameter to the GOstep of the COB2UCLG procedure. Any REGION parameter already codedon the GO step in the procedure is overridden. Other parameters on that orother steps in the procedure are not affected.

// EXEC COB2UCLG,REGION.GO=1048K

You can code each parameter as many times as there are steps in theprocedure as long as you code the parameters in the order the steps appearwithin the procedure. If the COB2UCLG procedure had a COB2 step, a

CATALOGED AND INSTREAM PROCEDURES 249

LKED step, and a GO step, in that order, you might code the following. Youdon’t have to place the parameters for each step on a separate continuationline, but it does make it easier to see which parameters apply to a particu-lar step.

// EXEC COB2UCLG,PARM.COB2=DECK,TIME.COB2=6,// TIME.LKED=7,// TIME.GO=4

The following is invalid because the LKED step precedes the GO step:

// EXEC COB2UCLG,TIME.GO=24,TIME.LKED=7

The order in which you code parameters for the same step doesn’t mat-ter. You could code the following:

// EXEC COB2UCLG,PARM.COB2=DECK,TIME.COB2=6

Or

// EXEC COB2UCLG,TIME.COB2=6,PARM.COB2=DECK

If you omit the stepname, the general rule is that the parameter appliesto all steps of a procedure. In the following, the system overrides all stepsin the procedure with REGION=1080K.

// EXEC COB2UCLG,REGION=1080K

This general rule has the following exceptions:

� The system applies the PARM parameter to only the first step in theprocedure and nullifies any PARM parameters on subsequent stepswithin the procedure. In the following example, the system overridesthe PARM in the first step with PARM=MAP and nullifies any PARMparameter on the following EXEC statements within the procedure.// EXEC COB2UCLG,PARM=MAP

� The TIME parameter sets the total time for the entire job, nullifyingthose on individual job steps. Here, the system overrides each stepwith TIME=10 and sets the total for the job to 10 minutes, just as ifTIME=10 had been coded on the JOB statement.// EXEC COB2UCLG,TIME=10

� If you omit the stepname for all the other parameters, the systemapplies them to all the job steps individually. You must code param-eters with a stepname appended before any parameters without step-names:// EXEC COB2UCLG,TIME.COB2=6,PARM.COB2=DECK,REGION=1080K



� To nullify an existing parameter within a step in a procedure, codethe keyword and appended stepname with just an equal sign: Here, thesystem nullifies the TIME parameter in the COB2 step, overrides thePARM parameters in both the COB2 and LKED steps, and applies the COND parameter to all steps.// EXEC COB2UCLG,TIME.COB2=,PARM.COB2=MAP,PARM.LKED=DECK,COND=(4,LT)

14.1.2 Overriding and Adding DD and OUTPUT Statements

To override the parameters on individual DD and OUTPUT statements,append the procedure stepname (procstep) to the ddname on the overridingDD statement. The general form for overriding or adding DD and OUTPUTstatements is

// EXEC procedure//procstep.ddname OUTPUT parameter,parameter,…,parameter//procstep.ddname DD parameter,parameter,…,parameter

To illustrate this, suppose that a procedure named RUN consists of thefollowing statements:

//RUN PROC//STEP1 EXEC PGM=ONE//INPUT DD DSN=PIANO,DISP=OLD//SCRATCH DD DSN=&&TEMP,DISP=(NEW,PASS),// UNIT=SYSDA,SPACE=(0,(2000,200)),// DCB=(RECFM=FB,LRECL=100)//STEP2 EXEC PGM=TWO//OUT DD DUMMY,SYSOUT=A

To invoke the RUN procedure and override the INPUT DD statement,you could code the following:

// EXEC RUN//STEP1.INPUT DD DSN=GUITAR,UNIT=TEMP,VOL=SER=PACK16

[INPUT matches a ddname in STEP1 so that parameters are over-ridden if they appear on the overridden statement or added if theydon’t appear. DSN is overridden, DISP is unchanged, and UNIT andVOL are added.]

For the job execution, the system then treats the //INPUT DD statementas if you had coded it as

//INPUT DD DSN=GUITAR,DISP=OLD,UNIT=TEMP,VOL=SER=PACK16

The changes made to a procedure by overriding DD and OUTPUT state-ments are effective only for the run and do not change the procedure per-


manently. The order in which you override the parameters doesn’t matter.The preceding results would be the same if you coded

// EXEC RUN//STEP1.INPUT DD VOL=SER=PACK16,UNIT=TEMP,DSN=GUITAR

Nor does the order in which you override the statements within a stepmatter. You could override both the INPUT and SCRATCH data sets bycoding

// EXEC RUN//STEP1.INPUT DD VOL=SER=PACK16,UNIT=TEMP,DSN=GUITAR//STEP1.SCRATCH DD SPACE=(0,(4000,400))

Or

// EXEC RUN//STEP1.SCRATCH DD SPACE=(0,(4000,400))//STEP1.INPUT DD VOL=SER=PACK16,UNIT=TEMP,DSN=GUITAR

The order in which you override steps does matter. Override them inthe order they appear in the procedure. The system adds DD and OUTPUTstatements if the stepname doesn’t match one in the procedure. To add a DDstatement named JUNK, you could code

// EXEC RUN//STEP1.JUNK DD DSN=&&STUFF,DISP=(NEW,PASS),// UNIT=SYSDA,SPACE=(0,(1000,100))

Since JUNK doesn’t match a name in STEP1 of the procedure, the sys-tem adds it and now treats the procedure as if it had been coded as

//STEP1 EXEC PGM=ONE//INPUT DD DSN=PIANO,DISP=OLD//SCRATCH DD DSN=&&TEMP,DISP=(NEW,PASS),// UNIT=SYSDA,SPACE=(0,(2000,200)),// DCB=(RECFM=FB,LRECL=100)//JUNK DD DSN=&&STUFF,DISP=(NEW,PASS),// UNIT=SYSDA,SPACE=(0,(1000,100))//STEP2 EXEC PGM=TWO//OUT DD DUMMY,SYSOUT=A

Code any overriding statement before any added statement within thestep.

// EXEC RUN//STEP1.INPUT DD VOL=SER=PACK16,UNIT=TEMP,DSN=GUITAR//STEP1.JUNK DD DSN=&&STUFF,DISP=(NEW,PASS),// UNIT=SYSDA,SPACE=(0,(1000,100))

The system overrides the INPUT DD statement in STEP1 and adds theJUNK DD statement. Suppose you had coded this:

// EXEC RUN//STEP1.JUNK DD DSN=&&STUFF,DISP=(NEW,PASS),// UNIT=SYSDA,SPACE=(0,(1000,100))//STEP1.INPUT DD VOL=SER=PACK16,UNIT=TEMP,DSN=GUITAR

Now the system adds the JUNK DD statement and ignores the INPUTDD statement. (It actually adds the INPUT DD statement when it can’t finda DD statement in the step to override after it adds JUNK. Now the step con-tains two DD statements named INPUT, and the system uses the first andignores the second.)

If the procedure has multiple steps, you must override or add DD andOUTPUT statements in the order of the steps.

// EXEC RUN//STEP1.INPUT DD DSN=GUITAR,UNIT=TEMP,VOL=SER=PACK16//STEP2.OUT DD DSN=PRINTIT

The system overrides the INPUT DD statement in STEP1 and the OUTDD statement in STEP2. The following is in error because the overridingstatements are in the wrong order:

// EXEC RUN//STEP2.OUT DD DSN=PRINTIT//STEP1.INPUT DD DSN=GUITAR,UNIT=TEMP,VOL=SER=PACK16

If you omit the procstep on the overriding DD or OUTPUT statement,the system places the statement following the last override or in the firststep if there is no last override. The next example shows this:

// EXEC RUN//STEP2.OUT DD DSN=PRINTIT//JUNK DD DSN=&&STUFF,DISP=(NEW,PASS),

[The system adds JUNK to STEP2.]

// EXEC RUN//JUNK DD DSN=&&STUFF,DISP=(NEW,PASS),

[The system adds JUNK to STEP1.]

When you override a DD or OUTPUT statement, the system overridesall, except the DCB parameter, in their entirety. For the DCB parameter, youmust override the individual subparameters rather than the entire DCBparameter.


// EXEC RUN//STEP1.SCRATCH DD LRECL=50,VOL=SER=PACK07

The system interprets the SCRATCH DD statement as

//SCRATCH DD DSN=&&TEMP,DISP=(NEW,PASS),// UNIT=SYSDA,SPACE=(0,(2000,200)),// DCB=(RECFM=FB,LRECL=50),VOL=SER=PACK07

Nullify parameters by coding the keyword followed by an equal sign butomit the value. To nullify the entire DCB parameter, nullify each subpara-meter. (DCB= cannot be coded to nullify the entire DCB parameter.) To nul-lify a dummy data set (DUMMY or DSN=NULLFILE), code a DSN parameteron the overriding DD statement. If the DD statement does not require a dataset name, code just DSN=.

// EXEC RUN//STEP1.SCRATCH DD DSN=,RECFM=F,LRECL=//STEP2.OUT DD DSN=

The system treats SCRATCH and OUT as

//SCRATCH DD DISP=(NEW,PASS),// UNIT=SYSDA,SPACE=(0,(2000,200)),// DCB=(RECFM=F)//OUT DD SYSOUT=A

If you override a DD or OUTPUT statement with parameters mutuallyexclusive from ones on the overridden statement, such as SYSOUT andDISP, the system nullifies the conflicting parameters on the overridden state-ment. Do not attempt to nullify them on the overriding statement. In the nextexample, SYSOUT=A conflicts with the parameters on the OUT DD state-ment in the procedure, the conflicting parameters are nullified, and the sys-tem treats OUT as if it were coded with only SYSOUT=A.

// EXEC RUN//STEP1.OUT DD SYSOUT=A

You must override concatenated DD statements within a procedureindividually in the same order they appear in the procedure. The followingprocedure contains a concatenated data set.

//WALK PROC//STEP1 EXEC PGM=PRIMARY//WORK DD DSN=LIBA,DISP=SHR// DD DSN=LIBB,DISP=SHR


TEAMFLY

Team-Fly®

To leave a particular DD statement unchanged, leave the operand fieldblank in the overriding DD statement.

// EXEC WALK//STEP1.WORK DD DSN=LIBRARY,DISP=SHR// DD// DD DSN=LIBC,DISP=SHR

The system overrides the first DD, leaves the second unchanged, andconcatenates the third data set. It then interprets the WORK DD statement as

//WORK DD DSN=LIBRARY,DISP=SHR// DD DSN=LIBB,DISP=SHR// DD DSN=LIBC,DISP=SHR

If you override a single DD statement, the other concatenated DD state-ments are undisturbed.

// EXEC WALK//STEP1.WORK DD DSN=LIBRARY,DISP=SHR

The system interprets the procedure as

//STEP1 EXEC PGM=PRIMARY//WORK DD DSN=LIBRARY,DISP=SHR// DD DSN=LIBB,DISP=SHR

14.2 CATALOGED PROCEDURES

Essential

Cataloged procedures are normally kept in a system library namedSYS1.PROCLIB, but other libraries may be concatenated to it. The systemsearches the libraries in the order you concatenate them. The IBM-suppliedutility program IEBUPDTE described in Chapter 19 adds and replaces pro-cedures in the partitioned data set. You can also place cataloged proceduresin your own partitioned data set and then name it with a JCLLIB statement.

14.2.1 Coding Cataloged Procedures

Sometimes Used

A cataloged procedure begins with a PROC statement and is followed by theJCL statements that constitute the procedure. You code the PROC statement as

//procedure-name PROC symbolic-parameters comments


The procedure-name must be unique within the procedure library. Theprocedure-name is one to eight alphanumeric (A to Z, 0 to 9) or national(@$#) characters. The first character must be alphabetic (A to Z) or national.The following JCL illustrates a cataloged procedure.

//ADDPROC PROC//GO EXEC PGM=IEBUPDTE//SYSPRINT DD SYSOUT=A//SYSUT1 DD DSN=SYS1.PROCLIB,DISP=OLD//SYSUT2 DD DSN=*.SYSUT1,DISP=OLD

This particular procedure executes the IEBUPDTE utility described inChapter 19 to add procedures to the SYS1.PROCLIB library. To invoke theprocedure, you need to code only the following:

// EXEC ADDPROC//GO.SYSIN DD DATA[ADD and REPL statements followed by JCL statements as required.]/*

Often a program must read lines of data that seldom change from run torun. The following example illustrates such a program.

//GO EXEC PGM=ONE//SYSIN DD *[Lines of data]/*

You might wish to store the preceding step as a cataloged procedure,and since the lines of data seldom change, you might like to make them apart of the cataloged procedure as well. The procedure library contains 80-column lines of data, and you can add any data, not just JCL, as a member.A //SYSIN DD statement can then point to the member containing the linesof data. The following example shows how the two members would appearif added to SYS1.PROCLIB. Member RUN:

//RUN PROC//GO EXEC PGM=ONE//SYSIN DD DSN=SYS1.PROCLIB(CARDS),DISP=OLD

Member CARDS:

[Lines of data]

The procedure is named RUN and the lines of data are stored in a mem-ber named CARDS. (You could have placed the lines in some other data setif desired.) You can now execute the program with a single EXEC statement.

// EXEC RUN



14.2.2 The JCLLIB Statement

Sometimes Used

The JCLLIB statement allows you to use cataloged procedures stored in your own library as a member of a partitioned data set. (It is also used with theINCLUDE statement described later in this chapter.) The partitioned data setmust be cataloged and have DCB attributes of LRECL=80,RECFM=FB. Thenyou name the library with a JCLLIB statement coded as

// JCLLIB ORDER=(data-set-name,data-set-name,...,data-set-name)

There can be only one JCLLIB per job placed following the JOB state-ment but before the first EXEC statement. You list 1 to 15 libraries in theorder you want them searched for the procedures. In this example, the sys-tem searches A0000.LIB1.TEST and A0000.LIB1.PROD in that order for theDOIT procedure. Note that the system does not search SYS1.PROCLIB. Ifyou want it searched, too, you must name it in the list.

//RT452216 JOB (45992),'SMITH',CLASS=A// JCLLIB ORDER=(A0000.LIB1.TEST,A0000.LIB1.PROD)//STEP1 EXEC DOIT

The JES2/*JOBPARM statement described in Chapter 13 has a PROCLIBparameter that names the library containing the cataloged proce-dure library to use for the job if it is not the normal SYS1.PROCLIB. Like-wise, the JES3//*MAIN statement has a PROC parameter to do the samething.

14.3 INSTREAM PROCEDURES

Sometimes Used

Begin instream procedures with a PROC statement and terminate them witha PEND statement coded as follows. (You can also code PEND for a cata-loged procedure, but it isn’t required.)

//optional-name PEND comments

Place the instream procedure following the JOB statement but beforethe first EXEC statement of the job. You can include as many as 15 instreamprocedures in a single job. Then you can invoke each instream procedureseveral times within the job. The following sample illustrates an instreamprocedure named RUN.

//RT452216 JOB (45992),'SMITH',CLASS=A//RUN PROC//GO EXEC PGM=ONE This is the//SYSOUT DD SYSOUT=A � instream procedure// PEND//STEP1 EXEC RUN <== This executes the instream procedure.

14.4 SYMBOLIC PARAMETERS

Sometimes Used

You can modify procedures for execution by overriding parameters onEXEC, DD, and OUTPUT statements. This is often inconvenient becauseyou must know the parameters that you can override, the stepnames withinthe procedure, the ddnames of the statements overridden, and the order ofthe statements. Symbolic parameters provide an alternative means of mod-ifying procedures for execution. They also allow you to change the otherJCL statements in a procedure that you can’t override. The following exam-ple illustrates symbolic parameters.

//RUN PROC PROGRAM=ONE,UNIT=SYSDA//GO EXEC PGM=&PROGRAM//A DD UNIT=&UNIT,SPACE=(TRK,20)

The ampersands preceding PROGRAM and UNIT mark them as sym-bolic parameters. The PROC statement can assign default values to sym-bolic parameters as shown. You can invoke the RUN procedure with an //EXEC RUN statement and the system interprets the procedure as

//GO EXEC PGM=ONE//A DD UNIT=SYSDA,SPACE=(TRK,20)

You can also assign values to symbolic parameters on the EXEC state-ment or on a SET statement. Any values coded on the EXEC or SET state-ments override the values on the PROC statement for the duration of therun. If you execute the step with

// EXEC RUN,UNIT=TEMP,PROGRAM=TWO

the system now interprets the procedure as

//GO EXEC PGM=TWO//A DD UNIT=TEMP,SPACE=(TRK,20)


14.4.1 Coding Symbolic Parameters

Sometimes Used

Create a symbolic parameter by selecting a name, one to seven alpha-numeric (A to Z, 0 to 9) or national (#@$) characters, the first of which mustbe alphabetic (A to Z) or national, and precede it with an ampersand (&).You can code symbolic parameters only in the operand field of JCL state-ments, not in the name or operation field.

//stepname EXEC PGM=program//ddname DD DSN=data-set-name, ...

↑ ↑ ↑——— Here.|————————

|——— But not here.

You cannot use keywords for the EXEC statement as symbolic parameternames, such as PGM, COND, and PARM. If you assign more than one valueto a symbolic parameter on a PROC or EXEC statement, the system uses thefirst.

//RUN PROC NAME=LIB1,NAME=LIB2//STEP1 EXEC PGM=ONE//A DD DSN=&NAME,...//STEP2 EXEC PGM=TWO//B DD DSN=&NAME,...

The system assigns each appearance of the symbolic parameter &NAMEin this procedure a default value of LIB1. If you did not use symbolic para-meters here, you would have to override each DD statement.

You can code symbolic parameters in any order on PROC or EXEC state-ments. If &NAME and &VOLS are symbolic parameters defined in a COBOLcompile, link-edit, and go procedure, you could code the following.

// EXEC COB2UCLG,NAME='SYS1.COB2LIB',// REGION.COB2=104K,VOLS=003345,COND.GO=EVEN

You can place a symbolic parameter within a field enclosed in apostro-phes, such as on the AMP and PATH DD parameters and the ACCT andPARM EXEC parameters. For example:

//STEP1 EXEC PGM=ONE,PARM='XX&DOIT/YYYYY'

The system recognizes &DOIT as a symbolic parameter only if youassign it a value on a PROC, EXEC, or SET statement. The & lets the systemrecognize the beginning of the symbolic, and you must follow it with somespecial character so that the system can tell where the name ends. If you


coded PARM=‘XX&DOITYYYYY’, the system would think that the sym-bolic parameter was named &DOITYYYYY, which is also in error becausethe name is more than eight characters. Although you can continue a fieldwithin apostrophes, you can’t break within a symbolic parameter within afield enclosed in apostrophes. The following would be in error:

Col 71//STEP1 EXEC PGM=ONE,… PARM='XX&DO// IT/YYYYY'

z/OS provides one built-in symbolic parameter: &SYSID. When youcode it within a procedure, the system replaces &SYSID with your userid,obtained either from the USER parameter on the JOB statement or theuserid with which your job was submitted. Here is an example:

//DD1 DD DSN=&SYSID..TEST.DATA,DISP=OLD

&SYSID is followed by two periods because of another rule. A periodmarks the end of a symbolic parameter but does not become part of theparameter. Since you want a period to follow the &SYSID, you must code asecond period. If your userid were A0000, the system would treat the state-ment as if you had coded

//DD1 DD DSN=A0000.TEST.DATA,DISP=OLD

14.4.2 Assigning Values to Symbolic Parameters

Essential

You can assign values to symbolic parameters on the PROC statement, onthe EXEC statement, or on a SET statement. The PROC and EXEC state-ments are described first. The general rules for assigning values apply to allstatements. Enclose a value in apostrophes if it contains the special charac-ters blank , . / ′ ) ( * & + − =. Code a legitimate apostrophe as two consecu-tive apostrophes.

//RUN PROC NAME='SYS1.PROCLIB',TAPE='2400-6'

Continue a PROC statement after a complete subparameter and itscomma. The following statement is in error.

//RUN PROC NAME='SYS1.,// PROCLIB',TAPE='2400-6

It should be coded as

//RUN PROC NAME='SYS1.PROCLIB',// TAPE='2400-6'


The value assigned to a symbolic parameter can be a maximum of 255characters. You can concatenate symbolic parameters with other symbolicparameters (PARM=&LEFT&RIGHT), with regular parameters (SPACE=&SPACE), or with portions of regular parameters such as SPACE=(TRK,&PRIMARY).

//RUN PROC VOLS=',3,4',NAME=A,IN='NEW,',OUT=KEEP� � �

//A DD VOL=SER=(2&VOLS),DSN=SYS1.&NAME,DISP=(&IN&OUT)

The system interprets the DD statement as

//A DD VOL=SER=(2,3,4),DSN=SYS1.A,DISP=(NEW,KEEP)

Nullify symbolic parameters by coding the keyword and equal signwithout a value, either on the PROC or EXEC statement.

//RUN PROC VOLS=,NAME=PROCLIB� � �

//A DD VOL=SER=(2&VOLS),DSN=SYS1.&NAME


//A DD VOL=SER=(2),DSN=SYS1.PROCLIB

The system does not remove a delimiter, such as a leading or trailingcomma, next to a symbolic parameter when you nullify the parameter.

//RUN PROC VOLS=� � �

//A DD VOL=SER=(2,&VOLS)

The system interprets the DD statement as follows, which contains asyntax error that fails the job.

//A DD VOL=SER=(2,)

To solve this problem, omit the comma preceding the symbolic param-eter and include the comma as part of the symbolic parameter. The follow-ing example corrects the previous error.

//RUN PROC VOLS=� � �

//A DD VOL=SER=(2&VOLS)

You could invoke the procedure with

// EXEC RUN,VOLS=',3'


The system now interprets the DD statement as

//A DD VOL=SER=(2,3)

If the symbolic parameter is followed by other alphanumeric or nationalcharacters, follow it with a period so that the system can recognize its end.(The period does not become a part of the parameter.) For example, if youcode DSN=A&DAY.1999 and assign &DAY a value of 365, the system treatsDSN as if you had coded DSN=A3651999.

If the symbolic parameter is followed by a special character blank,/′)(*&+−=, you don’t need to code the period. However, if you want the sym-bolic parameter actually followed by a period, you must code two periodsas shown here.

//RUN PROC TAPE=2400,NAME=SYS1� � �

//A DD UNIT=&TAPE-2,DSN=&NAME..P

The &NAME must be followed by a period, so you code two periods.The system interprets the DD statement as

//A DD UNIT=2400-2,DSN=SYS1.P

If you coded only DSN=&NAME.P, the system would interpret it asDSN=SYS1P.

Always separate any symbolic parameters used as positional parame-ters from any following parameters with a period rather than a comma. Thisway, if you nullify the positional parameter, a leading comma will notresult. The following example illustrates the correct way to code a posi-tional parameter as a symbolic parameter.

//RUN PROC TYPE='DUMMY,'//GO EXEC PGM=ONE//A DD &TYPE.DSN=THING


//A DD DUMMY,DSN=THING

Always give symbolic parameters a value on a PROC, EXEC, or SETstatement. Otherwise, the system considers it a JCL error. The one excep-tion to this is the DSN parameter. If you code DSN=&name and don’t assigna value, the system interprets &name to mean a temporary data set. In thenext example, the system considers &NAME to be a temporary data setname, not a symbolic parameter. The &DISPOSE is a symbolic parameter,but it is not assigned a value, resulting in a JCL error.


//WHATIF PROC//GO EXEC PGM=DOIT//INPUT DD DSN=&NAME,DISP=(OLD,&DISPOSE)

� � �

// EXEC WHATIF

Any symbolic parameter that you assign a value on a PROC, SET, orEXEC statement must appear as symbolic parameters in the procedure. Thefollowing procedure is in error because DISK does not appear as a symbolicparameter in the procedure.

//RUN PROC DISK=3390//GO EXEC PGM=ONE//A DD UNIT=3390,SPACE=(TRK,20)

You can correct this error by recoding the DD statement in the proce-dure.

//A DD UNIT=&DISK,SPACE=(TRK,20)

You can also correct it by overriding the UNIT parameter with a DDstatement.

// EXEC RUN//GO.A DD UNIT=&DISK

The preceding example shows that you can code symbolic parameterson overriding DD statements. You can also override DD statements contain-ing symbolic parameters if you are careful not to override a symbolic param-eter assigned a value. If the UNIT=&DISK correction is made to the previousprocedure, the following step is in error because &DISK is given a value onthe PROC statement but does not now appear in the procedure.

// EXEC RUN//GO.A DD UNIT=3390

14.4.3 The SET Statement

Sometimes Used

The SET statement provides another way of assigning values to symbolicparameters. You can include any number of SET statements in the JCL toassign values to symbolic parameters. The system assigns the values whenit encounters the SET statement, and they stay in effect until changed. Youcan place SET in procedures to assign default values rather than assigningdefault values on the PROC statement. You can also include them in the jobstream to assign values rather than assigning values on the EXEC statement.


You code the SET statement as follows:

// SET parameter=value,parameter=value,...

Code the assigned values the same as if they were coded on the PROCor EXEC. Here is one example:

//RUN PROC Same as: //RUN PROC TYPE='DUMMY'// SET TYPE='DUMMY' //GO EXEC PGM=ONE//GO EXEC PGM=ONE //A DD &TYPE.DSN=THING//A DD &TYPE.DSN=THING

And another example:

// SET TYPE= Same as: //STEP1 EXEC RUN,TYPE=//STEP1 EXEC RUN

The system assigns values as it encounters the statements. This meansthat a new SET statement changes the value of a previous SET statement, asdoes a later PROC or EXEC statement that assigns a value to the symbolicparameter. Likewise, a value set by a PROC statement is changed if a SETstatement appears within the procedure. You can place SET statementsanywhere following the JOB statement. Just make sure you place themwhere you want them to take effect. The SET statement is unconditionaland is not affected by the conditional execution of the IF/THEN/ELSE/ENDIF statement construct.

The SET statement can replace setting symbolic parameter values onboth the EXEC and PROC statements. In addition, it allows you to createsymbolic values in your JCL and assign them values without having to cre-ate a cataloged or instream procedure. This gives you considerable power inparameterizing your JCL streams.

14.4.4 Symbolic Parameters in the JCL Listing

Essential

When you execute a cataloged or instream procedure, the system lists allthe symbolic parameter substitution done within each step of the proce-dure. Suppose you executed the following procedure:

//RUN PROC PROGRAM=ONE,DISK=SYSDA//GO EXEC PGM=&PROGRAM//A DD UNIT=&DISK,SPACE=(TRK,20)

� � �

// EXEC RUN,PROGRAM=TWO//GO.A DD DISP=OLD


TEAMFLY

Team-Fly®


The following would be listed in your JCL:

STMT NO. MESSAGE4 IEF653I SUBSTITUTION JCL - PROGRAM=TWO5 IEF653I SUBSTITUTION JCL - UNIT=SYSDA

When you override a DD statement in a cataloged procedure, both theoverriding statement and the original statement are shown. The catalogedprocedure statement displays with an X/ in the first two columns.

//GO.A DD DISP=OLDX/A DD UNIT=&DISK,SPACE=(TRK,20)

You don’t get a display of how the overridden step actually appears tothe system. The //A DD statement will be treated as if it were written as

//A DD UNIT=SYSDA,SPACE=(TRK,20),DISP=OLD

14.4.5 Use of Symbolic Parameters

Essential

One final example should serve to show the usefulness of symbolic param-eters. The link-edit step usually contains a DD statement named SYSLIB todescribe the libraries that the linkage editor is to search for subroutines.You often concatenate SYSLIB to describe several subroutine libraries.

//LKED EXEC PGM=IEWL//SYSLIB DD DSN=SYS1.FORTLIB,DISP=SHR// DD DSN=SYS1.SSPLIB,DISP=SHR

The linkage editor searches both SYS1.FORTLIB and SYS1.SSPLIB tofind needed subroutines. Now suppose that the preceding LKED step is partof a FORTRAN compile, link-edit, and go procedure named FORTGCLG.You might wish to concatenate your own private library to SYSLIB.

// EXEC FORTGCLG� � �

//LKED.SYSLIB DD// DD// DD DSN=PRIVLIB,DISP=SHR

PRIVLIB is concatenated to SYS1.FORTLIB and SYS1.SSPLIB. Nowconsider what happens if the installation changes the FORTGCLG proce-dure by adding a subroutine library. SYSLIB might be changed to


//SYSLIB DD DSN=SYS1.NEWFORT,DISP=SHR// DD DSN=SYS1.FORTLIB,DISP=SHR// DD DSN=SYS1.SSPLIB,DISP=SHR

The PRIVLIB DD statement now overrides the SYS1.SSPLIB DD state-ment. If the job uses subroutines in SYS1.SSPLIB, it will fail becauseSYS1.SSPLIB is no longer searched. The JCL must be changed by addinganother // DD statement. Symbolic parameters solve this problem verynicely. Suppose the procedure had originally been coded to allow the userto specify a private library as a symbolic parameter.

//FORTGCLG PROC LIB='SYS1.FORTLIB'� � �

//SYSLIB DD DSN=SYS1.FORTLIB,DISP=SHR// DD DSN=SYS1.SSPLIB,DISP=SHR// DD DSN=&LIB,DISP=SHR

You concatenate a private library by coding the following:

// EXEC FORTGCLG,LIB=PRIVLIB

Not only is this method simpler to code with less chance of error, but,equally important, the installation can freely add libraries to the //SYSLIBDD statement without disturbing anyone’s JCL.

14.4.6 Using a Text Editor Instead of Symbolic Parameters

Essential

A cataloged procedure is not the only way of generalizing JCL. A text editor,with its ability to make global changes, can also generalize it. Rather thanwriting a cataloged procedure, you can use a text editor to copy in JCL state-ments from a file to wherever they are needed. Then you can make globalchanges as necessary. For example, if the volume serial number changeseach time you run some JCL, you could store the JCL statements as a cata-loged procedure with the volume serial number as a symbolic parameter.Alternatively, you could just code the JCL with some unique characters forthe volume serial number, such as the following:

//INPUT DD DSN=X0225.TEST.DATA,DISP=(NEW,CATLG),// UNIT=TAPE,VOL=SER=XXXX

Then with a text editor, you could make a global change of XXXX towhatever volume serial number you wanted. This gives you much of theflexibility of symbolic parameters without the bother of writing a cataloged

procedure. Alternatively, you could also use the SET statement to do thesame thing:

// SET XXXX=002314� � �

//INPUT DD DSN=X0225.TEST.DATA,DISP=(NEW,CATLG),// UNIT=TAPE,VOL=SER=&XXXX

14.5 NESTING PROCEDURES AND THE INCLUDE STATEMENT

14.5.1 Nesting Procedures

Rarely Used

You can nest cataloged and instream procedures to a maximum of 15 levels.That is, one procedure can invoke another. If you nest procedures, makesure all the stepnames are unique so that you can override them correctly.Also, you can’t make a backward reference between nested procedures.

The main complexity in nesting procedures is in overriding statementsin them. You can override to only one level. However, a procedure itself cancontain override statements for other procedures that it invokes. The fol-lowing example illustrates this. Assume you have two procedures namedSTART and ENDUP, and that START invokes ENDUP.

Procedure START: Procedure ENDUP://START PROC //ENDUP PROC,OUTCLASS=C//START1 EXEC PGM=ONE // SET OUTCLASS=B//OUT DD SYSOUT=&OUTCLASS //ENDUP1 EXEC PGM=TWO//START2 EXEC ENDUP //OUT DD SYSOUT=&OUTCLASS//OUT.ENDUP1 DD SYSOUT=&OUTCLASS,// COPIES=2

Each procedure has a symbolic parameter named &OUTCLASS. If youinvoke the START procedure as follows:

//STEP1 EXEC START,OUTCLASS=A

the JCL appears as follows to the system:

//START1 EXEC PGM=ONE//OUT DD SYSOUT=A//ENDUP1 EXEC PGM=TWO//OUT DD SYSOUT=B,COPIES=2

[The SET in the ENDUP PROC overrides the value set by the EXECstatement.]

When you assign symbolic parameter values on an EXEC statement, theyoverride all default values assigned on the PROC statements at all levels. SET,


when encountered, also sets the value for all levels of a nested procedure. Ifthere were no SET statement in the preceding ENDUP procedure, the systemwould interpret the OUT DD statement in the ENDUP1 step as SYSOUT=Abecause the value set on the EXEC overrides the value set on the PROC.

You can override the OUT DD statement in START because it is onlyone level down, but not the OUT DD statement in ENDUP.

Suppose that you need an additional DD statement with a ddname of INin both START and ENDUP. You can override to only one level. To supply the//IN DD statement to ENDUP, you must code the override in the START pro-cedure. To add the DD statement to START, you can override it in the jobstream. First, you must modify START to override ENDUP: Procedure START:

//START PROC//START1 EXEC PGM=ONE//OUT DD SYSOUT=&OUTCLASS//START2 EXEC ENDUP//ENDUP1.IN DD DSN=A0000.TEST.DATA,DISP=SHR

Then you add the DD statement to START by overriding in the jobstream:

// SET OUTCLASS=A//STEP1 EXEC START//START1.IN DD DSN=A0000.PROD.DATA,DISP=SHR

The system will see the JCL as if it were coded as

//START1 EXEC PGM=ONE//OUT DD SYSOUT=A//IN DD DSN=A0000.PROD.DATA,DISP=SHR//ENDUP1 EXEC PGM=TWO//OUT DD SYSOUT=B//IN DD DSN=A0000.TEST.DATA,DISP=SHR

14.5.2 The INCLUDE Statement

Sometimes Used

You can copy in JCL stored as a member of a partitioned data set using theJCLLIB statement to name the partitioned data set and by placing INCLUDEstatements in the JCL where you want the member copied. INCLUDE worksvery much as if you used a text editor to copy in the JCL where you want it.Place the INCLUDE statement in the input stream, in a cataloged procedure,or an instream procedure. Code the INCLUDE statement as follows, namingthe member you want copied in:

// INCLUDE MEMBER=member


Unless the partitioned data set containing the member is SYS1.PRO-CLIB or an installation-provided library, you must name the partitioneddata set with a JCLLIB statement. The same JCLLIB statement can name pro-cedure libraries to search, libraries containing members to include, or both.The partitioned data set must be cataloged and have DCB attributes ofLRECL=80,RECFM=FB.

In the input stream, you can place the INCLUDE statement anywherefollowing the JOB and any JCLLIB statements. You can also place INCLUDEin a member that is itself included, nesting INCLUDE groups to 15 levels.The INCLUDE member cannot contain JOB, PROC/PEND, JCLLIB, DD * orDD DATA, or JES statements. Here is an example:

Member START of PDS A0000.MEMBER.LIB:

//STEPA1 EXEC PGM=ONE//SYSPRINT DD SYSOUT=&OUTTYPE//OUT DD DSN=&DATASET,DISP=OLD

You could then execute the following job:

//RT452216 JOB (45992),'SMITH',CLASS=A// JCLLIB ORDER=(A0000.MEMBER.LIB)// SET DATASET=A0000.TEST.DATA,OUTTYPE=B//STEP1 EXEC PGM=IEFBR14//A DD DSN=&DATASET,DISP=(NEW,CATLG),// UNIT=SYSDA,AVGREC=U,SPACE=(255,(2000,200)),// RECFM=VB,LRECL=255// INCLUDE MEMBER=START//STEP3 EXEC PGM=PRINT//IN DD DSN=&DATASET,DISP=(OLD,DELETE)

The system executes the job steps as if the JCL were coded as

//RT452216 JOB (45992),'SMITH',CLASS=A//STEP1 EXEC PGM=IEFBR14//A DD DSN=A0000.TEST.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,AVGREC=U,SPACE=(255,(2000,200)),// RECFM=VB,LRECL=255//STEPA1 EXEC PGM=ONE//SYSPRINT DD SYSOUT=B//OUT DD DSN=A0000.TEST.DATA,DISP=OLD//STEP3 EXEC PGM=PRINT//IN DD DSN=A0000.TEST.DATA,DISP=(OLD,DELETE)

If the INCLUDE statement or the member of the partitioned data setbeing included contains symbolic parameters, the system substitutes thevalues that are current when the symbolic parameters are encountered.


14.6 DDNAME: POSTPONING DEFINITION OF DATA SETS

Rarely Used

The DDNAME parameter is mainly used in cataloged procedures so that a//SYSIN DD statement doesn’t have to be coded with DCB subparameters.The need for DDNAME has largely disappeared. It may still appear in aninstallation’s cataloged procedures, but it is difficult to visualize a situationwhere it is needed. However, DDNAME does serve as documentation in theprocedure that a //SYSIN DD statement is needed.

The DDNAME=ddname parameter is placed in cataloged procedures forinput stream data sets to postpone the definition of the data set until a subse-quent DD statement is encountered with the specific ddname. DCB subpa-rameters BLKSIZE, BUFNO, and DIAGNS, along with the SMS LIKE andREFDD DD parameters may be coded with the DDNAME parameter; no otherparameters or subparameters are permitted. The following step requires bothBLKSIZE and BUFNO on the DD * statement.

//GO EXEC PGM=INITIAL//TWO DD *,BLKSIZE=80,BUFNO=3[Lines of data]/*

You can make this step a cataloged or instream procedure, but DD * andDATA statements cannot be placed in procedures, and so the //TWO DDstatement cannot be in the procedure. If the procedure were named JOG, thestep would consist of

// EXEC JOG//GO.TWO DD *,BLKSIZE=80,BUFNO=3[Lines of data]/*

The lengthy DCB parameter makes this procedure inconvenient. The//TWO DD statement, with BLKSIZE and BUFNO subparameters, can beincluded in the procedure by using the DDNAME parameter. The procedureis coded as

//JOG PROC//GO EXEC PGM=INITIAL//TWO DD DDNAME=TWO,BLKSIZE=80,BUFNO=3

The step is simplified to

// EXEC JOG//GO.TWO DD *[Lines of data]/*



BLKSIZE and BUFNO subparameters coded on the DD statement pointedto by DDNAME override any subparameters on the DDNAME statement.Since DDNAME can refer to any name, SYSIN can be used as well as TWO.

//TWO DD DDNAME=SYSIN,BLKSIZE=80,BUFNO=3

The step is now executed with BLKSIZE set to 4,080.

// EXEC JOG//GO.SYSIN DD *,BLKSIZE=4080[Lines of data]/*

DD statements with a ddname matching a DDNAME parameter in a cat-aloged procedure can precede or follow any overriding or added DD state-ments. A maximum of five DDNAME parameters, each referring to uniqueddnames, may be included in a single job step. Don’t use the same DDNAMEstatement more than once in a single job step. You cannot code DDNAME onJOBLIB, JOBCAT, or STEPCAT DD statements.

A referback parameter on subsequent DD statements must refer to thestatement containing the DDNAME parameter, not to the statement with thematching ddname, and must follow the statement with the matchingddname; otherwise, it refers to a dummy data set. The following exampleillustrates such an error for the JOG procedure.

//STEP1 EXEC JOG//GO.ALPHA DD DSN=WHAT,DISP=OLD,UNIT=TAPE,VOL=SER=000200//GO.BETA DD DSN=*.STEP1.GO.ALPHA,DISP=OLD

[BETA results in a dummy data set]

//GO.GAMMA DD DSN=*.STEP1.GO.TWO,DISP=OLD

[GAMMA is coded correctly.]

A DDNAME parameter for a concatenated data set must be coded first,before the other concatenated data sets.

//INPUT DD DDNAME=SYSIN// DD DSN=SYS1.PROCLIB(LIST),DISP=SHR

The following is in error because DDNAME is not coded first.

//INPUT DD DSN=SYS1.PROCLIB(LIST),DISP=SHR// DD DDNAME=LATER

The DD statement that matches a DDNAME statement cannot be con-catenated. The next example illustrates this. Assume that a cataloged pro-cedure contains the following DD statement.


//INPUT DD DDNAME=SYSIN

Next, SYSIN is defined as a concatenated data set, resulting in an error.

//GO.SYSIN DD DSN=ONE,DISP=SHR// DD DSN=TWO,DISP=SHR

To correct the error, override the //INPUT DD statement with the con-catenated data set.

//GO.INPUT DD DSN=ONE,DISP=SHR// DD DSN=TWO,DISP=SHR

14.7 EXAMPLE OF CATALOGED PROCEDURE

Essential

As an example of a cataloged procedure, suppose that you have a job withmany steps, each of which you may or may not want to execute each timethe job is run. You can implement this by using an instream procedure witha symbolic parameter for each step to control the step execution. Aninstream procedure is used because it lets you use a text editor to look at itand make changes which can then apply to many job steps.

You can take advantage of the COND parameter to control step executionby instructing the symbolic parameter to set a condition for the step to eitherbe executed or bypassed. If the step is to be executed, use COND=(5,LE). Ifthe step is not to be executed, use COND=(0,LE). Use the symbolic parame-ter to set the value to five or zero.

This example also illustrates the use of PARM information to turndebugging on and off. For the example, assume that each program canaccept a PARM value of YES or NO to turn debugging on or off within theprogram. This is also set in the instream procedure for all the programs.Here is the example:

//RT452216 JOB (45992),'SMITH',CLASS=A//******************************************************************//*DATE: 12/31/1999 **//* WEEKLY PRODUCTION RUN. **//* **//* FOLLOW THESE STEPS TO EXECUTE THE JOB **//* **//******************************************************************//* STEP1. THE JOB IS NORMALLY RUN WITH DEBUGGING TURNED OFF. **//* TO TURN DEBUGGING ON FOR A TEST RUN, CHANGE THE **//* FOLLOWING LINE FROM DEBUG=NO TO DEBUG=YES. **//WEEKLY PROC DEBUG=NO, <== CHANGE THIS IF NECESSARY. **//******************************************************************


//* STEP2. READ EACH OF THE FOLLOWING LINES AND MAKE THE **//* APPROPRIATE CHANGE IF YOU DON’T WANT A PARTICULAR **//* STEP IN THE PROCESS RUN. TO CAUSE A STEP TO NOT **//* RUN, JUST CHANGE THE JOBn=5 TO JOBn=0 ON THE **//* APPROPRIATE LINE. **//==================================================================//* JOB1 PRINTS THE AUDIT TRAIL. CHANGE JOB1=5 TO JOB1=0 ==//* IF YOU DON’T WANT IT PRODUCED. ==// JOB1=5, <== CHANGE 5 TO 0 IF YOU DON’T WANT IT.//==================================================================//* JOB2 PRINTS THE TRANSACTION REPORT. CHANGE JOB2=5 TO =//* JOB2 =0 IF YOU DON’T WANT IT PRODUCED. ==// JOB2=5, <== CHANGE 5 TO 0 IF YOU DON’T WANT IT.

� � �

//==================================================================//* JOB50 PRINTS THE SUMMARY REPORT. CHANGE JOB50=5 TO ==//* JOB50=1 IF YOU DON’T WANT IT PRODUCED. ==// JOB50=5 <== CHANGE 5 TO 0 IF YOU DON’T WANT IT.// PEND//******************************************************************//* STEP3. SUBMIT THE JOB. **//******************************************************************//* END OF JCL CHANGES. NOTHING BUT THE JCL ITSELF FROM HERE **//* ON, AND YOU DON’T NEED TO LOOK AT IT. IT’S REALLY DULL! **//******************************************************************//STEP0 EXEC PGM=IEFBR14//* THIS DUMMY STEP IS NEEDED BECAUSE THE SYSTEM DOES NOT CHECK **//* CONDITION CODES ON THE FIRST STEP OF A JOB. NOW THE FIRST **//* STEP BELOW IS NO LONGER THE FIRST STEP. **//******************************************************************//* STEP1 PRODUCES AN AUDIT TRAIL REPORT. **//******************************************************************//STEP1 EXEC PGM=CALC1,PARM=&DEBUG,COND=(&JOB1,LE)//SYSPRINT DD SYSOUT=A//INPUT DD DSN=RT452216.AUDIT.DATA,DISP=SHR//******************************************************************//* STEP2 PRODUCES A TRANSACTION REPORT. **//******************************************************************//STEP2 EXEC PGM=CALC2,PARM=&DEBUG,COND=(&JOB2,LE)//SYSPRINT DD SYSOUT=A//INPUT DD DSN=RT452216.TRANS.DATA,DISP=SHR

� � �

//******************************************************************//* STEP50 PRODUCES A SUMMARY REPORT. **//******************************************************************//STEP50 EXEC PGM=CALC50,PARM=&DEBUG,COND=(&JOB50,LE)//SYSPRINT DD SYSOUT=A//INPUT DD DSN=RT452216.SUMMARY.DATA,DISP=SHR//******************************************************************//* END OF PROGRAM **//******************************************************************

You could also make this into a cataloged procedure that would looklike this:

//******************************************************************//* DATE: 12/31/1999 **//* WEEKLY PRODUCTION RUN. **//******************************************************************//WEEKLY PROC DEBUG=NO, **//* TO TURN DEBUGGING ON FOR A TEST RUN, CHANGE DEBUG=NO TO **//* DEBUG=YES. **//* CHANGE JOBN=5 TO JOBN=0 IF A STEP IS TO NOT BE RUN. **// JOB1=5,JOB2=5,JOB3=5,...,JOB50=5//******************************************************************//* STEP1 PRODUCES AN AUDIT TRAIL REPORT. **//******************************************************************//STEP0 EXEC PGM=IEFBR14//STEP1 EXEC PGM=CALC1,PARM=&DEBUG,COND=(&JOB1,LE)//SYSPRINT DD SYSOUT=A//INPUT DD DSN=RT452216.AUDIT.DATA,DISP=SHR//******************************************************************//* STEP2 PRODUCES A TRANSACTION REPORT. **//******************************************************************//STEP2 EXEC PGM=CALC2,PARM=&DEBUG,COND=(&JOB2,LE)//SYSPRINT DD SYSOUT=A//INPUT DD DSN=RT452216.TRANS.DATA,DISP=SHR

� � �

//******************************************************************//* STEP50 PRODUCES A SUMMARY REPORT. **//******************************************************************//STEP50 EXEC PGM=CALC50,PARM=&DEBUG,COND=(&JOB50,LE)//SYSPRINT DD SYSOUT=A//INPUT DD DSN=RT452216.SUMMARY.DATA,DISP=SHR//******************************************************************//* END OF PROGRAM **//******************************************************************

To execute this as a cataloged procedure, write the following JCL.Notice that with a text editor to view the job and make JCL changes, theinstream procedure is perhaps easier to use because you can view the JCLand type over what you want changed.

//RT452216 JOB (45992),'SMITH',CLASS=A//* WE DON’T WANT STEP3 AND STEP 42.// EXEC WEEKLY,RUN3=0,RUN42=0

EXERCISES

Write an instream procedure to allocate some number of tracks on a speci-fied volume for a data set and write lines of data into the data set. The pro-cedure is to be invoked as follows:


TEAMFLY

Team-Fly®

// EXEC BLOPPO,PACK=volume,TRACKS=number//PGM.SYSIN DD *[Program from Chapter 5]/*//DATA.IN DD *[Lines of input]/*

The procedure is to have three steps. The first step executes theIEFBR14 null program to allocate the specified number of tracks on the vol-ume selected. The second and third steps are to be the language compileand go procedure. You will need one of your old run listings to determinethe JCL statement required for the procedure.


CHAPTER 15

GENERATION DATA GROUPS

Sometimes Used

A generation data group (GDG) is a group of chronologically or functionallyrelated data sets. They are processed periodically, often by adding a newgeneration, retaining previous generations, and perhaps discarding the old-est generation. For example, an income tax report is a generation data groupwith a new generation added each year, chronologically and functionallyrelated to previous years. When a new generation is added, the four previ-ous reports must be retained for legal purposes, but the fifth might be dis-carded.

Generation data groups are referred to by a name and a relative genera-tion number. For example, DSN=A1000.TAX.STATE(0) refers to the currenttax report and DSN=A1000.TAX.STATE(−1) to last year’s tax report. Youadd a new generation by calling it DSN=A1000.TAX.STATE(+1). A genera-tion data group is limited to 255 entries and must be cataloged.

The advantage of generation data groups is that all data sets have thesame name, the system keeps track of adding and deleting successive gen-erations, and you don’t need to change the JCL between runs. Generationdata groups are sequential and can reside on disk or tape. They can also beSMS-managed. You must catalog all generation data groups. You use gener-ation data groups like any other data set except for the relative generationnumber in the DSN parameter.

15.1 CREATING THE GENERATION DATA GROUP BASE ENTRY

The first step in creating a generation data group is to create an entry for itin the system catalog. You create this entry, called a generation data groupbase, with the IDCAMS DEFINE command described in Chapter 17. Thefollowing example creates a generation data group named A1000.TAX.STATE.

276

GENERATION DATA GROUPS 277

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *DEFINE GDG -(NAME(A1000.TAX.STATE) -

[Names the generation data group.]

LIMIT(5) -

[Maximum number of generations to keep (1 to 255).]

EMPTY -

[Optional. Tells the system to uncatalog all the generation data setswhen the limit is reached. Omit EMPTY or code NOEMPTY touncatalog only the oldest data set.]

OWNER(userid) -

[Optional. Gives the userid of the owner of the data set.]

SCRATCH -

[Optional. Scratches a data set when it is uncataloged. OmitSCRATCH or code NOSCRATCH to keep the data set when it is uncat-aloged.]

FOR(days) -

[Optional. Tells how many days to retain the data set. Alternatively,you can code TO(yyyymmdd) to specify the last date of retention.

)/*

15.2 CREATING THE MODEL DATA SET LABEL (NON-SMS-MANAGED DATA SETS ONLY)

There is one additional step needed before you can create an individual non-SMS-managed generation data set belonging to a generation data group. Thesystem needs an existing cataloged data set to serve as a model supplying theDCB parameters for the generation data group you want to create. You thenname this data set in the DCB parameter on the DD statement that creates thegeneration data group. (If SMS is active, you can also use LIKE or REFDD forthis.) The DCB attributes in the model data set label don’t have to be exactlywhat you need because you can override them.

//ddname DD DCB=(data-set-name,other-parameters),...//DDOUT DD DCB=(A1000.TAX.DATA,BLKSIZE=4096),...

[A1000.TAX.DATA must be cataloged. Regardless of its block size,the generation data set created by DDOUT will have BLKSIZE=4096.]


If there isn’t an existing cataloged data set that you can use, create adummy data set containing the required DCB parameters and catalog it. Ifyou don’t want to catalog the dummy data set, you must give it the samename as the generation data group and place it on the same volume as thecatalog containing the generation data group. (You can’t catalog it becausethe catalog already contains the same name for the generation data group.)Here is an example:

//STEP2 EXEC PGM=IEFBR14//BUILDIT DD DSN=A1000.TAX.STATE,DISP=(NEW,KEEP),// VOL=SER=PACK12,RECFM=FB,LRECL=80,// SPACE=(TRK,0),

[The model data set must be on the volume containing the catalogfor the generation data group base. You cannot catalog it herebecause it has the same name as the generation data group. DSORG,BLKSIZE, OPTCD, KEYLEN, and RKP could additionally have beencoded as DCB subparameters.]

15.3 CREATING A GENERATION DATA SET

You can now create a generation data set. The following step illustrateshow. Always code a disposition of CATLG when adding to a GDG.

//STEP1 EXEC PGM=CREATE

[Assume CREATE is a program which writes a data set.]

//GEN DD DSN=A1000.TAX.STATE(+1),DISP=(NEW,CATLG),// UNIT=SYSDA,SPACE=(0,2000)

[The system searches for the generation data group base entrynamed A1000.TAX.STATE. It then creates a generation data set andcatalogs it.]

Code DSN (and UNIT unless set by STORCLAS) for each new genera-tion data group. Use a disposition of CATLG for all new generation datasets. Code DCB subparameters on the DD statement as necessary to overrideor add parameters from the model data set label. For SMS-managed datasets, code DATACLAS and STORCLAS unless they default.

Generation (0) is always the current generation; (−1) is the precedinggeneration, (−2) the second generation, and so on. Generation (+1) indicatesa new generation and causes all generations to be pushed down one level atthe end of the job. You code the generation number following the genera-tion data group name:

DSN=data-set-name(generation-number)DSN=A000.TAX.STATE(+1)


You can code the current generation-number as (0), (+0), or (−0). Beginany number other than 0 with a + or −: (+1) or (−1) but not (1). The numbercan be no more than three digits: (+1), (+01), or (+001), but not (+0001).

Generations are referred to by the same number throughout the varioussteps in a job, and the system does not update the generation numbers untilthe job terminates.

//STEP1 EXEC PGM=ONE//INPUT DD DSN=A1000.TAX.STATE(0),DISP=OLD

[This is the current generation.]

//OUT DD DSN=A1000.TAX.STATE(+1),DISP=(NEW,CATLG),// UNIT=SYSDA,SPACE=(0,2000)

[This creates a new generation.]

//STEP2 EXEC PGM=TWO//NEXT DD DSN=A1000.TAX.STATE(+2),DISP=(NEW,CATLG),// UNIT=SYSDA,SPACE=(0,2000)

[This creates another new generation. You cannot refer to it as (+1)because the system does not update the generation numbers untilthe end of the job. At that time (+2) becomes (0), (+1) becomes (−1),and (0) becomes (−2).]

For an SMS-managed data set, the system temporarily catalogs the cur-rent generation when it creates it and gives it what is termed a deferred roll-in status. Then at the end of the step, the system deletes the oldest generationGDG if necessary and rolls in the new generation and makes an entry in theGDG base. If the step (or the system) ABENDs during processing, you mustlook at the output or list the GDG to see if the entry was added. You may need to delete the data set by its absolute name before rerunning to add it tothe GDG.

Within a generation data group, the entries are individual data sets. Anindividual entry is referred to by DSN=data-set-name(generation-number).The system actually saves the entry as DSN=data-set-name.GggggVnn. Thegggg is the absolute generation number, 0001 to 9999, and the nn is the ver-sion number, 00 to 99. The nn cannot be set through the JCL and defaults to00. For example, A1000.TAX.STATE(0) refers to the current generation, butif it was the tenth entry added to the generation data group, its actual dataset name would be A1000.TAX.STATE.G0010V00. You can refer to an entryin a DD statement by its relative generation number or by its actual data setname. Any listing of the data sets on a volume will show the data set withthe name A1000.TAX.STATE.G0010V00. If the current gggg is 9999 and youadd a generation, the generation number wraps around and the new gener-ation is 0001.

Although the entries within a generation data group need not have thesame DCB subparameters or even the same data set organization, they usu-ally will.

15.4 RETRIEVING GENERATION DATA SETS

To retrieve an individual generation data set, just give the data set name andthe relative generation wanted. Code a disposition of CATLG if you changethe data set in any way.

//ANYDD DD DSN=A1000.TAX.DATA(-1),DISP=(SHR,KEEP)

You can also retrieve all generations of a generation data group as if theywere all concatenated. Do this by omitting the generation number. The DDstatement refers to all generations, and the result is the same as if all theindividual data sets were concatenated.

//NEXT DD DSN=A1000.TAX.STATE,DISP=OLD

To retrieve all generation data sets this way, they must reside on thesame device type (disk or tape) and have the same DCB attributes.

15.5 LISTING GENERATION DATA GROUP CATALOG INFORMATION

The IDCAMS utility program lists all the catalog information for generationdata groups.

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *LISTCAT GDB -ENTRIES (data-set-name,data-set-name,...,data-set-name) ALL

[This lists all the catalog information for the data sets named.]

/*

15.6 DELETING GENERATION DATA GROUPS

The system normally deletes the individual generation data sets automati-cally according to the generation data group base specification as you addnew generations. You can also delete specific generation data sets by spec-ifying a disposition of DELETE. To delete the generation data group baseitself, use the IDCAMS utility as shown:


//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *DELETE data-group-name GDG

/*

You can also code PURGE and FORCE:

DELETE data-group-name GDG -PURGE -

[PURGE deletes the generation data set even if the retention date isunexpired. The default is NOPURGE.]

FORCE

[FORCE deletes a nonempty generation data group, along with all ofits data sets. The default is NOFORCE, causing DELETE to fail for anonempty generation data group.]


CHAPTER 16

MISCELLANEOUS JCL FEATURES

This chapter wraps up some remaining loose ends: checkpoint/restart,spanned records, data set protection, job priority, parameters for TSO, nullstatements, command statements, and data transmission.

16.1 CHECKPOINT/RESTART

Sometimes Used

z/OS allows programs that abnormally terminate, and even those that run tocompletion, to be restarted so that the entire job does not need to be rerunif an error occurs. There are two methods of restarting a job: restarting froma step (step restart) and restarting from a checkpoint (checkpoint restart).Step restart is simpler and doesn’t require the system to take a checkpoint.You simply code a RESTART parameter on the JOB statement to name thestep from which to restart and resubmit the job.

A restart can be automatic (the system restarts the job immediately) ordeferred (permitting you to examine your output and make the appropriatechanges before resubmitting the job). The restart, whether automatic ordeferred, is specified by the RD parameter on the EXEC statement. Auto-matic restart can occur only if the completion code accompanying the stepagrees with a set of eligible completion codes specified by the installation,and if the operator consents.

Checkpoints consist of a snapshot of a program’s status at selected pointsduring execution so that if the program terminates for some reason, the runcan be restarted from the last checkpoint rather than the beginning of therun. Checkpointing is only done because of the potential cost or time limita-tions of restarting a large job. The checkpoints themselves are expensive,complex, and require careful planning. You may not always be able to suc-cessfully restart the run—the problem may be caused by a program error thatoccurred before the checkpoint or by bad data. You use checkpoints more asa protection against hardware, operating-system, and operator errors than asprotection against application program errors.

282

MISCELLANEOUS JCL FEATURES 283

When the system takes a checkpoint, it notes the position of each opendata set, but does not copy it. This can make restarting from a checkpointdifficult. If you update a data set in place after the system takes the check-point, the system will not return the data set to its original status for therestart. If you subsequently delete a temporary data set, it will not be presentfor the restart.

The system can take several checkpoints during the execution of the jobstep. You must include a DD statement in the step to specify the data set tocontain the checkpoints. For sequential data sets, DISP=OLD rewrites eachnew checkpoint over the previous one. This is dangerous because if the jobterminates while the system is taking a checkpoint, there is no usable check-point. Coding DISP=MOD writes each new checkpoint beyond the end of theprevious and is safer. Alternatively, you can make the DD statement point toa partitioned data set on a direct-access volume. The system then adds eachcheckpoint as a member.

Checkpointing is supported in various languages as follows:

COBOL checkpoints are taken by the RERUN clause, which gives theddname of the checkpoint data set.

FORTRAN has no provision for checkpointing.

PL/I checkpoints are taken by CALL PLICKPT. The ddname of thecheckpoint data set is SYSCHK.

C/C++ has no facility for checkpointing.

Assembler Language takes checkpoints by executing the CHKPT macroinstruction. The DCB macro gives the ddname of the checkpointdata set.

JCL checkpoints are taken by coding the CHKPT parameter on a DDstatement. The ddname of the checkpoint data set is SYSCKEOV.

Sort/Merge checkpoints are taken by the CKPT parameter on a SORT/MERGE statement. The ddname of the checkpoint data set isSORTCKPT.

A unique name called the checkid, assigned by you or the system, isprinted on the operator’s console to identify each checkpoint as it occurs.The system assigns checkids in the form Cn. The n is a seven-digit number,starting with 0000001, identifying the successive checkpoints within thestep. To restart from a checkpoint, you must obtain the latest checkid fromthe operator or from your output listing.

16.1.1 CHKPT: Checkpoint at End of Volume

Coding CHKPT=EOV on a DD statement tells the system to take a check-point when the end of volume is reached on a sequential data set, either


input or output. You must also include a //SYSCKEOV DD statement in thejob step to contain the checkpoint. You code SYSCKEOV as a normal DDstatement with DSN, DISP, UNIT, and VOL parameters as needed. If youcode the LABEL parameter for a tape, also code SL: LABEL=(file,SL). Don’tcode DCB parameters on SYSCKEOV because the system sets them. A//SYSCKEOV DD statement, or any DD statement that is to contain a check-point, must describe a sequential or partitioned data set.

//STEP1 EXEC PGM=WRITEALL//OUT DD DSN=AFILE,DISP=(NEW,KEEP),// UNIT=TAPE,VOL=SER=(004001,004002),CHKPT=EOV

[The system takes a checkpoint when tape 004001 is completelywritten.]

//SYSCKEOV DD DSN=SAVEIT,DISP=(MOD,CATLG),UNIT=TAPE

[Code DISP=MOD so that each new checkpoint is written beyondthe previous checkpoint.]

16.1.2 RD: Restart Definition

The RD parameter on the JOB or EXEC statement controls automatic restartand may also suppress the CHKPT macro so that no checkpoints are taken.You code the parameter as RD=restart-conditions. Table 16.1 describes therestart conditions.

For example, RD=RNC permits automatic restart and suppresses theCHKPT macro. If you request automatic restart, the system restarts from thelast checkpoint in the step (checkpoint restart). If no checkpoint occurredbecause the CHKPT macro was suppressed or omitted, or the step termi-nated before the macro was executed, the system restarts at the start of thestep (step restart). If you omit the RD parameter, automatic restart occursonly if a CHKPT macro was executed.

Automatic restart requires that the system make special disposition ofdata sets. When the system automatically restarts a step, it deletes any datasets created in the step and keeps any data sets existing when it initiated thestep. If the system restarts from a checkpoint, it keeps all data sets currentlyused by the job. The system resets any CPU time limit for a step to its orig-inal value when it restarts the step.

TABLE 16.1 Restart Conditions

Restart conditions Automatic restart? Suppress CHKPT?

R—Restart Yes NoNC—No checkpoint No YesNR—No automatic restart No NoRNC—Restart and no checkpoint Yes Yes

TEAMFLY

Team-Fly®


RD on EXEC Statements//STEP1 EXEC PGM=CSMP,RD=R

[The system may automatically restart STEP1.]

// EXEC COB2UCLG,RD.LKED=NR,RD.GO=NC

[The system will not automatically restart the LKED step of theCOB2UCLG procedure. The system will not automatically restartthe GO step, and, in addition, it suppresses any CHKPT macros inthe step.]

// EXEC COB2UCLG,RD=RNC

[The system will automatically restart any step in the COB2UCLGprocedure. It suppresses any CHKPT macros in all the steps.]

RD on the JOB StatementWhen you code RD on the JOB statement, it applies to each step within thejob, and the system ignores any RD parameters on EXEC statements withinthe job.

//RT452216 JOB (45992),'SMITH',CLASS=A,RD=R

[The system will automatically restart all steps within the job.]

16.1.3 RESTART: Resubmit a Job for Restart

After examining the output from your job, you may elect to restart it laterfrom a checkpoint or the start of a job step. You can use a deferred restartregardless of the way the job terminates—abnormally or normally—andirrespective of whether automatic restart occurred. With deferred restartyou can correct or change data and fix program errors before resubmittingthe job. The RESTART parameter coded on the JOB statement requestsdeferred restart. In JES2 you can also code the RESTART parameter on the/*JOBPARM statement and in JES3 you can code the FAILURE parameteron the //*MAIN statement.

Step RestartA deferred restart from a job step begins execution at a specific step withinthe job, bypassing all preceding steps. You cannot process data sets passedfrom previous steps because the system does not execute the previoussteps. Nor can you use referbacks except in the DCB, DSN, and VOL param-eters. Any referback in the VOL must refer back to a DD statement giving thevolume serial number. Remember that new data sets created in the previousrun may still be in existence—attempts to recreate them may cause the jobto fail because of duplicate data sets on the same volume. You may have tomodify the JCL to circumvent these restrictions.


Always examine the output from the previous run to reconstruct condi-tions so that you can restart the step. Perhaps you cannot restart the step. If atemporary data set passed from a previous step is deleted, restart from the stepthat created the data set. If a passed data set was kept, identify the data setwith name, unit, volume, and label information. The system needs only thename and disposition if the data set was cataloged. For data sets residing ondirect-access volumes that were created and kept previously within the step,either change the disposition on the DD statement from NEW to OLD or MOD,or delete the data set before resubmitting the job, or define a new data set.

Simplify the restart by cataloging all data sets when you create them sothey can be referred to by name without having to specify the unit and vol-ume. Use conditional data set dispositions (the third parameter of DISP) todelete new data sets or catalog passed data sets. You can make any neces-sary changes to the JCL, such as requesting different devices or volumes,using different data sets, or modifying data

RESTART=stepname restarts the job at the stepname given.//RT452216 JOB (45992),'SMITH',CLASS=A,RESTART=STEP6

� � �

//STEP6 EXEC ...

[Execution resumes at STEP6.]

RESTART=stepname.procstep restarts the job from a step within a cata-loged procedure://RT452216 JOB (45992),'SMITH',CLASS=A,RESTART=RUN.LKED//STEP1 EXEC ...//RUN EXEC COB2UCLG

[Execution resumes at the LKED step in the COB2UCLG catalogedprocedure.]

RESTART=* restarts at the first step. (The same happens if you omit theRESTART parameter.)

Restart from a CheckpointThe RESTART parameter on the JOB statement, in addition to specifying thestep at which to restart, can also name the checkpoint to use for the restart.All the data sets required by the original job step must be present for therestart because the checkpoint doesn’t save them; it only notes the positionin each data set when the checkpoint is taken. The restart step must not referto data sets that are deleted after the checkpoint is taken. If data sets arepassed to the restart step, modify the JCL to include the UNIT and VOL ofthe data sets. Use the conditional disposition to catalog passed data sets ifthe step abnormally terminates to eliminate having to code UNIT and VOL.

The DD statements in the restart step must point to the same data setson the same units and volumes as when the checkpoint was taken, but you

can change other parameters. You can add another volume for a multivol-ume output data set, add new DD statements, alter data, and dummy outunneeded DD statements. You can’t use referbacks except in the DCB, DSN,and VOL parameters. The VOL must refer back to a DD statement giving thevolume serial number.

To restart a job from a checkpoint, code the following on the JOB state-ment:

RESTART=(stepname,checkid)

[Restart from a job step.]

RESTART=(stepname.procstep,checkid)

[Restart from a step within a cataloged procedure.]

RESTART=(*,checkid)

[Restart from the first step within the job.]

Enclose the checkid in apostrophes if it contains special characterssuch as blank , . / ′ ) ( * & + − =. Code a legitimate apostrophe as two con-secutive apostrophes.

You must include a //SYSCHK DD statement to describe the checkpointdata set. Place the //SYSCHK DD statement immediately following the JOBstatement and any JOBLIB statement, but before the first EXEC statement.

//RT452216 JOB (45992),'SMITH',CLASS=A,RESTART=(STEP1.GO,CK10)

[The system restarts from the GO step of the COB2UCLG catalogedprocedure invoked by STEP1. It makes the restart from the CK10checkpoint.]

//JOBLIB DD DSN=A1000.PROGLIB.LOAD,DISP=SHR//SYSCHK DD DSN=A1000.CHKPTLIB.DATA,DISP=OLD

[The //SYSCHK DD statement follows the JOB and any JOBLIBstatement.]

//STEP1 EXEC COB2UCLG

The //SYSCHK DD statement may include other DD parameters asneeded. If you don’t catalog the checkpoint data set, you must include unitand volume information. Do not include a member name for a checkpoint dataset that is partitioned. SYSCHK must imply or specify DISP=(OLD,KEEP).

Generation data groups require that you change the generation in theJCL for deferred step restart if you cataloged the data set in a precedingstep. The JCL must point to the new generation number rather than theoriginal generation number if you created and cataloged the generationdata set in steps preceding the restart step. For example, if you created



(+2) in STEP 1, refer to it as (0) to restart in STEP 2. Generation datagroups do not have this problem if you keep rather than catalog them. Theproblem also disappears with automatic restart and with deferred restartfrom a checkpoint.

RESTART with the IF/THEN StatementWhen you attempt to restart from a specific step and the step is enclosed byan IF/THEN statement, a relational expression referring to a prior step isassumed to be negative and the step is not executed. For example, supposeyou had the following:

//RT452216 JOB (45992),’SMITH’,CLASS=A,RESTART=STEP2//STEP1 EXEC PGM=PGM1// IF STEP1.RC=0 THEN//STEP2 EXEC PGM=PGM2//STEP3 EXEC PGM=PGM3// ELSE//STEP4 EXEC PGM=PGM4// ENDIF

STEP2 and STEP3 will not execute but STEP4 will. To restart fromSTEP2, add an | ¬STEP1.RUN condition to the logical expression to exe-cute STEP2 when STEP1 is not executed.

//RT452216 JOB (45992),’SMITH’,CLASS=A,RESTART=STEP2//STEP1 EXEC PGM=IEFBR14// IF STEP1.RC=0 | ¬STEP1.RUN THEN//STEP2 EXEC PGM=PGM2//STEP3 EXEC PGM=PGM3// ELSE//STEP4 EXEC PGM=PGM4// ENDIF

RESTART on the JES2/*JOBPARM StatementIn JES2, you can specify job restart with the RESTART parameter on the/*JOBPARM statement.

/*JOBPARM RESTART=YES or NO

RESTART=YES restarts the job from the start of the job. RESTART=NO,the default, tells the system to take no special action.

FAILURE on the JES3//*MAIN StatementIn JES3, you can also specify the restart conditions with the FAILUREparameter of the //*MAIN statement.

//*MAIN FAILURE=action


The action can be RESTART, CANCEL, HOLD, or PRINT to specify therecovery in case the job fails. RESTART restarts the job, CANCEL cancels it,HOLD holds the job for operator intervention, and PRINT prints the job andholds it for restart.

16.2 SPANNED RECORDS

Sometimes Used

Spanned records get around the system limitation that a block cannot belarger than 32,760 bytes. With spanned records, one record spans two or more blocks. Spanned records must be variable length, blocked orunblocked: RECFM=VS or VBS. Figure 16.1 illustrates spanned records.For QSAM (sequential records), code LRECL=X to indicate a record lengthgreater than 32,760 bytes. (LRECL=X is not valid for ISO/ANSI/FIPS ver-sion 3 records.)

RECFM=VS,LRECL=X or RECFM=VBS,LRECL=X

For example:

//OUT DD DCB=(RECFM=VBS,LRECL=X),...

Don’t use DISP=MOD with spanned records because it can result in thesystem embedding short blocks in the data set.

16.3 DATA SET PROTECTION

16.3.1 RETPD, EXPDT: Retention Checks

Sometimes Used

You can assign a retention period for data sets on tape or direct-access vol-umes. You cannot normally modify or delete a data set with an unexpiredretention date. (The VSAM IDCAMS utility program described in Chapter 19

FIGURE 16.1 Spanned records.

XXXXXXXXXXXX XX

Block 1

Record 1

Block 2

YYYYYYYY YY

Block 3

Record 2

Block 4


can delete them.) When the retention period expires, the data set becomeslike any other data set without a retention check—you can modify or delete it.

A RETPD parameter on a DD statement sets the retention period in days.

//ddname DD RETPD=days,...

[days is the number of days (0 to 9999) in the retention period.]

Alternatively, an EXPDT parameter specifies the expiration date.

//ddname DD EXPDT=yyyy/ddd,...

[yyyy is the four-digit year and ddd is the three-digit day number(001 to 366).]

You may also see EXPDT on old JCL coded as EXPDT=yyddd, an obso-lete form. Change it to yyyy/ddd. The system assumes a retention period ofzero days if you don’t specify retention. EXPDT=1999/365 and 1999/366(and 99365 and 99366 in the old form) request permanent retention.

RETPD and EXPDT override any expiration date from a DATACLASparameter. You can also code them as subparameters of the LABEL param-eter. Older versions of the system required this, and so they sometimesappear in the LABEL parameter in older JCL. You usually assign the reten-tion period when you create the data set, but you can change or removethem later by coding the LABEL parameter in any job step that opens thedata set.

RETPD=nnnnNOPWREAD INPASSWORD OUT EXPDT=yyyy/ddd

LABEL=(file,type, , , )

RETPD and EXPDT override the values set by a DATACLAS parameter.

16.3.2 PASSWORD, NOPWREAD: Password Protection

Rarely Used

You can give a measure of security to data sets that have IBM and ISO/ANSI/FIPS labels by protecting them with a password. The PASSWORDsubparameter, coded when you create the data set, sets a password thatmust then be supplied to open or delete the data set. If instead you specifyNOPWREAD (no password read), the data set can be read, but the passwordmust be supplied to write or delete the data set. Data set names cannot belonger than 17 characters if they are to be PASSWORD-protected. SEC-MODEL sets the protection for SMS-managed data sets, and the systemignores PASSWORD for them.

When you code the PASSWORD subparameter on a DD statement creat-ing a data set, the system selects an eight-digit password and assigns it. Theoperator, or in TSO the time-sharing user, must thereafter supply the pass-word whenever the data set is used. If the correct password is not given intwo tries, the system cancels the job.

Password protection does not yield a high measure of security. A cleverprogrammer can circumvent the protection, and a second party—the oper-ator—must know the password. Password protection is adequate for non-critical data sets but may not be appropriate for highly sensitive data setssuch as payroll. It is inadequate for national security classified information.To request that a data set be protected by password, code LABEL=(,,PASS-WORD) or LABEL=(,,NOPWREAD).

PASSWORD and NOPWREAD are positional subparameters and RETPDand EXPDT are keyword subparameters. You may code them in any combi-nation with other LABEL subparameters.

//A DD LABEL=(2,SL,PASSWORD,IN,RETPD=30),...//B DD LABEL=(,,NOPWREAD,EXPDT=99360),...

16.3.3 RACF Protection

Sometimes Used

The Resource Access Control Facility (RACF, pronounced rack-f ) is an IBMprogram product that limits access to data sets residing on direct-accessvolumes. RACF contains a list of users that may have access to a data set,along with the type of access that they may have. You can give a data setRACF protection either automatically when you create it (if you have theautomatic data set protection attribute) or through the RACF command lan-guage. If a data set is both password-protected and RACF-protected, thepassword protection is ignored.

USER, GROUP, PASSWORD, and SECLABEL ParametersYou code the USER, GROUP, PASSWORD, and SECLABEL parameters onthe JOB statement to give access to a RACF-protected data set. Code theparameters as follows:

USER=userid supplies your userid to the system. You must code USERif you code either GROUP or PASSWORD.

GROUP=group-name associates your userid with a RACF group. GROUPis optional. If you omit it, the system uses the default group for youruserid.

PASSWORD=password identifies the current RACF password. CodePASSWORD=(old-password,new-password) to change the passwordof RACF-protected data sets.


SECLABEL=label-name specifies the security level at which the job is to execute. The installation must tell you the label-name to use. Ifyou don’t code SECLABEL, the system uses a default security level.

//RT452216 JOB (45992),'SMITH',CLASS=A,// USER=ITSMETOO,GROUP=OURS,PASSWORD=L22434L3

The PROTECT Parameter

Sometimes Used

To request RACF protection for non-SMS-managed data sets on disk ortape, add the PROTECT=YES parameter:

//OUT DD DSN=Y2254.TEST.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,PROTECT=YES,// SPACE=(TRK,(100,10))

PROTECT can be used only for nontemporary data sets and then onlywhen they are created. For disk data sets, the normal and abnormal dispo-sition cannot be DELETE. Tape labels must be SL, NSL, SUL, AL, or AUL.The system protects the entire volume of a tape if you don’t specify the filenumber in the LABEL statement, and the tape can contain any type of label.For SMS-managed data sets, the PROTECT parameter has been replaced bythe SECMODEL parameter described in Chapter 11.

16.3.4 Summary

VSAM data sets described in Chapter 17 may also have password protection,although it is implemented differently. Data security is not an easy problem.Don’t be lulled into complacency by the features provided by the operatingsystem. For example, when you delete a password-protected data set, the sys-tem changes pointers in the VTOC but does not erase the data on the volume.The system will eventually allocate the same space to another data set, makingit possible to read the deleted data set. You cannot password protect temporarydata sets, such as sort work files, and they, too, present a security problem.Likewise, the system does not zero out central storage when it loads anotherprogram, and the program can potentially access the data left in storage.

16.4 JOB EXECUTION PRIORITY

Rarely Used

16.4.1 The JCL PRTY JOB Parameter

PRTY=priority specifies the job execution priority, the priority with whichjobs are selected from the queue to be executed. (Dispatching priority, the


priority with which each job in storage gets the CPU while running, is setby the installation.) The priority may range from 0 (lowest) to 15 in JES2and 14 in JES3. If you omit PRTY, the system assumes a default priority setby the installation. The priority may also be changed by the operator or bythe system as the job ages in the input queue. Your installation will likelycontrol the use of this parameter.

Priority is within job class. When several jobs of a given class arequeued up waiting to be executed, the system selects the job with the high-est priority first. It selects jobs with equal priority on a first-in-first-outorder. The job scheduler determines which job classes have the highest pri-ority for job selection.

//RT452216 JOB (45992),'SMITH',CLASS=M,PRTY=7

16.4.2 The JES2/*PRIORITY Statement

You can also set the priority with a JES2/*PRIORITY statement that over-rides any PRTY on the JOB statement. Place the /*PRIORITY statement infront of the JOB statement. For example:

/*PRIORITY 6//RT452216 JOB (45992),'SMITH',CLASS=A

16.5 OTHER JCL PARAMETERS

16.5.1 PERFORM: Performance Group Assignment

Sometimes Used

The PERFORM=n parameter assigns a job or step to a performance groupdefined by the installation to optimize the system’s performance and to giveappropriate response to groups of jobs. If you omit PERFORM, the systemassumes a default set by the installation.

PERFORM on EXEC StatementsCode PERFORM on an EXEC statement to apply it to a specific step.

//STEP1 EXEC PGM=ONE,PERFORM=6

[STEP1 is assigned to performance group 6.]

//STEP2 EXEC COB2UCLG,PERFORM.COB=8

[The COB step of the COB2UCLG procedure is assigned to perfor-mance group 8.]


//STEP3 EXEC COB2UCLG,PERFORM=3

[All steps within the procedure are assigned to performance group 3.]

PERFORM on the JOB StatementCode PERFORM on the JOB statement to apply it to all steps within the job,overriding any PERFORM parameters coded on EXEC statements.

//RT452216 JOB (45992),'SMITH',CLASS=A,PERFORM=12

[All steps within the job are assigned to performance group 12.]

16.5.2 ADDRSPC: Prohibit Paging

Rarely Used

The ADDRSPC parameter prevents a job or job step from being paged.ADDRSPC=REAL locks the job or step into central storage during execution.ADDRSPC=VIRT, the default, lets the job or step be paged. Installations con-trol the use of ADDRSPC=REAL because of its adverse effect on the system’sperformance. You might use it for time-dependent programs and those thatdynamically modify channel programs during I/O operations.

ADDRSPC on EXEC StatementsCode ADDRSPC on the EXEC statement to apply it to a specific job step.

//STEP6 EXEC PGM=ONE,ADDRSPC=REAL

[The system won’t page STEP6.]

//STEP7 EXEC COB2UCLG,ADDRSPC.GO=REAL

[The system won’t page the GO step of the cataloged procedure.]

//STEP8 EXEC COB2UCLG,ADDRSPC=REAL

[The system will page none of the steps in the cataloged procedure.]

ADDRSPC on the JOB StatementCode ADDRSPC on the JOB statement to apply it to all steps within the job,overriding any ADDRSPC parameters coded on EXEC statements.

//RT452216 JOB (45992),'SMITH',CLASS=A.ADDRSPC=REAL

[The system will page no steps in the job.]

16.5.3 The BLKSZLIM DD Parameter

Rarely Used

If you don’t code the BLKSIZE parameter and let the system select the blocksize, you can place an upper limit on the block size by coding


TEAMFLY

Team-Fly®


n [bytes: n is 18-2147483648 bytes]nK [Kilobytes: n is 1-2097152x103 bytes]nM [Megabytes: n is 1-2048x106 bytes]nG [Gigabytes: n is 1-2x109 bytes]

BLKSZLIM=__

//DD1 DD DSN=SOMETHING,DISP=(NEW,CATLG),BLKSZLIM=10M,...

16.5.4 The DYNAMNBR DD Parameter

Rarely Used

You normally specify all the data sets you need with the DD statements inyour JCL for a step. However, if you write programs that dynamically allo-cate data sets, you should code the DYNAMNBR parameter on the EXECstatement so the system can acquire the resources just before their use andrelease them immediately after use. You code

//stepname EXEC DYNAMNBR=n

The n tells the system how many data set allocations to hold in antici-pation of reuse. (The system actually holds n plus the total number of DDstatements used by the step.)

16.5.5 The MEMLIST JOB and EXEC Parameter

Rarely Used

MEMLIST limits the total number of usable virtual pages above the line fora single address space. You code it as follows:

nM [Megabytes: nx106 bytes]nG [Gigabytes: nx109 bytes]nT [Terabytes: nx1012 bytes]nP [Petabytes: nx1015 bytes]NOLIMIT

MEMLIMIT=__

The n can range from 0 to 99999. NOLIMIT removes any limit. Thedefault if you don’t code MEMLIMIT is set by your system programmers.Any MEMLIMIT coded on the JOB statement overrides any MEMLIMIT onthe EXEC statements.

//STEP1 EXEC PGM=DOIT,MEMLIMIT=10G

16.5.6 The QNAME DD Parameter

Rarely Used

Code the QNAME=procname,jobname parameter to indicate that the DDstatement defines a data set for TCAM (Telecommunications Access Method)


messages. The procname is the procname in the name field of the TPROCESSmacro instruction. The jobname, from the JOB statement, is optional. Itallows the job to be task started by an operator.

//ddname DD QNAME=TCAMONE

[The only other parameters you can code are the BLKSIZE, BUFL,LIKE, LRECL, OPTCD, RECFM, and REFDD parameters.]

16.5.7 The SCHENV JOB Parameter

Rarely Used

For jobs in JES2 and JES3, you can name the Workload Management (WLL)scheduling environment by coding the SCHENV parameter on the JOBstatement. The scheduling environment is a list of resources and theirrequired settings, and SCHENV schedules the job only on a system that sat-isfies the requirements. This lets your job run on any system that meets theresource requirements without your having to name the system.

//jobname JOB …,SCHENV=name

Your installation must provide a name to use.

16.5.8 The SUBSYS DD Parameter

Rarely Used

The SUBSYS parameter on the DD statement requests a subsystem toprocess the data set. You can’t use SUBSYS with SMS-managed data sets.You code

SUBSYS=(subsystem-name,parameter,parameter,…,parameter)

The subsystem is the name of the subsystem to process the data set.Code the parameters as needed by the subsystem.

16.6 NULL STATEMENT

Rarely Used

The null statement contains // in columns 1 and 2 with the remainingcolumns blank and causes the system to look for the next JOB statement,ignoring any intervening statements. Back when punched cards were used,a null coded on distinctive colored cards was often used to help operatorsseparate card decks. Today there is little use for it.


16.7 OPERATOR COMMANDS

Rarely Used

Operators normally enter operator commands from the console, but theycan code frequently used commands on command statements to be read inthrough the input stream. Command statements are generally limited tooperator use because they affect machine operation. The commands mustbe synchronized with the execution of jobs because the system executes thecommands as it reads them.

16.7.1 JCL COMMAND Statement

Place the command statement anywhere after a JOB statement. Code COM-MAND statements as

// COMMAND 'command operand'

The command can be any MVS or JES2 command. Because the com-mand and any operand are enclosed in apostrophes, continue the COM-MAND statement by coding into column 71, and code // on the next line,and continue the commands in column 16. If any command contains anapostrophe, code it as two consecutive apostrophes. Here is an example:

1 2 3 4 5 6 712345678901234567890123456789012345678901234567890123456789012345678901// COMMAND 'SEND "This is to notify user SAM12 that the job is complete// d and the output is ready.",USER=SAM12

16.7.2 JES2 Operator Commands

The /*MESSAGE statement lets you send a message to the computer opera-tor. The system displays the message when JES2 reads the job.

/*MESSAGE message

For example:

//RT452216 JOB (45992),'SMITH',CLASS=A/*MESSAGE I AM ENCLOSING A TAPE REEL WITH THE JOB.

Code the /*$command statement to enter JES2 operator commands inthe input stream.

/*$command operand,operand,...,operand

Place the command statement in front of the JOB statement. The systemexecutes the command as soon as it reads it.

16.7.3 JES3 Operator Commands

The //*OPERATOR statement sends a message to the computer operatorthat displays when JES3 reads the job.

//*OPERATOR message

The //**command statement enters operator commands in the inputstream. Place it in front of JOB statements in the input stream.

//**command operands

16.8 CNTL/ENDCNTL PROGRAM CONTROL STATEMENTS

Rarely Used

You can direct some subsystems, such as Print Services Facility (PSF), withtheir own set of control statements. To do this, you include the program con-trol statements in the input stream for a data set by placing them betweenCNTL and ENDCNTL statements. Then you add a CNTL parameter to the DDstatement to refer to the label of the CNTL statement as shown here.

//stepname EXEC PGM=program//label CNTL *[Place the control statements here.]// ENDCNTL//ddname DD CNTL=*.label,…

Place CNTL, and the DD statement that references it, in the same step.The DD statement must follow CNTL/ENDCNTL in the input stream.

You can place both CNTL/ENDCNTL and the DD statement in a cata-loged procedure, and the control statements can contain symbolic parame-ters. Or you can place CNTL/ENDCNTL in a procedure and place the DDstatement in the invoking job step (but not vice versa). When you do this,code the CNTL parameter on the DD statement as a referback:

//ddname DD CNTL=*.stepname.procstepname.label,…

If you use the same control statements in several steps, place thembefore the first EXEC statement, making sure that the CNTL label is unique.

16.9 XMIT DATA TRANSMISSION STATEMENTS

The XMIT statements send a job or data stream to another JES or non-JESnode. The job is only transmitted—not executed. You generally use XMITto send data to another node.


//RT452216 JOB (45992),'SMITH',CLASS=AJES2 /*XMIT node-name,DLM=xxJES3 //*XMIT DEST=node-name,DLM=xx,SUBCHARS=yyJCL // XMIT dest=node-name,DLM=xx,SUBCHARS=yy Only in JES3.[Lines of data]/*

The parameters are as follows:

node-name names the node to which the data is to be sent. You code itas node-name.userid for a TSO workstation and as node-name.vmguestid for a VM system.

DLM=xx is optional and changes the delimiter characters from /* to thetwo characters you specify. (Same as the DLM parameter on the DDstatement.)

SUBCHARS=yy is also optional and specifies replacement characters tobe used for the first two characters of any /*EOF or /*DEL internalreader control statement that are transmitted as lines of data so thatthey will not be executed.

You can transmit several data packages by including more than oneXMIT statement.


CHAPTER 17

VSAM DATA SETS

Essential

Virtual Storage Access Method (VSAM) data sets are supported in Assem-bler Language, COBOL, C/C++, PL/I, and FORTRAN. They can also be SMS-managed. The term virtual in VSAM is perhaps misleading. It means thatthe access method has been implemented in IBM’s virtual operating system,MVS. There is nothing inherently virtual in VSAM. VSAM can process datasets both sequentially and randomly. The JCL requirements are very simple.What follows is only an introduction to VSAM.

You can organize VSAM data sets four ways. Key-sequenced data sets(KSDSs) store records in sequential order based on the record keys. You canprocess a data set sequentially, in the order of the record keys, or randomly,by presenting the key of the record to access. Entry-sequenced data sets(ESDSs) store records in the order they are entered and are the VSAMequivalent of a sequential data set. You usually process the records sequen-tially, but you can retrieve or update them randomly. However, you mustexternally keep track of where each record is stored to access records ran-domly. Relative record data sets (RRDSs) let you access records by therecord’s relative position in the data set. Linear data sets (LDSs) treat thedata as a very large linear space. They are primarily used for DB2 databasesand are not described here.

Entry-sequenced data sets are easy to understand because they are anal-ogous to sequential data sets. Relative record data sets are also simple inconcept. Key-sequenced data sets are frequently used and are a bit morecomplicated. To understand VSAM key-sequenced data sets, suppose apublic library maintains a data set containing a record for each book andthere are 150,000 books. Each record might contain the title, author, pub-lisher, and other information about the book. The Dewey decimal numbercan be used as the key to arrange the books in the stacks.

Sequential processing works well when you must process all the records,as you would for an inventory, but suppose a book titled Zelda’s Zilch

300

requires a change. When you must change a single record, random access ismuch faster. You can add and delete books from the data set directly withouthaving to process the entire data set.

The analogy with a library is a good one to pursue because the VSAMkey-sequenced organization is similar to the way in which a public libraryis organized. The basic unit of storage in a library is a shelf (control intervalin VSAM). Books (records) are arranged on the shelves in the stacks orderedon their library number (record key). A separate index to the books is con-tained in the library’s index (index area). The index of the library does notpoint directly to a book, but only to the location of the shelf. Once you findthe shelf, you must search it for the book with the matching library number.

When you add a book, you update the library’s index and insert thebook on the shelf. Note that before libraries were computerized, the indexhad two levels: an index in the form of card trays and the index to the bookswithin the trays. VSAM provides as many levels of index as are needed.

Follow this analogy a little further to illustrate how VSAM data sets areupdated. When you add a book, you insert it where it belongs on the shelf,moving over the remainder of the books. If there were no room on the con-trol interval (shelf), VSAM would insert the record where it belongs, createa new control interval, and move any records forced off the end of the oldcontrol interval to the new control interval.

The index of a VSAM data set is a little different from that of a library.The library has an entry in the index for every book. In VSAM, there is anindex entry only for the last record on each control interval. Thus, the indextells where the record should be on the control interval. The control inter-val must be searched to see if the record actually exists.

Key-sequenced and relative-record VSAM data sets may also have alter-nate indexes. This allows VSAM data sets to be inverted on some key. If theterm inverted is unfamiliar, the concept is not. Libraries invert their filesand provide alternate indexes. One listing might be in order of the booktitles, and then this file is inverted on the author to list the catalog in orderof the authors. This allows you to quickly retrieve a book given either itsauthor or title.

VSAM data sets may have password protection. This password protectionis not the same as the JCL password protection coded in the LABEL parame-ter. VSAM password protection affords some control over data set access, andthe application program supplies the password rather than the operator.

VSAM data sets must be cataloged and reside on direct-access volumesand can contain fixed- or variable-length records. You can create them withJCL, with TSO, or with the IDCAMS utility that is a part of VSAM. The TSOcommands are described in Chapter 22.

You create VSAM data sets sequentially, even if they are RRDS or KSDS.When you create the data set, you write the records ordered on their keys,

VSAM DATA SETS 301


and VSAM blocks the records and creates a separate index containing thekey of the last record written in each block. VSAM retrieves records ran-domly by searching the index to find the block containing the record, andthen searching the block for a record with a matching key. You can alsoupdate VSAM data sets by replacing, adding, or deleting records. VSAMreplaces records by overwriting the old record.

The records in a VSAM data set are stored in control intervals. A con-trol interval is similar to a block in that it contains several records, but italso contains free space as shown in Figure 17.1. VSAM selects an efficientcontrol interval size based on the track size of the direct-access volume andthe data set’s record length. When you create the data set, you can specifyfree space in two ways: as a percentage of each control interval to leave free,and as a percentage of the total control intervals to leave free.

The index area also consists of these same control intervals. As the dataset is created, the key of the last record stored in each control interval, alongwith a pointer to the control interval containing the record, is stored in theindex control interval. The pointer consists of the relative byte address(RBA) of the record’s location in the data set. (Figure 17.2 illustrates VSAMindexes.)

VSAM creates as many levels of index control intervals as needed.When an index control interval is filled, VSAM allocates another controlarea and creates a higher-level index control interval to point to the twolower-level control intervals. When this higher-level control interval isfilled with pointers, VSAM creates another higher-level control interval.This continues for as many levels as needed. The lowest level group of con-trol intervals is termed the sequence set, and it points to all the control

FIGURE 17.1 VSAM control interval.

RecordA

RecordD

RecordF

Freespace

FIGURE 17.2 VSAM pointer structure.

D IFree

space

A DFree

space

Index

G IFree

spaceSequenceset

VSAM DATA SETS 303

intervals containing data records. The entire data set, including the indexesand the sequence set, is termed a cluster. You name the cluster so that youcan refer to all the components with one name.

VSAM reorganizes data sets as it updates them. When VSAM deletes arecord, it moves up all the records following it in the control interval,increasing the free space. When VSAM adds a record, it inserts the recordwhere it belongs in the control interval and moves down all the records fol-lowing it, consuming the free space at the end of the control interval. Ifthere is not enough free space to contain the new record, a control intervalsplit occurs. VSAM allocates a new control interval and moves records offthe original control interval so that both the old and new control intervalswill contain free space. It then updates the indexes. The overflow recordsare thus stored in the same blocked format as the original records. Theresult is that VSAM data sets seldom require a separate reorganization. Fig-ure 17.3 illustrates a control interval split.

When you update data sets, VSAM writes the records into the data setand updates the pointers. If the program abnormally terminates when youopen the data set for output or update, the data set may become unusablebecause the pointers may not be updated. This is a serious problem if you do

FIGURE 17.3 VSAM control split.

�A D

�A B

Free area

C

Transactions

B

D I

Before updating

K Index

Index

D K

After updating

�C D

��

G I

�J K Sequence set

Sequence set

Index control split occurs,necessitating the creationof a higher-level index.

B D��I K��

J K

�G I

Control split occurs. The systemrearranges records so that there is freespace in each control interval.

not have a backup. This generally requires that you backup the data set atsome point and save the transactions entered until you make a new backup.

17.1 CREATING VSAM DATA SETS WITH JCL

Although you can create a VSAM data set through JCL, you cannot specifyall the options that are available through the IDCAMS utility. With JCL, theVSAM cluster name becomes the data set name. To create a VSAM data setthrough JCL, SMS must be active. You code all the normal DD parameters:

//ddname DD DSN=data-set-name,DISP=(NEW,CATLG),

[VSAM files have the same naming convention as normal data sets.The DISP is usually CATLG because nontemporary VSAM data setsmust be cataloged.]

// STORCLAS=storage-class,MGMTCLAS=management-class,

[If the VSAM data set is to be SMS-managed, code STORCLAS andMGMTCLAS as needed. If not SMS-managed, code UNIT and VOLas you would for any data set. You can also code LIKE/REFDD, SEC-MODEL, and EXPDT/RETPD.]

// LRECL=length,

[Code LRECL if it is not supplied by the application program or bya DATACLAS parameter.]

// AVGREC=U,SPACE=(0,(10000,1000),RLSE),

[If a DATACLAS does not supply a default space amount, code theSPACE parameter to specify it as you would for any data set.]

// RECORG=type,KEYOFF=bytes

Code RECORG=type to specify the type of VSAM data set. The type canbe one of the following:

KS Key-sequenced data set—KSDS.ES Entry-sequenced data set—ESDS.RR Relative-record data set—RRDS. Fixed-length records only.LS Linear-space data set—LSD.

For a key-sequenced data set (RECORG=KS), you must additionallyspecify the key offset in bytes with KEYOFF=bytes, where the offset of thefirst byte is zero. Here is an example of creating an SMS-managed KSDSthrough JCL.


TEAMFLY

Team-Fly®

//STEP1 EXEC PGM=IEFBR14//DD1 DD DSN=A1000.FILE.DATA,DISP=(NEW,KEEP),// STORCLAS=VSAM,DATACLAS=PERMVSAM,RECORG=KS,KEYOFF=20

[The system creates a KSDS data set with the key beginning in rela-tive byte 20.]

VSAM data sets can have 123 extents and reside on 1 to 59 volumes. Themaximum data set size is 4GB or 64K tracks. You can create a VSAM data setwith spanned records, but not through JCL. If SMS is active, the guaranteedspace attribute can be made default or can be assigned to STORCLAS param-eters. For VSAM data sets, guaranteed space is in effect for a data set, the sys-tem first allocates the primary amount requested on all of the volumes. Thenit fills the primary area on the first volume and allocates secondary amountson the same volume until either it uses all 123 extents or the volume has nomore space. Then it moves to the second volume, fills its preallocated pri-mary area and begins allocating secondary amounts, and so on.

Allocate temporary VSAM data sets by giving them a name beginningwith an ampersand, as you would any data set. Temporary data sets can’t be multivolume, and any EXPDT/RETPD is ignored. They must be SMS-managed.

//ddname DD DSN=&TEMPDATA,DISP=(NEW,PASS),// LRECL=250,AVGREC=U,SPACE=(0,5000,500)),// STORCLAS=TEMP,RECORG=ESDS

17.2 ACCESSING VSAM DATA SETS THROUGH JCL

For an existing VSAM data set, code DSN and DISP=OLD, SHR, or PASS asyou would for any data set. DUMMY, FREE, DYNAM, and PROTECT like-wise work as they do for normal data sets.

//ddname DD DSN=data-set-name,DISP=OLD

If the VSAM data set is SMS-managed, you can delete it through JCLwith a DISP of DELETE. Use SHR or OLD to read VSAM data sets. Use OLDto rewrite a data set. VSAM treats MOD as OLD. You can code two addi-tional parameters unique to VSAM for existing data sets.

17.2.1 The AMP Parameter on the DD Statement

The AMP parameter specifies options to pass to VSAM. You code it as fol-lows, enclosing the options in apostrophes.

AMP=('option,option,...,option')//ddname DD DSN=MY.VSAM.DATA,DISP=OLD,AMP=('AMORG,BUFND=3,BUFNI=3')

VSAM DATA SETS 305

AMP has the following options:

AMORG indicates that the DD statement describes a VSAM data set andit is needed if the data set is not accessed through the catalog—when UNIT and VOL=SER are coded on the DD statement. (The sys-tem will know that it is a VSAM data set if it accesses it through thecatalog.) AMORG is also needed for DUMMY data sets.

STRNO=n specifies the number of VSAM requests that require concur-rent data set positioning.

BUFND=n specifies the number of buffers for data records. The n mustbe a minimum of 1+STRNO, but at least two buffers must be pro-vided. If you omit BUFND, it defaults to an installation-definedvalue that usually suffices.

BUFNI=n specifies the number of buffers for index records. At least onebuffer must be provided. If you omit BUFNI, VSAM assumes aninstallation default that usually suffices.

BUFSP=n specifies the same number for BUFND and BUFNI and over-rides both. At least two buffers must be provided. If you omitBUFSP, VSAM assumes BUFND, BUFNI, or an installation defaultthat usually suffices.

CROPS=RCK, NCK, NRE, or NRC (code only one) specifies the check-point/restart option.� RCK defaults. It requests VSAM to perform erase and data set

post-checkpoint modification tests.� NCK eliminates the data set post-checkpoint modification test.� NRE eliminates the data-erase test.� NRC eliminates the data-erase and data set post-checkpoint mod-

ification tests.

SYNAD=module-name names a module to be used by the EXLISTmacro instruction.

TRACE requests the generalized trace facility to gather statistics.

17.2.2 The RLS Parameter

You can share VSAM data sets with other users by specifying this in theapplication program. For existing applications, you can specify the sharingby coding the RLS parameter on a DD statement. You code RLS=NRI or CR.NRI, No Read Integrity, lets the application read all records, including com-mitted and uncommitted changes made to the data set by another applica-tion. CR, Consistent Read, lets the application read only committed changes,not uncommitted changes, made to the data set by another program.


//INPUT DD DSN=A1000.TEST.DATA,DISP=SHR,RLS=NRI

17.2.3 The LGSTREAM Parameter

LGSTREAM specifies the prefix of the name for the forward recovery logstream for an SMS-managed VSAM data set. The log stream records changesmade to the data set when accessed in RLS mode. The default prefix isderived from the SMS data class assigned to the data set. Your installationmust provide the prefix to use.

//INPUT DD DSN=A1000.TEST.DATA,DISP=SHR,RLS=NRI,LGSTREAM=BACK10

17.3 THE IDCAMS UTILITY

The IDCAMS utility, sometimes called the Access Method Services (AMS)program creates VSAM data sets. The following describes only the essentialcommands. You invoke IDCAMS in a job step as follows:

//stepname EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A

[Prints the IDCAMS messages.]

//ddname DD DSN=...

[Some commands require one or two DD statements to describeinput or output data sets.]

//SYSIN DD *[Command statements]/*

Code the command statements in columns 2 through 72. Continue acommand statement by coding a hyphen after a complete subparameter,leaving at least one blank between the subparameter and the hyphen.

REPRO - But not REPRO-INFILE(INDD) INFILE(INDD)

IDCAMS returns the standard IBM completion codes. If a data set ispassword-protected, append/password to the ddname or data set name tospecify the password. For example, INFILE(ddname/password) or OUT-DATASET(data-set-name/password).

Besides creating VSAM data sets, IDCAMS can also perform many util-ity functions, such as copying and printing, on both VSAM and non-VSAMdata sets. The utility functions are described in Chapter 19.

VSAM DATA SETS 307

17.3.1 CREATING DATA SETS WITH IDCAMS

You can create both VSAM and non-VSAM data sets, SMS-managed andnon-SMS-managed data sets, and disk and tape data sets. In short, any dataset you are likely to use that you can allocate with JCL, you can create withIDCAMS. You code an ALLOCATE statement to allocate data sets withIDCAMS. When you create a VSAM data set with ALLOCATE, the clustername becomes the data set name. There is a DEFINE CLUSTER commandnot described here that lets you name each of the components.

ALLOCATE goes through TSO to create the data set. If you have codedthe USER=userid parameter on the JOB statement, ALLOCATE prefixes thisuserid to the data set name unless you enclose it in apostrophes:

//RT452216 JOB (45992,522),'SMITH',CLASS=A,USER=T44221� � �

ALLOCATE DATASET(TEMP.DATA) ...

[The data set/cluster is named T44221.TEMP.DATA. To name it justTEMP.DATA, you must enclose it in apostrophes: DATASET(‘TEMP.DATA’).]

The following lists the parameters you are likely to use. Since they cor-respond so closely to JCL parameters, most need no explanation.

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *ALLOCATE -DSN(data-set-name) -

[You must name the data set. For a generation data group, give thefully qualified name, including the generation number.]

NEW CATLG -

[The disposition can be only NEW, KEEP, or CATLG.]

Specify DCB subparameters with these:

DSORG(type) -

[The type can be DA, PO, or PS.]

RECFM(record-format) -LRECL(length) -

Allocate space with these:

AVGREC(units) -

[The units can be U, K, or M.]


VSAM DATA SETS 309

SPACE=(primary,secondary) -

[You can also allocate space in units of blocks, tracks, or cylinders,but this is beyond the scope of this book.]

RELEASE -

[Same as RLSE in the JCL SPACE parameter.]

ROUND -

[Same as ROUND in the JCL SPACE parameter.]

DIR(n) -

[Only needed for a new PDS to specify the number of directoryblocks.]

The SMS parameters act the same as for JCL:

DSNTYPE(type) -

[The type can be LIBRARY, PDS, or EXTENDED.]

DATACLAS(data-class) -STORCLAS(storage-class) -MGMTCLAS(management-class) -LIKE(dsname) or REFDD(data-set-name) -

Request protection the same as with JCL.

SECMODEL(profile-name,GENERIC) -PROTECT -

[Same as PROTECT=YES in JCL.]

EXPDT=yyyy/ddd or RETPD(days) -

You can catalog tape data sets with IDCAMS.

LABEL(label) -

[For tape, you can specify any label type for a non-VSAM data set.VSAM data sets can have only label types of SL, SUL, AL, AUL, orLTM.]

POSITION(n) -

[The relative file position of the data set on the tape.]

OPTCD(Q) -

[For tape, converts between ASCII and EBCDIC.]


VSEQ(n) -

[Volume sequence number of multivolume data set with which tobegin processing.]

RECORG(type) -

[For VSAM data sets, you can specify ES, KS, RR, or LS. Don’t codeRECFM if you code RECORG.]

KEYOFF(offset) -

[Needed for RECORG=KS.]

VOL(volume,volume,...,volume) -MAXVOL(count) -

[Maximum volumes on which the data set can reside.]

UNIT(device)/*

When you create a VSAM data set with ALLOCATE, the data set namebecomes the cluster name. All the parts of the cluster, including the dataarea and index, must have the same attributes. (You can create VSAM datasets with the DEFINE CLUSTER command to give the different componentsdifferent attributes, but this is beyond the scope of this book.) With ALLO-CATE, the system chooses the name for the data component and the index.The rules for this are as follows:

1. If you use CLUSTER as the last qualifier of the data set name, the sys-tem used DATA and INDEX to name the data and index components:� Cluster name: RX4421.PAYROLL.CLUSTER� Data name is then: RX4421.PAYROLL.DATA� Index name is then: RX4421.PAYROLL.INDEX

2. Failing this, if the cluster name is 38 characters or less long, includ-ing periods, then the system appends .DATA and .INDEX to namethese components:� Cluster name: RX4421.PAYROLL.C� Data name is then: RX4421.PAYROLL.C.DATA� Index name is then: RX4421.PAYROLL.C.INDEX

3. Failing this, if the data name is 39 to 42 characters long, includingperiods, the system appends .D and .I to the cluster name to namethe components.

4. Failing this, the naming becomes very complicated. Use shorternames.

17.3.2 Copy or Load a Data Set

You must load a VSAM data set by writing it sequentially. Entry-sequencedand linear-space data sets are in whatever sequence you want. Key-sequenced and relative-record data sets must be ordered on the record keys.You can load the data set with your own application program or with theREPRO command. The REPRO command copies data sets as follows:

� Copies or loads non-VSAM sequential data sets to VSAM� Copies or loads VSAM data sets to VSAM data sets� Copies VSAM data sets to non-VSAM sequential data sets

Copy or load data sets as follows:

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//in-ddname DD DSN=...

[Describes the input data set.]

//out-ddname DD DSN=...

[Describes the output data set.]

//SYSIN DD *REPRO -INFILE(in-ddname) -

[Names the DD statement describing the data set to copy. For VSAMdata sets, you can instead code INDATASET(data-set-name) with-out a DD statement.]

OUTFILE(out-ddname)

[Names the DD statement describing the output data set. For VSAMdata sets, you can instead code OUTDATASET(data-set-name)without a DD statement.]

/*

Code the in-ddname and out-ddname DD statement parameters as nec-essary for the input and output data sets. The following example copies thedata set named A1000.TEST.DATA to A1000.RUN.DATA.

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *REPRO INDATASET(A1000.TEST.DATA) OUTDATASET(A1000.RUN.DATA)

/*

VSAM DATA SETS 311

REPRO also has extensive facilities for encrypting data that it copieswhich are beyond the scope of this book.

17.3.3 Creating an Alternate Index

Both key-sequenced and relative-record VSAM data sets may have alternateindexes. An alternate index allows the data set to be accessed by some alter-nate key. For example, a telephone data set might have the name be the pri-mary key and the telephone number as the alternate index. The steps increating an alternate index are as follows:

1. Create the VSAM data set with the ALLOCATE command.

2. Load the database with the REPRO command.

3. Define the alternate index with the DEFINE ALTERNATEINDEXcommand.

4. Connect the alternate index to the data set with the DEFINE PATHcommand.

5. Build the alternate index with the BLDINDEX command.

This step defines the alternate index.

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *DEFINE AIX -(NAME(index-name) -

[This names the alternate index.]

RELATE(data-set-name) -

[This names the data set for which this is the index.]

RECORDS(primary secondary) -

[This allocates space for the index. You can also code CYL, KB, MB, or TRK to request space in these units. The secondary isoptional.]

VOL(volume,volume,...,volume) -

[List the volumes on which to store the alternate index. This is notrequired for an SMS-managed data set.]

The remaining parameters are all optional. Not all are listed.

KEYS(length position) -

[Specify the length of the record key and its relative byte position (0 to n) in the record.]


VSAM DATA SETS 313

UNIQUEKEY -

[UNIQUEKEY specifies that each record must have a unique key.The default of NONUNIQUEKEY allows the data set to have multi-ple records with the same key.]

ERASE -

[ERASE the alternate index when it is deleted by overwriting it withbinary zeros. The default of NOERASE does not overwrite.]

FREESPACE(interval-pct area-pct) -

[Specifies the percent of free space to leave in any control intervalor control area split.]

DATACLAS(data-class) -

[Same as DATACLAS in the JCL and can be used when SMS isactive.]

)/*

After defining an alternate index, you must define a path to access thedata set. This forms the connection between the alternate index and thedata set, and the connection is stored in the catalog.

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *DEFINE PATH -(NAME(data-set-name) -

[Give the path a name.]

PATHENTRY(index-name) -

[Name the alternate index.]

)/*

Finally, you must build the alternate index. The data set must first beloaded, and then you execute the following step.

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *BLDINDEX -INDATASET(data-set-name) -

[Name the data set.]

OUTDATASET(index-name)

[Name the alternate index.]

/*

17.4 JOBCAT AND STEPCAT DD STATEMENTS

You can create your own catalog for VSAM data sets so that the catalog canbe copied with the data set. Then you place a JOBCAT special DD statementafter the JOB statement or the STEPCAT DD statement after the EXEC state-ment to point to the user catalog data set.

//RT45216 JOB (45992),"SMITH',CLASS=A//JOBCAT DD DSN=catalog-name,DISP=SHR

[Code only DSN and DISP=SHR.]

//STEP1 EXEC PGM=…//STEPCAT DD DSN=catalog-name,DISP=SHR

[Code only DSN and DISP=SHR.]


TEAMFLY

Team-Fly®

CHAPTER 18

THE LINKAGE EDITOR AND LOADER

The linkage editor and loader, although not a part of JCL proper, areinvoked by JCL and are used for many JCL applications. This chapter dis-cusses how their function is necessary to the use of z/OS facilities.

18.1 THE LINKAGE EDITOR

Essential

The language compilers convert source language statements into what istermed an object module, a sequential data set containing relocatable ma-chine instructions and data produced by a language compiler. However, youcannot execute an object module because it doesn’t include all the systemfunctions and external subroutines. The linkage editor combines the objectmodule with all these external references (references in one module tosomething in another module, usually a function or subroutine) to create aload module that can be executed.

When you write a program, it usually includes a main program, alongwith several functions or subroutines. You might compile them all togetherthe first time, but thereafter, you will likely need to compile only a fewitems each time, leaving the others unchanged as the debugging proceeds.The linkage editor lets you do this, taking the newly compiled functionsand subroutines and adding them to the old load module, replacing the oldsubroutines and functions with the new, to form a new load module. Forthis, the linkage editor must process several types of input:

� Object modules produced by the language compiler. These are usu-ally placed in a temporary data set and passed to the linkage-editorstep.

� Load modules stored in a nontemporary partitioned data set thatserves as a subroutine and function library. All of the standard sys-

315

tem functions for input and output come from such libraries. Thelinkage editor creates and updates these libraries.

� Load modules that are complete programs stored in nontemporarydata sets.

The linkage editor processes object and load modules to form a loadmodule suitable for execution. You must store the load module as a memberof a partitioned data set on a direct-access volume, as a temporary data set ifyou won’t use it again, but more commonly in a nontemporary data set.

The basic unit processed by the linkage editor is a control section, a unitof program (instructions and data) that is itself an entity. A control section,the smallest separately relocatable unit of a program, is usually the mainprogram, a subroutine, or a function.

The linkage editor reads and processes input described in two DD state-ments and the input stream in the following order:

1. //SYSLIN DD statement. It describes the primary input and isalways required.

2. The input stream. The input stream is concatenated to SYSLIN,which allows both newly compiled subroutines and control state-ments to be included. Object modules are RECFM=FB,LRECL=80,so that the input stream can be concatenated to them. The linkage-editor control statements can reference other DD statements thatpoint to additional sources of input as needed. For example, whenyou compile and link-edit replacement subroutines, you make theold load module an additional input source to include those sub-routines not recompiled.

3. //SYSLIB DD statement. It describes subroutine or functionlibraries for the linkage editor to search for any unresolved refer-ences. For example, you can have subroutines used by a COBOL pro-gram automatically looked up in a library. Several subroutinelibraries can be concatenated together in the //SYSLIB DD statement.

When the linkage editor processes its input and encounters two mod-ules with the same name, only the first is used. This means that if you com-pile a subroutine contained in a SYSLIB library, your subroutine is used,not the one in the library.

18.1.1 JCL for the Linkage Editor

The linkage editor, an IBM-supplied program usually named IEWL, is con-tained in SYS1.LINKLIB.

//LKED EXEC PGM=IEWL,REGION=1024K,PARM=(option,option,...,option)


The linkage-editor step is traditionally named LKED. The PARMoptions, which you can code in any order, request the following options.

LIST lists the linkage-editor control statements and you usually specifyit. Omit LIST to not list the statements.

MAP produces a storage map showing the length and relative locationsof all control sections. It can help you estimate the region sizeneeded for the program. It also helps you identify the point of fail-ure when a program ABENDs. Omit MAP for no map.

XREF includes MAP plus a cross-reference table of the load module.Omit XREF if you don’t want a cross-reference listing.

NCAL cancels the automatic library call mechanism and you often useit for creating subroutine libraries so that the load module containsa single subroutine. Omit NCAL to request automatic librarylookup.

LET marks load modules as executable even if the linkage editor findsminor errors, such as external references left unresolved by NCAL.Omit LET to suppress execution if the linkage editor finds errors.

AMODE=value specifies whether the program uses 24- or 31-bit ad-dressing—that is, whether it can address memory above the 16MBline. AMODE=31 specifies 31-bit addressing. AMODE=ANY speci-fies both 24- and 31-bit addressing. AMODE=24 specifies 24-bitaddressing and requires the program to run below the 16MB line.The compiler establishes the default.

RMODE=value indicates where the program can reside in virtual stor-age. RMODE=ANY allows the program to reside above the 16MB lineand requires AMODE=31 or AMODE=ANY. RMODE=24 requires theprogram to reside below the 16MB line. If AMODE is coded,RMODE=24 defaults. Otherwise, the compiler establishes the de-fault, usually RMODE=24.

TERM writes linkage-editor diagnostic messages to a //SYSTERM DDstatement. This is primarily for TSO where SYSTERM is defined tobe the terminal. TERM is ignored when there is no //SYSTERM DDstatement. Omit TERM to not print the messages when there is a//SYSTERM DD statement.

There are more options, but they are seldom used. You code the follow-ing parameters for most linkage-editor steps.

//LKED EXEC PGM=IEWL,PARM='LIST,XREF'

The IEWL program also requires a //SYSPRINT DD statement to de-scribe a print data set, a //SYSUT1 DD statement to allocate a scratch

THE LINKAGE EDITOR AND LOADER 317

data set, and a //SYSLIN DD statement to describe the primary input. A//SYSLMOD DD statement is required to describe the data set that is to con-tain the load module, a //SYSLIB DD statement is needed for automatic calllookup, and other DD statements may be included to describe additionalsources of input. The LKED cataloged procedure contains the followingstatements to perform a link edit.

//LKED PROC//LKED EXEC PGM=IEWL,REGION=1024K,PARM='XREF,LIST,LET,NCAL'//SYSPRINT DD SYSOUT=A//SYSLIN DD DDNAME=SYSIN//SYSLMOD DD DSN=&&GOSET(GO),SPACE=(1024,(50,20,1)),// UNIT=SYSDA,DISP=(MOD,PASS)//SYSUT1 DD UNIT=VIO,SPACE=(32000,(30,30))

Usually, though, you execute the linkage editor following a compilestep. The following example illustrates the use of the linkage editor in aCOBOL compile, link-edit, and go cataloged procedure.

//IGYWCLG PROC CMP='SYS1.COB2COMP',LIB='SYS1.COB2LIB'//COBOL EXEC PGM=IGYCRCTL,PARM='OBJECT',REGION=1024K

[The COBOL compiler is named IGYCRCTL and normally is con-tained in SYS1.LINKLIB.]

//STEPLIB DD DSN=&CMP,DISP=SHR

[We’ll assume we have our own COBOL compiler contained in theSYS1.COB2COMP library.]


[SYSPRINT describes a print data set.]

//SYSLIN DD DSN=&&LOADSET,DISP=(MOD,PASS),// UNIT=SYSDA,SPACE=(TRK,(3,3)),// DCB=(RECFM=FB,LRECL=80)

[SYSLIN describes the output data set that is to contain the objectmodule produced by the compiler. The disposition of MOD placesobject modules from several steps in one sequential data set.]

//SYSUTn DD UNIT=VIO,SPACE=(32000,(30,30))

[Several //SYSUTn DD statements are needed by the compiler aswork data sets.]

//LKED EXEC PGM=IEWL,PARM='LIST,XREF,LET',COND=(5,LT,COB2),// REGION=1024K

[COND bypasses the link-edit step unless the compile step returns acompletion code of five or less. By convention, condition codesgreater than five represent severe errors.]


//SYSLIN DD DSN=&&LOADSET,DISP=(OLD,DELETE)// DD DDNAME=SYSIN

[SYSLIN describes the primary input—the output from the com-piler concatenated with the input stream. The DCB attributes arebuilt-in as RECFM=FB,LRECL=80.]

//SYSLMOD DD DSN=&&GOSET(GO),DISP=(NEW,PASS),// UNIT=SYSDA,SPACE=(CYL,(1,1,1))

[SYSLMOD defines the data set to contain the load module pro-duced. The RECFM=U attribute is built-in.]

//SYSLIB DD DSN=&LIB,DISP=SHR

[SYSLIB points to the library used for the automatic call lookup.The DCB attributes are built in as RECFM=FB,LRECL=80.]

//SYSUT1 DD UNIT=VIO,SPACE=(32000,(30,30))

[SYSUT1 defines a scratch data set used by the linkage editor.]


[SYSPRINT defines a print data set. The DCB attributes are built inas RECFM=FBA,LRECL=121.]

//GO EXEC PGM=*.LKED.SYSLMOD,COND=((5,LT,COB2),(5,LT,LKED))

[GO executes the program created by the linkage editor. CONDbypasses the step unless both the compiler and linkage editor returncompletion codes of 5 or less.]

//STEPLIB DD DSN=&LIB,DISP=SHR

[The SYS1.COB2LIB contains subroutines loaded in at run time.]

You can execute the entire procedure as follows:

// EXEC IGYWCLG//COBOL.SYSIN DD *[COBOL source statements]/*//LKED.SYSIN DD *[Any linkage editor control statements]/*//GO.ddname DD ...[Place any DD statements required by the program here.]/*

18.1.2 Linkage Editor Messages

The linkage editor issues one of the following messages when it has completed.


member ADDED AND HAS AMODE address-mode.member REPLACED AND HAS AMODE address-mode. The member

was already in the SYSLMOD data set, and the system replaces itwith the new member.

member DID NOT PREVIOUSLY EXIST BUT WAS ADDED AND HAS address-mode. You asked to replace a load module in theSYSLMOD data set, the load module was not there to replace, andso the load module was added rather than replaced. The DISPparameter on the //SYSLMOD DD statement tells you whether toadd or replace. DISP=MOD or NEW is a request to add, andDISP=OLD to replace.

MODULE HAS BEEN MARKED NOT EXECUTABLE. Although themodule is not executable, you may be able to recover by link-editingthe control section causing the problem and replacing it in the loadmodule. An unresolved external reference often causes this error.

If the member in any of the messages is TEMPNAME, it also meanssomething went wrong. When you add a load module to a library (DISP=MOD on the //SYSLMOD DD statement) and one already exists in thelibrary with the same name, the linkage editor adds the new member underthe name TEMPNAME.

18.1.3 Batch Compilation

Compilation is not a function of the linkage editor. However, batch compi-lation requires special control statements in some language processors, andthis is a natural place to describe them. With batch compilation, a singlecompilation step can compile a main program and several subroutines. Yourequest batch compilation as follows:

COBOL: Place an END PROGRAM statement following each program orsubroutine.// EXEC IGYWCLG//COBOL.SYSIN DD *[Main program]

END PROGRAM main. <== Begins in column 8.[Subroutine]

END PROGRAM name.� � �

FORTRAN: Batch compilation does not require any special controlstatements. Simply place all the FORTRAN programs, functions, orsubroutines together to compile.

PL/I: Place a PROCESS statement following each program or externalprocedure.


// EXEC IBMZCPLG//PLI.SYSIN DD *[Main program]* PROCESS NAME('name') <== Begins in column 1.[External procedure]* PROCESS

� � �

Code the NAME(‘name’) if you want each procedure to be link-edited as a separate load module. Otherwise, the system combinesall the procedures into one load module.

C/C++: Batch compilation does not require any special control state-ments. Simply place all the functions together to compile.

Assembler Language: The assembler does not do batch compilation.Assemble each program or subroutine in a separate assemble step.

18.1.4 Linkage Editor Control Statements

The linkage editor provides several control statements to combine, delete,replace, and order control sections. (Some rarely used statements are omit-ted.) Place the linkage-editor control statements before or after any objectmodules or other control statements.

Code the linkage-editor control statements in columns 2 through 71. Tocontinue a linkage-editor control statement, interrupt the statement after acomma anywhere before column 72, code a nonblank character in column72, and continue in column 16 of the next line. The following exampleillustrates a continued statement.

Col 72INCLUDE INPUT, X

DD2(ONE,TWO)

ENTRY StatementThe ENTRY statement specifies the first instruction to be executed in a loadmodule, which can be a control section name or entry name within a con-trol section. Each load module must have an entry point. If you omit theENTRY statement, the system assumes the first byte of the first control sec-tion is the entry point unless an assembler-produced END statement speci-fies an entry point. Code the ENTRY statement as

ENTRY name

[The name must be the name of an instruction, not data. ENTRYmust begin in column 2 or beyond.]

ENTRY SUB1

[Execution begins at SUB1.]


The entry names for the various language processors are as follows:

COBOL PROGRAM-ID name.FORTRAN MAINPL/I PLISTARTC/C++ CEESTARTAssembler CSECT name

The system does not retain the entry point when the load module islink-edited again. If the main routine is not the first routine in the loadmodule, include the ENTRY statement each time you link-edit the loadmodule.

INCLUDE StatementThe INCLUDE statement specifies additional sources of linkage-editorinput to be included. INCLUDE is most often used to include an old loadmodule when subroutines within it must be recompiled and link-edited.The linkage editor first processes the new subroutine and then includes theentire old load module except the subroutines being replaced.

� For a sequential data set, code INCLUDE asINCLUDE ddname,ddname,...,ddname

� For a partitioned data set, you must name at least one member:INCLUDE ddname(member,...,member),ddname(...),...

The ddname is the name of a DD statement describing the data toinclude. It can be either a partitioned or sequential data set containing bothobject modules and control statements, or a partitioned data set containingjust load modules. Multiple INCLUDE statements are permitted.

In the following example, three sequential data sets described by theINPUT1, DD1, and INPUT2 DD statements are included. Members ONE andTWO are also included from the library described by the DD2 statement,and member SQRT is included from the library described by DD3.

INCLUDE INPUT1,DD1INCLUDE INPUT2,DD2(ONE,TWO),DD3(SQRT)

The sequence of data sets and modules in the load module that is cre-ated does not necessarily follow the order of the INCLUDE statements. TheORDER statement described in a later section can specify the order.

LIBRARY StatementThe LIBRARY statement names control sections to be looked up in librariesother than the libraries described by the //SYSLIB DD statement. LIBRARYalso allows external references to go unresolved for a particular run or for


the life of the load module. (The NCAL option on the EXEC statement can-cels all automatic call lookups.) Code the LIBRARY statement in the fol-lowing ways.

LIBRARY ddname(member,...,member),ddname(..),...

[Include a DD statement with the given ddname to describe thelibrary. Supply the member names of each control section to look upin the library.]

LIBRARY (name,...,name)

[The control sections named are left unresolved for the run and noautomatic call lookup takes place for the named control sections.For example, a program might refer to a subroutine in a library butmight not call it during a particular run. Since the program will notcall the subroutine, you can leave the reference unresolved to savestorage by not including the subroutine. (You should also code LETon the EXEC statement.)]

LIBRARY *(name,...,name)

[Appending the asterisk to the names causes the external referencesto go unresolved for the entire life of the load module.]

You can code all the preceding parameters on one or several LIBRARYstatements.

LIBRARY DD1(SUB1,SUB2),(HALT),*(ALTO)

[SUB1 and SUB2 are looked up in the library described by the//DD1 DD statement. The linkage editor makes no automatic sub-routine lookup for HALT or ALTO. Furthermore, ALTO is left un-resolved for the life of the load module.]

NAME StatementThe NAME statement marks the end of a load module, names it, and per-mits several load modules to be produced by a single link-edit step. Youoften use NAME to create a subroutine library. You can compile severalsubroutines together, adding each subroutine to the library as a separateload module. Place the NAME statement after the last object module that isto be included in the load module. Any ENTRY statements must precedethe NAME statement. Code the NAME statement as

To add: To replace:NAME name NAME name(R)

You can select any name for the load module, but since that name is theone matched in the library lookup, use the subroutine name. Code the (R) to


replace an existing subroutine in the load module. If you omit (R) for areplacement module, the new module is added and renamed TEMPNAME.

NAME SUB1

[SUB1 is added.]

NAME SUB2(R)

[SUB2 is replaced.]

REPLACE StatementThe REPLACE statement replaces one control section with another ordeletes a control section. The linkage editor automatically replaces controlsections when the new control section has the same name as the old controlsection. REPLACE can replace an old control section with one having a dif-ferent name. To replace a control section, place the REPLACE statementimmediately before the module or INCLUDE statement containing the oldcontrol section. Name the old and new control sections with the REPLACEstatement as follows:

REPLACE old-name(new-name)

[The old-name is replaced by the control section following it. Thecontrol section is assigned the new-name.]

In the next example, SUB2 is replaced by the control section describedby the //DD1 DD statement. The new control section is named SUB4.

REPLACE SUB2(SUB4)INCLUDE DD1

To delete a control section, code REPLACE as follows:

REPLACE nameREPLACE SUB6

[The SUB6 control section is deleted.)

PAGE StatementThe PAGE statement aligns a control section on a 4K page boundary. CodePAGE as

PAGE name,name,...,namePAGE SUB2,SUB4

[SUB2 and SUB4 are aligned on a 4K page boundary.]

ORDER StatementThe ORDER statement reorders the control sections in a load module. Thelinkage editor normally leaves the control sections in the order it encoun-


TEAMFLY

Team-Fly®

ters them. Virtual storage paging is more efficient if you order the controlsections to minimize paging. In the unlikely event that you would knowwhat this order is, you could use the ORDER statement to rearrange the con-trol sections. The ORDER statement orders the control sections in the orderyou list the names on the statement. The linkage editor places any namesnot appearing on the ORDER statement last. There may be multiple ORDERstatements. The general form is

ORDER name,name,...,nameORDER SUB6,SUB2,SUB3

[The control sections are placed in the order given.]

To align a control section on a 4K page boundary, add (P) to the name:

ORDER name(P),name(P),...,name(P)ORDER SUB14,SUB10(P),SUB16

[The control sections are placed in the order given and SUB10 isaligned on a 4K boundary.]

18.1.5 Creating Load Module Libraries

Suppose now that you want to compile three COBOL programs, ONE, TWO,and THREE, and retain them in load module form in a partitioned data setnamed A1000.LIB.LOAD. (Partitioned data set member names must be oneto eight alphanumeric (A to Z, 0 to 9) or national (@$#) characters, beginningwith an alphabetic (A to Z) or national character.) Use the IGYWCLG cata-loged procedure here to compile the programs and link-edit them to createthe library. You must override the //SYSLMOD DD statement to create thenontemporary data set.

// EXEC IGYWCLG,PARM.COBOL='NAME'

[You use the compile/link-edit procedure. The NAME parametertells the COBOL compiler to append linkage-editor NAME state-ments to the object modules so that they can be link-edited as sepa-rate load modules for output in a partitioned data set.]

//COBOL.SYSIN DD *[ONE source statements]

END PROGRAM ONE[TWO source statements]

END PROGRAM TWO[THREE source statements]

END PROGRAM THREE/*//LKED.SYSLMOD DD DSN=A1000.LIB.LOAD,DISP=(NEW,CATLG),// SPACE=(1024,(100,30,10)),// STORCLAS=PDSLIB,DSNTYPE=LIBRARY


[The A1000.LIB.LOAD data set is created, and the load modules areadded as members named ONE, TWO, and THREE. It is a PDSE.]

The A1000.LIB.LOAD library can also be included as input when anyCOBOL program is compiled as shown in the following example.

// EXEC IGYWCLG//COBOL.SYSIN DD *[Main COBOL source statements.]/*//LKED.DD1 DD DSN=A1000.LIB.LOAD,DISP=SHR//LKED.SYSIN DD *ENTRY THING

[Although the main routine is still loaded first, it is a good idea totell the linkage editor the entry point.]

INCLUDE DD1

[The A1000.LIB.LOAD library is included as additional input.]

/*

18.1.6 Creating Load Modules for Program Development

Now compile a COBOL program and its subroutines and link-edit them intoa single load module. Name the library A1000.PGM.LOAD and the loadmodule as THING. The following JCL does this.

// EXEC IGYWCLG

[You use the compile/link-edit/go procedure.]

//COBOL.SYSIN DD *[Main COBOL source statements][ONE source statements][TWO source statements][THREE source statements]/*

[When the system encounters no END PROGRAM statement, itplaces all the modules into a single load module.]

//LKED.SYSLMOD DD DSN=A1000.PGM.LOAD(THING),DISP=(NEW,CATLG),// UNIT=SYSDA,SPACE=(1024,(100,30,10))

[The A1000.PGM.LOAD data set is created to contain the load mod-ule named THING. It is a PDS.]

//GO.IN DD DSN=A1000.JUNK.DATA,DISP=SHR[Place any DD statements for the GO step here.]


You could place other programs in the A1000.PGM.LOAD library aslong as you give them different member names. You can now execute theprogram in a single step.

//RT452216 JOB (45992),'SMITH',CLASS=A//GO EXEC PGM=THING//STEPLIB DD DSN=A1000.PGM.LOAD,DISP=SHR

[The //STEPLIB DD statement describes the data set containing theprogram to execute. The //JOBLIB DD statement could have beenused as well.]

//IN DD DSN=A1000.JUNK.DATA,DISP=SHR[Place any DD statements for the GO step here.]

Now suppose that the ONE subroutine contains an error and must bereplaced. You can compile just the ONE subroutine and replace it in theload module as follows:

// EXEC IGYWCLG//COBOL.SYSIN DD *[ONE source statements]/*//LKED.SYSLMOD DD DSN=A1000.PGM.LOAD(THING),DISP=OLD,SPACE=,UNIT=

[SYSLMOD is again overridden to describe the data set that is to con-tain the new load module. Since THING is already a member ofA1000.PGM.LOAD, it is replaced by the new load module. By select-ing a different name, the new load module would be added ratherthan replace the old load module. You code the SPACE= parameterto nullify the SPACE parameter on the overridden SYSLMOD state-ment so that it does not change the secondary allocation specifiedwhen A1000.PGM.LOAD was created. You can write the UNIT=because you want the system to locate the data set from the catalog.]

//LKED.DD1 DD DSN=A1000.PGM.LOAD,DISP=SHR

[The //DD1 DD statement describes the library containing the oldload module.]

//LKED.SYSIN DD *ENTRY THING

[The main routine is no longer loaded first, and so you must tell thelinkage editor that THING is the entry point.]

INCLUDE DD1(THING)

[The old load module is included as additional input.]

/*//GO.IN DD DSN=A1000.JUNK.DATA,DISP=SHR


18.2 THE LOADER

Rarely Used

The loader performs all the functions of the linkage editor except for pro-ducing a load module, combining the link-edit and go steps into a singleload and go step. The loader does not create an object module, but buildsthe executable program in virtual storage. The advantage of the loader isthat it saves roughly half the cost of the linkage editor step. The disadvan-tage is that you must recompile the entire program each time rather thanjust the functions or subroutines that you change. Consequently, the loadermay cost more to use.

The JCL to execute the loader is illustrated in the following COBOLcompile and go procedure. The loader has no //SYSLMOD DD statementand ignores any linkage-editor control statements.

//IGYWCG PROC CMP='SYS1.COB2COMP',LIB='SYS1.COB2LIB'//COBOL EXEC PGM=IGYCRCTL,PARM='OBJECT',REGION=1024K//STEPLIB DD DSN=&CMP,DISP=SHR//SYSPRINT DD SYSOUT=A//SYSLIN DD DSN=&&LOADSET,DISP=(MOD,PASS),// UNIT=SYSDA,SPACE=(TRK,(3,3))//SYSUTn DD UNIT=VIO,SPACE=(32000,(30,30))//GO EXEC PGM=LOADER,PARM='loader-options/program-options',// COND=(5,LT,COB2),REGION=1024K

[The MAP, NCAL, and LET loader options are identical to those ofthe linkage editor. You usually code MAP and LET. Code EP=nameto specify the entry point. Notice that the loader parameters are sep-arated from the GO step parameters by the slash.]

//SYSLIB DD DSN=&LIB,DISP=SHR

[SYSLIB points to the library used for the automatic call lookup.]

//SYSLIN DD DSN=*.COB2.SYSLIN,DISP=(OLD,DELETE)

[SYSLIN describes the primary input; the output from the compilerconcatenated with the input stream.]

//SYSLOUT DD SYSOUT=A

[SYSLOUT is used for error and warning messages.]

You might execute this procedure as follows:

// EXEC IGYWCG//GO.ddname DD ...[Place any DD statement required by the program here.]


EXERCISES

1. Compile the program from Chapter 5 using the compile and link-editprocedure and create a partitioned data set named userid.PGMS.LOAD,adding the program as a member named COPY.

2. Make up an instream procedure to execute the COPY program. Executethe instream procedure to ensure that the program works correctly.

3. Add the following subroutine to userid.PGMS.LOAD as a membernamed SUB. Use the compile/link-edit cataloged procedure.

� COBOL:IDENTIFICATION DIVISION.PROGRAM-ID. SUB.ENVIRONMENT DIVISION.CONFIGURATION SECTION.DATA DIVISIONLINKAGE SECTION.PROCEDURE DIVISION.BEGIN-PROGRAM.

DISPLAY "I HAVE BEGUN."EXIT PROGRAM

� FORTRAN:100 SUBROUTINE200 WRITE (6,300)300 FORMAT(1H ,13HI HAVE BEGUN.)400 RETURN500 END

� PL/I:SUB: PROC;PUT SKIP LIST('I HAVE BEGUN.');END SUB;

� C/C++:#include <stdio.h>#include <stdlib.h>void sub(){printf("I have begun.\n");return;

}

4. Modify the program from Chapter 5 to add one statement calling thesubroutine SUB as the first statement in the program as shown:

COBOL: CALL “SUB”FORTRAN: nnnnn CALL SUB


PL/I: CALL SUB;C/C++: sub();

5. Recompile the modified program and replace member COPY inuserid.PGMS.LOAD with it. Include the member SUBS. Execute thisnew program with the instream procedure to make sure that it workscorrectly.


CHAPTER 19

IBM UTILITY PROGRAMS

Essential

Utility programs provide a variety of useful functions, such as copying datasets, listing them, and maintaining source libraries. Although not a part ofJCL, they are an important part of z/OS, and knowledge of them is impor-tant to all programmers.

IBM supplies three sets of utility programs that you can run in batch: thearchaic IBM Utilities, the DFSORT ICETOOL utility, and the VSAM IDCAMSutility. You cannot use the IBM Utilities on VSAM data sets whereas bothICETOOL and IDCAMS, far easier to use, operate on normal and VSAM datasets. IDCAMS also creates VSAM files as described in Chapter 17.

ISPF as described in Chapter 21 has many utility functions that youinvoke on-line. IBM also provides an optional set of utility programs calledData Facility Data Set Services (DFDSS). DFDSS manages direct-access stor-age space and is intended more to operate on all data sets in a volume or alldata sets having some SMS management class rather than on individualdata sets. You can use DFDSS interactively from a terminal similar to theway ISPF is used, or you can invoke it through JCL. DFDSS is easy to useand provides several facilities not in the other utility programs, such asreleasing unused space in data sets, combining data set extents, consolidat-ing free space on volumes, and backing up and restoring data sets. DFDSScan convert data sets to be SMS-managed data sets. It can also back up andrestore, compress, and otherwise provide for the management of SMS-managed data sets. It is intended more for site management than for indi-vidual application programmer use and is not described in this book.

19.1 THE IDCAMS UTILITY

Essential

The IDCAMS utility operates on normal data sets as well as VSAM datasets. The IDCAMS facilities for VSAM data sets are described in Chapter 17.

331

The operations on normal data sets are described here. You invoke IDCAMSwith the following JCL.

//stepname EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A

[This prints the IDCAMS messages.]

//ddname DD DSN=...

[Some commands require one or two DD statements to describeinput or output data sets.]

//SYSIN DD *[Command statements]/*

Code the command statements in columns 2 through 72. Continue acommand statement by coding a hyphen after a complete subparameter,leaving at least one blank between the subparameter and the hyphen.

REPRO - But not REPRO-INFILE(INDD) INFILE(INDD)

IDCAMS returns the standard IBM completion codes. If a data set ispassword-protected, append /password to the ddname or data set name to specify the password. For example, INFILE(ddname/password) or OUT-DATASET(data-set-name/password).

19.1.1 Copy a Sequential Data Set

The REPRO command copies sequential (but not partitioned) data sets.However, you can copy individual members of a partitioned data set.

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//in-ddname DD DSN=...

[This describes the input data set.]

//out-ddname DD DSN=...

[This describes the output data set.]

//SYSIN DD *REPRO -INFILE(in-ddname) -

[This names the DD statement describing the data set to copy.]

OUTFILE(out-ddname)

[This names the DD statement describing the output data set.]

/*


You can code the COUNT and SKIP options to control which records tocopy.

REPRO -INFILE(in-ddname)-OUTFILE(out-ddname) -COUNT(n)-

[Copy the first n records.]

SKIP(n)

[Skip n records before starting the copy.]

The following statement copies 100 records from the data set describedby the //INDD DD statement, skipping the first four records, and writesthem to the data set described by the //OUTDD DD statement.

REPRO INFILE(INDD) OUTFILE(OUTDD) COUNT(100) SKIP(4)

19.1.2 Listing Catalog Entries

The LISTCAT command lists catalog entries. You code it as follows:

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *LISTCAT -ENTRIES (data-set-name data-set-name ... data-set-name) ALL

[This lists all the catalog information for the data sets named.]

/*

The following statement lists all the catalog information for theA1000.TEST.DATA.

LISTCAT ENTRIES(A1000.TEST.DATA) ALL

You can restrict the information printed by replacing ALL with one ofthe following. (ALL is the only valid option for tape.)

NAME prints only the name and data set type.

HISTORY prints only the name, data set type, creation date, and expi-ration dates. For SMS-managed data sets, IDCAMS also lists the lastbackup date.

VOLUME prints the same information as HISTORY, plus the volumeserial numbers and device types on which the data set is stored.

ALLOCATION prints the same information as VOLUME plus all theinformation about the space allocation.

IBM UTILITY PROGRAMS 333

19.1.3 Printing Sequential Data Sets

The PRINT command prints sequential data sets.

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//ddname DD DSN=...

[This describes the data set to print.]

//SYSIN DD *PRINT -INFILE(ddname) -

[This names the DD statement of the data set to print.]

CHAR

[CHAR prints each record in character form. Alternatively, you cancode HEX to print in hexadecimal or DUMP to print in both characterand hexadecimal. IDCAMS prints the hexadecimal dump on twolines with each column representing a single hexadecimal character.]

/*

The following statement prints the data set described by the //DDIN DDstatement in hexadecimal format.

PRINT INFILE(DDIN) HEX

The COUNT and SKIP options control which records to print.

PRINT -INFILE(ddname) -CHAR -COUNT(n) -

[Print the first n records.]

SKIP(n)

[Skip n records before starting to print.]

The following statement prints the data set described by the //DDIN DDstatement in hexadecimal format. It skips the first 10 records and thenprints the next 100 records.

PRINT INFILE(DDIN) HEX COUNT(100) SKIP(10)

19.1.4 Renaming Data Sets

The ALTER command renames and recatalogs data sets. In addition, it canchange many data set attributes, although this is beyond the scope of thisbook. ALTER operates on all types of data sets, including partitioned.


TEAMFLY

Team-Fly®

ALTER old-data-set-name NEWNAME(new-data-set-name)

[This renames the entire sequential or partitioned data set.]

ALTER data-set-name(old-member) NEWNAME(data-set-name(new-member))

[This renames a member of a partitioned data set.]

Here is an example:

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *ALTER A1000.TEMP.DATA NEWNAME(A1000.TEST.DATA)

[IDCAMS renames A1000.TEMP.DATA as A1000.TEST.DATA.]

ALTER A1000.PGM.LOAD(COMP) NEWNAME(A1000.PGM.LOAD(COMPIT))

[IDCAMS renames member COMP as COMPIT in data setA1000.PGM.LOAD.]

/*

19.1.5 Deleting Cataloged Data Sets

The DELETE command deletes and uncatalogs cataloged data sets.

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *DELETE data-set-name

[This deletes and uncatalogs an entire sequential or partitioned dataset.]

DELETE data-set-name(member)

[This deletes a member of a partitioned data set.]

DELETE A1000.TEMP.DATADELETE A1000.PGM.LOAD(COMPIT)/*

You can also code the PURGE and ERASE options.

//SYSIN DD *DELETE data-set-name -

PURGE -

[PURGE deletes the entry regardless of the retention date. NOPURGEis the default and deletes the data set only if the retention date hasexpired.]


ERASE

[ERASE overwrites the deleted item with binary zeros and shouldbe used for all sensitive data. NOERASE is the default.]

/*

For a VSAM data set, you can delete any item—data set, index, alternateindex, or whatever.

//SYSIN DD *DELETE data-set-name -

ALTERNATEINDEX -

[Code this if you want the alternate index and its path deleted forthe data set.]

PATH -

[Code this to delete the alternate index path.]

CLUSTER

[Code this only if you want everything associated with the data setdeleted—its base cluster, indexes, and alternate indexes.]

/*

19.2 THE ICETOOL UTILITY PROGRAMS

Essential

The DFSORT ICETOOL utilities are both easy to use and very helpful. Youinvoke them with the following JCL:

//jobname JOB …//stepname EXEC PGM=ICETOOL//TOOLMSG DD SYSOUT

[ICETOOL writes its messages here. RECFM=FBA,LRECL=121 arebuilt in.]

//DFSMSG DD SYOUT=A

[DFSORT messages are written here. RECFM=FBA,LRECL=121 arebuilt in.]

//in-ddname DD DSN=data-set-name,DISP=SHR

[You usually must include a DD statement describing the input dataset.]


//TOOLIN DD *

[RECFM=FB,LRECL=80 are built in.]

[ICETOOL statements]/*

You code ICETOOL statements in columns 1 to 72. To continue a state-ment, place a dash (-) after any complete operand and continue the state-ment in any column (1 to 72) on the next line.

COPY FROM(INDD) -TO(OUTDD)

You can code several ICETOOL statements in one job step.

UNIQUE FROM(INDD) ON(1,10,CH)COPY FROM(INDD) TO(INDD)

Several ICETOOL statements require you to specify fields in the follow-ing form:

ON(start,length,format)

The start is the starting byte position. For a fixed-length record, the firstbyte is 1. For a variable-length data set, the first data byte is 5. The length isthe length of the field in bytes. The format is the format of the field asshown in Table 19.1.

Most statements let you define several fields in one statement:

UNIQUE FROM(INDD) ON(1,10,CH) ON(11,4,BI) ON(15,10,CH)

19.2.1 COPY Data Sets

To copy a data set, code the COPY statement as follows:

COPY FROM(in-ddname) TO(out-ddname)

[You can write 1 to 10 TO(out-ddname) parameters to copy theFROM data set to as many as 10 output data sets. Include a //out-ddname DD statement for each output data set.]


TABLE 19.1 Formats for ICETOOL

BI Unsigned binary, 1–256 bytesFI Signed fixed point, 1–256 bytesPD Signed packed decimal, 1–32 bytesZD Signed zoned decimal, 1–32 bytesCSF or FS Signed numeric with optional leading floating point, 1–16 bytesCH Character, 1–256 bytes

19.2.2 Select Records

To select and copy records, code the SELECT statement as follows:

SELECT FROM(in-ddname) TO(out-ddname) ON(start,length,format) option

ICETOOL makes one pass of the data to read the in-ddname data set andcount occurrences of values in the field specified. Then it makes a secondpass to select the records based on the field counts and write them into theout-ddname data set. Code one of the following options to select therecords.

ALLDUPS selects records in which a value in the field occurs more thanonce.

NODUPS selects records in which a value in the field occurs only once.

HIGHER(n) selects records in which a value in the field occurs morethan n times (n can be 1 to 99).

LOWER(n) selects records in which a value in the field occurs less thann times (n can be 1 to 99).

EQUAL(n) selects records in which the field value occurs exactly ntimes (n can be 1 to 99).

FIRST selects only the first record of a group in which the field valueoccurs more than once.

LAST selects only the last record of a group in which the field valueoccurs more than once.

The following selects only records in which the binary field in columns4 to 7 contains a value found in no other record.

SELECT FROM(INDD) TO(OUTDD) ON(4,4,BI) NODUPS

You can specify 1 to 10 ON parameters. ICETOOL treats the multiplefields as if they were one long field for counting duplicate values. Here,ICETOOL looks at columns 10 to 13 and 20 to 23 as if they were one fieldand selects records in which these eight columns contain a character stringnot found in other records.

SELECT FROM(INDD) TO(OUTDD) ON(10,4,CH) ON(20,4,CH) NODUPS

19.2.3 Count Records

To count and print the number of records in a data set, code the COUNTstatement as follows:

COUNT FROM(in-ddname)


19.2.4 Print Ranges for Numeric Data

To print the minimum, maximum, average, and total for numeric fields,code the STATS statement as

STATS FROM(in-ddname) ON(start,length,format)

You can code from 1 to 10 ON parameters to gather statistics on multi-ple fields. The format must be numeric. CH is not allowed.

19.2.5 Print Count of Unique Values in a Field

To print a count of the unique values in a field, that is, a count of those val-ues that occur only once, code the UNIQUE statement as

UNIQUE FROM(in-ddname) ON(start,length,format)

Code only one ON parameter.

19.2.6 Print Values in a Data Set

To print the values of fields within a data set, code the DISPLAY statementas

DISPLAY FROM(in-ddname) ON(start,length,format) LIST(ddname)

Include a //ddname DD statement to print the output. You can code 1 to20 ON parameters to print multiple fields. DISPLAY has many otheroptions that give it the power of a report writer, but these are beyond thescope of this book.

19.2.7 Print the Number of Times Values Occur

To print the number of times values within a field occur, code the OCCURSstatement as follows:

OCCURS FROM(in-ddname) ON(start,length,format) LIST(ddname)

ICETOOL prints the number of times each unique value within the fieldoccurs. Include a //ddname DD statement to print the output. You can code1 to 10 ON parameters to display values for multiple fields.

You can also display the value and counts for fields meeting selectioncriteria by including an option. (The default is to display all unique values.)

OCCURS FROM(in-ddname) ON(start,length,format) LIST(ddname) option


The option can be one of the following:

ALLDUPS displays the value and count for field values that occur morethan once.

NODUPS displays the value and count for field values that occur onlyonce.

HIGHER(n) displays the value and count for field values that occurmore than n times.

LOWER(n) displays the value and count for field values that occur lessthan n times.

EQUAL(n) displays the value for field values that occur exactly n times.

This displays records that have characters in columns 1 to 10 found inno other records.

OCCURS FROM(INDD) ON(1,10,CH) LIST(PRINTIT) NODUPS

19.2.8 Print a Count of Values within a Specified Range

RANGE is like OCCURS, except you can specify criteria for the field forcounting. That is, ICETOOL prints a count of records meeting criteria. Youcode RANGE as

RANGE FROM(in-ddname) ON(first,length,format) options

The format must be numeric. CH is not allowed. The option can be oneof the following:

HIGHER(n) prints a count of the records with the field having a valuehigher than n.

LOWER(n) prints a count of the records with the field having a valuelower than n.

HIGHER(n1) LOWER(n2) prints a count of the records with the fieldhaving a value higher than n1 and lower than n2.

EQUAL(n) prints a count of the records with the field having a valueequal to n.

NOTEQUAL(n) prints a count of the records with the field having avalue not equal to n.

This prints a count of the records in which the binary field in columns1 to 4 contains a value of 100 through 200.

RANGE FROM(INDD) ON(1,4,BI) HIGHER(99) LOWER(201)


19.2.9 Print Records Having Invalid Values in a Decimal Field

To print a message identifying invalid decimal data in a field, code the VERIFY statement as

VERIFY FROM(in-ddname) ON(start,length,format)

The format must be PD or ZD. You can code 1 to 10 ON parameters.

19.2.10 Sorting Records

The full sorting powers of DFSORT are described in Chapter 20. However,ICETOOL also has a SORT statement that lets you sort input records. Youwrite it as

SORT FROM(in-ddname) TO(out-ddname) USING(xxxx)

The in-ddname is the ddname of the input data set. The out-ddname is theddname of the output data set. The xxxx is appended to CNTL to name theDD statement containing the DFSORT control statements as described inChapter 20. The full ddname is xxxxCNTL.

// EXEC PGM=ICETOOL//TOOLMSG DD SYSOUT//DFSMSG DD SYOUT=A//DDIN DD DSN=A1000.TEST.DATA,DISP=SHR//DDOUT DD DSN=A1000.SORTED.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,RECFM=FB,LRECL=80,// SPACE=(0,(100,20))//SORTCNTL DD DSN=A1000.SORTCNTL.DATA,DISP=SHR

[You would store the DFSORT control statements in this data set.]

//TOOLIN DD *SORT FROM(DDIN) TO(DDOUT) USING(SORT)/*

19.3 THE IBM UTILITY PROGRAMS

Sometimes Used

Most of the IBM Utility programs perform functions easier done byIDCAMS, TSO, or ISPF. Others perform limited functions for the operatorsor systems programmers. All these are omitted here. The IBM utility pro-grams were anything but user-friendly when IBM wrote them over a third ofa century ago, and they have gone virtually unchanged since. You’ll proba-bly use them only when there is no alternative or when it is necessary to


perform a function that will run on all z/OS installations. For example,many data sets and applications sent from one installation to another usethe IBM utility programs for installation because the utility programs are apart of the operating system and all installations have them. The only twoIBM utility programs you are likely to use are

IEBCOPY copies partitioned data sets and compresses a PDS.

IEBUPDTE maintains libraries containing 80-byte records—primarilyprocedures, source, and macro libraries for the system.

The obsolete utility programs and their replacements are as follows:

IEBCOMPR compares data sets. Use the SUPERC utility of ISPF, whichcan be run on-line or in batch.

IEBGENER copies sequential data sets. Use the IDCAMS REPRO state-ment or the ICETOOL COPY statement.

IEBPTPCH prints and punches data sets. Use the IDCAMS PRINT state-ment.

IEHLIST lists direct-access volume information. Use the IDCAMS LISTCAT statement.

IEHMOVE copies or moves data sets. Use the IDCAMS REPRO state-ment to copy sequential data sets, and IEBCOPY to copy partitioneddata sets. Or use the ICETOOL COPY statement.

IEHPROGM maintains data sets. Use the IDCAMS DELETE and ALTERstatements.

You execute the IBM utility programs with the same general JCL state-ments.

//stepname EXEC PGM=program-name


[Prints the utility messages. LRECL=121,RECFM=FBA are built in.]

//SYSUT1 DD ...

[If needed, describes an input data set.]

//SYSUT2 DD ...

[If needed, describes an output data set.]

//SYSIN DD *

[RECFM=FB,LRECL=80 is built in.]

[Control statements]/*


Code the control statements in columns 2 through 71. To continue acontrol statement, break the statement at a comma, code a nonblank char-acter in column 72, and continue the statement in column 16 of the follow-ing line. The following example illustrates a continued statement.

Col 72COPY INDD=YEAREND, X

OUTDD=NEWYEAR

The completion codes are also the IBM standard.

19.3.1 IEBCOPY: Copy Partitioned Data Sets

Do not use IEBCOPY for SMS-managed data sets—use DFDSS for them.IEBCOPY performs the following functions:

� Copies a partitioned data set to a direct-access volume. Often used toexpand the space allocation or change the directory space.

� Copies a partitioned data set, converting it to a sequential data set(termed unloading). Used to save a partitioned data set on tape or cre-ate a backup copy.

� Copies an unloaded partitioned data set to a direct-access volume(termed loading). Used to restore a partitioned data set from tape.

� Compresses a PDS partitioned data set by copying it in place toreclaim the space occupied by deleted members.

� Converts a PDS to a PDSE or back. To do this, just code DSNTYPE=LIBRARY on the DD statement for the PDSE and DSNTYPE=PDS onthe DD statement for the PDS.

ISPF performs many of the functions of IEBCOPY and is much easier touse. If it is available, you are usually better using it than IEBCOPY. IEB-COPY has the following general form:

//stepname EXEC PGM=IEBCOPY//SYSPRINT DD SYSOUT=A//SYSUT1 DD DSN=old-data-set-name,DISP=SHR

[SYSUT1 points to the input data set, which cannot be concatenated.]

//SYSUT2 DD DSN=new-data-set-name,DISP=(..),…

[Describes the output data set.]

For all but the compress operation, you can increase the space allocatedto the output data set or reblock it. If the DCB parameter is not coded on the//out-ddname DD statement, the blocking is unchanged. Reblock the dataset by specifying the BLKSIZE subparameter.


Unload a Partitioned Data SetThe following example unloads a cataloged partitioned data set namedA1000.TEST.LOAD tape number 002345.

//STEP1 EXEC PGM=IEBCOPY//SYSPRINT DD SYSOUT=A//SYSUT1 DD DSN=A1000.TEST.LOAD,DISP=SHR//SYSUT2 DD DSN=TEST,DISP=(NEW,KEEP),UNIT=TAPE,VOL=SER=002345

Load a Partitioned Data SetThe following example loads the TEST data set from tape to disk vol-ume PACK12. Assume that A1000.TEST.LOAD does not already exist onPACK12.

//STEP1 EXEC PGM=IEBCOPY//SYSPRINT DD SYSOUT=A//SYSUT1 DD DSN=TEST,DISP=OLD,UNIT=TAPE,VOL=SER=002345//SYSUT2 DD DSN=A1000.TEST.LOAD,DISP=(NEW,CATLG),// DSNTYPE=PDSE,DATACLAS=PERMLIB,STORCLAS=A1268,// AVGREC=K,SPACE=(0,(100,50,10))

Copy a Partitioned Data Set as a Partitioned Data SetThe following example copies the A1000.TEST.LOAD data set from PACK12to PACK10, expanding the directory space. It then deletes the old copy andrenames the new copy to be A1000.TEST.LOAD.

//STEP1 EXEC PGM=IEBCOPY//SYSPRINT DD SYSOUT=A//SYSUT1 DD DSN=A1000.TEST.LOAD,DISP=SHR

[You could delete the old copy with DISP=(SHR,DELETE), but to besafe, do this in a separate step.]

//SYSUT2 DD DSN=$$$$$$$$=(NEW,CATLG),

[You give the copy a unique data set name.]

// UNIT=SYSDA,VOL=SER=PACK10,// AVGREC=K,SPACE=(0,(10,5,50),RLSE)

[You give the copy a large directory.]

Now use IDCAMS to delete the old copy and rename the new copy.

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *DELETE A1000.TEST.LOAD

[This deletes and uncatalogs the old data set.]


TEAMFLY

Team-Fly®

ALTER $$$$$$$$ NEWNAME(A1000.TEST.LOAD)

[This renames the new data set.]

/*

Select and Exclude Members in a CopyIn all of the previous copy operations, the SELECT statement can select spe-cific members of a partitioned data set to copy, or the EXCLUDE statementcan select specific members to exclude from a copy. SELECT and EXCLUDEare mutually exclusive. Place any SELECT or EXCLUDE statements imme-diately after the COPY statement. There can be several SELECT or EXCLUDEstatements. You can either write one statement and continue it onto severallines or write separate statements on each line.

COPY INDD=...SELECT MEMBER=(member,member,...,member)

[IEBCOPY copies only the named members.]

SELECT MEMBER=(SUB1,SUB2,SUB3)SELECT MEMBER=((member,newname),(member,newname),...)

[IEBCOPY copies the member and assigns it a new name.]

SELECT MEMBER=((CALCIT,SUB4),(DOIT,SUB5))

[IEBCOPY copies member CALCIT and renames it SUB4. It alsocopies member DOIT and renames it SUB5.)

SELECT MEMBER=((member,,R),(member,,R),...)

[The copied member replaces an identically named member in theoutput data set.]

SELECT MEMBER=((SUB8,,R),(SUB9,,R))EXCLUDE MEMBER=(member,member,...,member)

[IEBCOPY copies all members except those named.]

EXCLUDE MEMBER=(SUB20,SUB21,SUB22)

Compress a Partitioned Data SetYou need to compress only a PDS, not a PDSE. You can’t code SELECT andEXCLUDE for a compress operation. The following example compresses theA1000.TEST.LOAD data set. Since the input and output data sets are thesame, you must name the ddname with a COPY statement.

//STEP1 EXEC PGM=IEBCOPY//SYSPRINT DD SYSOUT=A//INOUT DD DSN=A1000.TEST.LOAD,DISP=OLD//SYSIN DD *COPY INDD=INOUT,OUTDD=INOUT/*


To release any excess space, code the //INOUT DD statement as

//INOUT DD DSN=A1000.TEST.LOAD,DISP=OLD,SPACE=(,,RLSE)

19.3.2 IEBUPDTE: Maintain Source Libraries

IEBUPDTE creates and updates a sequential or partitioned data set contain-ing source data with record lengths of 80 bytes or less. You usually performthe functions of IEBUPDTE with a text editor, such as ISPF. The main use forIEBUPDTE today is to distribute source libraries to different installations. Italso updates IBM source libraries such as the cataloged procedure libraries.The source libraries normally contain 80-character lines in which columns73 to 80 contain sequential numbers. IEBUPDTE has the following generalform:

//stepname EXEC PGM=IEBUPDTE,PARM=NEW or MOD

[NEW specifies that all the input comes from the input stream. Don’tcode a SYSUT1 DD statement for it. MOD, the default if you omitPARM, specifies that the input comes from both the input stream(control statements and data) and the SYSUT1 data set (data only).]


[LRECL=121,RECFM=FBA are built in.]

//SYSUT1 DD ...

[Specifies the input data set. Needed for PARM=MOD but not forPARM=NEW.]

//SYSUT2 DD ...

[Specifies the output data set. Not required for updating in place.]

//SYSIN DD *[Control statements]/*

The control statements are the following. (Begin the ./ in column 1.)

Copy from Input Stream to Partitioned Data SetThe ADD statement precedes lines in the job stream and adds these lines asa member or a data set of the SYSUT2 data set.

// EXEC PGM=IEBUPDTE,PARM=NEW//SYSPRINT DD SYSOUT=A//SYSUT2 DD DSN=pds-data-set-name,DISP=OLD

[If the partitioned data set already has a member of this name, it isreplaced.]


//SYSIN DD *./ ADD NAME=member,LIST=ALL[Lines of data to add as the first member.]./ ADD NAME=member,LIST=ALL[Lines of data to add as the second member.]

[Add as many members as you wish in the same step.]

/*

The following example creates a PDSE named A1000.PDS.TEXT to con-tain 80-column lines. Two members are added, ONE and TWO.

//STEP1 EXEC PGM=IEBUPDTE,PARM=NEW//SYSPRINT DD SYSOUT=A//SYSUT2 DD DSN=A1000.PDS.TEXT,DISP=(NEW,CATLG),// STORCLAS=PERSLIB,// RECFM=FB,LRECL=80,DSNTYPE=LIBRARY,// AVGREC=K,SPACE=(0,(10,5,10))//SYSIN DD *./ ADD NAME=ONE,LIST=ALL[Place member ONE data here]./ ADD NAME=TWO,LIST=ALL[Place member TWO data here]/*

Copy from the Input Stream to Sequential Data Set// EXEC PGM=IEBUPDTE,PARM=NEW//SYSPRINT DD SYSOUT=A//SYSUT2 DD DNS=sequential-data-set-name,DISP=NEW or OLD//SYSIN DD *./ ADD LIST=ALL[Lines of data to store as the sequential data set.]/*

The following example copies the member named ONE from theA1000.PDS.TEXT data set to create a sequential data set on tape.

//STEP1 EXEC PGM=IEBUPDTE,PARM=NEW//SYSPRINT DD SYSOUT=A//SYSUT1 DD DSN=A1000.PDS.TEXT,DISP=SHR//SYSUT2 DD DSN=SEQT,DISP=(NEW,KEEP),// UNIT=TAPE,VOL=SER=003322,// RECFM=FB,LRECL=80//SYSIN DD *./ REPRO NEW=PS,NAME=ONE,LIST=ALL/*

Copy from the SYSUT1 Data Set to Partitioned Data Set// EXEC PGM=IEBUPDTE,PARM=MOD//SYSPRINT DD SYSOUT=A


//SYSUT1 DD DSN=pds-data-set-name,DISP=OLD//SYSUT2 DD DNS=pds-data-set-name,DISP=NEW or OLD

[The SYSUT2 partitioned data set must not already have one of themember names you are adding.]

//SYSIN DD *./ ADD NAME=member,LIST=ALL./ ADD NAME=member,LIST=ALL

[You can add as many members as you wish in the same step.]

/*

Copy Member from Partitioned Data Set to Sequential Data Set// EXEC PGM=IEBUPDTE,PARM=MOD//SYSPRINT DD SYSOUT=A//SYSUT1 DD DSN=pds-data-set-name,DISP=OLD//SYSUT2 DD DNS=sequential-data-set-name,DISP=OLD or NEW//SYSIN DD *./ ADD NAME=member,NEW=PS,LIST=ALL

[NEW=PS tells the system you are changing the organization frompartitioned to sequential.]

/*

Copy Sequential Data Set to Member of Partitioned Data Set// EXEC PGM=IEBUPDTE,PARM=MOD//SYSPRINT DD SYSOUT=A//SYSUT1 DD DSN=sequential-data-set-name,DISP=OLD//SYSUT2 DD DNS=pds-data-set-name,DISP=OLD or NEW//SYSIN DD *./ ADD MEMBER=member,NEW=PO,LIST=ALL

[MEMBER gives a name to the member you are adding. NEW=POtells the system you are changing the organization from sequentialto partitioned.]

/*

19.3.3 REPL Statement

REPL is similar to ADD, but it replaces rather than adds. All this means isthat if the member does not exist in the output data set, the step is termi-nated. You can place ADD and REPL in the same job step.

./ REPL NAME=member,LIST=ALL[Lines of data to replace the existing member.]

To renumber the new lines, follow the ADD or REPL statement with asingle NUMBER statement. NEW1 specifies the first sequence number and


INCR the increment. IEBUPDTE numbers the source statements in columns73 to 80. It stores the numbers with leading zeros, but you need not code theleading zeros. NEW1=00000460 is the same as NEW1=460.

./ ADD or REPL …

./ NUMBER NEW1=first,INCR=increment[Place new lines to be added here.]

19.3.4 CHANGE Statement

The CHANGE statement is also similar to ADD and REPL, but it updates themember or sequential data set described by the SYSUT2 DD statement.CHANGE lets you add, change, delete, or renumber lines in the originaldata set.

To delete lines in a member or sequential data set, place a DELETE state-ment after the CHANGE statement and give starting and ending line num-bers with SEQ1 and SEQ2.

./ CHANGE NAME=member,LIST=ALL

./ DELETE SEQ1=n,SEQ2=m

You can renumber the lines of a member or sequential data set by placing one or more NUMBER statements after the CHANGE statement.IEBUPDTE renumbers the lines from SEQ1 through SEQ2 as specified byNEW1 and INCR.


./ NUMBER SEQ1=start,SEQ2=last,NEW1=first,INCR=increment

To renumber an entire member, place a single NUMBER statement withSEQ1=ALL after the CHANGE statement.

./ NUMBER SEQ1=ALL,NEW1=start,INCR=increment

To add or replace data lines, place them after the CHANGE statement.Code the sequence numbers in columns 73 to 80 with leading zeros. If thesequence number matches a record in the member, the data replaces it. Other-wise, IEBUPDTE inserts the data line in the order of its sequence number.

./ CHANGE NAME=member,LIST=ALL[Data lines with sequence numbers in columns 73 to 80.]

The following example replaces member ONE, adds member TWO, anddeletes records 12 to 15 in member THREE.

//STEP1 EXEC PGM=IEBUPDTE,PARM=MOD//SYSPRINT DD SYSOUT=A


//SYSUT1 DD DSN=A1000.PDS.TEXT,DISP=OLD

[DISP must be OLD.]

//SYSUT2 DD DSN=A1000.PDS.TEXT,DISP=MOD

[DISP must be MOD. The input and output data sets are the same.]

//SYSIN DD *./ REPL NAME=ONE,LIST=ALL[New member ONE placed here.]./ ADD NAME=TWO,LIST=ALL[New member TWO placed here.]./ CHANGE NAME=THREE,LIST=ALL./ DELETE SEQ1=12,SEQ2=15/*

You can update specific columns by coding the COLUMN option on theCHANGE statement. For any data records that follow the CHANGE whosesequence numbers match existing records in the data set, IEBUPDTE re-places columns dd through 80 of the existing record with the correspond-ing columns of the new lines.

./ CHANGE NAME=member,LIST=ALL,COLUMN=dd

You can also code the following options on the ADD, REPL, CHANGE,and REPRO statements.

SEQFLD=ddl specifies the starting column dd and the length l to con-tain the sequence numbers. The dd cannot exceed 80, and l cannotexceed 8. The default is 738 if you omit SEQFLD.

LEVEL=hh specifies the update level in hexadecimal (00–FF).IEBUPDTE records this level number in the directory of the outputmember to track the update levels.

SOURCE=0 tells the system that the modifications are yours.SOURCE=1 indicates that the modifications are IBM’s.

Inserting RecordsThere are two ways to insert records.

� Place the data lines after the CHANGE statement. The data must con-tain a sequence number in columns 73 to 80, with leading zeros.IEBUPDTE inserts the data lines in place based on this sequencenumber. (A line replaces a record if the data set already contains arecord having this sequence number. Otherwise, IEBUPDTE insertsthe record.)

� Use the NUMBER statement to denote where you want the datarecords inserted. You can code several NUMBER statements to insertthe records.



./ NUMBER SEQ1=after,NEW1=start,INCR=incr,INSERT=YES

IEBUPDTE inserts the records that follow the after record. IEBUPDTEnumbers the inserted records beginning with start and increments eachsucceeding record by incr. If the last inserted record has a number greaterthan the next existing record, IEBUPDTE renumbers all the following exist-ing records using incr.

Updating in PlaceYou can also update a data set in place, but you can only replace or renum-ber records. Code only one CHANGE statement per job step. The followingexample illustrates the update in place.

//STEP1 EXEC PGM=IEBUPDTE,PARM=MOD//SYSPRINT DD SYSOUT=A//SYSUT1 DD DSN=A1000.PDS.TEXT,DISP=OLD

[SYSUT2 is not required.]

//SYSIN DD *./ CHANGE NAME=THREE,LIST=ALL,UPDATE=INPLACE

[You can code one CHANGE statement with an UPDATE=INPLACEparameter in a job step.]

THIS DATA LINE REPLACES RECORD 1000000010./ NUMBER SEQ=ALL,NEW1=10,INCR=10/*

The next example updates an existing sequential data set in place. Withthe update in place, you can only replace or renumber records, and the dataset must reside on a direct-access volume.

//STEP1 EXEC PGM=IEBUPDTE,PARM=MOD//SYSPRINT DD SYSOUT=A//SYSUT1 DD DSN=A1000.SEQT.TEXT,DISP=OLD//SYSIN DD *./ CHANGE LIST=ALL,UPDATE=INPLACETHIS DATA LINE REPLACES RECORD 1000000010./ NUMBER SEQ1=ALL,NEW1=10,INCR=10/*


CHAPTER 20

SORT/MERGE

20.1 SORTING CONCEPTS

Essential

Sorting consists of arranging records in ascending or descending sequence.The sort order of alphanumeric data is termed its collating sequence, whichspecifies the sort order of each alphanumeric character in the character set.The two popular collating sequences are EBCDIC and ASCII. You will likelyuse only EBCDIC in MVS. ASCII is the standard for most other computersystems, including UNIX and PCs. There are significant differences betweenthe two collating sequences. Table 20.1 shows the collating sequences, fromlow to high.

In sorting character fields, the system compares the characters from leftto right to determine the sequence of the fields. Thus, NORTH would sortbefore NORTHERN because while the first five characters are identical, thesixth character in NORTH is a blank, which places it before the E inNORTHERN.

Numeric fields sort according to their numeric values, taking into con-sideration the signs. That is, 100 is greater than 50; 50 is greater than −100.

352

TABLE 20.1 EBCDIC and ASCII Collating Sequences

EBCDIC ASCII

blank blank¢.<(+|&!$*);¬-/,%_>?:#@ '=" !"#$%&'()*+,-./a through z 0 through 9A through Z :;<=>?@0 through 9 A through Z

[\]^_`a through z{ |}−

The main problem with numeric data lies in confusing it with characterdata that happens to contain only numbers. Character data is compared onecharacter at a time, from left to right. With numeric data, the system com-pares the numeric value. The following example shows the difference. Thefields are listed in ascending sequence for both character and numeric data.

As character datab999, 0009 (Blank comes before zero)+9, −9 (+ comes before −)b9, −9 (Blank comes before −)

As numeric data9, 999 (9 is less than 999)−9, +9 (−9 is less than +9)−9, 9 (−9 is less than 9)

You can use more than one sort key to arrange the data. A census fileillustrates this. Each record for a household might contain a city, state, anda family name. The census file might be sequenced on the state, city, andname, making these three items the sort keys. When there are multiple sortkeys, you must decide which key to sort on first, which second, and so on.

The sort key sorted first is termed the major sort key, and the last sortkey the minor sort key. Consequently, when there are several sort keys, youspecify the hierarchy of the keys in major to minor sequence. Changing thehierarchy of the sort keys completely rearranges the census file.

A lower-level hierarchy (minor sort key) cannot change the sequence ofa higher-level (major sort key) hierarchy. That is, if the sort hierarchy is asfollows:

1. State

2. City

3. Name

all records for a particular state will sort together. Whether you sort on citysecond and name third, or name second and city third, or city second alone,all records for a state will still sort together.

20.2 THE DFSORT PROGRAM

Essential

The SORT statement in COBOL and subroutine calls in PL/I and AssemblerLanguage can invoke the sort program. More often, you invoke them as aseparate job step through the SORTD cataloged procedure as follows:

SORT/MERGE 353

//stepname EXEC SORTD//SORT.SORTIN DD DSN=input-data-set,DISP=OLD,...

[SORTIN specifies the input data set to sort. It must be a sequentialor VSAM data set.]

//SORT.SORTOUT DD DSN=output-data-set,DISP=(NEW,...

[SORTOUT specifies the output data set to contain the sortedrecords. It must be a sequential or VSAM data set.]

//SORT.SYSIN DD *SORT FIELDS=(1,4,CH,A,20,10,CH,D)

[Code the sort statements in columns 2 through 71.]

/*

Each installation tailors the SORTD cataloged procedure to suit its ownneeds. Check your installation’s cataloged procedure for the specific state-ments. The following statements are usually included in the procedure.

//SORTD PROC//SORT EXEC PGM=ICEMAN

[The sort/merge program is named ICEMAN.]

//STEPLIB DD DSN=SYS1.LINKLIB,DISP=SHR

[Installations may place the sort program in some other library.]

//SORTLIB DD DSN=SYS1.SORTLIB,DISP=SHR//SYSOUT DD SYSOUT=A

Each installation establishes a default storage size for the sort program.To change this size, code the SIZE parameter in the PARM field.

// EXEC SORTD,PARM='SIZE=bytes'

[SIZE specifies the number of bytes to give to the sort.]

// EXEC SORTD,PARM='SIZE=MAX'

[SIZE=MAX allocates all the available space in the region to sort. Thisis usually the installation default. You can also code SIZE=MAX−n toallocate the maximum available space less the n value. The sort effi-ciency depends on the amount of central storage allocated to the sort.Generally, the more storage allocated, the more efficient the sort.]

20.3 THE SORT STATEMENT

Essential

The SORT statement specifies the sort order as follows:


TEAMFLY

Team-Fly®

1,4,CH,A

[Starting in character position 1, sort 4 CHaracters in Ascendingsequence.]

20,10,CH,D

[Starting in character position 20, sort 10 CHaracters in Descendingsequence.]

The general form of the SORT statement is

SORT FIELDS=(sort-key,sort-key,...sort-key)

The sort-key specifies the fields within the record to sort, their data types,and whether they are to be sorted in ascending or descending sequence. Listthe keys from left to right in the major to minor order in which they are tosort. The sort keys must all be within the first 4,092 bytes of the record. Eachsort-key has four parts: start, length, format, and order.

SORT FIELDS=(start,length,format,order,...)

The start specifies the starting byte position in the record. The first byte is1. (For VB records, the first byte of data is 5.) For binary fields, specify startin the form byte.bit, where byte is the byte number and bit is the bit numberwithin the byte. (The first bit is 0.) Hence, 4.2 indicates that the key beginsin the third bit of the fourth byte. The first bit in a field is 1.0.

The length specifies the length of the field in bytes. For binary fields,specify the length in the form bytes.bits, where bytes is the number of bytesand bits is the number of bits. Hence, 0.3 indicates that the key is 3 bits long.

The format specifies the format of the sort field. Table 20.2 shows theformats permitted.

The order specifies the sequence:

A AscendingD Descending

The following example sorts records into ascending sequence with twosort keys.

SORT FIELDS=(4,6,ZD,A,12,3,PD,D)

The sort order is

1. 4,6,ZD,A—Bytes 4 to 9 as zoned decimal in ascending sequence.

2. 12,3,PD,D—Bytes 12 to 14 as packed decimal in descendingsequence.

If all the fields have the same format, you can add the FORMAT=formatparameter to specify it and omit the format in the FIELDS parameter.

SORT/MERGE 355

SORT FORMAT=CH,FIELDS=(4,6,A,12,3,D)

Same as:

SORT FIELDS=(4,6,CH,A,12,3,CH,D)

20.3.1 Continuing SORT Statements

Code sort statements in columns 2 through 71. To continue a sort statement,break it after a comma but before column 71 and continue somewhere incolumns 2 to 16 of the following line.


TABLE 20.2 Formats for Fields in Sorting

Format Description Signed Length in bytes

CH EBCDIC character 1–4,092AQ EBCDIC character, alternative 1–256

collating sequence set by theALTSEQ command

ZD Zoned decimal Yes 1–32PD Packed decimal Yes 1–32PDO Packed decimal with both

first digit and sign ignored Yes 2–8FI Fixed point Yes 1–256BI Binary 1 bit to 4,092 bytesFL Floating point Yes 1–256CSF or FS Signed numeric character with

optional leading floating sign Yes 1–16CSL or LS Numeric character, leading Yes 2–256

separate signCST or TS Numeric character, trailing Yes 2–256

separate signCLO or OL Numeric character, leading Yes 1–256

overpunch signCTO or OT Numeric character, trailing Yes 1–256

overpunch signAC ISCII/ASCII character 1–256

(Sequences EBCDIC data usingISCII/ASCII collating sequence)

ASL ISCII/ASCII numeric character, Yes 2–256leading separate sign

AST ISCII/ASCII numeric character, Yes 2–256trailing separate sign

D1 User-defined data type 1–4,092


20.3.2 SORT Options

You can specify sort options in the PARM field of the EXEC statement, onthe SORT statement, or on an OPTION statement. You code the OPTIONstatement as

OPTION parameter,parameter,...,parameter

Place the OPTION statement before the SORT statements to which it isto apply. The following are the most-used options.

Preserving the Sort Order of Records with Identical KeysThe EQUALS option requests that records having identical keys sort in theorder they appear in the input data set. For a merge, EQUALS preserves the order in which the records occur within the data sets specified by the//SORTINnn DD statements. If you don’t need to preserve the sequence ofrecords having identical keys, code NOEQUALS. This is usually the instal-lation default.

// EXEC SORTD,PARM='EQUALS'

Or

//SORT.SYSIN DD *OPTION EQUALSSORT …/*

Specifying the Average Record Length for Variable-Length RecordsAVGRLEN=n, where n is the estimated record length, enables the sort to bemore efficient by estimating the average record length of variable-lengthrecords.

// EXEC SORTD,PARM='AVGRLEN=n'

Or

OPTION AVGRLEN=n

Sorting a Portion of the Input RecordsSKIPREC=n skips n records before sorting. STOPAFT=n specifies the maxi-mum number of records to sort. After n input records are read for sorting,the system proceeds as if an end of file had been encountered. You can codeSKIPREC and STOPAFT separately or together.

SORT/MERGE 357

// EXEC SORTD,PARM='SKIPREC=n,STOPAFT=n'

Or

OPTION SKIPREC=n,STOPAFT=n

Or

SORT FIELDS=(...),SKIPREC=n,STOPAFT=n

Specifying CheckpointsThe CKPT parameter requests the system to take checkpoints at the start ofthe first sort phase, at the start of each intermediate merge phase pass, andat the start of the final merge phase.

OPTION CKPT

Or

SORT FIELDS=(...),CKPT

20.4 MERGE STATEMENT

Sometimes Used

MERGE merges several input data sets having identical record formats intoa single output data set in this same sequence. It yields the same results asif you concatenated several data sets as input to a sort. Merging is muchmore efficient because the sort program can take advantage of the fact thatthe input data sets are already in the proper sort sequence.

The JCL for a merge is identical to that for a sort, except that instead ofone //SORTIN DD statement describing the input, there are up to 100 (nnfrom 00 to 99) //SORTINnn DD statements describing the data sets to merge.You write a merge as

// EXEC SORTD//SORTIN01 DD ...//SORTIN02 DD ...

� � �

//SORTIN16 DD ...//SORTOUT DD ...

[The system writes the output to this data set.]

//SYSIN DD *MERGE FIELDS=(sort-key,sort-key,...sort-key)/*


The //SORTINnn DD statements (maximum of 16) name the input datasets to merge and tell how many data sets are to be merged. The nn in the//SORTINnn DD statements must begin with 01 and continue in increasing,consecutive order: (01, 02, 03, but not 01, 03, 04). The //SORTINnn DDstatements can’t be concatenated.

The MERGE statement is identical to the SORT statement except youwrite MERGE instead of SORT. The special rules are as follows:

� The RECFM for all the //SORTINnn DD statements must be the same.� The LRECL for fixed-length records must be the same.� For variable-length records, the largest LRECL must be SORTIN01.� The BLKSIZE does not need to be the same, but the data set with the

largest BLKSIZE must be SORTIN01.

20.5 OTHER SORT STATEMENTS

Rarely Used

The SORT or MERGE statement is necessary for every sort or merge, butthere are several other statements provided for specialized use.

20.5.1 The RECORD Statement

The RECORD statement specifies the output record length and is usedunder the following conditions:

To reformat records before they participate in a sort.

For VSAM data sets. The RECORD statement is required to specify therecord length.

For variable-length records. The RECORD statement is optional to esti-mate the record lengths to make the sort faster.

To change the record length in a sort exit in a sort called by PL/I orAssembler Language, or if you have no //SORTIN DD statement.The RECORD statement is then required to specify the length.

Write the RECORD statement as

RECORD TYPE=type,LENGTH=(in-len,E15-len,out-len,min-len,avg-len)

The type is the record type: F for fixed-length, V for EBCDIC variable-length, and D for ASCII variable-length. The in-len is the length of the input

SORT/MERGE 359

record and needs to be specified only for VSAM or if there is no //SORTINDD statement. For variable-length records, it is the maximum record length.The E15-len is needed only if an E15 sort exit changes the length. The out-len is the length of the output record and needs to be specified only if thereis no //SORTOUT DD statement. The min-len is the minimum record lengthand is needed only for variable-length records. The avg-len is the averagerecord length and is needed only for variable-length records.

For VSAM data sets and for situations where there is no //SORTIN DDstatement, write RECORD as follows:

RECORD TYPE=type,LENGTH=(length)

The type is F for fixed, V for EBCDIC variable-length, and D for ASCII variable-length. The length is the LRECL record length. Add four bytes forVSAM variable-length records. The first byte of a variable-length record isfive.

If the record length is changed in a sort exit, write the following:

RECORD TYPE=type,LENGTH=(input-length,output-length)

[Add four bytes to the length for variable-length records.]

To increase the sort efficiency of data sets containing variable-lengthrecords, write:

RECORD TYPE=type,LENGTH=(,,,min-length,avg-length)

The min-length is the length of the shortest record. The avg-length is anestimate of the most frequent record length.

20.5.2 The MODS Statement

The MODS statement names an Assembler Language entry point or COBOLsubprogram to invoke during the sort. These branches are termed sort exits.With sort exits, you can supply records to the sort rather than having thesort read SORTIN, and you can retrieve the sorted records rather than hav-ing them written in SORTOUT.

There are 13 sort exits possible during the various sort phases. The sys-tem numbers each sort exit with numbers ranging from E11 to E61. You areunlikely to write a MODS statement, but it is important to understand howthe sort exits work. Here is the sequence in which the two most-used sortexits occur: the E15 before-sort exit and the E35 after-sort exit.

1. The Sort/Merge utility reads an input record.

2. If you have included a MODS statement for an E15 before-sort exit,Sort/Merge calls the subprogram you name on the MODS statement.


Your subprogram might then modify the records being passed to thesort.

3. Sort/Merge goes back to step 1 until all input records are read.

4. Sort/Merge sorts the file.

5. Sort/Merge selects the next sorted record and if you have includeda MODS statement for an E35 after-sort exit, Sort/Merge calls thesubprogram you name on the MODS statement. Your subprogrammight then modify the sorted record.

6. Sort/Merge writes the output record and goes back to step 5 until alloutput records are written.

The general form of the MODS statement for Assembler Language rou-tines is

MODS exit=(routine,bytes,ddname),exit=(routine,bytes,ddname),...

For COBOL subprograms, you write it as follows:

MODS exit=(routine,bytes,ddname,C),...

The exit is the type of sort exit, such as E15. The routine names the routineto receive control. The bytes is the number of bytes occupied by the rou-tine. The ddname is the ddname of the data set containing the routine. Forexample:

MODS E15=(PROCESS,1000,LIB)

20.5.3 The ALTSEQ Statement

Code the ALTSEQ statement along with SORT or MERGE statements tochange the EBCDIC collating sequence of any character fields. ALTSEQapplies only to fields specified as AQ in the SORT or MERGE statement.

ALTSEQ CODE=ffllALTSEQ CODE=(ffll,ffll,...,ffll)

The ff is the hexadecimal representation of the EBCDIC character to change.The ll is the hexadecimal representation of an EBCDIC character that the ffcharacter is to sort as. For example, to make a lowercase a (X‘61’) sort as anuppercase A (X‘41’), code the following:

ALTSEQ CODE=6141SORT FIELDS=(1,4,AQ,A,20,10,AQ,D)

SORT/MERGE 361

Note that the data itself is not changed, only the collating sequence forthe sort.

20.5.4 INCLUDE/OMIT Statements

The INCLUDE and OMIT statements select or exclude records from theSORTIN data set by testing specified fields in the input records. Placeeither a single INCLUDE or OMIT (but not both because they are mutuallyexclusive) along with the SORT, MERGE, RECORDS, or ALTSEQ controlstatements.

INCLUDE ...SORT FIELDS=(...

Write INCLUDE or OMIT as

INCLUDE COND=(logical-expression)OMIT COND=(logical-expression)

The system applies the logical-expression to each record and selects oromits if the expression is true. In its simplest form, you write the logical-expression as

COND=(field,comparison,field or constant)

The field specifies a field in the record in a similar format to the SORT andMERGE statements: byte,length,format. The comparison is the comparisonoperation:

EQ Equal GE Greater than or equalNE Not equal LT Less thanGT Greater than LE Less than or equal

The constant is a decimal constant, such as

� 12, −16, 222.46.� A hexadecimal constant X‘nnnn...nn’.� A character constant: C‘character-literals’. (Write an apostrophe as

two apostrophes: C‘ISN”T’.)

INCLUDE COND=(8,4,CH, EQ, C'ABCD')

[The record is included only if columns 8 to 11 equal ‘ABCD’.]

OMIT COND=(1,2,PD, LT, 20)

[If columns 1 and 2 are less than 20, the system omits the record.]


For INCLUDE, a record is accepted when the logical expression is true.A false logical expression results in the system rejecting the record. ForOMIT, the system rejects a record if the logical expression is true. A falselogical expression causes the system to select the record. You can also codeCOND=ALL to include or omit all or COND=NONE to include or omit none.As an example suppose you have records such as

70014AL.....70049AL.....80016CA.....80049OH.....

To include only records having “AL” in columns 6 and 7, you write

INCLUDE COND=(6,2,CH, EQ, C'AL')

To omit zip 80016 in columns 1 to 5 and include all others, you write

OMIT COND=(1,5,CH, EQ, 80016)

You can write several logical expressions connected by AND or OR. Useparentheses to specify the order in which you want the tests applied. Hereis an example:

OMIT COND=((1,5,ZD, EQ, 80016),OR,(9,2,CH, EQ, C'AL')),AND,(15,2,BI, GT, 6)))

The following rules apply:

� Any number of AND/ORs is permitted.� You can use parentheses to specify the nesting to any level.� Where parentheses don’t specify the evaluation order, the AND con-

ditions are evaluated before the OR.� Any fields being compared must be in the first 4,092 bytes of a

record.� Binary fields can be compared, but must begin and end on byte

boundaries.� The maximum field length for comparison is 256 bytes.� The system pads character fields on the right with blanks for the

comparison to make a shorter field equal a longer field for compari-son. It pads hexadecimal fields with X‘00’.

� The system pads numeric data on the left with zeroes to compare ashorter field with a longer field.

SORT/MERGE 363

You can also select or omit records based on whether a constant appearswithin a field or a field value appears within a constant by coding:

(byte,length,SS,comparison,constant)

The byte is the starting byte position of the field to search: 1 for fixed-lengthrecords and 5 for variable-length. The length is the length in bytes of thefield, 1 to 256. The comparison is either EQ or NE. The constant is either acharacter or hexadecimal string.

If length is greater than the length of constant, the field is searched tosee if it contains the constant. If length is less than the length of the con-stant, the constant is searched to see if it contains the field. In the followingexample, the system searches bytes 4 to 11 of each record and includes therecord if it contains an ‘X’.

INCLUDE COND=(4,8,SS,EQ,'X')

You can also use AND and OR to form the logical expression. Finally,you can test bits for selecting or omitting records by coding:

(byte,length,test,mask)

The byte,length are the starting byte and length of the field in bytes. The testis the test to perform the following:

ALL or BO—All mask bits are on in the input field.

SOME or BM—Some but not all mask bits are on in the input field.

NONE or BZ—No mask bits are on in the input field.

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

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

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

The mask is either a hexadecimal string of the form X‘yy . . . yy’ or a bitstring in the form B‘bbbbbbbb...bbbbbbbb’. The bbbbbbbb represents eightbits with a value of 0 or 1.

The following example selects records in which the two rightmost bitsof bytes 4 and 5 are on (equal 1).

INCLUDE COND=(4,2,ALL,B’0000001100000011’)

20.5.5 The INREC and OUTREC Statements

The INREC statement reformats a record before sorting it, so that only thefields you need are passed to the sort. This lets you shorten the record


TEAMFLY

Team-Fly®

length to speed up the sort. OUTREC reformats the record after it is sorted.You can code INREC and OUTREC together.

INREC reformats after any E15 before-sort exit and after INCLUDE orOMIT have selected records. Note that the SORT, MERGE, OUTREC, andSUM statements refer to the sort keys after they have been reformatted.INCLUDE and OMIT refer to the sort keys before they have been reformat-ted. Be sure to account for this if you change the position of fields. OUTRECreformats before any E35 after-sort exit. You write INREC and OUTREC asfollows:

INREC FIELDS=(n:field or constant,...)OUTREC FIELDS=(n:field or constant,...)

The n is the starting byte position (1 to 32752) of the field in the inputrecord. The first byte of a variable-length record is five. Any unspecifiedspace preceding this column as it is moved to the reformatted record ispadded with EBCDIC blanks. The n must not overlap the previous inputfield in the reformatted input record.

The field is of the form byte,length,align in which byte is the startingbyte position of an input field, length is the length in bytes of the field, andalign specifies the alignment: H = half-word, F = full-word, D = double-word. Omit align if you wish no alignment. The system moves the inputfield to the reformatted record, converting and padding with binary zeros toalign the data as necessary.

The constant can be one of the following:

nX inserts n bytes of EBCDIC blanks.

nZ inserts n binary zeros.

nC‘xx...x’ inserts n repetitions of the EBCDIC characters. (If you omitn, the system assumes 1.) Code a legitimate apostrophe as twoapostrophes.

nX‘xx...xx’ inserts n repetitions of the hexadecimal characters, twohexadecimal digits per byte. (If you omit n, the system assumes 1.)

Suppose you have the following record:

12TEST324633ROAD25

If you write INREC FIELDS=(1:3,4), the reformatted record would con-tain TEST. If instead you wrote OUTREC FIELDS=(4:7,3,7:13,4,13:C‘12’),the reformatted record would contain bbb324ROADbb12.

The rules to cover special situations are as follows:

SORT/MERGE 365

� The LRECL of the //SORTOUT DD statement must specify the newrecord length if it is changed.

� The INREC fields can overlap each other.� For variable-length records, you must copy the 4-byte record descrip-

tor word. DFSORT will set the new length of the reformatted record.If the input record is variable-length, the reformatted record mustalso be variable-length.

� You can copy from any byte position in a variable-length input recordto the end of the record by coding the byte position last, withoutspecifying length or align.

The following example shows how to write INREC for a variable-lengthrecord.

INREC FIELDS=(1:1,4,5:5,20)

The first record descriptor word of the variable-length record is copied.Then 20 bytes, starting in byte 5—the first data byte—are copied. The resultis a variable-length record containing the first 20 bytes of the original record.

20.5.6 The SUM Statement

The SUM statement summarizes records by specifying numeric fields in theinput record to sum. The system sums records having the same sort keysand writes a single output record with the summed fields. The other fieldsin the record are obtained from the last record summed. The records aresummarized after sorting. You do not sort the summarized records. Instead,the input records are sorted, then summarized, and then written to theSORTOUT. You write the SUM statement as

SUM FIELDS=(byte,length,format,byte,length,format,...)

The byte is the starting byte position of the field in the input record to sum.(The first byte of a variable-length record is five.) The length is the length ofthe field in bytes to sum. The format is the format of the field to sum: BI, FI,FL, PD, or ZD.

Records are summarized based upon the sort keys specified in theSORT or MERGE statement. If three sort keys are specified in a SORT state-ment, records are summarized only when the three sort keys are equal. Youcan also write the SUM statement as

SUM FIELDS=NONE


This summarizes the records without adding any fields. SUM takes onlythe last record of a group whose keys match and drops any records havingduplicate keys.

The rules for SUM are as follows:

� You can’t sum sort keys.� Sum fields cannot overlap.� If overflow occurs, the system sums the records up to the overflow

and writes a record. Then the summation begins over.� A summed field must be in the first 4,092 bytes of the record.

Here, the record is sorted on bytes 1 to 4 in ascending order and then onbytes 9 to 12 in descending order.


Next, the binary field in bytes 5 to 8 and the packed decimal data inbytes 12 to 17 are summed.

SUM FIELDS=(5,4,BI,13,5,PD)

20.5.7 The OUTFIL Statement

The OUTFIL statement lets you select and reformat records and write themto several separate output files with a single pass over the input data sets.OUTFIL begins its processing after all the other control statements and sortexits have been processed. You write OUTFIL as

OUTFIL FNAMES=ddname,parametersOUTFIL FNAMES=(dd1,dd2,...,ddn) parameters

Include DD statements with the ddnames in the sort step to describe theoutput file. You can specify the first and last records to include by codingthe STARTREC and ENDREC parameters:

OUTFIL FNAMES=DD1,STARTREC=100,ENDREC=999

Records 100 through 999 are written to DD1. The default for STARTRECis 1 and for ENDREC is the number of records in the data set.

To specify the records to include or omit, code the INCLUDE or OMITparameter.

INCLUDE=(logical-expression)OMIT=(logical-expression)

SORT/MERGE 367

The logical-expression is the same as for the INCLUDE and OMIT state-ments previously described. In the next example, the DD2 file contains allrecords in which bytes 8 to 11 contain the characters XXXX. DD3 containsall records except those in which column 12 contains a Y.

OUTFIL FNAMES=DD2,INCLUDE=(8,4,CH,EQ,C'XXXX')OUTFIL FNAMES=DD3,OMIT=(12,1,CH,EQ,C'Y')

Notice that you create multiple output files by coding multiple OUTFILstatements. When you select records, you can also code the SAVE parame-ter to create a file containing the records not selected. In the followingexample, DD4 contains all the records containing XXXX in columns 8 to 11;DD5 contains the records containing YYYY in the same columns; and DD6contains all the remaining records.

OUTFIL FNAMES=DD4,INCLUDE=(8,4,CH,EQ,C'XXXX')OUTFIL FNAMES=DD5,INCLUDE=(n:field or constant,...)OUTFIL FNAMES=DD6,SAVE

SPLIT writes successive records into separate output files. In the fol-lowing example, records are selected in which columns 8 to 11 containYYYY. The first selected record is written to DD7, the second to DD8, thethird to DD9, the fourth to DD7 again, and so on.

OUTFIL FNAMES=(DD7,DD8,DD9),SPLIT,INCLUDE=(8,4,CH,EQ,C'YYYY')

To reformat the output records, code the OUTREC parameter.

OUTREC=(n:field or constant,...)

Write OUTREC the same as the FIELDS parameter for the INREC/OUT-REC statements described previously. The following example selects recordsin which columns 8 to 11 contain YYYY and writes columns 12 to 91 of theselected records into the DD10 file.

OUTFIL FNAMES=DD10,INCLUDE=(8,4,CH,EQ,C'YYYY'),OUTREC=(1:12,80)

To reformat variable-length records to make them fixed-length, code theCOVERT option in combination with the OUTREC parameter to reformatthe records. The following example converts the input record to fixed-length. The first 80 bytes of data of the variable-length records are writtenas fixed-length records in the DD11 file.

OUTFIL FNAMES=DD11,CONVERT,OUTREC=(1:5,80)


20.5.8 The SYMNAMES DD Statement

Sometimes Used

DFSORT also lets you define symbols and assign them values, such asdefining name_field as 15,30,CH, and then using the symbol in the SORTDcontrol statements. The following example illustrates this.

//stepname EXEC SORTD//SORT.SORTIN DD DSN=PERSONNEL.DATA,DISP=OLD//SORT.SORTOUT DD DSN=NEWPERSONNEL.DATA,DISP=(NEW,CATLG),...//SYMNAMES DD *name_field,15,30,CH//SORT.SYSIN DD *SORT FIELDS=(name_field,A)

[Same as if you had coded SORT FIELDS=(15,30,CH,A).]

/*

This lets you define a collection of symbols for a file that many people canuse to simplify referring to fields in a file.

The SYMNAMES DD statement can specify sequential data set, a mem-ber of a partitioned data set, a DD * data set, or all three concatenated, aslong as they are RECFM=F or FB and LRECL=80. You specify symbols andassign them values in the SYMNAMES data set as follows.

� comment.

[An * in column 1 denotes a comment and is ignored.]

symbol value comment

[You code these fields beginning in any column. Leave a blank afterthe value if you want a comment.]

The symbol is 1-50 of the following EBCDIC characters: A-Z a-z 0-9 * $ @ _.The first character cannot be 0-9. The symbol is case sensitive: ONE andOne and one are all different symbols. Don’t use DFSORT reserved words,such as CH, FI, etc.

The value can be the following:

� Character string: ‘Any characters’ Code an ‘ in the string as ‘‘:‘O’’Reilly’. Example: name_field,’1,30,CH,A’

� Hex string: X’yy…yy’ Example: control_field,X’F9’� Bit string: B’nn…nn’ Example: flag_field,B’10000100’

SORT/MERGE 369

� Number: n, +n, or –n The number can be 1-15 digits but no decimalpoint. Example: count,-15

� Field: start,length,format or start,length, or start Example:city_field,1,30,CH

In coding the field, you can code an * to refer to the next position.

name_field,1,30,CH

dependents_field,*,2,CSF [SORTD substitutes 31 (1+30) for the *.]title_field,*,20,CH.. [SORTD substitutes 33 (31+2) for the *.]

Note that the position is calculated in the order the lines appear in theSYMNAMES data set. Now if you coded the following,

SORT FIELDS=(name_field,A,title_field,A,dependents_field,D)

The statement is treated as if you coded

SORT FIELDS=(1,30,CH,A,33,20,CH,A,31,2,CSF,D)

You can also code an = for the previous position. Coding the = for thelength and format copies these fields from the previous lines.

full_name,1,30,CH

first_name,=,10,= .. [SORTD treats this as 1,10,CH.]middle_name,*,=,= .. [SORTD treats this as 11,10,CH.]last_name,*,=,= .. [SORTD treats this as 21,10,CH.]

20.5.9 DFSORT Year 2000 Features

Sometimes Used

DFSORT has features to sort the year, the month, or the day when the dateis stored as a single packed-decimal number or as a two-byte character orzoned-decimal field. In addition, you can specify a fixed or sliding 100-yearwindow to expand the two-digit year to four digits for the sort. DFSORT’sability to expand the two-digit year to four digits for the sort requires nochange to the data in the file, and can handle most date problems.

The windowing technique defines a 100-year window, and the two-digit years are converted to four digits based on this. For example, if youdefine the date window to be from 1903 through 2002, two digit years of


SORT/MERGE 371

03 through 99 would be 1900 and years of 00 through 02 would be 2000.The windowing technique requires that the dates fall within a 100-yearwindow.

There are two variations for the windowing technique: fixed and slid-ing. For a fixed window, you might convert dates with years 60 to 99 inter-nally be to 1960 to 1999, and dates 00 to 59 to be 2000 to 2059. As time goesby, you might have to change the ranges. This method has little to recom-mend it because the sliding window technique works as well and automat-ically slides the date range forward so that you don’t have to constantlychange it. With the sliding technique, you specify a window as the numberof years in the past and in the future that constitute a window around thecurrent date.

Table 20.3 shows the DFSORT format fields for sorting Y2K dates.Packed-decimal numbers are stored two-digits per byte, with the sign in

the right-most half-byte. When the date is stored as a single packed-decimalnumber, such as yymmdd, yyddd, mmddyyyy, and so on, the formats let yousort portions of a packed-decimal number. For example, you could sort onyy, mm, or dd in any of the following data items, even though the digitsappear in different bytes. The x represents any hexadecimal value and s thesign.

|xd|dm|my|ys| |xm|md|dy|ys| |xy|ym|md|ds| |yy|mm|dd|xs|

The formats also allow two-digit years to be converted internally to fourdigits for the sort, using the windowing technique. The data in the file is notchanged. You specify the windowing with a Y2PAST option described fol-lowing. If you don’t specify the Y2PAST option, an installation-definedvalue is used. The details of the formats are as follows.

Character and zoned-decimal years. Expanded to four digits for the sort.Y2C, Y2Z, and Y2S sort dates that contain two digits (yy) and occupy twobytes in either character or zoned decimal form as shown here. Y2C andY2Z treat blanks (X’4040’) and binary zeros (X’0000’) as year values of 00for the sort. Y2S treats blanks, X’0000’, and X’FFFF’ as special indicatorsand sorts them according to their hexadecimal values: X’0000’ sorts first,then blanks, then the years, and X’FFFF’ sorts last.

| x | y | x | y |

[Y2C, Y2Z, and Y2S define two bytes, x is any hexadecimal value,and y is a hexadecimal digit, 0-9.]


TABLE 20.3 Formats for Y2K Date Sorting

Format Description Signed Length in bytes

Y2C, Y2Z Two-digit, two-byte character or zoned No 2decimal year in form yy. Expanded to four digits for sort. Y2C and Y2Z are interchangeable.

Y2S Same as Y2C and Y2Z, except blanks, binary No 2zeros, and binary ones are considered to be special indicators rather than years. Expanded to four digits for the sort.

Y2B Two-digit, one-byte binary year in the form yy No 1as a binary number. Expanded to four digits for the sort.

Y2D Two-digit, one byte packed-decimal year in No 1the form yy. Expanded to four digits for the sort.

Y2P Two-digit, two-byte packed-decimal year in No 2form yy. Expanded to four digits for the sort.

Y2T Full date format in character or zoned decimal No 3-6containing yyx, yyxx, yyxxx, and yyxxxx, where yy is the two-digit year (expanded to four digits for the sort) and x represents non-year digits (month, day).

Y2W Same as Y2T, except the x digits come before No 3-6the y digits: xxyy, etc.

Y2U Full date format in packed decimal containing No 2-3P’yyxx’ (X’yyxxs’) and P’yyxxx’ (X’yyxxxs’), where yy is the two-digit year (expanded to four digits for the sort), x represents non-year digits (month, day), and s is the indicator (hex 0-F) and is ignored.

Y2X Same as Y2U, except the x digits come before No 2-3the y digits: P’xxyy’ (X’xxyys’), etc.

Y2V Full date format in packed decimal containing No 3-4P’yyxx’ (X’0yyxxs’) and P’yyxxxx’ (X’0yyxxxxs’), where yy is the two-digit year (expanded to four digits for the sort), x represents non-year digits (month, day), and s is the special indicator (hex 0-F) and is ignored.

Y2Y Same as Y2V, except the x digits come before No 3-4the y digits: P’xxyy’ (X’xxyys’), etc.

PDO Signed packed-decimal number with both first Yes 2 – 8and last digit ignored. Used for sorting mm, dd, ddd, etc.

Binary years. Expanded to four digits for the sort.Y2B is a two-digit year (yy) stored as a binary number in a single byte asshown here. (A byte can contain binary value of 0 – 255.) Note that a codefor a two-byte binary year is not needed because it can contain a four-digityear. If it contained only a two-digit year, the year would be in the right-most byte and you could sort it with Y2B.

| yy | [Y2B defines one byte with binary values of 2-255.]

Packed-decimal years. Expanded to four digits for the sort.Y2D is a two-digit, one-byte packed decimal number representing a year inthe form yy as shown here. It is used to specify the yy portion of a datewithin a packed-decimal number contained in a single byte.

| y | y | d | d | d | s |

[d is hexadecimal digit 0-9 representing the day here, and s is thesign.]

Y2P, similar to Y2D, is also a two-digit, packed-decimal number repre-senting a year in the form yy. However it occupies two bytes as shown next.It is used to specify the yy portion of a date within a packed-decimal num-ber in which the yy crosses a byte boundary.

| x | y | y | m | m | d | d | s |

[Y2P defines two bytes, x is any hexadecimal value, y is hexadeci-mal digit 0-9 representing a year, m and d are hexadecimal digit 0-9representing the month and day here, and s is the sign.]

Packed-decimal months and days. Not expanded to four digits for the sort.PDO represents two- to eight-byte packed-decimal number representing amonth or day in the form mm, dd, ddd, or whatever, in which the first digitand sign are ignored.

| x | y | y | m | m | d | d | s |

[PDO represents two bytes to sort on the dd.]

| x | y | y | m | m | d | d | s |

[PDO represents two bytes to sort on the mm.]

| x | y | y | m | m | d | d | s |

[PDO represents three bytes to sort on the mmdd, x is any hexadeci-mal value, y is a hexadecimal digit 0-9 representing the year, m and d

SORT/MERGE 373

are hexadecimal digit 0-9 representing the month and day here, and sis the sign.]

Full Date FormatsY2T and Y2W can be in either character or zoned decimal format with atwo-digit year and one to four digits representing the month and/or days inproper collating sequence (mmdd, but not ddmm). These fields can alsocontain the following special indicators.

X’00…00’ BI zeros C’9…9’ CH ninesX’40…40’ CH blanks Z’9…9’ ZD ninesC’0…0’ CH zeros X’FF…FF’ BI onesZ’0…0’ ZD zeros

Y2U and Y2S are in packed decimal format with a two-digit year andtwo or three digits representing the month or days. Y2V and Y2Y are in alsoin packed decimal format with a two-digit year and two or four digits rep-resenting the month and/or days. These fields can also contain the follow-ing special indicators.

Y2W, Y2X, Y2V, Y2Y:

P’0…0’ PD zeros P’9…9’ PD nines

The Y2PAST optionThe Y2PAST option is applied to the Y2 formats. If you don’t specify theY2PAST option for these fields, DFSORT uses an installation-suppliedvalue. Y2PAST specifies either a fixed or sliding window, depending on thevalue you set. Values of 1000 through 3000 specify a fixed window. Notethat with DFSORT, you specify the starting year of the 100-year window.

Y2PAST=1000 through 3000

[Denotes fixed window.]

Y2PAST=1960 ..

[The 100-year window is 1960 through 2059.]

Values of 0 through 100 specify a sliding window. The value is the num-ber of years to subtract from the current year to form the starting year of thesliding window.

Y2PAST=0 through 100

[Denotes sliding window.]

Y2PAST=80


TEAMFLY

Team-Fly®

If the current year were 1999, the 100-year window would be 1919through 2018. You code Y2PAST on the OPTION statement as follows:

OPTION Y2PAST=98SORT FIELDS=(1,2,Y2C,A,3,4,CH,A)

With the previous two statements, if you had the following date field inyymmdd format in columns 1 through 6, it would sort as shown, assuming1999 as the current year. The 100-year window is 1901 through 2000.

Appears in the file as: Sorts as if it were coded as:

011221 .. 19011221990604 .. 19990604000426 .. 20000426

Using the Y2K sort fields in a COBOL sortWhen you code a SORT or MERGE statement for Mainframe COBOL, thecompiler generates a DFSORT SORT or MERGE statement. You can over-ride this generated statement and supply your own to use the sort fields.You would only do this if you couldn’t use an external sort. The SORT orMERGE statement produced that you would replace appears in DFSORT’smessage data set. If it doesn’t, add the following to the DFSORT catalogedprocedure:

//GO.SORTDIAG DD DUMMY

Then revise the SORT or MERGE statement to use the formats andinclude it in the execution step when you run your COBOL program.

//GO.DFSPARM DD *OPTION Y2PAST=98SORT FIELDS=(1,2,Y2C,A,3,4,CH,A)

/*

You can also use the OUTFIL statement of Sort/Merge to convert two-digit years to four digits using the formats. Assume that you have the fol-lowing date in an 80-byte record, beginning in column 10.

1 2…812345678901234567890…0 <== Columnsxxxxxxxxxyymmddxxxxx…x

SORT/MERGE 375

To convert the year to four digits, resulting in an 82-byte record, youcode the following.

OUTFIL FNAMES=ddname,

OUTREC=(1,9, [Copy bytes 1-9.]10,2,Y2C, [Convert yy to yyyy.]12,69) [Copy mmdd and the rest.]

Now suppose the date were carried as a single packed-decimal numberin the form yymmdd occupying 4 bytes in bytes 10-13 of an 80-byte record.The following OUTFIL statement converts the year to four digits and storesthe entire date back (yyyymmdd) as a 5-byte field, lengthening the record to81 bytes. The packed-decimal date appears in bytes 10 through 13 as fol-lows, where x is ignored and s is the sign.

| x | y | y | m | m | d | d | s |

OUTFIL FNAMES=ddname,OUTREC=(1,9, [Copy bytes 1-9.]

1,2,Y2P, [Convert yy to yyyy.]3,2,PDO, [Copy mm.]5,2,PDO, [Copy dd.]14,67) [Copy bytes 14-69.]

The next OUTFIL statement converts the same record from packed-decimal to character.

OUTFIL FNAMES=ddname,OUTREC=(1,9, [Copy bytes 1-9.]

1,2,Y2P, [Convert yy to yyyy.]3,2,PDO, [Copy mm.]5,2,ZD,M11 [Copy dd.]17,69) [Copy bytes 14-69.]

The M11 is a mask provided by DFSORT to mask off the right-most signbits of the packed decimal number.

20.6 SORT EFFICIENCY

Essential

You may be able to dramatically reduce the cost of sorting by using the fol-lowing suggestions.


Sort with JCL rather than with application program sort statements.The SORTD cataloged procedure is generally more efficient thanCOBOL or PL/I sort statements.

Sort fewer records. Sort cost varies exponentially with the number ofrecords sorted. That is, it costs more than twice as much to sort 1,000records as it does 500. You can reduce the number of records byselecting records before you sort. For example, if you were workingwith census data and wanted to list only the names of people wholive in Wyoming, you could first select the records for Wyoming andthen sort. That way, you would sort only about 350,000 recordsrather than 200 million records.

Sort shorter records. The cost of a sort is proportional to the recordlength. When you select records, you can drop all the fields that youdon’t need to shorten the record length.

Perform a tag sort. This shortens the record length for random-accessfiles having record keys. You create a small record containing onlythe random-access key needed to retrieve the record, along with theother fields of the record needed as sort keys. Then you sort theseshort records on the sort keys and later use the random-access keyto retrieve the full records in the sequence wanted.

Reduce the number of sort keys. The cost of a sort is proportional tothe number of sort keys. Perhaps you can’t control the sort keys, butsometimes in the design of a record you can. Suppose you are sort-ing a data set on date. Often the date is stored as

m m d d y y y yThis necessitates three sort keys to sort the date: yyyy, mm, and dd.But if you store the date in the record as

y y y y m m d dthe entire date can be treated as a single sort key to sort on date. Byplacing sort keys together in major to minor order and having thembe the same format, you can treat several alphanumeric sort keys ina sort as if they were a single sort key.

Block big. Large blocks reduce the amount of I/O; they reduce the CPUtime required to transmit the blocks, and, properly chosen, theyconserve storage space on tape or disk; another reason to let the sys-tem select the appropriate block size.

Sort data as binary or character fields. If fixed-point data containsonly positive values, you can sort it as a binary field. If you knowthat packed-decimal or zoned-decimal fields contain only positivevalues, you can also sort them as binary fields. Use packed-decimalrather than zoned-decimal wherever possible.

SORT/MERGE 377

EXERCISES

Create a data set containing the following lines and place them in the se-quence shown:

991992999981982989891899881882

Sort the lines into ascending sequence, placing them in a nontemporarydata set on disk. Then sort the disk data set back into the original sequence,printing the sort output. (Make the //SORTOUT DD statement containSYSOUT=A.)


CHAPTER 21

ISPF

Essential

ISPF (Interactive System Productivity Facility) is a text editor that also pro-vides many utility functions. Since much of your computer usage willlikely be through ISPF, this chapter gives an overview. ISPF also has a dia-log manager beyond the scope of this book that enables you to build screensto be filled in as part of an application. Unlike the other products describedin this book such as JCL, TSO/E, and the IBM Utilities, ISPF is easy to useand well human engineered. It is menu driven, which means you don’thave to memorize many commands.

ISPF displays its panels in two forms. The original form operates on anonprogrammable terminal (a 327x terminal or a PC emulating one) that dis-plays a panel in fixed column positions with no icons. The newer form is aGUI (graphical user interface) that runs on a programmable terminal (a PCrunning Windows or OS/2) and displays the same information in a graphicform. Since not all installations may elect the GUI form, this book shows theoriginal. The main difference between the two, aside from appearance, isthat the original form interrupts the mainframe to do anything, such as dis-play a pull-down list. The GUI interface makes use of its programmable ter-minal to do as much locally as possible. The GUI lets you move the cursorbetween options on a menu with the left/right cursor keys. If an option isunderlined, you can hold the ALT key down and type the first letter of theoption to select it. The various keys display as icons or buttons. Best of all,you can use your mouse to select buttons, pull-down lists, and list boxes.

21.1 USING ISPF

You invoke ISPF by logging into TSO/E and typing ISPF or whatever elseyour installation has provided to invoke it. You then get the first panel, theISPF Primary Option Menu.

379

The top line, termed the action bar, lets you jump out to perform otherfunctions. The numbered items are the main choice for the panel. The bot-tom line shows the active PF (program function) keys and what they dowhen you press them.

21.1.1 Selecting the Action Bar

To select an item on the action bar (the top line), move your cursor to it andpress the Enter key. Move the cursor to the action bar in one of three ways:

� Use the cursor control keys.� If there is a Command ===> line at the bottom of the menu, type the

name of an item on the action bar on it and press Enter.� Press F10 or the Home key.

Once you position the cursor on the action bar, move it to the otheroptions by pressing the Tab key or the cursor movement keys. For example,you might move your cursor to the Utilities option.

Menu Utilities Compilers Options Status Help

This causes a programmable terminal to display a pull-down list. On anonprogrammable terminal, you must press Enter to get the list. ISPF dis-


ISPF Primary Option Menu:Menu Utilities Compilers Options Status Help

------------------------------------------------------------------------------------ISPF Primary Option Menu

0 Settings Terminal and user parameters User ID . : xxxxx1 View Display source data or listings Time. . . : hh:mm2 Edit Create or change source data Terminal. : 32783 Utilities Perform utility functions Screen. . : 14 Foreground Invoke language processing Language. :5 BATCH Submit job for language processing Appl ID . :6 Command Enter TSO or workstation commands TSO logon :7 Dialog Test Perform dialog testing TSO prefix:8 LM Facility Library administration functions System ID :9 IBM Products IBM program development products MVS acct. :10 SCLM SW Configuration Library Manager Release . : ISPF 4.211 Workplace ISPF Object/Action Workplace

Enter X to Terminate using log/list defaults

Option ===>F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=Swap

F10=Actions F12=Cancel

ISPF PRIMARY OPTION MENU

plays the pull-down menu over the panel as shown in ISPF Primary OptionMenu pop-up list.

Select from the pull-down list as you do for any numbered item asdescribed in the following. To cancel a pull-down list, press PF12.

21.1.2 Selecting a Numbered Option

You select numbered items in one of two ways:

� Position the cursor on the Option line, type the number of the itemyou want, and press Enter. This is often the fastest method of select-ing because ISPF positions your cursor to the Option line when itdisplays a new menu.

� Move your cursor directly onto the item and press Enter. Fields thatyou can select by moving your cursor on them and pressing Enter aretermed point-and-shoot fields.

The function keys displayed at the bottom of the menu are alwaysactive. Pressing them results in actions shown in Table 21.1.

In addition to the PF keys, the terminal keys have functions as follows:

Enter key. It acts somewhat as a mouse button to select an item. How-ever, it interrupts the computer and makes available the input

ISPF 381

Menu Utilities Compilers Options Status Help------------------------------------------------------------------------------------

1. Library ry Option Menu0 Set 2. Data set ameters User ID . : xxxxx1 Vie 3. Move/Copy r listings Time. . . : hh:mm2 Edi 4. Data Set List ce data Terminal. : 32783 Uti 5. Reset Statistics ions Screen. . : 14 For 6. Hardcopy ssing Language. :5 BAT 7. ISPSF C/S Install... ge processing Appl ID . :6 Com 8. Outlist ion commands TSO logon :7 Dia 9 . Commands... g TSO prefix:8 LM *0. Reserved n functions System ID :9 IBM 11. Format nt products MVS acct. :10 SCL 12. SuperC ary Manager Release . : ISPF 4.211 Wor 13. SuperCE rkplace

14. Search-ForEnter 15. Search-ForI X to Terminate using log/list defaults

Option ===>F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=Swap


ISPF PRIMARY OPTION MENU POP-UP LIST

fields. The computer then decides what to do, depending on thecontext of the screen. PF keys also interrupt the computer. None ofthe following keys interrupts the computer.

Home key. It moves the cursor to the ISPF command line.

Tab keys. They move the cursor to the next or previous input field onthe screen.

Insert key. Pressing it toggles the reset mode for overtyping or insert-ing text where the cursor is positioned on the screen.

Delete key. It deletes the character where your cursor is on the screen.

Alt key. It acts similar to the shift key, except it results in the actionshown on the face of the key being activated.

Cap Lock key. It toggles the keyboard for uppercase only or upper/lowercase.


TABLE 21.1 ISPF PF Key Functions

Name PF Key Function

Help PF1 Displays a pull-down list for selecting help.Split PF2 Splits the screen to allow you to work on one thing at

the top of the screen and another at the bottom.Exit PF3 Ends the current function and goes back to previous

panel. If you press this when displaying a pull-down list, it exits the panel under the pull-down list. If you are on the ISPF Primary Option Menu, itexits ISPF.

Return PF4 Returns you to the Primary Option Menu. PF4 doesn’tdisplay at the bottom of panels. You must remember it.

Rfind PF5 Finds the next instance after you enter a FIND command.

Rchange PF6 Makes a change for a CHANGE command.Backward PF7 Scrolls the screen up.Forward PF8 Scrolls the screen down.Swap PF9 Swaps the cursor between top and bottom of a split

screen.Action PF10 Moves the cursor to the action bar. If you press it a sec-

ond time, it moves the cursor to the Command line.Cancel PF12 Cancels what you are doing. Press it to remove a pull-

down menu. If you are displaying the ISPF PrimaryOption Menu, this also positions the cursor to theOptions line.

21.1.3 Shortcuts with Menus

If you know the numbers of a series of selections you want, you can typethem all together on the Option line, separating them with periods. Forexample, if you are on the ISPF Primary Option Menu and you want Utili-ties (item 3), and on the Utilities menu you want Hardcopy (item 6), youcan type the following on the Option line to go there directly:

Option ===> 3.6

If you go down several levels in the hierarchy of the menus, you canpress PF3 several times to get back to the ISPF Primary Option Menu. As ashortcut, you can just press PF4.

On any panel with a Command line, you can enter an equal sign (=) fol-lowed by the options you want. The equal sign tells ISPF to return to theISPF Primary Option Menu and then to select the options you specify. Thefollowing takes you directly to the Move/Copy utility panel, regardless ofwhat panel you enter it on.

Command ===> =3.3

To enter a command and not have it erased so that you can edit the com-mand and execute it again, precede it with an ampersand. (After you entera command, you can also press PF12 to have it redisplayed on the Com-mand line so that you can execute it again.)

Command ===> &C This That ALL

To stack several commands on a line and enter them all at once, sepa-rate the commands with semicolons:

Command ===> CAPS OFF;C This That ALL

21.1.4 Common Action Bar Selections

Most of the major menus have a menu bar across the top of the screen, suchas the following:

Menu RefList RefMode Utilities LMF Workstation Help

Here is what the menu choices do:

Menu displays a menu action bar choice that lets you select differentoptions that depend on the screen you are viewing.

RefList displays a pop-up menu that lets you select for display a list ofdata sets and libraries that you have referenced in this ISPF session.

RefMode displays a pop-up list with two choices to tell ISPF what todo when you select a data set from RefList. The List Execute

ISPF 383

option places the data set’s name in the appropriate place in themenu and executes it. The List Retrieve option also selects thedata set, but you must press the Enter key to execute it, enablingyou to examine the screen and make changes before you press theEnter key.

Utilities displays a pull-down list of the ISPF utilities that you canselect.

LMF is an optional feature that controls access to data sets. It lets youkeep other users from accessing a member of a library while you areediting it, and lets you store the member back in a controlled librarywhen you have made your changes.

Workstation controls the graphic user interface.

Help displays a pull-down list for obtaining help.

21.1.5 Printing the Screen

To print a snapshot of the current display on your terminal panel on a high-speed printer when you exit ISPF, enter either of these commands:

Command ===> PRINT (Normal print.)Command ===> PRINT-HI (Double-strike to show highlighted characters.)

The PRINT and PRINT-HI commands print the physical screen. That is,they print exactly what appears on the screen. You can also print the logi-cal screen—data on the screen without any of the ISPF menu. You print thelogical screen by entering the following:

Command ===> PRINTL Print the logical screen.Command ===> PRINTLHI Print the logical screen with highlighting.Command ===> PRINTG Print the screen on a graphics printer.

21.2 USING ISPF FOR PROGRAMMING

21.2.1 Submitting Jobs

To submit a data set, you select the Edit option from the IFSP PrimaryOption Menu and name the data set. After Edit Entry Panel 2 displays onyour screen, enter the SUB (SUBMIT) command to submit it.

The system then displays the following message on your screen:

JOB jobname(jobid) SUBMITTED***


TEAMFLY

Team-Fly®

21.2.2 Printing Your Output: The OUTLIST Utility

Select Outlist (option 8) from the Utilities menu (enter 3.8 on the ISPF Pri-mary Option Menu) to obtain the Outlist Utility Panel 3.8 that lets youexamine the output. List the names of the jobs that you have run and thenselect the ones for which you want output displayed on your terminal, oroutput printed, or output deleted without printing it, or you can change theoutput class.

ISPF 385

Menu Utilities Help------------------------------------------------------------------------------------

Outlist UtilityMore: +

L List job names/id(s) via the TSO STATUS commandD Delete job output from SYSOUT hold queueP Print job output and delete from SYSOUT hold queueR Requeue job output to a new output class

blank Display job output

For Job to be selected:Jobname . .Class . . .JobID . . .

For Job to be requeued:New Output class . . _

For Job to be printed: (A for ANSI)Printer Carriage Control . . _ (M for machine)

(blank for none)

Option ===> ________________________________________________________________________F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=Swap


OUTLIST UTILITY PANEL 3.8

Menu Utilities Compilers Help------------------------------------------------------------------------------EDIT - data-set-name - vv.vv ---------------------- Line 00000000 Col 001 076COMMAND ===> SUB******************************* Top of Data *********************************//userid JOB (account),'name',…

EDIT ENTRY PANEL 2

21.2.3 Interactive Programming: The FOREGROUND Option

Selecting Foreground (option 4) on the ISPF Primary Option Menu givesyou the Foreground Selection Panel 4 with a menu of various language-processing programs that you can execute interactively. The items availabledepend on your installation.

21.2.4 Batch Programming: The BATCH Option

Batch (option 5) on the ISPF Primary Option Menu gives you the BatchSelection Panel 5 that lets you select a language processor. It then generatesthe JCL you need and lets you submit batch jobs. The language processorsavailable will depend on your installation.

21.2.5 Printing Data Sets

Hardcopy (option 6) on the Utilities menu (enter 3.6 on the ISPF PrimaryOption Menu) gives you the Hardcopy Utility Panel 3.6 to print an entiredata set or partitioned data set member.

21.2.6 Entering TSO/E, CLIST, and REXX Commands

Command (option 6) on the ISPF Primary Option Menu lets you enterTSO/E commands, CLISTs, and REXX execs. You get a screen on which you



Foreground Selection Panel

1 High Level Asm / Asm H 10 *VS COBOL II debug1A Assembler XF 10A *OS/VS COBOL debug2 VS COBOL II 11 *FORTRAN debug2A OS/VS COBOL 12 Member Parts List3 VS FORTRAN 13 *C/3704 PL/I checkout 14 *REXX/3705 PL/I optimizing 15 *ADA/3706 VS PASCAL 16 (ADCycle C/3707 Binder/Link editor 17 AD/Cycle COBOL/3709 SCRIPT/VS 18 ISPDTLC

19 *C/C++ for MVS/ESA

Enter "/" to select option * No packed data support_ Source Data Packed

OPTION ===>

FOREGROUND SELECTION PANEL 4

ISPF 387


Batch Selection Panel1 High Level Asm/Asm H 5 PL/I Optimizing 14 *REXX/3701A Assembler XF 6 VS/PASCAL 15 *ADA/3702 VS COBOL II 7 *Binder/Link editor 16 *AD/Cycle C/3702A OS/VS COBOL 10 *VS COBOL II debug 17 AD/Cycle COBOL/3703 VS FORTRAN 12 Member Parts List 18 ISPDTLC4 PL/I checkout 13 *C/370 19 *C/C++ for MVS/ESA

20 *SOMobjects for MVS

Enter "/" to select option * No packed data support_ Source data online_ Source data packed

Job Statement Information: Verify before proceeding===> //userid JOB (account),'name' _________________________________________________===> //* ___________________________________________________________________________===> //* ___________________________________________________________________________===> //* ___________________________________________________________________________

Option ===> ________________________________________________________________________

Menu RefList Utilities Help------------------------------------------------------------------------------------

Hardcopy UtilityProcess option _ 1. Print and keep data set or member

2. Print and delete sequential data set

Data Set Name . . . ._____________________________________________________________Volume Serial . . . ._______(If not cataloged)Data Set Password ._______(If password protected data set)

Print Mode . . . . . . BATCH (BATCH or LOCAL)

Sysout class . . . . ._______(BATCH only)Local Printer ID . . ._______

Job statement information: (If not to local printer, verify before proceeding)===> //userid JOB (account),'name' _________________________________________________===> //* ___________________________________________________________________________===> //* ___________________________________________________________________________===> //* ___________________________________________________________________________Command ===> _______________________________________________________________________F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=SwapF10=Actions F12=Cancel

BATCH SELECTION PANEL 5

HARDCOPY UTILITY PANEL 3.6

can type your command. Actually, you don’t need the Command option toenter a TSO/E command. You can enter a TSO/E command on any Com-mand line. Just type TSO followed by the command:

Command ===> TSO LISTC

21.3 EDITING DATA SETS

To edit a data set, select Edit (option 2) on the ISPF Primary Option Menuto get Edit Entry Panel 2a and name the data set to edit.

Data sets usually have a three-level name: project.group.type. To accessa data set, enter these three items where indicated. To edit a partitioneddata set, enter the member name on the Member line. The following showshow to enter member SUB2 of the partitioned data set namedPAYROLL.DEVELOP.COBOL.

ISPF Library:Project . . . PAYROLL_Group . . . . DEVELOP_ . . . . . . . . . Type . . . . COBOL_Member . . . SUB2_ (Blank or pattern for member selection list)


Menu RefList RefMode Utilities Help------------------------------------------------------------------------------------

Edit Entry PanelMore _

ISPF Library:Project . . .____________Group . . . .____________ . . . ____________ . . . __________ . . . __________Type . . . .____________Member . . . _______(Blank or pattern for member selection list)

Other Partitioned or Sequential Data Set:Data Set Name . . . ___________________________________________________________________Volume Serial . . . ___________ (If not cataloged)

Initial Macro . . . . __________ Enter */* to select optionProfile Name . . . . . __________ Confirm Cancel/Move/ReplaceFormat Name . . . . . __________ Mixed Mode

Data Set Password . . (If password protected) LMF Lock1. Never2. No3. Yes

Command ===> ______________________________________________________________________________F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=SwapF10=Actions F12=Cancel

EDIT ENTRY PANEL 2a

If the data set has some other naming convention, enter the name on theData Set Name line. (To access a member of a partitioned data set this way,enter data-set-name(member) on the line.) Enter the name the way youwould for TSO/E. If you don’t enclose the name in apostrophes, the systemappends your LOGON id to the left of it as the first level. If you enclose thename in apostrophes, ISPF uses the exact name you enter. Enter the VolumeSerial, Data Set Password, and Profile Name only as required.

Other Partitioned or Sequential Data Set:Data Set Name . . . 'PAYROLL.DEVELOP.COBOL(SUB2)'Volume Serial . . . (If not cataloged)

If you aren’t sure what member you want or can’t remember its name,leave the Member blank and press Enter. You will get the Member ListPanel showing you the members.

You can also use the % and * as wild card characters in typing a mem-ber name to select members. The % represents a single character and * rep-resents one or more characters. T* would then select all members withnames that begin with T. If there are too many member names to fit on thescreen, you can scroll up and down to view the remainder.

The Row 00001 of 00003 tells you which line in the list is at the top ofthe screen and how many lines there are in the list. The columns give thefollowing information:

Name gives the member names.

Prompt shows information about the last action taken for a member.

VV.MM gives the version (VV) and the modification level (MM). MM isincremented each time you save the member.

Created gives the date created.

Changed gives the date and time last modified.

Size gives the current size in lines or records.

Init gives the initial size of member in lines or records.

ISPF 389

Menu Functions Confirm Utilities Help------------------------------------------------------------------------------

LIBRARY data-set-nameRow 00001 of 00003

Name Prompt VV.MM Created Changed Size Init Mod ID_ member ______ nn.mm yy/dd/mm yy/dd/mm hh:mm n n n userid_ member ______ nn.mm yy/dd/mm yy/dd/mm hh:mm n n n userid_ member ______ nn.mm yy/dd/mm yy/dd/mm hh:mm n n n userid

MEMBER LIST PANEL

Mod gives the number of lines added or changed since the version wascreated.

ID gives the userid of the person who created or updated this version.

You can enter any of the following commands to the left of the membername to act on the member:

B Browse the member.C Copy the member.D Delete the member.E Edit the member.G Reset statistics for the member.M Move the member.P Print the member.S Select the member. (Same as edit.)R Rename the member. Type the new name on the Prompt line.

Selecting a data set or member to edit gets you Edit Entry Panel 2b. Thetop line tells you the data set you are working on, the columns being dis-played, and the scrolling in effect.

When you edit an empty data set or member, you get Edit Entry Panel 2c.As you type in text and press Enter, unused lines—lines on which you

haven’t typed anything—are removed and each line is given a line number.Press PF10 to scroll right, beyond column 72 and PF11 to scroll back left.ISPF automatically numbers your lines. The numbers are for reference onlyand aren’t stored as part of the data unless you request this with the NUMON command described later.


File Edit Confirm Menu Utilities Compilers Test Help--------------------------------------------------------------------------EDIT PAYROLL.DEVELOP.COBOL(SUB2) - 1.01 Col 001 080****** **************************** Top of Data **************************000001 Line 1000002 Line 2000003 Line 3. . .00000n Line n****** ************************** BOTTOM OF DATA *************************

Command ===> ___________________________________________________________Scroll --->F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=SwapF10=Actions F12=Cancel

EDIT ENTRY PANEL 2b

The action bar contains the following:

File Edit Confirm Menu Utilities Compilers Test Help

File pull-down menu lets you SAVE, EXIT, or CANCEL. These can all beentered by commands described in the following.

Edit pull-down window lets you RESET, UNDO, or HILITE. Descrip-tions of the commands follow.

Confirm displays a panel to give you the option of confirming cancella-tions, moves, or replacements.

Menu gives you the menu action bar choices.

Utilities lets you select utilities.

Compilers lets you select the compilers available.

Test pull-down menu lets you select various options for the dialog testfeature.

Help pull-down menu lets you select help.

To jump out and edit another data set or member of a partitioned dataset while you are editing, you enter the following to get a menu on which toenter the name of a new data set to edit.

Command ===> EDIT

Alternatively, you can name another member of this partitioned data setto edit.

Command ===> EDIT member

Press PF3 to return to the original data set you were editing.

ISPF 391

File Edit Confirm Menu Utilities Compilers Test Help------------------------------------------------------------------------------EDIT PAYROLL.DEVELOP.COBOL(SUB2) - 1.01 Col 001 080****** **************************** Top of Data ******************************′′′′′′′′′′′′′′′′′′ This is where you′′′′′′ enter your data.′′′′′′′′′′′′****** ************************** BOTTOM OF DATA *****************************

Command ===>__________________________________________________________Scroll ---> CF1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=SwapF10=Actions F12=Cancel

EDIT ENTRY PANEL 2c

21.3.1 Entering Commands

ISPF provides the following ways to enter commands:

� Select a pull-down list from the action bar.� Press a PF key� Type the command name on the Command ===> line and press Enter.� Type a command over a line number. These commands apply to indi-

vidual lines.

The following sections describe the various edit commands.

21.3.2 Editing Commands to Change Text and Its Display

Enter the following editing commands on the Command ===> line at thebottom of a screen.

CAPS ON or OFF toggles the caps mode on and off.

HEX ON or OFF toggles the display of data in hexadecimal format.Hexadecimal display is on three lines, the first line for the charac-ters, and the two lines below it for the two hexadecimal digits.

NULLS ON or OFF toggles the null character mode. NULLS ON placesnull characters (hexadecimal value of X‘00’) at the end of lines;NULLS OFF places blanks.

PACK ON or OFF toggles packing text to save disk space. ISPF automat-ically unpacks packed text when you edit it.

21.3.3 Editing Commands to Browse, Edit, and Save Data Sets

BROWSE lets you jump out and browse another data set. BROWSEmember lets you browse a member of the current data set. BROWSEis like edit except that you can’t change the data set.

EDIT member lets you jump out and edit another member of the samedata set.

END ends the edit session and, if AUTOSAVE is on, saves the data set.

AUTOSAVE ON or OFF toggles the feature to automatically save yourdata set when you end the edit session. If you set AUTOSAVE OFFand end the edit session, ISPF will ask you whether you want tosave the data set before exiting. AUTOSAVE ON automatically savesthe data set when you end.

CANCEL exits the editor without saving the data set on which you areworking. This is handy when you have made changes that you don’twant to keep.


SAVE saves the data set without exiting edit. You might do this so thatyou don’t lose all your changes if the computer crashes, but a betterway is to set the recovery mode on.

RECOVERY ON or OFF toggles the recovery mode that lets you recoverall your changes made to a data set during a terminal session shouldthe computer crash.

21.3.4 Editing Commands to Undo Changes

UNDO lets you undo your most recent changes to the data set. You mustfirst turn the undo mode on with SETUNDO ON so that ISPF willsave your changes as you make them. You can enter UNDO severaltimes to undo a series of changes.

SETUNDO ON or OFF toggles the undo mode that lets you undochanges with the UNDO command.

21.3.5 Other Editing Commands

RESET removes any pending line commands, such as MOVE, COPY,and DELETE and removes any scale, ISPF line messages, and linemarking. It doesn’t remove line labels. Remove them with RESETLABEL.

LEVEL n sets the modification level (0 to 99) to n. This is used to keeptrack of changes.

VERSION n sets the version level (1 to 99) to n. This is also used to keeptrack of changes.

STATS ON or OFF toggles the stats mode on and off. ISPF keeps statis-tics for the data set when the stats mode is on.

There are several more commands that require more explanation dis-cussed later in this chapter.

21.3.6 Entering Text

You type your data on the lines made available for you on the EDIT panel.When you press Enter, ISPF removes the empty lines. Press the Home keyto move the cursor from the text area to the Command line.

To enter the text freeform, without having to do carriage returns(called power typing), type TE over the line number and press Enter. Linesare opened up for you to type on and ISPF automatically performs a car-riage return when you reach the end of a line. You can’t use tabs when youuse TE.

ISPF 393

To reflow the words in a paragraph, type TF over the line number of thefirst line of a paragraph. ISPF reflows all of the text within the bounds to theend of the paragraph. Bounds (margins) can be set as described later. Ablank line or indent marks the end of a paragraph.

To split a line, type TS over the line number, move the cursor underwhere you want to split, and press Enter. The system inserts the split partof the line on the next line and starts on the left margin.

The MASK feature automatically places fixed data into each new line.Do the following:

1. Type MASK over a line number and press Enter.mask00 This is a line.000200 This is another line.

The system displays any current MASK.00100 This is a line.MASK>000200 This is another line.

2. Overtype the MASK line with whatever mask you want and pressEnter.000100 This is a line.MASK> | | XYZ000200 This is another line.

Whatever you type as the mask will now appear on each new line asyou insert it.

3. Then type an I, TF, or TS command over a line number to insert newlines.I30100 This is a line.MASK> | | XYZ000200 This is another line.

The result is000100 This is a line.000200 | | XYZ000300 | | XYZ000400 | | XYZ000500 This is another line.

21.3.7 Exiting the Editor

Exit from the EDIT panel by either

� Pressing PF3 or entering the END command. This saves the data setand returns to the previous Edit Entry Panel.

� Pressing PF4. This saves the data set and returns to the ISPF PrimaryOption Menu.


TEAMFLY

Team-Fly®

� Entering the CANCEL command. This returns to the previous editentry panel without saving the data set.

21.3.8 Displaying Text

ScrollingThe PF keys for scrolling are as follows:

PF7 or PF19 scrolls up.

PF8 or PF20 scrolls down.

PF10 or PF22 scrolls left.

PF11 or PF23 scrolls right.

Listing Specific LinesYou can also list text beginning at some line number by entering the L (forLOCATE) command on the Command line:

Command ===> L 1 Lists starting at the first line.Command ===> L 99999 Lists starting at 99999 of the data set.Command ===> L FIRST List starting at the first line.Command ===> L LAST Lists the last line.

Rather than listing by line number, you can plant labels in the data setand name them in an L command. This acts like a bookmark feature. Youtype the labels over a line number. The label must begin with a period andbe one to five alphabetic characters (.label). The labels are not stored as apart of your data set, but exist only during the terminal session. The firstcharacter cannot be a Z because ISPF provides three built-in labels thatbegin with a Z:

.ZF represents the first line of your data set. Same as FIRST.

.ZL represents the last line of your data set. Same as LAST.

.ZCSR represents the line your cursor is on—or the first line on thescreen if your cursor is not in the data area.

You can then use the LOCATE command to list lines by the label, just asyou list them by line number: L .label. To list the first lines (top) of the dataset, enter the following:

Command ===> L .ZF or L 1 or L FIRST

To list the last lines (bottom) of the data set, enter the following:

Command ===> L .ZL or L LAST

ISPF 395

21.3.9 Editing Commands

Inserting LinesTo insert lines following a line in the text, type an I over the line numberand press Enter. (You can type all commands in upper- or lowercase.)

I inserts a line.

In inserts n lines, where n is an integer.

For example, if you typed an I3 as shown here:

000100 IDENTIFICATION DIVISION.000200 PROGRAM-ID. JCLTEST.I30300 ENVIRONMENT DIVISION.000400 CONFIGURATION SECTION.

three lines would be opened up below it as follows:

000100 IDENTIFICATION DIVISION.000200 PROGRAM-ID. JCLTEST.000300 ENVIRONMENT DIVISION.’’’’’’’’’’’’’’’’’’000400 CONFIGURATION SECTION.

Any lines on which you then type become part of the data set. Any lineson which you don’t type are removed when you press Enter. When youinsert lines, the lines following the point of insertion are renumbered whenyou press Enter.

Deleting LinesTo delete lines, type the following over the line numbers to delete and pressEnter.

D deletes a line.

Dn deletes n lines, where n is a number.

DD defines a range of lines to delete. You type a DD over the first andlast line number of the range.

The following shows how to delete a range of lines.

000100 IDENTIFICATION DIVISION.dd0200 PROGRAM-ID. JCLTEST.000300 ENVIRONMENT DIVISION.000400 CONFIGURATION SECTION.dd0500 SOURCE-COMPUTER. IBM-390.000600 INPUT-OUTPUT SECTION.


When you press Enter, the lines are deleted, and the lines following thedeletion are renumbered.

000100 IDENTIFICATION DIVISION.000200 INPUT-OUTPUT SECTION.

Copying and Moving LinesCopying and moving lines is a two-step process:

1. First, type a C or M over the top of the line to move or copy.

2. Then move the cursor to the line number where you want the linescopied or moved and type an A on the line (to copy or move after),a B (to copy or move before this line), or an O (to overlay this line),and press Enter.

You can type the following over the line numbers:

C to copy this line.

Cn to copy n lines, where n is an integer, starting at this line.

M to move this line.

Mn to move n lines, where n is an integer, starting at this line.

A to insert after this line.

B to insert before this line.

O to insert over this line. ISPF overlays only blank characters in theline.

To copy or move a range of lines, termed a block, you type an MM or CCover the first and last line number of the range.

MM defines a range of lines to move.

CC defines a range of lines to copy.

Here is an example of moving a range of lines.

000100 IDENTIFICATION DIVISION.mm0200 PROGRAM-ID. JCLTEST.000300 ENVIRONMENT DIVISION.000400 CONFIGURATION SECTION.mm0500 SOURCE-COMPUTER. IBM-390.a00600 INPUT-OUTPUT SECTION.

When you press Enter, the move is made and the lines are renumbered,resulting in the following:

000100 IDENTIFICATION DIVISION.000200 INPUT-OUTPUT SECTION.

ISPF 397

000300 PROGRAM-ID. JCLTEST.000400 ENVIRONMENT DIVISION.000500 CONFIGURATION SECTION.000600 SOURCE-COMPUTER. IBM-390.

When you use a CC or MM to copy or move a block of lines and youwant to overlay them over other lines, define the block of lines to overlaywith OO over the first and last line of the block.

Moving or Copying Lines from Another Data SetTo move or copy an entire member or a data set into the text you are cur-rently editing, mark where you want the data copied with a B (before thisline) or A (after this line) or O (overlay this line). Then enter COPY orMOVE on the command line, naming the member to copy in.

Command ===> COPY member or MOVE member

If you code COPY or MOVE without naming a member, ISPF displays apanel on which to name the sequential data set or partitioned data set member.

Storing into Another Data SetTo save lines in the data set you are working on into another data set, youfirst mark the lines you want to save by typing the following over the linenumbers.

To copy: C To move: MCn MnCC/CC MM/MM

Then enter one of the following commands:

Command ===> CREATE member

[For partitioned data sets only. Stores the text as a new member ofthe current data set.]

Command ===> CREATE

[To store in another sequential data set. You get a panel on which toname the other data set.]

Command ===> REPLACE member

[To replace a partitioned data set member in the current data set.]

Command ===> REPLACE

[To replace a sequential data set or a member of a partitioned dataset other than the one on which you are currently working. You geta panel on which to name the other data set.]


Repeating LinesTo repeat lines, type the following over the line number and press Enter.This replicates the line or range of lines:

R repeats this line.

Rn repeats this line n times, where n is an integer.

RR defines a range of lines to repeat. Type RR on the first and last lineof the range of lines you want repeated.

RRn typed on a line repeats the range of lines n times.

Shifting ColumnsColumns are shifted left or right n spaces by typing parentheses over theline numbers:

� Shift n columns in a single line.Left: (n Right: )n

� Shift n columns for a range of lines.Left: (( Right: ))

((n ))n

Data is lost if it is shifted beyond the left or right margin. Alternatively,you can also do what ISPF terms data shifting. With data shifting, the linesare shifted, but they are never moved closer than one space from the left orright margin.

� To data shift n columns in a single line, you enter:Left: <n Right: >n

� To shift n columns for a range of lines, enter:Left: << Right: >>

<<n >>n

Finding and Changing DataFinding Text—The FIND Command Write the FIND command as

Command ===> F word Or F 'characters'

The apostrophes are needed if there is an embedded blank or comma.ISPF begins its search at your current cursor position (or with the first charac-ter on the screen if your cursor is in the Command area) and continues for-ward. You can find the next instance by pressing PF5. Tell ISPF where to startthe search and how to search for the characters by entering the F command as

Command ===> F options 'characters' Or F 'characters' options

The first set of options tells where to start the search and the directionto search:

ISPF 399

ALL starts with the first character, counts the number of times found,and positions to the first instance.

FIRST starts with the first character and searches forward for the firstoccurrence.

LAST is the opposite of FIRST. It starts at bottom of data and searchesbackward to find the last occurrence.

NEXT (default) starts from the cursor position (or with the first charac-ter on the screen if your cursor is not in the text area) and searchesforward for the next occurrence.

PREV is opposite of NEXT. It starts where your cursor is (or with the lastcharacter on the screen if your cursor is not in the text area) andsearches backward.

The second set of options specify how to search for characters:

CHAR (default) just finds any characters in the data that match ‘charac-ters’.

SUF finds the characters as a suffix—at the end of a word.PRE finds the characters as a prefix—at the beginning of a word.WORD finds the characters as a complete word.

Here are some examples:

Command ===> F WORD THE

[Finds the next occurrence of the word the or The or THE. ISPFignores upper- and lowercase in the search.]

Command ===> F FIRST SUF ING

[Finds the first occurrence of a word ending in ing, ignoring thecase.]

Command ===> F PREV "THE END"

[Searches backward to find the previous occurrence of the string theend, ignoring the case.]

To search for characters matching upper- or lowercase exactly, enclosethe string in apostrophes and place a C in front of it. The following com-mand searches for the next occurrence of the lowercase characters the.

Command ===> F C'the'

Changing Text—The CHANGE Command You can find characters andthen change them by writing:

Command ===> C old-word new-word OrC 'old-characters' 'new-characters'


The apostrophes are needed if the characters contain blanks or commasor are a search option, such as ALL. To make several selective changesthroughout the text, do the following steps.

1. Press PF5 to find the next instance of the old characters.

2. Press PF6 if you want to change the characters.

3. Continue with step 1 to find the next instance.

The search begins where your cursor is positioned (unless it is not inthe data area; then it begins with the first character on the screen). You canalso write the same options for CHANGE as FIND.

Command ===> C options 'old-characters' 'new-characters'

Here are some examples:

Command ===> C FIRST C'THE END' 'That’s all folks'Command ===> C PREV GONE WENT

Limiting the Search or Change The EXCLUDE command (abbreviated X)excludes lines from viewing on the screen or from a FIND or CHANGE. Itoperates like FIND. When you execute the EXCLUDE command, the linesthat match the characters in the command disappear from the display. Youthen have the option on the FIND and CHANGE command of excludingthese lines from a search. You write EXCLUDE as

Command ===> X options 'characters'

The options are the same as those for FIND and CHANGE. For example,if you had these lines:

000300 LOS ANGELES 33967 833291000400 NEW YORK 45639 228456000500 NEW YORK 22974 536781000600 PHOENIX 11248 388857

and you entered this command:

Command ===> X 'NEW YORK'

the display would appear as follows:

ISPF 401

EDIT PAYROLL.DEVELOP.COBOL(SUB2) = 01.01 Line 00000000 Col 001 080*********************************** Top of Data ******************************000300 LOS ANGELES 33967 833291- - - - - - - - - - - - - - - - - - - - - - - - - -.- 2 LINE(S) NOT DISPLAYED000600 PHOENIX 11248 388857

The RESET command negates the EXCLUDE and makes the lines reap-pear. As an alternative to EXCLUDE, you can mark specific lines in the textto be excluded by writing an X or XX over line numbers:

X Exclude one line. XX Exclude a block of lines.XX

The FLIP command reverses the exclusion. Excluded lines becomeincluded and included lines excluded.

Command ===> FLIP

The FIND and CHANGE commands operate on all lines (bothINCLUDED and EXCLUDED) unless you specify otherwise. You do this byadding the X or NX option to the FIND or CHANGE command. X limits theoperation to only the excluded lines. NX limits the operation to only thelines not excluded.

F options X 'characters' Or F options NX 'characters'C options X 'old' 'new' Or C options NX 'old' 'new'Command ===> F NEXT WORD X 'smith'

To search a range of lines, from one label through a second, you list thelabels. The following example searches from .STEP1 through .STEP2.

F .STEP1 .STEP2 'washington'

The FIND, CHANGE, and EXCLUDE commands normally operate on anentire line. However, you can set margins (or bounds) to specify the startingand ending columns of the text to operate on. Alternatively, you can spec-ify a starting and ending column in the FIND, CHANGE, or EXCLUDE com-mand itself. The following FIND command searches only columns 20through 30 in the text.

Command ===> F ALL 20 30 'THE END'

FIND, CHANGE, EXCLUDE Options The complete FIND, CHANGE, andEXCLUDE commands are as follows:

NEXTALL CHARFIRST SUFLAST PRE XPREV WORD NX

F .label .label first-col last-col 'characters'C .label .label first-col last-col 'old' 'new'X .label .label first-col last-col 'characters'


You can write the characters on a FIND, CHANGE, or EXCLUDE com-mand as follows:

‘characters’ by enclosing the characters in single quotation marks

“ ‘characters” when the characters begin or end with single quotationmarks

C‘characters’ to search for exact match of upper- or lowercase charac-ters

The new characters in a CHANGE command can be

characters if there are no blanks, commas, and it is not a special ISPFword such as WORD.

‘characters’ if the characters begin or end with an apostrophe or con-tain embedded commas, blanks, or a special ISPF word such asWORD. For simplicity, always enclose the string in apostrophes.

The search string can also be a picture string as shown in Table 21.2.The following example searches for any nondisplayable characters in

the text.

Command ===> F P'.'

To find the first string of three numeric characters, you code

Command ===> F P'###'

You can use the P‘#’, P‘>’, and P‘<” picture characters as the new char-acters for a CHANGE, as long as the old and new have the same number ofcharacters. The following example illustrates this.

C P'<#>' P'>#<'

ISPF 403

TABLE 21.2 String Search Options

String Searches for

P‘=’ Any character. (The “don’t care” character)P‘¬’ Any nonblank characterP‘.’ Any nondisplayable character—usually an invalid characterP‘#’ Any numeric (0 to 9) characterP‘-’ Any nonnumeric characterP‘@’ Any alphabetic character (A to Z, a to z). Upper- or lowercaseP‘<’ Any lowercase alphabetic character (a to z)P‘>’ Any uppercase alphabetic character (A to Z)P‘$’ Any special character. (Not A to Z, a to z, or 0 to 9)

The P‘<#>’ searches for a lowercase character followed by any characterfollowed by an uppercase character. The P‘>#<” changes the first characterto uppercase, leaves the second character unchanged, and converts thethird character to lowercase. Thus, abC would be changed to Abc.

Line NumberingISPF automatically numbers your text and displays the line numbers in thefirst six columns of the display. However, the line numbers are not made apart of your data and are lost when you save the data set unless you requestISPF to save them for you. You do this by entering the NUM ON command.Numbers are stored in columns 1 to 6, 1 to 8, or 73 to 80, depending on thedata type.

Command ===> NUM ON Or just NUM

You can also specify the language and ISPF will number the lines incolumns appropriate to the language as indicated by the lowest-level qual-ifier of the data name. You can also specify the language in the NUM com-mand. The following stores line numbers in columns 1 to 6.

Command ===> NUM ON COBOL

NUM OFF turns line numbering off. During an edit session, you canrenumber lines by entering:

Command ===> REN

To remove the line numbers from the display so that your lines begin inthe left column, enter the UNN command. UNN also sets NUM OFF.

Command ===> UNN

When you save a data set with NUM ON, ISPF automatically renumbersthe lines, beginning with 100 and incrementing by 100. To save the data setwith renumbering, you enter

Command ===> AUTONUM ON Or just AUTONUM

You can turn line numbering off by entering

Command ===> AUTONUM OFF

Displaying the Rule LineTo display a scale under a line to show column positions, type COL over aline number.

col100 This is a line.

results in:


TEAMFLY

Team-Fly®

000100 This is a line.=COLS> ---+---1---+---2---+---3---+---4---+---5---+---6---+---7---+

21.3.10 Setting the Editing Environment

Setting TabsBecause of limitations on the 3270-type terminal, ISPF has three types oftabs: software, hardware, and logical. All three have their problems.

Hardware Tabs For hardware tabs, you must first enable the tabs by entering

COMMAND ===> TABS ALL

Then you set the tab columns by typing TABS over a line number andpressing Enter. (If you want a scale, first type COLS over the line.) Thenspecify the tab positions by typing an asterisk one column to the left ofwhere you want the tabs set and press Enter to set the tabs. ISPF places ahardware character in the column for each tab set. When you press the Tabkey, the hardware positions the cursor to the immediate right of the hard-ware character. You can’t see the hardware character because it displays asa blank. If you have data in the columns, they are wiped out. Obviously, thismight work for columns of data, but is worthless for text.

Software Tabs For software tabs, you don’t need to enter the TABS ALLcommand. You set software tabs the same as hardware tabs, except that youspecify the tab positions by typing a dash (-) or underline (_) rather than anasterisk (*) in the columns of the scale line where you want a tab set. Thenpress Enter to set the tabs. To tab, press the Enter key as you are typing.ISPF moves the cursor right to the next tab set. The problem with this is thatpressing Enter is not a natural action for tabbing. The computer must alsobe interrupted to perform a tab, and the response can be slow.

Rather than just a single tab position, you can define a field by settingtwo or more tabs consecutively. When you tab to such a field, ISPF posi-tions to the first nonblank character in the field, or if the entire field isblank, to the first character.

Logical Tabs Logical tabs let you tab by typing any character that you spec-ify as the tab by entering:

COMMAND ===> TABS ON character

For example:

COMMAND ===> TABS ON @

Now any time you type the @ character, the effect is a tab. You won’t seeanything on the screen until you press Enter. Then the @ characters will be

ISPF 405

removed and the text will be aligned according to the tabs. You might typesuch a line as

443545@992614@4417@9

Then when you press Enter, the tabbing is done and the line mightappear as follows, assuming tabs were set in columns 10, 19, and 26:

443545 992614 4417 9

The problem with this is that typing some character is not a naturalaction for tabbing, and you can’t see what your line actually looks like untilyou press Enter, which interrupts the computer, so response can vary. Tabsstay in effect until you remove them. They are saved with your profile forthe document.

Margins (or Bounds)To set up margins or bounds, type BOU over the line number of a line andpress Enter. Any current bounds are displayed on a line with < indicatingthe left bound and > the right bound. To change a bound, delete the < or >character, retype it where you want the bounds set, and press Enter.

A FIND, CHANGE, or EXCLUDE command does not search the text inthe columns outside of the bounds you set. You can also enter the BOUcommand to set the bounds.

Command ===> BOU left-column right-column

Code an asterisk (*) in place of a column to leave that boundunchanged. The following example sets the left bounds to column 7 andleaves the right bounds unchanged.

Command ===> BOU 7 *

Upper- or LowercaseCAPS OFF lets you enter text in upper- and lowercase. CAPS ON coverts allyour text to uppercase as you enter it.

Command ===> CAPS ON Or CAPS OFF

To convert lines to upper- or lowercase after you type them in, ISPF pro-vides two sets of commands. You type the command over the line numbers.

UC converts a single line to uppercase.

UCn converts n lines to uppercase.

UCC typed over a beginning and ending line converts the block of linesto uppercase.


LC converts a single line to lowercase.

LCn converts n lines to lowercase.

LCC typed over a beginning and ending line converts the block of linesto lowercase.

Saving the Editing EnvironmentAll the tabs, margins, and other information you set for an editing session con-stitutes your editing profile. ISPF saves the profile when you save a data set.The system reinstates the profile when you edit the data set again. The datatype in the data set name should match the language name (COBOL, PL/I, andso forth) because ISPF keeps a separate profile of each data type for you.

You can name and enter several different profiles. Name the profile onthe Profile Name line of the Edit Entry Panel. To display the profile cur-rently in effect, enter

Command ===> PRO

To save a profile or request a new one during an edit session, enter

Command ===> PRO name

The name is a one- to eight-character name, first character alphabetic. Ifa profile exists with this name, ISPF uses it. Otherwise, ISPF saves the cur-rent profile under this name.

You can make changes to your edit profile during an edit session andnot save the changed profile when you exit the editor by entering:

Command ===> PRO LOCK Unlock it with: PRO UNLOCK

21.3.11 Sorting Text

The most general form of the SORT command is

XNX

SORT .label .label sort-field sort-field ... sort-field

The X or NX are optional and tell whether to sort just the excluded lines(NX) or to sort all but the excluded lines (X). You write each sort-field as

order first-column last-column

[order is A for ascending and D for descending.]

The following sorts lines 200 to 300 on columns 10 to 20 in ascendingorder.

ISPF 407

Command ===> SORT 200 300 A 10 20

The next example sorts all the lines on columns 10 to 20 in ascendingorder and then columns 30 to 35 in descending order.

Command ===> SORT .ZF .ZL A 10 20 D 30 35

If you don’t specify first-column and last-column, ISPF uses all thecolumns of a line for sorting. If bounds have been set, the system uses onlythe columns within the bounds to determine the sort order. The followingsorts all the lines into descending order using all the columns for the sortkey.

Command ===> SORT D

If you name only one column, ISPF sorts from that column to the end ofthe line (or the right bounds column). The following sorts all the lines intodescending order using column 10 to the end of the line for the sort key.

Command ===> SORT D 10

Ascending sort order is assumed if you don’t write an A or D. The fol-lowing sorts on columns 16 to 20 in ascending order.

Command ===> SORT 16 20

You can write several sort fields. If you write an A or D for one field, youmust write them for all fields:

Command ===> SORT A 1 10 D 15 20

You can sort only excluded lines or lines not excluded:

Command ===> SORT X ... [Sorts only excluded lines.]Command ===> SORT NX ... [Sorts only lines not excluded.]

You can also sort from a starting label to an ending label:

Command ===> SORT .FROM .TO D 17 20

21.4 BROWSING TEXT

To browse a data set, select View (option 1) on the ISPF Primary OptionMenu to get View Entry Panel 1.

Fill in the name of the data set you wish to view. The Browse option dif-fers from the EDIT in that browse is “look but don’t touch.” Browse allowsseveral people to browse the same data set at the same time whereas only


one person can edit a data set at a time. Browsing also uses less computerresources than editing. In addition to the function keys, you can enter thefollowing commands when you browse a data set: DISPLAY, COLUMNS,FIND, HEX, LOCATE, RESET, SUBMIT, VIEW, BROWSE, and EDIT.

21.5 THE ISPF UTILITIES

Selecting Utilities (option 3) on the ISPF Primary Option Menu gives youthe Utility Selection Panel 3.

21.5.1 Operations on Partitioned Data Sets

Selecting Library (option 3.1) from the Utilities Selection Panel gives youthe Library Utility Panel 3.1, allowing you to perform operations on parti-tioned data sets.


blank displays a member list.

C compresses a PDS.

X prints general information about the data set (size, record length,blocking, and so forth) and prints a list of the member names. You

ISPF 409

Menu RefList RefMode Utilities Help---------------------------------------------------------------------------

View Entry PanelISPF Library:

Project . . . ________Group . . . . ________ . . . ________ . . . ________ . . . ________Type . . . . ________Member . . . ________ (Blank or pattern for member selection list)

Other Partitioned or Sequential Data Set:Data Set Name . . . _____________________________________________________________Volume Serial . . . ___________ (If not cataloged)

Initial Macro . . . . ___________ Enter "/" to selectProfile Name . . . . . ___________ _ Browse ModeFormat Name . . . . . ___________ _ Confirm Cancel/Move/Replace

_ Mixed Mode

Data Set Password . . (If password protected)

Command ===>_______________________________________________________________________F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=SwapF10=Actions F12=Cancel

VIEW ENTRY PANEL 1


Menu Help------------------------------------------------------------------------------

Utility Selection PanelMore +

1 Library Compress or print data set. Print index listing. Printrename, delete, browse, edit or view members.

2 Data Set Allocate, rename, delete, catalog, uncatalog, or displayinformation of an entire data set.

3 Move/Copy Move, copy, or promote members of data sets4 Dslist Print or display (to process) list of data set names.

Print or display VTOC information5 Reset Reset statistics for members of ISPF library6 Hardcopy Initiate hardcopy output7 ISPF C/S Install ISPF C/S workstation code from MVS to your workstation.8 Outlist Display, delete, or print held job output9 Commands Create/change an application command table* Reserved This option reserved for future expansion.11 Format Format definition for formatted data Edit/Browse12 SuperC Compare data sets (Standard dialog)13 SuperCE Compare data sets and Search for strings (Extended dialog)14 Search For Search data sets for strings of data. (Standard dialog)Option ===> __________________________________________________________________F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=SwapF10=Actions F12=Cancel

Menu RefList Utilities Help-------------------------------------------------------------------------------

Library UtilityMore +

Blank Display member list E Edit memberC Compress data set V View memberX Print index listing B Browse memberL Print entire data set D Delete memberI Data set information R Rename memberS Short data set information P Print member

ISPF Library:Project . . . ________Group . . . . ________ . . . ________ . . . ________ . . . ________Type . . . . ________Member . . . ________ (If B, D, E, P, R, V, or blank selected)New name . . ________ (If R selected)

Other Partitioned or Sequential Data Set:Data Set Name . . . ________________________________________________________Volume Serial . . . _______(If not cataloged)

Option ===> ___________________________________________________________________F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=SwapF10=Actions F12=Cancel

UTILITY SELECTION PANEL 3

LIBRARY UTILITY PANEL 3.1

fill in the data set name but not the member name for this. (You canalso use this option for sequential data sets.)

L prints the entire data set. Don’t fill in the member name. (You can alsouse this option for sequential data sets.)

I displays information about the data set, such as the record type,length, blocking, space allocation, directory blocks used, and mem-ber names.

S is the same as I, except a list of members and directory block infor-mation is not displayed.

When you display the member list, you get a pop-up window display-ing the following option for members of a partitioned data set.

B browses through a member. (There is also a BROWSE option on theISPF Primary Option Menu that does the same thing.)

C copies a member.

D deletes a member.

E edits a member.

G resets the panel display.

M moves a member.

P prints a member.

R renames a member.

T prompts you for a TSO/E command for a member.

V lets you view a member.

W displays a panel for entering WS commands.

21.5.2 Creating, Deleting, and Renaming a Data Set

To operate on data sets as a whole, select the DATA SET option 3.2 from theUtilities Selection Panel. You get the Data Set Utility Panel 3.2.

Enter an ISPF library name in the top menu:

ISPF Library:Project . . . ________Group . . . . ________Type . . . . ________

Write the name of a partitioned or sequential data set name in the lowerfield.

ISPF 411


Menu RefList Utilities Help------------------------------------------------------------------------------

Data Set UtilityA Allocate new data set C Catalog data setR Rename entire data set U Uncatalog data setD Delete entire data set S Data set information (short)

Blank Data set information M Enhanced data set allocationV VSAM Utilities

ISPF Library:Project . . . ________Group . . . . ________Type . . . . ________

Other Partitioned, Sequential or VSAM Data Set:Data Set Name . . . _______________________________________________________Volume Serial . . . ________ (If not cataloged, required for option "C")

Data Set Password . . (If password protected)

Option ===> __________________________________________________________________F1=Help F2=Split F3=Exit F7=Backward F8=ForwardF9=Swap F12=Cancel

Allocate New Data SetMORE: +

Data Set Name . . . . : data-set-nameVolume serial . . . . . ________ (Blank for authorized default volume) *Generic unit. . . . . . ________ (Generic group name or unit address) *Space units . . . . . . ________ (BLKS, TRKS, CYLS, KB, MB or BYTES)Primary quantity. . . . ________ (In above units)Secondary quantity. . . ________ (In above units)Directory blocks. . . . ________ (Zero for sequential data set)Record format . . . . . ________Block size . . . . . . ________Expiration date . . . . ________ (YY/MM/DD, YYYY/MM/DD

YY.DDD, YYYY.DDD in Julian formEnter "/" to select option DDDD for retention period in days

Command ===> ______________________________________________________________________F1=Help F2=Split F3=Exit F7=Backward F8=ForwardF9=Swap F12=Cancel

DATA SET UTILITY PANEL 3.2

ALLOCATE NEW DATA SET PANEL

Other Partitioned, Sequential or VSAM Data Set:Data Set Name . . . _______________________________________________Volume Serial . . . ________ (If not cataloged, required for option "C")

To create a data set without the SMS options, enter an A (for Allocate)as the option. When you press Enter, you get the Allocate New Data SetPanel. Fill it in and press Enter to allocate the data set. You specify essen-tially the same data you specify on the JCL DD statement.

For a multivolume data set, place a slash (/) in the Allocate MultipleVolumes field to get a pop-up list on which to write a maximum of 20 vol-ume serial numbers. To create a data set when SMS is active, enter an Minstead of an A. Press Enter, and fill in the Allocate New Data Set panel a.

21.5.3 Copying and Moving Data Sets

To copy or move a data set, you select Move/Copy (option 3.3) from theUtility Selection Panel and get the Move/Copy Utility Panel 3.3.

A MOVE deletes the FROM data set. P (Promote) is used for librarieswhose access is controlled. To copy FROM a sequential data set, you enterthe data set name. For a partitioned data set, you add one of the followingon the Member line:

� A member name to copy a single member.� An asterisk (*) to copy all members.

ISPF 413

Allocate New Data SetMore: +

Data Set Name . . . . : data-set-nameManagement class. . . . . _________ (Blank for default management class)Storage class . . . . . . _________ (Blank for default storage class)Volume serial . . . . . _________ (Blank for authorized default volume) *

Data class . . . . . . . _________ (Blank for default data class)Space units . . . . . . _________ (BLKS, TRKS, CYLS, KB, MB or BYTES)Primary quantity. . . . _________ (In above units)Secondary quantity. . . _________ (In above units)Directory blocks. . . . _________ (Zero for sequential data set) *Record format . . . . . _________Block size . . . . . . _________Data Set Name type. . . _________ (LIBRARY, PDS, or blank) *

Expiration date . . . ____________________ (YY/MM/DD, YYYY/MM/DDYY.DDD, YYYY.DDD in Julian form)

Command ===> _______________________________________________________________________F1=Help F2=Split F3=Exit F7=Backward F8=ForwardF9=Swap F12=Cancel

ALLOCATE NEW DATA SET PANEL a


Menu RefList Utilities Help------------------------------------------------------------------------------------

Move/Copy UtilityMore: +

C Copy data set or member(s) CP Copy and printM Move data set or member(s) MP Move and printL Copy and LMF lock member(s) LP Copy, LMF lock, and printP LMF Promote data set or member(s) PP LMF Promote and print

Specify "From" Data Set below, then press Enter keyFrom ISPF Library:

Project . . . ________ (--- Options C,CP, L, and LP only ----)Group . . . . ________ . . . ________ . . . ________ . . . ________Type . . . . ________Member . . . ________ (Blank or pattern for member list,

"*" for all members)

Other Partitioned or Sequential Data Set:Data Set Name . . . _____________________________________________________________

Option ===> ________________________________________________________________________F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=SwapF10=Actions F12=Cancel

Menu RefList RefMode Utilities Help----------------------------------------------------------------------------------

Data Set List UtilityBlank Display data set list P Print data set list

V Display VTOC information PV Print VTOC informationEnter one or both of the parameters below:

Dsname Level . . . _______________________________________________Volume serial . . ___________

Data set list optionsInitial View . . . _ 1. Volume Enter "/" to select option

2. Space _ Confirm Data Set Delete3. Attrib _ Confirm Member Delete4. Total

The following actions will be available when the list is displayed:Enter a "/" on the data set list command field for command prompt pop-up.Enter TSO commands, CLIST, REXX execs, or "=" to execute previous command.

Option ===> ______________________________________________________________________F1=Help F2=Split F3=Exit F7=Backward F8=Forward F9=SwapF10=Actions F12=Cancel

DATA SET LIST UTILITY PANEL 3.4

MOVE/COPY UTILITY PANEL 3.3

TEAMFLY

Team-Fly®

� Blank to get a list of member names. Then type an S to the left of eachname you want to select for the copy.

When you select the COPY option and press Enter, you get anotherpanel on which to enter the name of the data set to copy to. You can copyfrom sequential or partitioned data sets to sequential or partitioned datasets. You might also copy a data set to change the record format, recordlength, and block size. Records are truncated or padded on the right withblanks as necessary when the record length is changed.

21.5.4 Operations on Groups of Data Sets

Selecting Dslist (option 3.4 Data Set List), on the Utility Selection Panelgives you the Data Set List Utility Panel 3.4 that lets you browse, edit,delete, rename, print, and compress data sets, among other things. It doesmany of the things already described for the other utilities. The big advan-tage of the Dslist utility is that you can view the names of your data sets andspecify operations on several of them at the same time. Dslist lets you dooperations on several data sets similar to the way the Library Utility letsyou perform operations on several members of a partitioned data set.

To select data sets, you can specify a Dsname Level or a Volume. Youcan use an asterisk (*) as a wild card character to represent any charactersin the Dsname Level. Don’t enclose the data set name in apostrophes. Spec-ify the level 1 qualifier. Don’t use a * in the level 1 qualifier. The * can onlyappear first and/or last in a level name.

If you enter a slash (/) on the Option line, you get the Data Set ListActions Pop-up Menu with several options.

21.5.5 Other Utilities

The remaining utilities are used less often. They are as follows:

Reset resets the version number of a library or partitioned data set.

Hardcopy prints a sequential data set or single member of a partitioneddata set.

ISPF C/S installs the ISPF client/server workstation software at your ter-minal.

Outlist lets you browse, print, delete, or requeue SYSOUT data setsheld in the queue.

Commands builds command tables for application programs.

Format formats data using the double-byte character set (for Kanji).

SuperC compares two data sets.

ISPF 415

SuperCE does more extensive comparison of two data sets.

Search-For searches data sets to see if they contain character strings.

Search-ForE does a more extended search of characters in data sets.(Press More+ to get it.)


Data Set List Actions:Data Set: data-set-nameDSLIST Action

1. Edit 12. Compress2. View 13. Free3. Browse 14. Print Index4. Member List 15. Reset5. Delete 16. Move6. Rename 17. Copy7. Info 18. Refadd8. Short Info 19. Exclude9. Print 20. Unexclude 'NX'10. Catalog 21. Unexclude first 'NXF'11. Uncatalog 22. Unexclude last 'NXL'

Select a choice and press ENTER to process data set action.F1=Help F2=Split F3=Exit F7=BackwardF8=Forward F9=Swap F12=Cancel

DATA SET LIST ACTIONS POP-UP MENU

CHAPTER 22

TSO/E

Essential

TSO/E (Time-Sharing Option/Extended) is a system that runs under z/OSand acts as a host to other on-line applications. TSO/E has a command lan-guage that lets you do many of the things that you can do with JCL and thebatch utilities, such as create, delete, and copy files. You can also store JCLin a data set, submit the data set as a batch job through TSO/E, and retrievethe output from your terminal.

This chapter gives a brief description of the features of TSO/E that youare likely to use on a regular basis. TSO/E has many commands not coveredhere that you seldom need to use. Many people using TSO/E to run on-lineapplications are unaware that they are using TSO/E. For example, ISPFruns under TSO/E. You first log in to TSO/E and then invoke ISPF. Conse-quently, you aren’t aware that you are using TSO/E because you pass rightthrough it on your way to ISPF.

22.1 THE TSO/E LANGUAGE

You enter TSO/E commands from a terminal. The general form of a TSO/Ecommand is as follows. Separate the parameters with one or more blanks.Type the command in either upper- or lowercase characters and then pressthe Enter key.

command parameter ... parameter

The TSO/E command language is actually quite simple, but it appearscomplex because the commands have many synonyms and abbreviations.For example, the following two TSO/E commands are identical:

ALLOCATE DATASET(TEST.DATA) FILE(INPUT) OLDALLOC DD(INPUT) DSNA(TEST.DATA)

417

Write the command first (ALLOC is an abbreviation for ALLOCATE),and then the parameters for the command in any order. (DA is an abbrevia-tion for DATASET, which is a synonym for DSNAME, which you can abbre-viate as DSNA. DD is an abbreviation for DDNAME, which is a synonym forFILE.) For simplicity, only one form is used here for each command (usu-ally an abbreviation) to save typing and reduce the chance for error.

You need type only enough of any TSO/E command for the system torecognize it. This works well in practice because TSO/E will tell you whenan abbreviation is too short. New TSO/E commands may occasionallychange how many characters you must type. In this book, an abbreviation isused that is both short and unique, but which still conveys the idea of thecommand.

If a TSO/E command is too long to fit on a line, just continue typing itand TSO/E will automatically wrap around to the next line. You can alsotype a plus (+) or minus (−) sign, press the Enter key, and continue any-where on the next line.

ALLOC FILE(INPUT) +DATASET(TEST.DATA)

Wherever you might want to name several data sets, you can enclose thenames in parentheses, separating them with a blank or comma. For exam-ple, you can type the following to list information about one data set:

LISTDS TEST.DATA

The following lists information about three data sets.

LISTDS (TEST.DATA RUN.DATA SAVE.DATA)

Or

LISTDS (TEST.DATA,RUN.DATA,SAVE.DATA)

When you name a data set, TSO/E automatically appends your LOGONuserid to the front of the data set to qualify it. If you wrote

LISTDS TEST.DATA

and your userid were A1000, TSO/E would list the data set whose fullyqualified name was A1000.TEST.DATA. To list the fully qualified data setname yourself and not have TSO/E append your userid to it, enclose thedata set name in apostrophes. This lets you name a data set belonging tosome other userid.

LISTDS 'B2020.TEST.DATA'


You can use the asterisk (*) as a wild card character to represent alevel of a data set name. For example, if your userid were A1000, the fol-lowing would list all data sets having names such as A1000.TEST.* andB2020.*.DATA, where the * represents any name.

LISTDS TEST.*, 'B2020.*.DATA'

However, you cannot code an asterisk as the userid, so ‘*.TEST.DATA’would not be valid.

22.2 LOGGING ON AND OFF TSO/E

You log on to TSO/E with the LOGON command:

LOGON userid

Your installation must establish a userid for you and assign a passwordbefore you can log on. After you log on, the system prompts you for yourpassword. You can also request an amount of virtual memory when you logon; similar to the way you request virtual memory with the JCL REGIONparameter. You add the SIZE parameter to the LOGON.

LOGON userid SIZE(n) Or LOGON userid/password SIZE(n)

The n is the number of K (1,024) byte amounts. The following examplelogs on user A1000 with a password of SHAZAM and assigns a 2000Kregion. There are several other logon options that may be required by yourinstallation.

LOGON A1000/SHAZAM SIZE(2000)

If the connection is broken with TSO/E while you are logged on, spec-ify the REC (RECONNECT) option when you log back on. (If you don’t spec-ify REC, TSO/E won’t let you log back on because it thinks you’re alreadylogged on.)

LOGON A1000/SHAZAM REC

To obtain help in TSO/E, you can enter the following to obtain adescription of the help feature:

H HELP

To list the valid commands, enter

H

TSO/E 419

To obtain help on a particular command, enter

H command

After you enter the LOGON command, the system displays some mes-sages and then the TSO/E prompt:

READY

You may then enter any TSO/E command. To log off from TSO/E, enter

LOGOFF

22.3 DISPLAYING INFORMATION ABOUT DATA SETS

22.3.1 Listing the Names of Data Sets: The LISTCAT Command

The LISTC command (short for LISTCAT and stands for LIST Catalog) dis-plays all the data sets on disk cataloged under your userid. You enter

LISTC

22.3.2 Listing Information about Data Sets: The LISTDS Command

The LISTDS (for LIST Data Sets) command displays the attributes of dataset, such as the RECFM, LRECL, BLKSIZE, volumes, and creation date. Youwrite it as follows to list a single data set:

LISTDS data-set-name

To list all the member names of a partitioned data set, follow the data setname with an M:

LISTDS data-set-name M

To list the data sets created within the last number of days, code

LISTDS data-set-name CREATION(days)

The following command displays the data set named A1000.TEST.DATA, assuming your userid was A1000.

LISTDS TEST.DATA Same as LISTDS 'A1000.TEST.DATA'

22.3.3 Editing Data Sets: The EDIT Command

You can view and edit the lines in a data set by using the TSO/E line editor.However, the ISPF editor described in Chapter 21 is infinitely superior. Thefollowing command edits a sequential data set in TSO/E:


EDIT data-set-name

Add the member name in parentheses to edit a member of a partitioneddata set.

EDIT data-set-name(member)

Add the NONUM option to edit the lines without displaying the linenumbers.

EDIT data-set-name NONUM Or EDIT data-set-name(member) NONUM

List the lines in your data set with the LIST command.

LIST data-set-name Or LIST data-set-name(member)

Enter the following to display a range of lines.

LIST data-set-name first-line last-line

When you’re done, END terminates the edit.

END

The following example displays lines 1 through 100 of member SUB2 ofthe partitioned data set LIB.DATA. The display is unnumbered.

L LIB.DATA(SUB2) 1 100 NONUM

To stop the display, press PA1, the TSO/E interrupt key.

22.3.4 Printing Data Sets: The PR Command

The PR (PRINTDS) command prints a data set on a printer. You enter thefollowing:

PR DSNAME(data-set-name)

If the data set is a partitioned data set, the system prints the directoryand all the members of the data set. To print a single member of a parti-tioned data set, enter

PR DSNAME(data-set-name(member))

To list all the members of a partitioned data set but not the directory, enter

PR DSNAME(data-set-name) MEMBERS

To print just the directory of a partitioned data set, enter

PR DSNAME(data-set-name) DIR

TSO/E 421

To print specific lines of a data set, add the LINES(first,last) parameter.The following prints lines 1 through 100 of the TEST.DATA data set.

PR DSNAME(TEST.DATA) LINES(1,100)

22.4 ALLOCATING DATA SETS

22.4.1 The ALLOCATE Command to Access Data Sets

When you run an on-line program, you must connect each data set to theprogram by giving the ddname. The DD statement does this in JCL, but youdon’t execute an on-line application with JCL, you do this with the TSO/EALLOC (for ALLOCATE) command written as

ALLOC FILE(ddname) DATASET(data-set-name) OLD or SHR or MOD

This associates an application program with an existing data set throughthe ddname. If you omit the disposition, the system assumes OLD.

ALLOC FILE(TEST) DATASET(RUN.DATA) OLD Same asALLOC FILE(TEST) DATASET(RUN.DATA)

Remember that the system would prefix your userid as the first levelqualifier: userid.RUN.DATA in the preceding example. You can also writethe ALLOC command with DD in place of FILE and DSNAME in place ofDATASET. It is a matter of personal preference.

ALLOC FILE(TEST) DATASET(RUN.DATA) Or ALLOC DD(TEXT) DSNAME(RUN.DATA)

22.4.2 Freeing Allocated Data Sets: The FREE Command

The system deallocates all data sets when you LOGOFF. To deallocate orfree data sets while still logged on, you enter

FREE DATASET(data-set-name) Or FREE DD(ddname)

For example:

ALLOC FILE(TEST) DSNAME(RUN.DATA)� � �

FREE FILE(TEST) Same as FREE DATASET(RUN.DATA)

To free all data sets, enter

FREE ALL


However, the system usually automatically allocates several systemdata sets to your TSO/E session when you log on, and FREE ALL will freethem, too, which you probably won’t want.

22.4.3 Listing Allocated Data Sets: The LISTALC Command

The LISTA (for LIST Allocations) command lists all the data sets allocatedto you.

LISTA

22.4.4 The ALLOCATE Command to Create Data Sets

You’ve just seen how to associate an existing data set with an applicationprogram by writing an ALLOC statement. You can also create data sets fromTSO/E, although it is much easier to do this from ISPF or even with JCL. Tocreate a data set in TSO/E, you write the ALLOC command as follows:

KEEPDELETECATALOG

ALLOC FILE(ddname) DATASET(data-set-name) NEW +UNIT(device) VOL(volume) +RECFM(format) LRECL(length) +

TRACKSCYLINDERSAVBLOCK(blocksize)

SPACE(primary,secondary) DIR(directory-blocks)

The options are like those of JCL statements, except you separate theparameters of the RECFM with a comma or space: RECFM(F,B) or RECFM(FB) but not RECFM(FB). If you omit the SPACE parameter, a default amountfor your installation is allocated. You can also code the AVGREC parameterif SMS is active:

AVGREC(U) SPACE(primary,secondary) AVBLOCK(blocksize) +

To create an SMS-managed data set, enter the DATACLAS, STORCLAS,MGMTCLAS, and SECMODEL parameters, omitting UNIT, VOL, LRECL,and RECFM parameters as needed.

ALLOC FILE(ddname) DATASET(data-set-name) NEW CATALOG +AVGREC(U) SPACE(primary,secondary) AVBLOCK(blocksize) +DATACLAS(data-class) STORCLAS(storage-class) +MGMTCLAS(management-class) SECMODEL(profile)

TSO/E 423

You can specify all of the JCL parameters on the ALLOC statement, butyou seldom need most of them. Here is an ALLOC command to create a dataset shown with a JCL DD statement that would do the same thing, assumingyour userid were A1000:

ALLOC DD(OUT) DSN(TEST.DATA) NEW CATALOG +UNIT(SYSDA) VOL(PACK12) +AVGREC(U) SPACE(10000,2000) AVBLOCK(4400) DSNTYPE(LIBRARY) +RECFM(F,B) LRECL(80)

Same as

//OUT DD DSN=A1000.TEST.DATA,DISP=(NEW,CATLG),// UNIT=SYSDA,VOL=SER=PACK12,// AVGREC=U,SPACE=(4400,(10000,20000)),DSNTYPE=LIBRARY,// RECFM=FB,LRECL=80

22.5 CALLING PROGRAMS

The CALL command invokes a program in TSO/E session. You write it asfollows:

CALL data-set-name(member) 'parameter-string'

Enclose data-set-name(member) in apostrophes if you write a fullyqualified name:

CALL 'A1000.PGM.LOAD(RUN1)'

When you omit the apostrophes, the system assumes the standard TSO/Enaming convention of the userid as the first level of the name. The systemthen assumes a data type of LOAD. The next example calls a programnamed CALC stored as a member in a partitioned data set namedA1000.PGM.LOAD. The program is passed a parameter string of ‘(100,20,10)’.Assuming your TSO/E userid was A1000, you could call the program asfollows:

CALL PGM(CALC) '(100,20,10)'

22.6 SUBMITTING JOBS

22.6.1 The SUBMIT (SUB) Command

You submit a data set in the batch mode as a job by entering

SUB data-set-name Or SUB data-set-name(member)


TEAMFLY

Team-Fly®

For example, to submit member RUN2 of a partitioned data set namedPROD.CNTL, you could enter

SUB PROD.CNTL(RUN2)

Add the NOTIFY parameter to have the system notify you when the jobterminates. Add HOLD to hold the output in the output queue so you canview it from your terminal.

SUB PROD.CNTR(RUN2) NOTIFY HOLD

22.6.2 Checking the Status of Jobs: The STATUS Command

To inquire about the status of your job after you submit it, enter the ST (forSTATUS) command:

ST

To inquire about the status of some other user’s job, enter

ST jobname

If you have more than one job with the same jobname, follow the job-name with the jobid (job number) enclosed in parentheses. The system dis-plays the jobid when you submit the job:

ST jobname(jobid)

22.6.3 Notification of Job Completion

The NOTIFY Parameter on the JOB StatementCode NOTIFY=userid on the JOB statement of a batch job to have the sys-tem notify you when the job completes.

//jobname JOB (…),CLASS=A,NOTIFY=A0000

You can also code the NOTIFY parameter on the SUBMIT command. Ifyou are not logged on when the job completes, the message will be savedand displayed when you next log on.

The JES2 /*NOTIFY StatementAlternatively, you can code the JES2 /*NOTIFY statement, coded as follows:

/*NOTIFY userid/*NOTIFY node.userid

TSO/E 425

[The system will notify the userid at the node specified. Use thisform if you want someone not at the job’s origin notified.]

22.6.4 Canceling Jobs: The CANCEL Command

To cancel a background (or batch) job, enter

CANCEL jobname Or CANCEL jobname PUR

PUR purges your output. Otherwise, the system prints it. The jobnameis from the JOB statement:

//jobname JOB ...

If you have more than one job with the same jobname, follow the job-name with the jobid enclosed in parentheses. The system displays the jobidwhen you submit the job:

CANCEL jobname(jobid)

22.6.5 Retrieving Output: The OUTPUT (OUT) Command

HOLD=YES on the //SYSOUT DD statement holds your output on diskrather than printing it. Alternatively, many installations set up a specialoutput class to hold your output. Either way, you can examine your outputfrom your terminal rather than waiting for it to be printed.

//RT452216 JOB (45992),'SMITH',CLASS=A,NOTIFY=A1000// EXEC PGM=TEST//OUT DD SYSOUT=A,HOLD=YES

To then display on your terminal the output produced by a batch job,enter

OUT jobname(jobid)

To route the output to a remote workstation, add the DEST parameter:

OUT jobname(jobid) DEST(station-id)

The station-id is defined by your installation and is either a userid (todisplay the output on a terminal) or the name of a local printer. The systemthen removes your output from disk. (You can also code the DEST optionon a //SYSOUT DD statement as DEST=(node,station-id)). If you add theHOLD parameter, the system leaves your output on disk after displaying it.This enables you to view it again or print it.

OUT jobname(jobid) HOLD


22.6.6 Terminal Data Sets

If you want to type data in from your terminal as it is read by a batch job,code the TERM=TS parameter on the DD statement. (Don’t use this for anSMS-managed data set.) You can code only the SYSOUT and DCB parame-ters with TERM. The system ignores any other parameters. CodingTERM=TS on a //SYSOUT DD statement sends the output data set back tothe terminal if it was submitted from a terminal.

22.7 USE OF TSO/E FOR UTILITY FUNCTIONS

22.7.1 Deleting Data Sets: The DELETE (DEL) Command

To delete a cataloged data set, enter

DEL data-set-name

To delete a member of a partitioned data set, enter

DEL data-set-name(member)

The following command deletes member RUN2 in the A1000.PROD.CNTL partitioned data set:

DEL PROD.CNTL(RUN2)

22.7.2 Copying Data Sets: The SMCOPY (SMC) Command

To copy a cataloged data set to another, first create and allocate space for thesecond data set if it does not already exist. Then enter the following:

SMC FDS(from-data-set-name) TDS(to-data-set-name)

You can copy to or from the following types of data sets:

From ToSequential data set Sequential data setSequential data set Member of a partitioned data setMember of a partitioned data set Sequential data setMember of a partitioned data set Member of a partitioned data set

To copy to or from a member of a partitioned data set, enclose the mem-ber name in parentheses. The following example allocates a partitioneddata set A1000.LIB.DATA and then copies a sequential data set namedA0000.TEST.DATA to it as a member named SUB2:

TSO/E 427

ALLOC FILE(OUT) DATASET(LIB.DATA) NEW CATALOG +DIR(10) UNIT(SYSDA) +SPACE(100,20) AVBLOCK(4400) +RECFM(V,B) LRECL(80)

SMC FDS(TEST.DATA) TDS(LIB.DATA(SUB2))

22.7.3 Renaming Data Sets: The RENAME (REN) Command

To rename a cataloged data set, enter

REN old-data-set new-data-set

The following renames A1000.TEST.DATA to be A1000.PROD.DATA.

REN TEST.DATA PROD.DATA

You can also rename a member of a partitioned data set. Notice that youdon’t need to mention the data set name a second time. The followingrenames member SUB2 as SUB2A in a partitioned data set namedA0000.LIB.DATA.

REN LIB.DATA(SUB2) SUB2A

22.8 TSO/E CLISTS

A TSO/E CLIST is a combination of TSO/E commands and CLIST state-ments. A CLIST allows you to program TSO/E commands to do such thingsas allocate files, request input from the terminal, execute TSO/E commandsunder program control, display output on the terminal, and read and writefiles. The system executes each command in a CLIST as it reads it. That is,the commands are not compiled. (It is the TSO/E equivalent of a MS/DOS.BAT file.) The following briefly introduces CLISTs.

A CLIST may contain any TSO/E command. At its simplest, a CLISTcan be nothing more than one or more TSO/E commands. For example, youmight create a CLIST named DOIT containing these TSO/E commands.

LISTCLISTDS TEST.DATADEL TEST.DATA

Then instead of typing the three TSO/E commands, you invoke theDOIT CLIST by typing:

DOIT

The statements and commands in a CLIST must be in uppercase char-acters. A CLIST is usually a member of a partitioned data set allocated with


either RECFM=VB,LRECL=255 or RECFM=FB,LRECL=80. CLIST data setsusually have a data type of CLIST:

userid.name.CLIST

Assume that you want to execute a CLIST stored as a member namedDOIT in a partitioned data set named A1000.PROC.CLIST. You could enterthe following at the TSO/E READY prompt:

EXEC 'A1000.PROC.CLIST(DOIT)'

Or if A1000 is your userid, you can omit it and the apostrophes. Whenthe data set name is not enclosed in apostrophes, TSO/E suffixes .CLIST tothe name, so omit it, too.

EXEC PROC(DOIT)

Or if A1000.PROC.CLIST is allocated with a ddname of SYSPROC,which you can do by adding an ALLOC statement to the default CLIST exe-cuted when you log on to TSO/E, you can omit EXEC data-set-name andtype just the member name, preceded by a percent sign:

%DOIT

Alternatively, if you know that there is no TSO/E command namedDOIT, you can omit the percent sign:

DOIT

22.8.1 Variables

Variables are not predefined—TSO/E defines them on the fly the first timethey appear in a PROC, SET, or READ statement. Variables have a defaultvalue of zero or null, depending whether they first appear in a numeric orcharacter expression. You can use variables in arithmetic expressions ifthey contain valid numeric values. A null value is not a valid numericstring. The rules for variable names are as follows:

� First character A to Z, _, #, $, or @.� Remaining characters any of the preceding plus A to Z, 0 to 9.� 1 to 252 characters long.� Precede variable names to the right of the equal sign with an amper-

sand. The & is optional to the left of the equal sign.

For example, this statement stores the value 1 in the variable TEST:

SET &TEST = &TEST + 1 Or SET TEST = &TEST + 1

TSO/E 429

TEST is set to 1. Since this is the first time TEST has appeared in a state-ment and it appears in a numeric expression, it is given a value of 0. A 1 isadded to it, so it contains 1 after the statement is executed. The followingstatement defines the NAME variable and assigns the string MY NAME ISHAL to it. Don’t enclose literal strings in a CLIST in quotes, which is ratherunorthodox.

SET NAME = MY NAME IS HAL

22.8.2 Arithmetic Expressions

The arithmetic operators are as follows:

+ - * / Add, subtract, multiply, divide.** Exponential.// Remainder.

Use parentheses to specify the hierarchy:

SET A = ((3 + 2) * 8) + 6

22.8.3 Logical Expressions

The logical operators are as follows:

EQ NE LT GT LE GEAND OR

Override the normal hierarchy with parentheses.

IF (&A GE 10) OR ((&B LT 5) AND (&C GT 9)) THEN ...

22.8.4 Character Operations

Concatenate strings by placing them together in an expression. No operatoris used—again rather unorthodox. Blanks are significant for concatenation.The following stores BILL JONES in NAME.

SET FIRST = BILLSET NAME = &FIRST JONES

The following sets NAME to null. TSO/E sees that a new variable,FIRSTBILL, is defined and sets it to a null value.

SET NAME = &FIRSTBILL


Use a period when concatenating literals if there is to be no spacebetween the concatenated items. The following stores BILLSMITH in NAME.

SET NAME = &FIRST.SMITH

Code two periods if you want a period between the concatenated items,say for data set names. The following stores MR.BILLSMITH in TITLE.

SET TITLE = MRSET NAME = &TITLE..&NAME

TSO/E provides the following system functions for character strings.

&STR(expression) tells TSO/E that an arithmetic expression should notbe evaluated, but be treated as a character string. For example, if youhad this:SET A = 5 * 4

TSO/E would evaluate the 5 * 4 numerically as 20 and store 20 in A.But if you code this:SET A = &STR(5 * 4)

TSO/E will store the string “5 * 4” in &A.

&EVAL(expression) is the opposite of &STR and forces TSO/E to evalu-ate the expression. This is used in WRITE statements in which theexpression is not evaluated.

&SUBSTR( f:l,string) returns a substring from another string.� f is the first character position of the substring.� l is the last character position of the substring.� string is the string.SET A = 1234567890SET B = &SUBSTR(3:5,&A)

[B will contain “345”.]

&LENGTH(string) returns the length of a string.SET C = &LENGTH(&A)

[C contains 10.]

&SYSCAPS(string) converts a string to uppercase.SET A = &SYSCAPS(&B)

[Converts the string in B to uppercase.]

&SYSLC(string) converts a string to lowercase.

&SYSINDS(string1,string2,n) searches string2 for the characters instring1 starting at the nth character in string2. It returns the positionof the first character in string2 if found. If not found, it returns zero.

TSO/E 431

22.8.5 CLIST Statements

The general rules are as follows:

� Code one statement per line.� Capitalize everything except character literals. (You don’t need to

capitalize some things, but it is easier to capitalize than to rememberthe exceptions.)

� Continue statements by typing a + or − at end of the line. The + meansto ignore leading blanks on the continuation. The − preserves themand is useful when breaking a character literal.WRITE+ Treated as: WRITE&A&A

WRITE + Treated as: WRITE &A&A

WRITE- Treated as: WRITE &A&A

� Comments begin with /* and you can code them anywhere on a linethat a blank can appear. If the comment doesn’t go to the end of theline, terminate it with a */:ALLOC FILE(&DDN) DATASET (&DSN) OLD /* Comment goes to end of line.ALLOC /* Comment not at end of line. */ FILE(&DDN) DATASET(&DSN) OLD

� It is best to code the CLIST statements in columns 10 through 71. Theactual restrictions depend on the record format, but columns 10through 71 are always safe.

The standard CLIST statements are as follows:

Assignment statement:SET variable = expression

DO group: (To execute several statements where one statement wouldnormally appear.)DOstatementsEND

DO WHILE:DO WHILE expression

statementsEND

DO UNTIL:DO UNTIL expression

statementsEND

Iterative DO:DO variable = from-expression TO to-expression BY expression

statementsEND


CASE:SELECTWHEN expression statementWHEN expression +

DOstatementsEND

WHEN ...OTHERWISE statement Or DO group <== OptionalEND

IF/THEN/ELSE:IF logical-expression THEN statementIF logical-expression THEN statementELSE statementIF logical-expression THEN +

DOstatementsENDELSE +DOstatementsEND

GOTO:GOTO label

LABELS:� First character A to Z� Remaining characters A to Z, 0 to 9, @, #, $� 1 to 31 characters long� Must end with a colon� If coded on a line by itself, continue by typing a +

LABEL1: SET VAR1 = 0LABEL2: +

SET VAR2 = 0

Terminating a CLIST:EXIT Terminates the CLIST.EXIT CODE(n) Terminates the CLIST and returns n as return code.

Or just execute the last statement in the CLIST.

Terminal I/OThe WRITE statement displays a line on the terminal. The following exam-ple displays THIS STRING IS DISPLAYED. on the terminal.

WRITE THIS STRING IS DISPLAYED.

The variable names in a WRITE are not to the left of an equal sign, soyou don’t need to prefix them with an ampersand.

TSO/E 433

WRITE LNAME Or WRITE &LNAME

The WRITE statement writes the text and positions the cursor on thefollowing line. The WRITENR statement is identical, except it leaves thecursor at the end of the line, positioned ready for input.

WRITE YOUR NAME PLEASE Results in: YOUR NAME PLEASEWRITENR YOUR NAME PLEASE Results in: YOUR NAME PLEASE

Arithmetic expressions are normally evaluated wherever they appear.However, the WRITE and WRITENR statements are exceptions. Arithmeticexpressions are not evaluated when they appear in them.

SET A = SIZEWRITE &A IS 5 * 4

The terminal displays SIZE IS 5 * 4. Use the &EVAL built-in function totell TSO/E to evaluate an arithmetic expression wherever it appears. Thefollowing example displays SIZE is 20.

WRITE &A IS &EVAL(5 * 4)

The READ statement retrieves input from the terminal. It opens aninput field on the terminal and waits for you to press Enter.

WRITE ENTER YOUR AGEREAD &AGE Or READ AGE

Whatever the person at the terminal types in is read into AGE. If youwanted to allow blanks in the input, the person at the terminal would haveto enclose the text in apostrophes.

WRITENR ENTER YOUR FIRST AND LAST NAMEREAD &FNAME &LNAME

If the person at the terminal typed in John Smith, the system would storeJohn in FNAME and Smith in LNAME. If the person instead typed in ‘JohnSmith’, the system would store it in FNAME and set LNAME to null. If the per-son types in more items than there are variables in the READ, the excess vari-ables are ignored. The person can enter a null value by typing two apostrophes.In the following example, if the person typed in A B ‘’ C D E, the system wouldstore A in FIRST, B in SECOND, null in THIRD, and ignore the D and E.

READ &FIRST &SECOND &THIRD

When the person at the terminal types in DATA, TSO/E assumes thatindividual data items are separated by blanks. If no variables are named on


TEAMFLY

Team-Fly®

the READ, whatever the person at the terminal types in is stored in a systemvariable named &SYSDVAL. You can later read the data from &SYSDVALwith a READDVAL statement. It is identical to READ, except that it readswhat is stored in &SYSDVAL.

READREADDVAL &FNAME &LNAME

File I/OTo read or write a file, you must first allocate it with a TSO/E ALLOC com-mand. Then open it with the OPENFILE statement.

ALLOC FILE (ddname) DATASET(data-set-name) …OPENFILE ddname INPUT or OUTPUT or UPDATE

The GETFILE statement reads a record. (The file must be opened forINPUT or UPDATE.) The system creates a variable named ddname andstores the record in it. The following opens a file named TESTDATA andreads a record into the TESTDATA variable.

ALLOC FILE(ddname) DATASET(RUN.DATA) ...OPENFILE TESTDATA INPUTGETFILE TESTDATA

When an end of file is encountered, the system stores a value of 400 inthe system variable named &LASTCC.

PUTFILE writes whatever is stored in the ddname variable. (The filemust be opened for OUTPUT or UPDATE.)

PUTFILE ddnamePUTFILE TESTDATA

When a file is opened for UPDATE, PUTFILE overwrites the last recordread by GETFILE.

Always close files with CLOSFILE.

CLOSFILE ddname

The &SYSDSN built-in function determines whether a data set exists:

&SYSDSN(data-set-name)

It returns the string OK if the data set exists and is available, PRO-TECTED DATASET if the data set exists but is RACF-protected, UNAVAIL-ABLE DATA SET if it exists but someone else is using it, and INVALIDDATA SET NAME if it can’t find the data set.

TSO/E 435

22.8.6 Supplying Arguments in the Command Line

To supply arguments in a command line so that the user can enter differentvalues when a CLIST is invoked, begin the CLIST with the PROC statement.

PROC n var var ... var

The n is the number of variables that follow. The var represents the vari-ables whose values will be supplied by the user when the CLIST is invoked.

The person at the terminal must supply values for the positional param-eters in the same order they appear in the PROC statement. Assign a defaultvalue by enclosing the value in parentheses. For example, create a CLISTnamed GETIT that has three positional variables named DDN, NAME, andDISP defined on the PROC statement. Then execute the TSO/E ALLOCcommand using the value supplied when the CLIST is invoked.

PROC 3 DDN NAME DISPALLOC FILE(&DDN) DATASET(&NAME) &DISP

Now you can invoke this CLIST with the following:

GETIT A STUFF.DATA SHR

The result is the same as if you had entered

ALLOC FILE(A) DATASET(STUFF.DATA) SHR

If a parameter doesn’t have a value, TSO/E prompts for it. If you entered

GETID A STUFF.DATA

TSO/E would prompt the user with ENTER POSITIONAL PARAMETERDISP. When the user presses Enter, the system executes the CLIST. The sys-tem wouldn’t prompt for DDN or NAME because they were assigned defaultvalues.

Rather than positional parameters, you can code keyword parametersand assign them a default value. Here is the same example using three posi-tional parameters. Assign DDN a default value of B, NAME a default valueof JUNK.DATA, and DISP a default value of null. Since there are no posi-tional parameters, indicate this with a value of 0 on the PROC statement.

PROC 0 DDN(B) NAME(JUNK.DATA) DISP()ALLOC FILE(&DDN) DATASET(&NAME) &DISP

Now you can invoke this CLIST with the following. The order in whichyou code the keyword parameters doesn’t matter.


GETIT DDN(A) NAME(STUFF.DATA) Or GETIT NAME(STUFF.DATA) DDN(A)

A default value is used only if the user doesn’t supply a value for it. Theresult is the same as if you had entered

ALLOC FILE(A) DATASET(STUFF.DATA)

You can code both positional and keyword parameters on a PROC. Codethe number of positional parameters, the positional parameters, and thenthe keyword parameters.

PROC 2 NAME ADDRESS AGE(21) SEX(F)

22.8.7 Built-in System Variables

The following are representative of the many built-in system variables.They may appear wherever a variable is permitted, and the system suppliesthe value for the variable.

&SYSUID Contains TSO/E userid for the current session&SYS4DATE Date in the form mm/dd/yyyy&SYS4SDATE Date in sortable form of yyyy/mm/dd&SYSTIME Time in form hh:mm:ss&SYSCPU Seconds of CPU time used by this session&SYSSRV Number of service units used by this session

In addition, the LISTDSI command stores values for a data set in 34 sys-tem variables that you can display to test to make decisions about a data set.

LISTDSI data-set-name

&SYSDSNAME contains the data set name, &SYSUNIT the unit,&SYSVOLUME the volume, &SYSRECFM the RECFM, &SYSLRECL theLRECL, &SYSBLKSIZE the BLKSIZE, &SYSALLOC the allocation in spaceunits, &SYSUSED the allocation used in space units, &SYSSECONDS thesecondary allocation in space units, &SYSCREATE the date created—yyyy/dd, and &SYSREFDATE the date last referenced. And many more.

TSO/E 437

CHAPTER 23

TSO/E REXX

TSO/E REXX (REstructured Extended eXecutor) is a powerful interactiveprogramming language that can execute system commands, such as TSO/E,ISPF, and so forth. It allows you to do the following:

� Request input from the terminal� Execute TSO/E commands under program control� Display output on the terminal� Read and write files

REXX is executed interpretively, not compiled, and is a more modern,powerful language than TSO/E with its CLIST. It is the procedure languagefor IBM’s System Application Architecture (SAA), which means REXX isimplemented across IBM’s product line.

A REXX program is called an exec and may execute TSO/E, ISPF, andother commands. At its simplest, an exec might do nothing more than exe-cute TSO/E commands. Here is an example of an exec named DOIT thatexecutes three TSO/E commands. TSO/E commands in REXX are enclosedin quotes.

/* REXX DOIT EXEC */"LISTC""LISTDS TEST.DATA""DEL TEST.DATA"

Assume that DOIT is a member of a partitioned data set. Now instead oftyping the three TSO/E commands, you invoke the DOIT exec by typing thefollowing. (The second exec tells TSO/E that this is a REXX exec.)

EXEC "data-set-name(DOIT)" exec

An exec is usually a member of a partitioned data set that by conventionyou give a data type of EXEC:

438

userid.name.EXEC

Assume that you want to execute an exec stored as a member namedDOIT in a partitioned data set named A1000.PROC.EXEC. You could enterthe following at the TSO/E READY prompt:

EXEC "A1000.PROC.EXEC(DOIT)" exec

Alternatively, if the A1000 is your userid, you can omit it and thequotes:

EXEC PROC.EXEC(DOIT) exec

If the data set has a data type of EXEC, you can omit it:

EXEC PROC(DOIT) exec

If the data set is allocated with a ddname of SYSPROC (which you cando by adding an ALLOC statement to the default exec executed when youlog on to TSO/E), you can omit the exec data set name and type just themember name. The first line of the exec must then be a comment with theword REXX in it.

DOIT

23.1 VARIABLES

Variables are not predefined. REXX defines them on the fly the first timethey appear in a statement and gives them a default value of null. Variablescan be used in arithmetic expressions if they contain valid numeric values.(A null value is a valid numeric value.) The rules for variable names are asfollows:

� Names are composed of the characters A to Z, a to z, 0 to 9, @, #, $, ?,!,., _.

� The first character cannot be 0 to 9 or a period.� Names can be 250 characters long.� Upper- and lowercase characters are treated as if they were the same.

For example, this statement stores the value 1 in the variable TEST:

TEST = TEST + 1

TEST contains 1. Since this is the first time TEST has appeared in astatement, REXX gives it a default value of 0. A 1 is added to it, so it con-tains 1 after this statement is executed. The next example defines the

TSO/E REXX 439

NAME variable and stores the string MY NAME IS HAL in it. Single or dou-ble quotes are permitted as long as you begin and end the string with thesame type.

NAME = "MY NAME IS HAL" Or NAME = 'MY NAME IS HAL'

23.2 ARITHMETIC EXPRESSIONS

In highest to lowest order, the arithmetic operators are as follows:

+ − * / Add, subtract, multiply, divide

% Integer divide

// Divide and return only the remainder

** Integer exponential

Override the normal hierarchy with parentheses:

A = ((3 + 2) * 8) + 6

23.3 LOGICAL EXPRESSIONS

In REXX, true has a value of 1 and false of 0. You can place a logical expres-sion in an assignment statement. In the following example, A is set to 1 if Bequals C. Otherwise, it is set to 0.

A = B = C

The logical operators are

& Logical AND—true if both terms are true

| Logical OR—true if either term is true

&& Exclusive OR—true if either but not both are true

\ Logical NOT—changes true to false and vice versa

The comparison operators are as follows. The \= is the not-equal com-parison. (You can also use the not sign (¬) in place of the \ on a 3270 ter-minal.)

= \= > < >= <=

Variables are compared numerically if they are numeric; otherwise,they are compared as strings, padding a shorter string on the right to equalthe longer string for the comparison. To always have the logical operation


compare the two values as strings and not pad on the right, code the = astwo equal signs (= =). For example:

A = 2 = 2.0 results in 1--true. (Compared as numeric.)A = 2 == 2.0 results in 0--false. (Compared as strings.)A = "AB" = "AB " results in 1--true. (Shorter padded with blanks.)A = "AB" == "AB " results in 0--false. (Compared exactly.)

Override the hierarchy with parentheses.

IF (A >= 10) | ((B < 5) AND (C > 8)) THEN ...

23.4 CHARACTER OPERATIONS

There are three ways to concatenate strings:

� Separate them in an expression with a blank:A = 27B = A "miles" B contains "27 miles".

� Use the || concatenation operator to concatenate without a blank:A = 27B = A || "miles" B contains "27miles".

� Abut them to concatenate without a blank:A = 27B = A"miles" B contains "27miles".

Note that you can’t abut two variables because REXX won’t know wherethe two variables begin and end: C = AB would tell REXX to store the vari-able AB in C, not to abut the contents of B to A and store them in C.

The following system functions are provided for character strings.

SUBSTR(string,n,length) returns length characters in string, startingwith the nth character. For example:A = "1234567890"B = SUBSTR(A,4,3) [B will contain "456".]

LEFT(string,n) returns the nth leftmost characters of string.A = "1234567890"B = LEFT(A,4) [B will contain "1234".]

RIGHT(string,n) returns the nth rightmost characters of string.A = "1234567890"B = RIGHT(A,4) [B will contain "7890".]

LENGTH(string) returns the length of the string.A = "1234567890"C = LENGTH(A) [C will contain 10.]

TSO/E REXX 441

INDEX(string,search-string) searches string for first instance of search-string. It returns the character position (1 to n) of found string or 0 ifnot found.]A = "1234567890"C = INDEX(A,"45") [C will contain 4.]

INSERT(new-string,old-string,n) inserts the new-string into the old-string, starting after the nth character. An n of 0 inserts in the frontof old-string and a value greater than the length concatenates new-string to the end of old-string.A = "1234567890"INSERT("ABC",A,3) [A will contain "123ABC4567890".]

23.5 REXX STATEMENTS

Here are the general rules for statements:

� You normally write one statement per line. Use a semicolon to sepa-rate multiple statements on a line. The semicolon isn’t needed if onlyone statement appears on a line.

� You can write statements in upper- or lowercase.� Continue statements by typing a comma and continuing on the next

line. The comma is ignored in the statement, but one blank isinserted where the comma was coded.

� Code comments the same as in C/C++ and PL/I. Coded then anywherea blank can appear and begin with /* and end with */.

Typical exec statements are the following.

23.5.1 Assignment Statementvariable = expressionA = B + C - D

23.5.2 DO Statements

DO group: To execute several statements where one statement wouldnormally appear:DOstatementsENDDOA = B + 3C = A + 2END


Endless DO: To execute statements in an unending loop:DO FOREVER

statementsEND

Iterative DO:DO variable = from-expression TO to-expression BY expression

statementsENDDO I = 1 TO 10

K = K + IEND

DO WHILE:DO WHILE expression

statementsENDI = 1DO WHILE I < 11

K = K + IEND

DO UNTIL:DO UNTIL expression

statementsEND

LEAVE terminates the loop and continues execution with the next state-ment following the END. Same as BREAK in C/C++.

ITERATE jumps to the end of the loop and continues. Same as CON-TINUE in C/C++.DO FOREVER

SAY, "Pick a number from 1 to 10. Type END to quit."PULL NUMIF NUM = "END" THEN LEAVEIF NUM < 1 OR NUM > 10 THEN ITERATESAY "Great. Now do it again."

END

23.5.3 Logic Statements

CASE construct:SELECT

WHEN expression THEN statementWHEN expression THEN DO

statementsENDWHEN ...OTHERWISE statement or DO group <== Optional

ENDSAY, "Type a number."PULL NUM

TSO/E REXX 443

SELECTWHEN NUM = 1 THEN SAY "You typed a 1."WHEN NUM = 2 THEN SAY "You typed a 2."OTHERWISE SAY "You obviously typed something other than 1 or 2"

END

IF/THEN/ELSE:IF logical-expression THEN statementIF RC = 2 THEN SAY "RC equals 2."IF logical-expression THEN statementELSE statementIF RC = 2 THEN SAY "Rc equals 2."ELSE SAY "RC does not equal 2."IF logical-expression THEN

DOstatementsENDELSEDOstatementsEND

Null statement: Mainly for THEN or ELSE clauses:NOP

GO TO (branch):SIGNAL labelSIGNAL STARTIT

23.5.4 Statement Labels

Labels may contain the characters: A to Z, a to z, 0 to 9, @#$.!? and _. Thelabel may be 1 to 250 characters long and must end with a colon.

STARTIT:

23.5.5 Termination Statement

The EXIT statement terminates an exec. The exec also terminates when itexecutes the last statement in it.

EXIT

23.5.6 Terminal I/O

The SAY statement displays a line on the terminal. The following statementdisplays THIS STRING IS DISPLAYED.

SAY, "THIS STRING IS DISPLAYED."


TEAMFLY

Team-Fly®

A = "SIZE IS"SAY A 5 * 4

[The terminal displays SIZE IS 20. Arithmetic expressions are nor-mally evaluated wherever they appear.]

The PULL statement opens an input field on the terminal and waits foryou to press Enter. The following example converts whatever the persontypes to uppercase and stores it in AGE.

SAY, "ENTER YOUR AGE"PULL AGE

The next example is the same as the previous, but the input is not con-verted to uppercase.

PARSE PULL AGE

The PULL VAR lets you enter several variables. REXX assumes that thevariables are delimited by blanks.

SAY "ENTER YOUR FIRST AND LAST NAME"PULL VAR FNAME LNAME

23.5.7 File I/O

To read or write a file, you must first allocate it but you do not need to openit. The first read or write automatically opens it. An EXECIO command doesthe reading and writing. EXECIO reads lines into a stack in memory whereyou can retrieve them one at a time with the PULL statement. Lines are alsowritten from a stack. You place lines in a stack with a PUSH or QUEUEstatement described later and then write some number of lines from thestack.

The NEWSTACK command creates a new stack, leaving the previousstack undisturbed but unavailable. The DELSTACK command deletes thecurrent stack and makes the previous stack available. Thus, you can pushdown and pop up stacks containing the lines read or written. The stacks canbe used to store any lines, not just lines read and written.

To read or write lines, you first allocate all the files before using them byusing the TSO/E ALLOC command.

"ALLOC FILE(ddname) ..."

NEWSTACK creates a new, empty stack, leaving the previous stackundisturbed but unavailable. Most of the I/O is done through commands,which you enclose in quotes.

"NEWSTACK"

TSO/E REXX 445

DISKR requests the EXECIO function to open the data set for input if itis not already open. EXECIO then reads n records from the ddname file andstores the lines at the bottom of the current stack, first in, first out.

"EXECIO n DISKR ddname"

Append a (LIFO to the end of the command if you want the lines last in,last out:

"EXECIO n DISKR ddname (LIFO"

Code an asterisk (*) in place of the n to read all the lines into the stack.

"EXECIO * DISKR ddname (LIFO"

After the read, REXX sets a built-in variable named RC to 2 if it encoun-tered an EOF during the read. It sets RC to 0 if the read was successful. Notethat RC is not set when the asterisk is coded in place of the n.

The PULL command removes the next line from the current stack.PULL removes lines first in, first out. PULL stores character strings in theline (as delimited by blanks) in the variables, converting the characters touppercase. If there are no lines in the stack, PULL waits for the person at theterminal to type something and press Enter.

PULL variable variable ... variable

The next example is the same as the previous, except the characters arenot converted to uppercase.

PARSE PULL variable variable ... variable

PUSH converts the data in the expression to a single string and stores iton top of the current stack—last in, first out.

PUSH expression

QUEUE is the same as PUSH, except it stores the line at the bottom ofthe current stack—first in, first out.

QUEUE expression

QUEUED() returns the number of lines in the current stack.

QUEUED()

DISKW causes the EXECIO function to open the data set for output if itis not already open. EXECIO then writes n records from the stack into theddname file. Code an asterisk (*) in place of n to write all the lines in thestack.


"EXECIO n DISKW ddname"

Code a (FINIS at the end of the EXECIO command to close the file.

"EXECIO n DISKW ddname (FINIS"

DELSTACK deletes the current stack and pops the previous stack up tobe the current stack.

"DELSTACK"

After you close the data sets, execute the TSO/E FREE command torelease them.

"FREE FILE(ddname)"

Code the SYSDSN built-in function to determine whether a data setexists. It returns the string OK if the data set exists.

SYSDSN("data-set-name")IF SYSDSN("TEST.DATA") = "OK" THEN SAY "TEST.DATA exists."

23.6 SUPPLYING ARGUMENTS IN THE COMMAND LINE

The ARG statement allows you to supply arguments in a command line sothat the user can enter different values when an exec is invoked. You cansupply arguments either as a string containing separate words separated byblanks, or as several strings. To supply arguments for an exec named DOITas a string containing words separated by blanks, code the following state-ment to invoke the exec and supply it a character string.

DOIT "24 omaha nebraska 37"

Write the exec as shown in the following example. The exec itself mustcontain an ARG statement to list the variables whose values will be sup-plied by the person at the terminal. The 24 is stored in AA, OMAHA isstored in BB, and whatever is leftover, NEBRASKA 37, is stored in CC.REXX stores the characters up to the next blank in the next variable, exceptfor the last, into which it stores whatever text remains. If there are fewerwords in the string than variables, REXX sets the end variables to null.REXX converts the alphabetic characters in a string to uppercase.

/* REXX DOIT EXEC */ARG AA BB CC

If the exec were to be supplied separate strings, you would code the fol-lowing:

TSO/E REXX 447

DOIT 24 "omaha nebraska" 37

You can write the DOIT exec as shown in the following example. Plac-ing commas following the variables in the ARG statement tells REXX to takethe entire string. REXX stores 24 in AA, OMAHA NEBRASKA in BB, and 37in CC.

/* REXX DOIT EXEC */ARG AA, BB, CC

If you don’t want the alphabetic characters converted to uppercase,write PARSE ARG rather than just ARG.

PARSE ARG var var ... var

23.6.1 Built-in Functions

The many built-in functions can appear wherever a variable is permitted,and the system supplies the value for the function. Typical functions areUSERID() to return the TSO/E userid for the current session, LISTDSI(“data-set-name”) to return the same values as the TSO/E LISTDSI commanddescribed in the previous chapter, and TIME(N) to return time in the formhh:mm:ss. Time can also be returned in several other formats.

23.6.2 Executing TSO/E Commands

To execute a TSO/E command, enclose the command in double quotes andexecute it.

"FREE FILE(ddname)"

You can also store a string in a variable and execute it. This gives youthe ability to create almost any command you want and execute it.

CMD = "FREE DATASET(TEST.DATA)"CMD

[The FREE DATASET(TEST.DATA) command is executed.]


CHAPTER 24

HIERARCHICAL FILE SYSTEM (HFS) FILES

Sometimes Used

HFS files have a UNIX directory structure. They are a part of z/OS UNIXSystem Services, allowing z/OS to run UNIX applications and process filesfrom UNIX systems. HFS data sets must reside on a single volume and beSMS-managed.

24.1 JCL PARAMETERS FOR HFS FILES

The system provides five parameters for processing hierarchical files:

PATH specifies the path to the file. You always code PATH for an HFSdata set. PATH takes the place of the DSN parameter for an HFS file.

FILEDATA tells the type of data in the file, binary or text.

PATHDISP specifies the disposition of the file, equivalent to the DISPparameter.

PATHOPTS tells how to open and process the file.

PATHMODE tells who can access the file after the system creates it.

You can also code the DSNTYPE=PIPE parameter for FIFO special files.In addition, you can code the BLKSIZE, BUFNO, LRECL, and RECFM DCBsubparameters, along with DUMMY, DSNTYPE, and FILEDATA.

You associate the ddname on the DD statement with the ddname codedin the fopen statement:

fopen('dd:ddname',"rt");

24.1.1 The PATH Parameter

PATH tells the system that it is an HFS file and gives the directories for thepathname of the file in UNIX format.

449

PATH='/directory/directory/…/directory/filename'

The path can be as long as 254 characters, excluding the slashes. If adirectory or name contains a slash, code it as two slashes. The charactersmust all be printable. You can code symbolic parameters in a pathnamewhen you place it in a cataloged procedure. The names in the path are casesensitive. /One/Two is different from /one/two.

24.1.2 The FILEDATA Parameter

Code FILEDATA=TEXT or BINARY to tell the system the organization of theHFS file. A BINARY file, the default, is a stream of bytes with no recorddelimiter. A TEXT file is a stream of characters delimited by the EBCDICnew line character, X’15’. BINARY is default if you don’t code FILEDATA.

24.1.3 The PATHDISP Parameter

PATHDISP specifies the disposition of an HFS file.

PATHDISP=(normal-disposition,abnormal-disposition)

You can code both normal-disposition and abnormal-disposition asKEEP or DELETE. KEEP is the default for both dispositions if you omitPATHDISP or if you code only normal-disposition. If you code only abnormal-disposition, the system assumes it for the normal-disposition.

24.1.4 The PATHOPTS Parameter

PATHOPTS specifies the access and status for an HFS file.

PATHOPTS=(file-option,file-option,…,file-option)

You are limited to seven file-options. Select one from the access groupand then others as needed from the status group.

Access GroupSpecify only one of the following:

ORDONLY opens the file for reading

OWRONLY opens the file for writing

ORDWR opens the file for reading and writing. (Not allowed for FIFOspecial files)


Status GroupCode any of the following

OAPPEND sets the file offset to the end of file before each write to writedata at the end of file. (Like DISP=MOD does for normal data sets.)

OCREAT creates the file if it does not exist and if the directory specifiedby PATHNAME exists. The system performs the open() function tocreate the file and then it closes it with the close() function beforegiving control to the application program. If the file already exists,the system doesn’t create the file, but uses the old copy. If the path-name does not exist, the system creates neither the path nor the newfile.

OCREAT,OEXCL is the same as OCREAT alone, except that if the filealready exists, the system abnormally terminates the step.

ONOCTTY is used if the PATH parameter points to a terminal, so open-ing the file does not put this terminal in control of the process.

ONOBLOCK specifies the following for a FIFO special file:� ONOBLOCK,ORDONLY for a FIFO special file. An open() func-

tion for read-only access returns immediately. WithoutONOBLOCK, an open() function for read-only access waits untila process opens the file for writing.

� ONOBLOCK,OWRONLY for a FIFO special file. An open() func-tion for write-only access returns an error if no process currentlyhas the file open for reading. Without ONOBLOCK, an open()function for write-only access waits until a process opens the filefor reading.

� ONOBLOCK for a character special file that supports nonblock-ing open. An open() function returns without waiting until thedevice is ready or available. Without ONOBLOCK, the open()function waits until the device is ready or available.

OSYNC moves data from buffer storage to permanent storage beforeturning control from a callable service that performs a write.

OTRUNC truncates the file length to zero if the file specified by thePATH parameter exists and the file is a regular file (not FIFO orcharacter special files) and if the system successfully opened thefile with ORDWR or OWRONLY. The system ignores OTRUNC forFIFO and character special files.

If you omit PATHOPTS, the system assumes that the pathname existsand searches for it. If it can’t find it, it issues a message.

HIERARCHICAL FILE SYSTEM (HFS) FILES 451

24.1.5 The PATHMODE Option

PATHMODE tells the system who can later process the created file. Code itonly with PATHOPTS=OCREAT.

PATHMODE=(attribute,attribute,…,attribute)

The attributes you set limit access for the file owner class, the file groupclass, and the file other class. You can specify any or all of the attributes:

File Owner Class. The user who created the file or who currentlyowns it.� SIRUSR lets the file owner read the file.� SIWUSR lets the file owner write the file.� SIXUSR lets the file owner search, if the file is a directory. If not

a directory, the file owner can execute the program in the file.� SIRWXU lets the file owner read, write, and search, if the file is a

directory. If not a directory, the file owner can read, write, andexecute the program in the file. (SIRWXU is the same as specify-ing SIRUSR, SIWUSR, and SIXUSR.)

File Group Class. The users who are in the same group as the file.� SIRGRP is the same as SIRUSR, but for the file group, not the

owner.� SIWGRP is the same as SIWUSR, but for the file group, not the

owner.� SIXGRP is the same as SIXUSR, but for the file group, not the

owner.� SIRWXG is the same as SIRWXU, but for the file group, not the

owner. (SIRWXG is the same as specifying SIRGRP, SIWGRP, andSIRGRP.)

File Other Class. All users other than the owner or file group class.� SIROTH is the same as SIRUSR, but for users in the file other

class, not the owner.� SIWOTH is the same as SIWUSR, but for users in the file other

class, not the owner.� SIXOTH is the same as SIXUSR, but for users in the file other

class, not the owner.� SIRWXO is the same as SIRWXU, but for users in the file other

class, not the owner. (SIRWXD is the same as specifying SIROTH,SIWOTH and SIXOTH.)


To set user- and groupids in a program:� SISUID sets the userid of the process to be the same as the userid

of the file owner when the file is run as a program.� SISGID is the same as SISUID, but sets the groupid rather than the

userid. The system takes the groupid from the directory in whichthe file resides.

If you omit the PATHMODE parameter, the system prevents access byall users. If you code PATHMODE and the file already exists, the systemignores it.

24.2 TSO/E HFS PARAMETERS

You specify the same HFS parameters on the TSO/E ALLOC command asyou code on the JCL DD statement:

PATH(pathname)FILEDATA(BINARY or TEXT)PATHDISP(normal-disposition,abnormal-disposition)PATHOPTS(file-options)PATHMODE(file-access-attributes)

24.3 THE BPXBATCH UTILITY

The BPXBATCH program executes UNIX programs in z/OS. You can exe-cute them with JCL, with TSO/E, and with REXX. UNIX programs requirethat you define three files:

stdin—The default is /dev/null.

stdout—The default is /dev/null.

stderr—The default is the same as stdout.

Define these files with either a JCL DD statement or a TSO/E ALLOCcommand using the PATH and any of the other needed HFS parameters.

24.3.1 Environmental Variables

You can create the environmental variables for your application in two ways:

� As an HFS file identified with a ddname of STDENV. The default filename is /dev/null. It must be a text file with read access only. Codeone variable per line in the file, starting in column 1, in the form:variable=value.


� As a z/OS data set with a ddname of STDENV. The default file nameis /dev/null. The data set can be sequential, a member of a parti-tioned data set, or SYSIN. The RECFM can be F or V. Code one vari-able per record, starting in column 1, in the form: variable=value.

Here is an example of setting the environmental variable with lines inthe input stream.

//STDENV DD *variable=valuevariable=value/*

24.3.2 Invoking BPXBATCH with JCL

You invoke BPXBATCH as follows:

//jobname JOB …//stepname EXEC PGM=BPXBATCH,PARM='request'

The request is one of the following:

� SH program-name names the shell or file that contains the shellscript. SH STDIN defaults, and you can omit the PARM and supplythe name of a shell script with //STDIN DD statement.

� PGM program-name names an executable file or REXX exec that isstored in an HFS file.

� If BPXBATCH exceeds its REGION size, you receive the followingmessage:ABEND 4093 reason code 0000001c

Code the REGION parameter to increase the region size and resubmitthe job.

24.3.3 Running a Shell Script in Batch

You run the following JCL:

//jobname JOB …//stepname EXEC PGM=BPXBATCH,REGION=8M

[PARM=‘SH STDIN’ defaults. Code whatever REGION size is needed.]

//STDIN DD PATH=’/u/a1000/bin/scriptone.in’,PATHOPTS=(ORDONLY)

[Describes the stdin file containing the script shell.]


TEAMFLY

Team-Fly®

//STDOUT DD PATH=’/u/a1000/bin/stdone.out’,// PATHOPTS=(OWRONLY,OCREAT),PATHMODE=SIRWXU

[Describes the stdout file.]

//STDERR DD PATH='/u/a1000/bin/stdone.err',// PATHOPTS=(OWRONLY,OCREAT),PATHMODE=SIRWXW

[Describes the stderr file.]

24.3.4 Running a Shell Command in Batch

You execute the BPXBATCH program to run a shell command in batch. Thefollowing executes /u/lib/stuff.

//jobname JOB …//stepname EXEC PGM=BPXBATCH,REGION=8M,// PARM='SH nohup compress /usr/lib/stuff & sleep 1'

[The nohup prevents the processing from being ended when the jobstep ends.]

//STEPLIB DD DSN=CEE.SCEERUN,DISP=SHR

[STEPLIB is propagated for the execution of the shell and for anyprocess created by the shell.]

//STDERR DD PATH='/u/a1000/bin/stdone.err',// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU

24.3.5 Running BPXBATCH in TSO/E

To run BPXBATCH in TSO/E, you first allocate all the necessary files andthen invoke BPXBATCH by coding

"BPXBATCH SH shell-command"

The shell-command is the name of the shell command or shell script.

24.3.6 Running a Shell Command in TSO/E

Use the OSHELL REXX exec to invoke BPXBATCH to run noninteractiveshell commands from the TSO/E READY prompt.

oshell shell-commandoshell rm -r /u/a1000/testpgms/bigrun.c

[The rm command removes the file named bigrun.c.]


456

CHAPTER 25

JCL AND THE INTERNET

Although JCL may execute programs that use the Internet, it itself does notdirectly use the Internet. JCL is limited to sending e-mail and files.

25.1 USEFUL WEB SITES

Essential

As a JCL user, there are several IBM web sites that you will find helpful.Because web sites change from time to time, more than one site is some-times given to increase the likelihood that one will still be active.

Web Site for this BookThe Web site at www.wiley.com/compbooks/brown provides solutions tothe exercises and a summary of obsolete JCL features.

Access to IBM ManualsThe following site lets you search for IBM manuals by title or publicationnumber. Then you can order the manual, read it over the Internet, or down-load it to your PC in either Adobe or IBM’s BookManager format for view-ing without using the Internet. BookManager is very fast and powerful.

www.elink.ibmlink.com and then click on PUBLICATIONS.

www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbl.cgi and then select the country.

www.ibm.com/server/eserver/zseries/zos and then click LIBRARY.

Information on z/OSThese sites provide current information on z/OS, recent changes, and newdirections.

www.ibm.com/zserieswww2.s390.ibm.comwww.ibm.com/server/eserver/zseries/zos

IBM’s Home PageThe following site is the gateway to all of IBM’s computers.

www.ibm.com

MVS HelpAlmost everything in MVS is applicable to z/OS. This web site providesinformation on training, job listings, and links to other useful sites. It letsyou ask questions and post or look at resumes.

www.mvshelp.com

25.2 SENDING E-MAIL FROM BATCH JOBS

Sometimes Used

To send an e-mail from a batch job, you send it to a SYSOUT data set withthe following attributes:

//ddname DD SYSOUT=(B,SMTP),DCB=(RECFM=F,LRECL=80,BLKSIZE=80)

If you wish, you can use a LRECL and BLKSIZE of 133. SMTP (Simple MailTransport Protocol) is a special writer to send e-mail. Your e-mail must havethe following header lines:

HELO jobname

[This must be the first line. You can code the e-mail commands ineither upper or lower case: HELO or helo. Use the jobname of yourjob so that it appears in the SMTP log.]

MAIL FROM: <your-e-mail-address>

[The less than/greater than signs are required. If your keyboard hasthem, you can also use left and right brackets ([]).]

RCPT TO: <recipient-e-mail-address>

[If you want to send the e-mail to several recipients, add a RCPT TO:line for each.]

JCL AND THE INTERNET 457

DATA

[This marks the start of the actual e-mail message.]

DATE: today’s date

[Optional , but you should include a date.]

FROM: your-name <your-e-mail-address>

[Optional. Use this like the FROM: line in a memo. You can alsoomit your-name and code just your-e-mail-address to supply theaddress for the REPLY TO mail function.]

TO: “recipient-name”

[Optional. Use this like the TO: line in a memo. Use double quotes toenclose text. If you want to instead code an e-mail address, encloseit in less than/greater than (<>) signs. If you have multiple to fields,separate them with commas: “name1”,“name2”,<e-mail1>, …]

CC: <e-mail-address-to-receive-copy>

[Optional. If you list an e-mail address on a RCPT TO: header linebut not on a TO: or CC: line, the address becomes a blind copy—likebcc in letter writing.]

SUBJECT: any text

[Optional. This supplies a SUBJECT field in the mailbox.]

blank line

[You must have a blank line here. Don’t write “blank line”. Justleave a blank line.]

lines in the body of your e-mail message

[Include as many lines as you wish.]

.

[A line with a single period as the first character terminates themessage.]

To send an e-mail, write the previous data lines to the SYSOUT file. The fol-lowing example illustrates this using the IEBGENER utility program.

//TEST1 JOB …// EXEC PGM=IEBGENER//SYSPRINT DD SYSOUT=A//SYSIN DD DUMMY//SYSUT2 DD SYSOUT=(B,SMTP)//SYSUT1 DD *


HELO TEST1MAIL FROM: <[email protected]>RCPT TO: <[email protected]>DATADATE: January 1, 2002FROM: Lewis N. ClarkTO: "Randy Tupper" <[email protected]>CC: <[email protected]>SUBJECT: Testing the E-mail System

If you receive this, it means that batch e-mail is working. If you don’treceive this, please give me a call and we can discuss the problem.

./*

JCL AND THE INTERNET 459

//* (comment statement)definition, 35example, 56multiple job steps, 249style in writing, 57

//*, continuing JES3 statements,240

/*$ command statement, 297***, in JCL statements, 72//** command statement, 298//*ENDDATASET statements,

246–247//, in input stream, 68/*JOBPARM statement, 63–64,

238, 285//*MAIN statement, 241–242, 285//*NETACCT statement, 64/*NETACCT statement, 237–238//*NETACCT statement,

240–241/*NOTIFY statement, 425–426//*OPERATOR statement, 298/*OUTPUT statement, 237/*PRIORITY statement,

236–237, 293/*ROUTE statement, 237//*ROUTE XEQ statement, 241/*SETUP statement, 238–239/*SIGNON and /*SIGNOFF

statements, 239/* statement

in JES2, 35, 47, 236–237SYSIN, 153

/*XEQ statement, 237

+/, in JCL statements, 72++, in JCL statements, 71++*, in JCL statements, 72= (equal sign), nullifying exist-

ing parameters, 67, 254

AABEND parameter, 65, 69, 100Abnormal dispositions, 133–135ABSTR SPACE parameter,

205–206Access codes, 234Access techniques, 30Access time, minimizing, 193–194ACCODE DD parameter, 108Accounting information, 63–64Account numbers, for jobs,

240–241ACCT EXEC parameter, 99–100ACCT keyword-parameter, 78Acct-no,acct-information, 60Acct-number subparameter, 63ACMAIN parameter, 242Additional-acct-information

subparameter, 63ADDRESS DD parameter, 167Address space

definition, 10limitations, 15MVS/ESA, 19system requirements, 16

ADDRSPC EXEC parameter, 78,294

ADDRSPC JOB parameter, 61,294

ADD statement, 346–347, 348AFF, in UNIT parameter, 138AFP (Advanced Function Pre-

sentation), 165AL (American National Stan-

dard Labels), 227ALLOCATE statement, 308ALLOC command, TSO/E, 418,

422, 445Alphabetic characters, in JCL, 52Alphanumeric characters, in

JCL, 26, 52, 62, 121ALTER command, 334–335ALTSEQ statement, 361–362ALX SPACE subparameter,

193–194AMP DD parameter, 107, 305AMS (Access Method Services),

307Application programs, 8Application space, 20ARG statement, REXX, 447–448Arithmetic expressions, 430, 440ASCII (American Standard Char-

acter Code for InformationExchange)

collating sequence, 352–353conversion to EBCDIC, 234data sets, 226device control characters, 234historical perspectives, 27industry-standard labels, 233

461

INDEX

Assembler LanguageBLKSIZE parameter, 118checkpoints, 283DSORG parameter, 112invoking the sort program, 353with JCL, 4LRECL DD parameter, 116MODS statement, 360PARM values, 98–99RECFM parameter, 114referback parameter, 109

Assignment statement, REXX,442–447

AUL (ANS and User Labels), 227Automatic restart, 282, 284AVGREC DD parameter, 57, 107,

187, 197, 209AVGRLEN PARM parameter, 357

BBasic access technique, 30Batch compilation, 320–321Batch jobs

compared to on-line jobs, 8–9sending e-mail from, 457–459

BATCH option, ISPF, 386Batch programming, ISPF, 386Binary data, 27, 377Bipolar technology, 21Bit, 26Blksize, 187, 188BLKSIZE DD parameter

advantages, 116–118allocating space, 187for dummy data sets, 147efficiency, 195overriding subparameters, 271reblocking data sets, 343specifying block size, 110for tapes, 228, 233

BLKSZLIM DD parameter,294–295

Blocked records, 114, 116Blocking data, 29–30Blocking factor, 30BLP (Bypass Label Processing),

223, 225–226, 233

BPXBATCH utility, 453–455Breaking JCL statements, 55Buffers, 30, 118, 147BUFNO DD parameter, 118, 154,

271BUILDING DD parameter, 167Built-in functions, REXX, 448Built-in variables, 437BURST DD parameter, 106,

175Byte, 26, 172BYTES JOB parameter, 61

CCALL command, TSO/E, 424CANCEL command, TSO/E,

426CANCEL parameter, 172CASE construct, REXX, 443–444Cataloged data sets, 39, 202, 221,

335–336Cataloged procedures. see also

COB2UCLG; Data sets;Instream procedures

coding, 255–256creating, 50definition, 36, 39, 248example, 272–274JCLLIB statement, 36, 257libraries, 244LKED, 318modifying statements,

249–255names, 82–83, 246nesting, 267–268overriding DD statements, 70PARM values, 99SORTD, 353–354symbolic parameters substitu-

tions, 69Catalog entries, 333CATLG DISP subparameter, 132,

232C/C++ batch processing

batch compilation, 321BLKSIZE parameter, 118checkpoints, 283

DSORG parameter, 112with JCL, 4libraries, 41LRECL DD parameter, 116PARM values, 98RECFM parameter, 114referback parameter, 109

//CCSID EXEC parameter, 78CCSID EXEC pm, 235CCSID JOB parameter, 61, 235Central storage. see also Mem-

ory; Virtual storagecompared to virtual storage,

16costs, 21definition, 7job steps, 83–84limitations, 17MVS/ESA, 19MVS/XA, 19in MVT, 11

CHANGE command, ISPF, 402,403

CHANGE statement, 349–351Character data, 27Character operations

REXX, 441–442TSO/E, 430–431

Character sets, 371–376. seeASCII; EBCDIC

CHARS DD parameter, 106,175–176

Checkid, 287Checkpointing, 173–174,

282–289, 358CHKPT DD parameter, 108,

283–284CICS (Customer Information

Control System), 9, 19–20CKPT parameter, 358CLAS DD parameter, 140Class

defined by installation, 46for output stream data sets,

155CLASS DD parameter, 164CLASS JOB parameter, 60, 61,

64–65, 242

462 INDEX

Client/server environment, 23CLISTs, 386–391, 428–437CMOS (Complementary Metal

Oxide Semiconductor) tech-nology, 21

CNTL DD parameter, 108CNTL statement, 36, 298COB2UCLG procedure, 67, 90,

249–250COBCOMP program, 37COBOL batch processing

batch compilation, 320BLKSIZE parameter, 118checkpoints, 283DSORG parameter, 111invoking the sort program, 353with JCL, 4libraries, 41load module libraries,

325–326LRECL DD parameter, 116MODS statement, 360PARM values, 98RECFM parameter, 114referback parameter, 109symbolic parameters in, 259

COBOL II compiler, 45Collating sequence, 32COLORMAP DD parameter,

165Comma delimited data, 28Command line arguments,

REXX, 447–448COMMAND statement, 36, 297Command statements, place-

ment, 59Commas

in JOB statement, 63in operand field of JCL state-

ments, 52preceding symbolic parame-

ters, 261Comment (//*) statement

definition, 35example, 56multiple job steps, 249style in writing, 57

Comments field, 51–52

COMPACT DD parameter,177–178

Comparison operations, 93–97,362, 440–441

Compiler, 41Compile step, 45–47Completion codes

comparing, 93described, 85–88IDCAMS, 307testing, 85–89

Compressiondata on tapes, 231–232definition, 103effect on data transfer rates,

217partitioned data sets, 344PDS, 343

COMP TRTCH DD parameter,103

Computer data, 26–33Computer jobs. see DD state-

ment; EXEC statement; JOBstatement

COMSETUP DD parameter, 165

Concatenated data setscreating, 149–152members of partitioned data

sets, 31placement, 59

Concatenating names, 123Concatenation operator,

441–442COND EXEC parameter, 77,

85–92, 272COND JOB parameter, 60Constant, 362, 365CONTIG SPACE subparameter,

193–194CONTROL DD parameter, 178Control interval, 302Control programs, 8Control statements, 3, 321–325,

369COPIES DD parameter, 106,

170–171COPYG DD parameter, 171

Copyingdata sets, 337from input stream to parti-

tioned data sets, 346–347lines in ISPF, 397–398partitioned data sets, 343–346sequential data sets, 332–333VSAM data sets, 311–312

COPY parameter, JES2, 73COPY statement, 337, 344COUNT statement, 338CPU (central processing unit)

definition, 7multiple, 23time limit on jobs, 60, 65–66transmitting blocks, 377

CREATE program, 150Cylinders

accessing data, 181–182estimating, 200multiple volumes acting as,

215rounding up to, 194

CYL SPACE subparameter, 189

DDA (direct access), 111DASD (direct-access storage

devices). see also SMScharacteristics, 181–182DCB parameters, 194–195definition, 33estimating space, 196–200exercises, 206–207historical perspectives, 24space allocation, 183–185SPACE parameter, 185–192storage capacity, 198–199

DATACK DD parameter, 165DATACLAS, 103DATACLAS DD parameter, 107,

210–211, 213, 278, 423DATA DD parameter, 106Data Definition. see DD state-

mentData records, 28–33Data-set-name, 120

INDEX 463

Data sets. see also Concatenateddata sets; DASD; DD state-ment; PDS; Sequential datasets; SMS

allocating, 422–424allocating buffers, 118allocation messages, 70browsing text, 408–409cataloged, 39, 202, 221concatenating, 149–152copying, 337, 413–415,

427–428creating, 423–424creating on direct-access vol-

umes, 201–205deallocating, 422–423defining, 46deleting, 427direct-access volume, 46displaying information about,

420–422dummy status, 147dynamically allocating, 295editing, 388–391, 398–404generation, 280generic types, 124input stream, 153–154ISPF operations, 411–413labels, 118–119, 122, 200moving, 413–415multiple volumes, 138, 139,

143, 200–201, 232–233names, 120–125, 290, 418nontemporary, 120–121, 122,

202, 292organization, 30–33, 111output stream, 155–158permitted extents and vol-

umes, 184postponing definition of,

270–272printing, 386, 421–422qualified names, 123RACF-protected, 61relative file number, 221renaming, 334–335retention period, 289–290rules, 151–152security, 290–291

SMS-managed, 103, 184,203–204, 290, 423

sorting, 358–359status, 125–129submitting with ISPF, 384–385submitting with TSO/E,

424–425SYSOUT, 168, 179temporary, 120, 121, 202terminal, 427types and characteristics, 104updating, 351

Data spaces, 20DATA statements, 154Data storage. see DASD; Mag-

netic tapesData transfer rates, 217Date sorting, 372DCB (data control block), exam-

ple, 105DCB DD parameter

blocking input stream data,154–155

coding, 110–120, 156,201–205

for DASD, 194–195definition, 106for dummy data sets, 147for GDG, 277nullifying, 254style in writing, 57for tapes, 228for VSAM data sets, 308

ddnameassigning, 105for concatenated data sets, 149creating, 109in DATA statements, 154in DD statements, 106for dummy DD statement, 138for HSF files, 453for Language Processors, 109for spooled data sets, 246of statements overridden,

258SYSIN, 154SYSLIN, 70SYSMSG, 169SYSPRINT, 46, 49

DDNAME DD parameter, 108,270–271

//ddname DD statement, 339DD statement. see also ddname;

HFS; SMS; VSAM data setsconcatenating data sets,

149–152data control block (DCB), 105,

110–120data set disposition, 125–135data set name, 120–125data sets, 103–105definition, 35dummy data sets, 147–149, 254example, 43–45exercises, 145, 152format, 106–108input stream, 47for input stream and print

data sets, 153–180I/O unit, 135–140multiple job steps, 249overriding, 70, 251–255placement, 59referback parameter, 109–110in the restart step, 286–287retained parameters, 119in REXX, 442–443sequential and partitioned

data sets, 146–147style in writing, 57volume parameter, 140–145

DEADLINE JOB parameter, 242Decimal data, 341, 371Decompression, 103DEFAULT DD parameter, 163DEFER DISP parameter, 139–140Deferred restart, 282Deferred volume mounting, 138,

232–233DEFINE CLUSTER command,

310DEL command, TSO/E, 427DELETE DISP subparameter, 131Delimited data, 28Delimiter (/*) statement, 35Delimiter parameter, 154Density, 217–218DEN subparameter, 228

464 INDEX

TEAMFLY

Team-Fly®

DEPT DD parameter, 168DESORT ICETOOL utilities,

336–337DEST DD parameter, 107, 173Device overhead, 198DFSORT program, 353–354,

369, 370–376Direct-access volume, 46Direct data, 31Directory space, 186, 191–192DISKR command, REXX, 446Disk volumes, 136–137DISKW command, REXX,

446–447Dispatching priority, 292–293DISP DD parameter, 106,

125–135, 339Displaying text, in ISPF, 395&DISPOSE parameter, 262DISP parameter, coding, 57Distributed data systems, 23DLM DD parameter, 107, 154DNSTYPE parameter, 191–192DPAGELBL DD parameter, 165DSN DD parameter, 57, 106,

120–125, 155, 156DSNTYPE DD parameter, 107,

215DSORG DD parameter, 111–112Dummy data sets, 147, 254DUMMY DD parameter, 106DUMP parameter, 172DUPLEX DD parameter, 165DYNAMNBER EXEC parameter,

78DYNAMNBR DD parameter, 295

EEBCDIC (Extended-Binary-

Coded-Decimal-InterchangeCode)

collating sequence, 352–353,361

conversion to ASCII, 234–235converting from ASCII, 226,

233historical perspectives, 26symbols, 369

EDIT command, TSO/E,420–421

Editing data sets, 388–391,398–404

Editing environment, ISPF,405–407

E-mail, sending from batch jobs,457–459

ENDCNTL statement, 298END command, TSO/E, 421End-of-data-set marker, 128End-of-line (/*), 153Entry-sequence data set. see

ESDSENTRY statement, 321–322, 323Environmental variables, HFS,

453–454EOV (end of volume) check-

point, 283–284Equal sign (=)

nullifying existing parameters,254

Equal sign (=), nullifying exist-ing parameters, 67

ESDS (entry-sequence data sets),22, 32

EXCLUDE command, ISPF, 402EXECIO command, REXX, 445,

446EXEC statement, 77–102

abnormal termination dumps,100–101

cataloged procedures, 82–83conditions for bypassing job

steps, 85–92described, 35, 37–38example, 43exercises, 101–102format, 77–78IF/THEN/ELSE/ENDIF state-

ment construct, 92–97job step accounting informa-

tion, 99–100job steps, 78keyword-parameters, 77, 83multiple job steps, 249overriding, 249–255passing parameters to job

steps, 97–99

performance group assign-ment, 293–294

PGM keyword, 50placement, 59programs, 78–82region size, 83–84symbolic parameters in,

267–268Executable load module, 47–48Execute step, 41Execution step, 48–49EXPDTCHK JOB parameter, 242EXPDT DD parameter, 108,

289–290Explicit referencing, 161Extended sequential data sets,

104, 184, 215–216EXTENDED subparameter, 216External paging storage, 16External references, 41, 315

FFAILURE parameter, 243, 285,

288–289Fanfold output, bursting, 175FCB DD parameter, 107, 175FETCH JOB parameter, 243FILEDATA parameter, HFS, 450FILED DATA DD parameter, 108File I/O, REXX, 445–447File-protected tapes, 218Files. see Data setsFIND command, ISPF, 402Fixed blocked records, 117Fixed-length records, 29, 114,

115, 234Fixed-point data, 377FLASHC DD parameter, 177FLASH DD parameter, 107Floating-point data, 27–28FOREGROUND option, ISPF,

386FORMDEF DD parameter, 165FORMLEN DD parameter,

165–166Forms control buffer, 174FORMS DD parameter, 174Forms overflow, 179

INDEX 465

FORTRAN batch processingbatch compilation, 320BLKSIZE parameter, 118checkpoints, 283DSORG parameter, 112with JCL, 4LRECL DD parameter, 116RECFM parameter, 114referback parameter, 109

FREE command, TSO/E,422–423

FREE DD parameter, 107, 158Functions, 36

GGB (gigabyte or gig), 16GDG (generation data group)

advantages, 276base entry, 276–277creating, 278–280deleting, 280–281group catalog information,

280model data set label, 277–278

Generation data sets, 280Global processor, 239–240GO step, 41, 250GO TO command, REXX, 444Group disk volumes, 136–137GROUPID DD parameter, 166GROUP JOB parameter, 61,

291–292Guaranteed space attribute, 185,

204GUI (graphical user interface),

379

HHardware address, in UNIT

parameter, 137–138Hexadecimal notation, 26, 361,

371HFS files

BPXBATCH utility, 453–455characteristics, 104definition, 216

JCL parameters for, 449–453parameters, 453TSO/E parameters, 453

Hiperspaces facility, 21HOLD DD parameter, 107,

156–157, 164, 243HOLD JOB parameter, 73

IIBG (interblock gap) storage

device, 29, 116IBM manuals, 456IBM processing programs,

PARM values, 99IBM standard labels, 222, 223IBM utility programs, 4,

341–351ICETOOL utility program,

336–337, 339ICRF (Integrated Cryptographic

Service Feature), 25IDCAMS utility program. see

also VSAM data setscreating VSAM data sets,

307–314DEFINE command, 276features, 33–336VSAM data sets and, 304

IEBCOPY utility program, 342,343–346

IEBGENER utility program, 342IEBPTPCH utility program, 342IEBUPDTE utility program, 256,

342, 346–348IEFBR14 null program, 204IEHLIST utility program, 342IEHMOVE utility program, 342IEHPROGM utility program, 342IF/THEN/ELSE construct, REXX,

444IF/THEN/ELSE/ENDIF state-

mentcoding, 92–97definition, 36multiple job steps, 249restarting jobs, 288

IGYCRCTL program, 45, 46

Implicit referencing, 160–161IMS (Information Management

System/Virtual Storage), 9INCLUDE statement

coding, 268–269definition, 36for linkage-editor input, 322multiple job steps, 249for SORTIN data set, 362–363

Indexalternate, 312–314compared to key-sequenced

data, 32naming conventions, 123of VSAM data sets, 301

Initiator/terminator, in MVT, 12IN LABEL subparameter, 227INPUT DD statement, 251–252Input records, 357, 360, 362Input stream

concatenated to SYSLIN, 316

copying, 346–347data records, 117DD statements, 47, 153–155definition, 39JCL statements, 69list of, 68in MVT, 11

INREC statement, 364–366Instream procedures. see also

Cataloged proceduresdefinition, 248exercises, 274–275nesting, 267–268statements, 257–258

Interactive jobs, 8–9, 14Interactive programming, 386Interactive System Productivity

Facility. see ISPF text editorI/O devices

access techniques, 30coordinating, 38definition, 7I/O unit, 135–140SYSDA, 46

ISD/ANSI device control charac-ter, 114

466 INDEX

ISO/ANSI/FIPS Version 3 labels,233–235, 290–291

ISO/ANSI Version 4 labels,233–235

ISPF text editor, 378action bar, 380–381, 383–384batch programming, 386browsing text, 408–409displaying text, 395editing commands, 396–409editing data sets, 388–391entering commands, 392–394exiting, 394–395holding output, 156–157interactive programming,

386invoking, 379–380numbered items, 381–381PF key functions, 382printing data sets, 386printing output, 385–386for programming, 384–388shortcuts with menus, 383SUPERC utility, 342utilities, 409–416writing JCL, 38

JJCL (Job Control Language). see

also JCL statements; namesof specific statements, e.g.JOB statement

accessing VSAM data sets,305–307

alphanumeric characters, 26challenges, 3–4checkpoints, 283creating VSAM data sets,

304–305features, 4–5generalizing, 266–267generating within a program,

158historical perspectives, 1–2Internet resources, 456–459for linkage editor, 316–319output, 68–72

parameters, list of, xi–xivreducing risk of termination,

204SORT example, 42–45sorting, 377syntax errors, 73

JCLHOLD parameter, JES2, 73JCLLIB statement, 36, 257, 269JCL statements

commenting, 56continuing, 55–56format, 51–52list of, 35–36placement, 58–59printing, 72–73rules, 54–55, 58–59style in writing, 57–58

JECL (job entry control lan-guage), 3

JES (job entry system)definition, 3statement placement, 58workload management sched-

uling environment, 61JES2

/*JOBPARM statement, 63–64,238, 288

/*NETACCT statement,237–238

/*NOTIFY statement, 425–426/*OUTPUT statement,

168–169, 237/*ROUTE statement, 237/*SETUP statement, 238–239/*SIGNON and /*SIGNOFF

statements, 239/*XEQ statement, 237GROUPID DD parameter, 166JCLHOLD parameter, 73operator commands, 297page size and margins, 178placement of statements,

236–237in place of hardware address

for SYSPRINT, 70SEGMENT DD parameter,

157–158special job processing, 73–74

Workload Management (WLL)scheduling environment,296

JES3//*ENDDATASET statements,

246–247//*ENDPROCESS statement,

247//*FORMAT PR statement,

169//*MAIN statement, 241–242,

288–289//*NETACCT statement,

240–241//*NET statement, 244–246//*PROCESS statement, 247//*ROUTE XEQ statement,

241/*SIGNON and /*SIGNOFF

statements, 247accounting information, 64global processor, 239–240operator commands, 298OVFL DD parameter, 179parameters, 180PRTY DD parameter, 179–180THRESHOLD DD parameter,

179Workload Management (WLL)

scheduling environment,296

JES command, 236–237JESDS DD parameter, 164JEWL program, 316–319JOBCAT statement, 314Job classes, 61. see also CLASS

JOB parameterJob Control Language. see JCLJob Entry Subsystems. see JES2;

JES3JOBLIB DD statement, 79–80Job log, 69, 238Jobname, 60, 62–63Job net, 244Job queues, 61. see also CLASS

JOB parameterJobs. see DD statement; EXEC

statement; JOB statement

INDEX 467

Job scheduler messages, 68–72JOB statement. see also JES2;

JES3accounting information, 63–64COND parameter, 91–92described, 35, 36–37example, 54, 62exercises, 74–75job class, 64–65keyword-parameters, 60–62name of job, 62–63notification of job completion,

61, 425–426performance group assign-

ment, 293–294placement, 59programmer name, 64REGION parameter, 85special job processing, 73–74system messages, 67–72time limit, 65–66

Job stepscentral storage, 83–84names, 78passing parameters to, 97–99return codes, 85–86specifying within procedures,

93JOURNAL JOB parameter, 243

KK (kilobyte), 15–16, 419KEEP DISP subparameter, 131,

230KEYLEN subparameter, 119KEYOFF DD parameter, 107,

214Key-sequenced data set. see

KSDS VSAM data setsKeyword-parameters

in DD statements, 106definition, 52, 53enclosing in apostrophes, 55in EXEC statements, 83rules, 53–54

KISTDS command, TSO/E, 420KSDS VSAM data sets, 103, 214,

300

LLABEL DD parameter, 108, 200,

220–228Language Processors, ddname,

109Language statements

converted to object modules,315

creating execution programs,41

Language translators, 8. see alsoCOBOL

Latency delays, 181LDS (linear data sets), 300LGSTREAM DD parameter, 107,

307LIBRARY DNSTYPE subparame-

ter, 191, 216LIBRARY statement, 322–323LIKE DD parameter, 107,

213–214LINES JOB parameter, 61Lines of output, limiting,

171–172Line spacing, 178Linkage editor

control statements, 321–325executing, 41exercises, 329–330features, 315–316in JCL statements, 47–48,

316–319messages, 319–320

Linux, 9LISTALC command, TSO/E,

423LISTCAT command, 333LIST command, TSO/E, 421List of subparameters, 53LKED step, 250, 318LOAD data type, 424Loader, 328. see also Linkage

editorLoading partitioned data sets,

343, 344Load module

creating, 326–327definition, 41

executable, 47–48, 315–316libraries, 325–326

Logical-expression, 368Logical expressions, 430,

440–441Logical record length, 114–116Logic statements, REXX,

443–444LOGOFF command, TSO/E, 422LOGON command, TSO/E, 419LPARS (logical partitions)

definition, 24memory and, 25

LRECL DD parameterfor concatenated data sets,

150for DASD, 194–195, 201definition, 106, 110for tapes, 228, 233, 234value, 114–116

LTM (Leading Tape Mark), 226

MMachine code control character,

114Magnetic tapes. see TapesMainframe computers

compatibility issues, 2concepts and vocabulary, 6–7performance, 22support staff, 7

Margins, specifying, 178–179MASK feature, ISPF, 394MB (megabyte or meg), 16Members, in sequential data

sets, 48MEMLIMIT JOB parameter, 61,

295Memory, 25. see also Central

storageMERGE statement, 358–359, 375MGMTCLAS DD parameter, 107,

211–212, 423Minor sort key, 353MOD DISP subparameter,

127–129, 231MODIFY DD parameter, 107,

176–177

468 INDEX

MODS statement, 360–361Modules, 36. see also Load mod-

ule; Object modules; Sourcemodules

Move/Copy option, ISPF,413–415

Moving lines, in ISPF, 397–398MSGCLASS JOB parameter, 60,

67–68MSGLEVEL JOB parameter, 60,

72–73Multiprogramming, 10MVS/370 (Multiple Virtual Stor-

age/370), 17MVS/ESA (Enterprise Systems

Architecture), 19–20MVT (Multiprogramming with

Variable Tasks), 10–14MXIG SPACE subparameter,

193–194

NName, in JOB statement, 60NAME DD parameter, 168Name field, 51, 52, 54NAME JOB parameter, 64&NAME parameter, 262NAME statement, 323–324National characters, in JCL, 26,

52, 62, 121Nesting procedures, 267–268NEW DISP subparameter, 126NEWSTACK command, REXX,

445NL (No Labels), 223, 226Nontemporary data sets,

120–121, 122, 202, 292Normal disposition, in DISP

parameter, 129–133NOTIFY DD parameter, 164NOTIFY JOB parameter, 61,

425–426NSL (Nonstandard Labels), 226Nucleus, MVT, 11Null (//) statement, 36, 296Nullifying parameters, 67, 254,

261Null statement, in REXX, 444

Numbering lines, in ISPF, 404NUMBER statement, 348–349,

350Numeric data, 27, 339, 352,

381–381N-way multiprocessor, 24

OObject modules, 41, 45, 315OCCURS statement, 339OFFSETXB DD parameter, 166OFFSETXF DD parameter, 166OFFSETYB DD parameter, 166OFFSETYF DD parameter, 166OLD DISP subparameter, 126OMIT statement, 362–363On-line jobs, 8–9, 14Opening data sets, 30Operand field, 52, 53, 55, 56Operating system, space alloca-

tion rules, 183–185Operation field, 52Operator commands, 297OPTCD subparameter, 119, 226,

233OPTION statement, 357ORDER statement, 324–325ORG JOB parameter, 242OS/390 operating system,

21–25, 28–29OSHELL REXX exec, 455OS/VS2 operating system, 14,

15OUTBIN DD parameter, 164&OUTCLASS parameter, 267OUT command, TSO/E, 426OUTDISP DD parameter, 164OUTFIL statement, 367–368,

375OUT LABEL subparameter, 227OUTLIM DD parameter, 107OUTLIST utility, 385–386OUTPUT DD parameter, 107OUTPUT JCL statement,

158–168Output queue, priority for print-

ing, 179–180Output records, 368

OUTPUT statement, 36, 249,251–255

Output stream data sets, 11,155–158

OUTREC parameter, 368OUTREC statement, 364–366Overlapped I/O, 30OVERLAYB DD parameter, 166OVERLAYF DD parameter, 166Overriding parameters, 170, 251,

258Overriding procedures, 248–249Overriding statements, 249–255,

268Overriding subparameters, 271OVFL DD parameter, 179

PPacked-decimal data, 27,

373–374, 377Packed-decimal numbers, 371Page break, 17PAGEDEF DD parameter, 166Page frames, 16Page size, specifying, 178–179PAGES JOB parameter, 61Paging supervisor, 16Parallel Sysplex (System Com-

plex), 22–23Parallel volume mounting, 139Parameters. see also names of

specific parameterscoding, 57definition, 52nullifying, 67in the operand field, 53rules, 53–54

PARM EXEC parameter, 77,97–99, 357

Partitioned data sets. see PDSPASS DISP subparameter,

130–131, 230PASSWORD JOB parameter, 61,

290–291Passwords

RACF, 61, 291–296VSAM data sets, 301, 307

PATH DD parameter, 108

INDEX 469

PATHDISP parameter, HFS, 450PATHMODE DD parameter, 108PATHMODE option, HFS,

452–453PATHOPTS DD parameter, 108PATHOPTS parameter, HFS,

450, 450–451PATH parameter, HFS, 449–450PDS (partitioned data systems)

characteristics, 104copying, 343–346creating, 215definition, 23, 48directory space, 191–192DNSTYPE and, 216DSN parameter, 124–125features, 146–147ISPF operations on, 409–411permitted extents and vol-

umes, 184in z/OS, 31

PDSE (partitioned data setextended)

characteristics, 104creating, 215definition, 31directory space, 191–192features, 147permitted extents and vol-

umes, 184PEND statement, 35, 59, 257PERFORM EXEC parameter, 78,

293–294PERFORM JOB parameter, 61PGM EXEC parameter, 50PIMSG DD parameter, 166PIPE data sets, 104, 216PL/1

batch compilation, 320–321BLKSIZE parameter, 118checkpoints, 283DSORG parameter, 112invoking the sort program, 353with JCL, 4LRECL DD parameter, 116PARM values, 98RECFM parameter, 114referback parameter, 109

PO (partitioned organization),111

PORTNO DD parameter, 166Positional parameters, rules,

53–54PR command, TSO/E, 421–422Primary space allocation,

187–189PRINT command, 334Print data sets, DD statements,

155–180Private libraries, 41, 79PRIVATE VOL subparameter,

142Private volumes, 140, 142PRMODE DD parameter, 166Procedure-name, 256Procedures. see also Cataloged

procedures; Instream procedures

definition, 36, 77modifying, 258nesting, 267–268specifying job steps within,

93symbolic parameters in, 97

Processing programs, 8Processor requirements,

241–242PROC statement

coding, 255–256definition, 35placement, 59symbolic parameters in,

260–263Production jobs, 8–9Profile name, 212Programs

calling in TSO/E session, 424definition, 77functional parts, 36generating JCL, 158IBM utility programs, 4,

341–351JEWL, 316–319names, 78–79in private libraries, 79in system library, 79

in temporary libraries, 81–82writing output to, 174

PROTECT DD parameter, 108,292

PRTERROR DD parameter, 166PRTOPTNS DD parameter, 166PRTQUEUE DD parameter, 167PRTY DD parameter, 165,

179–180PRTY JOB parameter, 61, 64–65,

292–293PS (physical sequential), 111PSF (Print Services Facility),

298Public libraries, 41Public volumes, 140PULL command, REXX, 446PULL statement, REXX, 445PULL VAR statement, REXX,

445PUSH command, REXX, 446

QQNAME DD parameter, 108,

295–296Qualified names, 123QUEUE command, REXX, 446Queued access technique, 30Queues, 61. see also CLASS JOB

parameter

RRACF (Resource Access Control

Facility)definition, 25passwords, 61, 291–292profile name, 212protected data sets, 61userid, 61

RAID (Redundant Array of Inde-pendent Disks), 24

RAMAC disk storage, 24, 215Randomly processed data, 31RANGE statement, 340RBA (relative byte address), 302RD EXEC parameter, 78, 284–285

470 INDEX

RD JOB parameter, 61, 284–285Reader/interpreter, in MVT, 11REC command, TSO/E, 419RECFM DD parameter

coding, 114for concatenated data sets, 150for DASD, 194–195, 201definition, 106, 110for tapes, 228, 233, 234

Reclength, 187Records. see also Sort/Merge

programattributes, 110BLKSIZE subparameter, 112counting, 338definition, 28formats, 112–114, 223–224inserting, 350–351lengths, 117partitioned organization, 32requesting space for, 187sequential organization, 31sorting, 377spanned, 289specifying maximum number

of, 179types of, 28–29

RECORD statement, 359–360RECORG DD parameter, 108,

214REFDD DD parameter, 107,

213–214Referback parameter

in DD statements, 109–110,120, 141

definition, 48, 77in OUTPUT statement, 161in //SYSLMOD DD statement,

49REF VOL subparameter,

141–142REGION EXEC parameter, 77,

83, 85REGION JOB parameter, 60, 83REGION SIZE EXEC parameter,

83–84Relational expressions, 92–93Relative file number, 228

Relative generation number, 276Relative record data set, 32Renaming data sets, 334–335REPLACE statement, 324REPL statement, 348–349REPRO command, 311REPRO statement, 350RESET command, ISPF, 402RESFMT DD parameter, 167RESTART JOB parameter, 61,

282–289RETAIN DD parameter, 167RETAIN VOL subparameter,

142–143Retention checks, 289–290RETPD DD parameter, 108,

289–290Retrieving output, 426RETRYL DD parameter, 167Return codes. see Completion

codesREWIND command, 230Rewriting files, 229REXX. see also ISPF text editor;

TSO/Earguments in command line,

447–448arithmetic expressions, 440entering commands, 386–391executing TSO/E commands,

438–439, 448logical expressions, 440–441statements, 442–447

RINGCHK JOB parameter, 243RISC (reduced instruction

set computers), 21RKP subparameter, 119RLS DD parameter, 108, 306RLSE SPACE subparameter,

192–193ROOM DD parameter, 168Rotational delays, 181ROUND SPACE subparameter,

194Routing output, 173RRDS (relative record data sets),

300RUNA job, 37

RUNB job, 37RUN procedure, 251–254

SSAA (System Application

Architecture), 438SAY statement, REXX, 444SCAN JOB parameter, 73–74SCHENU JOB parameter, 61SCHENV JOB parameter, 296SCRATCH DD statement, 254Scrolling, in ISPF, 395SECLABEL JOB parameter, 61,

291–292SECMODEL DD parameter, 107,

212–213, 423Secondary space allocation,

189–191Security

RACF, 25, 61, 291–296VSAM data sets, 301

Seek delays, 181SEGMENT DD parameter, 107,

157–158Sequence set, 302–303Sequence subparameter, 143Sequential data sets. see also

ESDScharacteristics, 104, 146–149copying, 332–333, 348permitted extents and vol-

umes, 184printing, 334

Service programs, 8SER VOL subparameter,

141–142, 143SET statement

definition, 36multiple job steps, 249symbolic parameters in,

263–264SETUP JOB parameter, 243Shared data, 23Shell scripts, 454–455SHR DISP subparameter, 126Simultaneous peripheral opera-

tion on-line, 11

INDEX 471

SKIPREC parameter, 357SL (Standard Labels), 223, 225SMCOPY command, TSO/E,

427–428SMS (Storage Management Sub-

system), 208–209, 216. seealso DASD

SMS-managed data sets, 103,184, 203–204, 290, 423

SNA workstation, 180SORT command, ISPF, 407–408SORTD cataloged procedure,

353–354SORTD control statements, 369SORTIN data sets, 362–363//SORTIN DD statement,

358–359Sorting text, in ISPF, 405–407Sort keys, 355, 377Sort/Merge program

ALTSEQ statement, 361–362checkpoints, 283DFSORT program, 370–376exercises, 378INCLUDE/OMIT statement,

362–363INREC/OUTREC statements,

364–366MERGE statement, 358–359MODS statement, 360–361OUTFIL statement, 367–368RECORD statement, 359–360sort efficiency, 376–377sorting concepts, 352–353SORT statement, 353–358SUM statement, 366–367SYMNAMES DD statement,

369–370SORT program, 42–45SORT statement, 341, 353–358,

375Source language statements, 36Source modules, 41Space allocation, 46, 183–185,

308–309SPACE DD parameter

coding, 186defining storage on direct-

access volume, 46

definition, 46, 106estimating number of records,

197placement, 57

Spanned records, 114, 289SPART JOB parameter, 242Special characters

described, 26in JOB statement, 63in PARM parameter, 97

SPIN DD parameter, 107, 157–158SPLIT parameter, 368Spooling, 11, 12, 70//SSPRINT DD statement, 49Statement labels, REXX, 444Station-id, 426STATS statement, 339Status, of data sets, 125–129STATUS command, TSO/E, 425STEPCAT statement, 314STEPLIB DD statement, 80–81//STEPLIB DD statement, 150Stepname, 66–67, 77, 246,

250–251, 258, 267Stepname.procstep code, 93STOPAFT parameter, 357Storage protection, 10–11STORCLAS DD parameter

creating SMS-managed datasets, 423

for DASD, 204definition, 107for GDG, 278for SMS-managed data sets,

140, 209–210for tapes, 231–232

Striiping, 215String search options, ISPF,

403–404SUBMIT command, TSO/E,

424–425Subparameters

breaking statements after, 55coding in JOB statement, 63example, 53

Subroutine libraries, 41Subroutines, 36SUBSYS DD parameter, 108,

296

SUL (Standard and User Labels),226

SUM statement, 366–367SUPERC utility, 342Symbolic parameters, 69, 97,

248, 258–267, 264–267Symbols, defining, 369, 369–370SYMNAMES DD statement,

369–370Synchronizing I/O, 30Syntax errors, 73SYS1.LINKLIB directory, 78–79SYSABEND EXEC parameter,

100–101SYSAREA DD parameter, 167//SYSCHK DD statement, 287SYSDA I/O device, 46SYSGEN (system-generating

process), 8&SYSID parameter, 260SYSIN, ddname, 153, 154//SYSIN DD statement, 154, 256//SYSLIB DD statement, 316,

318//SYSLIN DD statement, 46, 48,

316, 318//SYSLMOD DD statement, 318SYSMDUMP EXEC parameter,

100–101SYSMSG ddname, 169SYSOUT data sets, 168, 179SYSOUT DD parameter, 155//SYSOUT DD statements

placement, 59SYSOUT keyword, 46SYSPRINT, 46, 49//SYSPRINT DD statement, 48,

317–318System/360 operating system,

8–9System completion codes, 86–87System library, 79System messages, 67–72SYSUDUMP EXEC parameter,

100–101SYSUT1 data set, 347–348//SYSUT1 DD statement,

317–318SYSUT2 data set, 346–347

472 INDEX

TTag sort, 377Tapes

cataloging data sets, 309compressing data on, 231–232deferred volume mounting,

138, 139–140definition, 33–34extended sequential data sets,

215hardware, 217–220labels, 220–228on mountable volumes, 103multiple volumes, 232–233with no labels, 224reading from another installa-

tion, 233rewinding, 230space allocation, 46storage capacity, 218, 219–220using, 228–231

TCAM (TellecommunicationsAccess Method), 295–296

Teleprocessing, in MVT, 12–13Temporary data sets, 120, 121,

202TERM DD parameter, 108Terminal data sets, 427Terminal I/O, REXX, 444Text editors, 38, 266–267Text records, 117THRESHOLD DD parameter, 179TIME EXEC parameter, 65,

66–67, 78TIME JOB parameter, 60, 65–66Time sharing, 9–10Time Sharing Option. see TSO/ETITLE DD parameter, 168Tokenized data, 28Tracks

delays in accessing, 181density, 217–218estimating, 197–200requesting specific, 205–206

TRK SPACE subparameter, 189TRTCH DCB subparameter, 119,

231–232TRTCH DD parameter, 103

TSO/E. see also ISPF text editor;REXX

ALLOCATE statement, 308arithmetic expressions, 430character operations, 430–431CLISTs, 386–391, 428–437commands, 417–419, 417–419commands executed by REXX,

438–439, 448definition, 417displaying information about

data sets, 420–422entering commands, 386–391HFS parameters, 453holding output, 156–157logging on and off, 419–420logical expressions, 430running BPXBATCH, 455running shell command, 455time-sharing, 9for utility functions, 427–428

Type, in UNIT parameter, 137TYPE DD parameter, 221–227TYPRUN JOB parameter, 61,

73–74

UUNCATLG DISP subparameter,

132–133Undefined-length records, 114Undefined records, 29UNIQUE statement, 339Unit affinity, 138UNIT DD parameter, 106,

135–140UNIT keyword, 46UNIT names, 136–137Unit record, in MVT, 11UNIX, 9, 453UNIX System Services, 22Unloading parital data sets, 344Unloading partitioned data sets,

343USERDATA DD parameter, 167Userid, RACF, 61USER JOB parameter, 61, 242,

291–292USERLIB DD parameter, 167

VValues, defining, 369Variable-length data, 115Variable-length ISO/ANSI

records, 114Variable-length records, 114,

115, 198, 234, 357, 368Variable records, 29Variables

REXX, 439–440TSO/E, 429–430

VERIFY statement, 341VIO (virtual input/output), 104,

195–196VIO DD parameter, 106Virtual paging hardware, 16Virtual storage, 14, 16, 17. see

also Central storageVOL DD parameter, 106, 139,

140–145, 230Volume count, 138–139Volume serial numbers, 136,

141, 285Volumes subparameter, 143–145Volume switching, 232VSAM data sets. see also

IDCAMSaccessing through JCL,

305–307catalogs, 314characteristics, 104control split, 303creating, 214, 307–314creating with JCL, 304–305dummy, 147extended format KSDS, 103features, 300–304IDCAMS utility program,

289–290logical record length, 114–115names, 310organization, 31–32passwords, 301, 307pointer structure, 302

VTAM (Virtual Telecommunica-tions Access Method), 9

VTOC (volume table of con-tents), 182, 183

INDEX 473

WWARNING parameter, 172Watson, T.J. (Sr.), 22Write-enable ring, 218Writers, in MVT, 11

XX/, in JCL statements, 71XMIT statement, 298–299

definition, 36XX, in JCL statements, 68XX*, in JCL statements, 72

YYear 2000 features, 370–376

ZZoned-decimal years, 371–376,

377z/OS operating system. see also

VSAMbuilt-in-symbolic parameter,

260challenges, 3–4concepts and vocabulary, 6–7

data sets, 103–105features, 8–10hardware architecture,

10–25Internet resources,

456–457numeric data formats, 27partitioned data sets, 31records, 29sequential data sets, 215space allocation, 183time-sharing, 9–10UNIX System Services,

22

474 INDEX

TEAMFLY

Team-Fly®

zos-jcl-5th-edition.9780471236351.31271

Documents