z/OS

MVS Programming: Authorized AssemblerServices GuideVersion 2 Release 3

SA23-1371-30

IBM

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

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

Last updated: May 29, 2018

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

Contents

Figures . . . . . . . . . . . . . . . xi

Tables . . . . . . . . . . . . . . . xiii

About this information . . . . . . . . xvWho should use this information . . . . . . . xvHow to use this information . . . . . . . . xviz/OS information . . . . . . . . . . . . xvi

How to send your comments to IBM xviiIf you have a technical problem . . . . . . . xvii

Summary of changes . . . . . . . . xixSummary of changes for z/OS Version 2 Release 3 xixSummary of changes for z/OS Version 2 Release 2(V2R2), as updated March, 2016 . . . . . . . xxSummary of changes for z/OS Version 2 Release 2(V2R2), as updated December, 2015 . . . . . . xxSummary of changes for z/OS Version 2 Release 2 xxiz/OS Version 2 Release 1 summary of changes . . xxi

Chapter 1. Introduction . . . . . . . . 1

Chapter 2. Subtask creation and control 7Creating a new task (ATTACH or ATTACHX macro) 7Ensuring that a process completes (STATUS macro) . 8Communicating with a program (EXTRACT, QEDIT) 8

Providing an EXTRACT answer area . . . . . 11

Chapter 3. Program management . . . 13Residency and addressing mode of programs . . . 13

Placement of modules in storage . . . . . . 14Addressing mode . . . . . . . . . . . 14

Specifying where the module is to be loaded (LOADmacro) . . . . . . . . . . . . . . . . 14Synchronous exits (SYNCH or SYNCHX macro) . . 15Using checkpoint/restart . . . . . . . . . . 16Using re-entrant modules. . . . . . . . . . 17Using LLACOPY to refresh LLA directories. . . . 17Changing the LNKLST concatenation. . . . . . 18

Changing the current LNKLST set . . . . . . 18Monitoring dynamic LPA processing . . . . . . 18

Listing contents of dynamic LPA withCSVDLPAU . . . . . . . . . . . . . 22

Monitoring dynamic exits processing . . . . . . 24Monitoring fetch and unfetch processing . . . . 27

Chapter 4. Serialization. . . . . . . . 33Choosing a serialization service. . . . . . . . 33Providing ENQ resource information on DISPLAYGRS command . . . . . . . . . . . . . 37Locking . . . . . . . . . . . . . . . 38

Categories of locks . . . . . . . . . . . 38

Types of locks . . . . . . . . . . . . 39Locking hierarchy . . . . . . . . . . . 40CML lock considerations . . . . . . . . . 40Obtaining, releasing, and testing locks(SETLOCK) . . . . . . . . . . . . . 41Suspend lock instrumentation data . . . . . 41

Using the must-complete function (ENQ/DEQ) . . 42Characteristics of the must-complete function . . 43Programming notes. . . . . . . . . . . 43

Shared direct access storage devices (shared DASD) 44Volume/device status . . . . . . . . . . 44Volume handling . . . . . . . . . . . 45Macros used with shared DASD (RESERVE,EXTRACT, GETDSAB). . . . . . . . . . 45

Serializing parallel tasks (WAIT and POST) . . . . 53Asynchronous cross memory POST . . . . . 53Synchronous cross memory post . . . . . . 54Bypassing the POST routine . . . . . . . . 54Waiting for event completion (EVENTS) . . . . 55

Writing POST exit routines . . . . . . . . . 55Identifying and deleting exit routines. . . . . 56Initializing extended ECBs and ECB extensions 56POST interface with exit routines . . . . . . 57Re-entry to POST from a POST exit . . . . . 58

Branch entry to the POST service routine . . . . 58Branch entry to the WAIT service routine . . . . 60Serializing RB processing . . . . . . . . . . 61

Suspending an RB until an event completes(SUSPEND) . . . . . . . . . . . . . 61Using the CALLDISP macro . . . . . . . . 63Resuming execution of a suspended RB . . . . 64

Synchronizing unit of work (tasks or SRBs) . . . . 65Pause elements and pause element tokens . . . 66Using the services . . . . . . . . . . . 68PE ownership and cleanup . . . . . . . . 71

Global resource serialization latch manager . . . . 72Overview . . . . . . . . . . . . . . 72How to use the callable services . . . . . . 73

Planning to use the latch manager callable services 74Including a latch manager interface definition file(IDF) . . . . . . . . . . . . . . . 75Loading the linkage assist routines . . . . . 75Providing recovery for the latch manager . . . 76

Guide to the latch manager callable services . . . 78Creating a latch set (ISGLCRT and ISGLCR64services) . . . . . . . . . . . . . . 79Specifying a latch's identity or usage . . . . . 80Obtaining a latch (ISGLOBT and ISGLOB64services) . . . . . . . . . . . . . . 82Releasing a latch (ISGLREL and ISGRE64services) . . . . . . . . . . . . . . 83Purging one or more latches (ISGLPRG andISGLPR64 services) . . . . . . . . . . . 84Purging one or more latches in a group of latchsets for a group of requestors (ISGLPBA andISGLPB64 services) . . . . . . . . . . . 84

Copyright IBM Corp. 1988, 2017 iii

Chapter 5. Reporting systemcharacteristics . . . . . . . . . . . 87Collecting information about resources and theirrequestors (ISGQUERY and GQSCAN macros) . . 87

How GQSCAN returns resource information . . 88How global resource serialization determines thescope of an ENQ or RESERVE request . . . . 92

Using the SRM reporting interface to measuresubsystem activity . . . . . . . . . . . . 93Obtaining dispatchability data about address spaces(IEAMRMF3 macro) . . . . . . . . . . . 93

Chapter 6. Tracing applications usingcomponent trace . . . . . . . . . . 95Planning an application trace . . . . . . . . 96

Trace activities . . . . . . . . . . . . 97Executable macros for component tracing . . . 98Operator commands for component tracing. . . 99IPCS subcommands for component tracing . . . 99Exit routines for component tracing . . . . . 99Data areas and mapping macros for componenttracing . . . . . . . . . . . . . . 100Parmlib members for component tracing . . . 100When to trace . . . . . . . . . . . . 100Where and what to trace . . . . . . . . 101Creating trace buffers. . . . . . . . . . 102Using multiple traces . . . . . . . . . . 104Setting up user-defined options . . . . . . 104Starting, stopping and changing the trace . . . 105Using parmlib members . . . . . . . . . 105Externalizing trace data in a dump . . . . . 107Externalizing trace data through the externalwriter . . . . . . . . . . . . . . . 108

Coding macros for application traces . . . . . 111Using the CTRACE macro to define theapplication to component trace . . . . . . 111Using CTRACECS to manage trace buffer status 117Deleting the application from component trace 120

Coding a start/stop exit routine . . . . . . . 120Exit routine environment . . . . . . . . 120Exit routine processing . . . . . . . . . 121Programming considerations . . . . . . . 123Start/stop exit routine communications. . . . 125Entry specifications . . . . . . . . . . 127Return specifications . . . . . . . . . . 128

Coding a display trace exit routine . . . . . . 129Exit routine environment . . . . . . . . 130Exit routine processing . . . . . . . . . 130Programming considerations . . . . . . . 131Exit routine communications . . . . . . . 131Entry specifications . . . . . . . . . . 131Return code specifications . . . . . . . . 132

Creating trace entries . . . . . . . . . . . 133Understanding the fields in a CTE . . . . . 134Organizing variable data in CTEs . . . . . 134

Chapter 7. Communication . . . . . 137Interprocessor communication . . . . . . . . 137Writing and Deleting Messages (WTO, WTOR, andDOM Macros) . . . . . . . . . . . . . 137

Routing the Message . . . . . . . . . . 137Altering Message Text . . . . . . . . . 139Writing a Multiple-Line Message . . . . . . 139Embedding Label Lines in a Multiple-LineMessage . . . . . . . . . . . . . . 139Issuing a Message and Loading a Wait State(WTO and LOADWAIT Macros) . . . . . . 140Using the Wait State Macro (LOADWAIT) . . . 140Non-restartable and Restartable Wait States . . 140Invoking the LOADWAIT Macro . . . . . . 141Deleting Messages Already Written . . . . . 143Writing to the System Log . . . . . . . . 143

Issuing an internal START or REPLY command(MGCR) . . . . . . . . . . . . . . . 143Issuing operator commands from a program(MGCRE macro) . . . . . . . . . . . . 145Issuing a command response message . . . . . 145

Rules for a command response WTO . . . . 146Old code conversion . . . . . . . . . . 146Where to get the information . . . . . . . 147Assembler example with CIB control block . . 147Assembler example with CMDX control block,multi-line WTO. . . . . . . . . . . . 148

Controlling command flooding (IEECMDS macro) 149Routing commands in a sysplex (CPF macro). . . 149

Assigning a prefix . . . . . . . . . . . 150Persistence of the prefix . . . . . . . . . 151

What is an extended MCS console? . . . . . . 151Activating an extended MCS console . . . . 153Receiving messages and command responses,and issuing commands . . . . . . . . . 158Deactivating extended MCS consoles . . . . 163Removing extended MCS consoles . . . . . 163Example of managing an extended MCS consolesession . . . . . . . . . . . . . . 163

Chapter 8. Listening for systemevents . . . . . . . . . . . . . . 167Establishing a listen request . . . . . . . . 167

Qualifying events . . . . . . . . . . . 167nn filtering events . . . . . . . . . . . 171

Coding the listener user exit routine. . . . . . 172Non-SRBEXIT routine . . . . . . . . . 172SRBEXIT routine . . . . . . . . . . . 174

Passing parameters to a listener user exit routine 175Ending the listener user exit routine . . . . . . 176ENF event codes and meanings . . . . . . . 176ENF sample programs . . . . . . . . . . 192

SMFLSTEN - Sample ENF listener . . . . . 192Listening for global resource serialization-relatedsystem events . . . . . . . . . . . . . 197

Monitoring contention changes . . . . . . 197

Chapter 9. Using a service requestblock (SRB) . . . . . . . . . . . . 203What is an SRB? . . . . . . . . . . . . 203Why would you use an SRB? . . . . . . . . 203Scheduling and managing SRBs . . . . . . . 204Specifying the addressing environment of the SRBroutine . . . . . . . . . . . . . . . 205

iv z/OS MVS Authorized Assembler Services Guide

Using the ENV parameter on IEAMSCHD. . . 205Using the MODE parameter on SCHEDULE . . 206

Characteristics and restrictions of SRB routines . . 206Implications of running in SRB mode . . . . 207Environment of the SRB routine at entry . . . 208

Scheduling an SRB (IEAMSCHD or SCHEDULEmacro). . . . . . . . . . . . . . . . 208

Scheduling an SRB using IEAMSCHD . . . . 208Scheduling an SRB using SCHEDULE . . . . 209

Purging an SRB (PURGEDQ macro) . . . . . . 211Identifying the SRB to be purged . . . . . . 212The resource manager termination routine(RMTR) . . . . . . . . . . . . . . 213Scenario of scheduling and purging an SRB . . 214

Serializing SRB processing . . . . . . . . . 216Suspending an SRB until an event completes(SUSPEND macro). . . . . . . . . . . 216Resuming or purging a suspended SRB(RESUME macro) . . . . . . . . . . . 218Scenario of suspending and resuming an SRB 218Recovery responsibilities for a suspended SRB 219

Terminating a preemptable SRB . . . . . . . 220Calling an SRB to run synchronously . . . . . 220Transferring control for SRB processing (TCTLmacro). . . . . . . . . . . . . . . . 220

Chapter 10. Virtual storagemanagement. . . . . . . . . . . . 221Allocating and freeing virtual storage (GETMAIN,FREEMAIN and STORAGE macros) . . . . . . 222

Comparison of GETMAIN/FREEMAIN macroswith the STORAGE macro . . . . . . . . 222Specifying branch entry to GETMAIN andFREEMAIN services . . . . . . . . . . 223Obtaining storage in another address space . . 223Obtaining and using disabled reference (DREF)storage . . . . . . . . . . . . . . 223

Using cell pool services (CPOOL macro) . . . . 224Selecting the right subpool for your virtual storagerequest . . . . . . . . . . . . . . . 225

Program authorization . . . . . . . . . 226Tracking virtual storage allocation (CPOOL BUILD,GETMAIN, and STORAGE OBTAIN macros) . . . 240Obtaining information about the allocation ofvirtual storage (VSMLIST) . . . . . . . . . 241

Using the VSMLIST work area . . . . . . 241Using IARQD The page status interface routine 249

Decide which entry point you want to use . . 250Obtain storage and load register 1 . . . . . 250Use NUCLKUP to find the address of the entrypoint you want to use . . . . . . . . . 251Invoke the entry point . . . . . . . . . 252

Chapter 11. Accessing the schedulerwork area . . . . . . . . . . . . . 255Using the IEFQMREQ and the SWAREQ macros 255

The SWAREQ macro . . . . . . . . . . 256How to invoke SWAREQ . . . . . . . . 256The IEFQMREQ macro . . . . . . . . . 258

Chapter 12. The virtual lookasidefacility (VLF) . . . . . . . . . . . . 261Deciding when to use VLF . . . . . . . . . 261Planning to use VLF . . . . . . . . . . . 262

Data objects and classes . . . . . . . . . 263Data integrity . . . . . . . . . . . . 266Recovery . . . . . . . . . . . . . . 266

Using the VLF macros . . . . . . . . . . 267Defining a class of VLF objects . . . . . . 268Identifying an end user to VLF . . . . . . 269Retrieving a VLF object . . . . . . . . . 270Creating a VLF object . . . . . . . . . 271Notifying VLF of a change . . . . . . . . 273Removing a VLF end user . . . . . . . . 274Purging a VLF class . . . . . . . . . . 274Modifying VLF . . . . . . . . . . . . 274

Chapter 13. Data-in-virtual . . . . . . 277When to use data-in-virtual . . . . . . . . 277

Factors affecting performance . . . . . . . 278Creating a linear data set . . . . . . . . 278

Using the services of data-in-virtual . . . . . . 279Identify . . . . . . . . . . . . . . 279Access. . . . . . . . . . . . . . . 280Map . . . . . . . . . . . . . . . 280Save, Savelist, and Reset. . . . . . . . . 281Unmap . . . . . . . . . . . . . . 282Unaccess . . . . . . . . . . . . . . 282Unidentify . . . . . . . . . . . . . 282

The IDENTIFY service . . . . . . . . . . 282The ACCESS service . . . . . . . . . . . 284The MAP service . . . . . . . . . . . . 286The SAVE service . . . . . . . . . . . . 291The SAVELIST service . . . . . . . . . . 293The RESET service . . . . . . . . . . . 293

Effect of RETAIN mode on RESET . . . . . 294The UNACCESS and UNIDENTIFY services . . . 296Sharing data in an object . . . . . . . . . 296DIV macro programming examples . . . . . . 297

Executing an application . . . . . . . . 297Processing a data-in-virtual object . . . . . 297

Chapter 14. Sharing application data(name/token callable services) . . . . 303Levels for name/token pairs . . . . . . . . 303

Determining what your program can do withname/token pairs . . . . . . . . . . . 303

Checking authorization when retrieving a token 304Deciding what name/token level you need . . . 304

Primary-level name/token pair . . . . . . 305System-level name/token pair . . . . . . . 306

Owning and deleting name/token pairs . . . . 308Example of using the name/token services . . 308

Chapter 15. Processor storagemanagement . . . . . . . . . . . . 311Fixing/freeing virtual storage contents . . . . . 312Protecting a range of virtual storage pages . . . 313PGFIX/PGFREE completion considerations . . . 314

Contents v

Input to page services . . . . . . . . . . 315Virtual subarea list (VSL) . . . . . . . . 315Page service list (PSL) . . . . . . . . . 315Short page service list (SSL) . . . . . . . 315

Branch entry to page services . . . . . . . . 316Cross memory mode . . . . . . . . . . 316Non-cross memory mode . . . . . . . . 317

Chapter 16. Sharing data in virtualstorage (IARVSERV macro) . . . . . 319Understanding the concepts of sharing data withIARVSERV . . . . . . . . . . . . . . 320Storage you can use with IARVSERV . . . . . 320Obtaining storage for the source and target . . . 321Defining storage for sharing data and access . . . 322Changing storage access . . . . . . . . . . 323How to share and unshare data . . . . . . . 324Accessing data in a sharing group . . . . . . 325Example of sharing storage with IARVSERV . . . 325Use with data-in-virtual (DIV macro) . . . . . 327Use with page services (PGSER macro) . . . . . 327Diagnosing problems with shared data . . . . . 327Converting a central to virtual storage address(IARR2V macro) . . . . . . . . . . . . 328

Chapter 17. The nucleus. . . . . . . 329Linking to routines in the DAT-OFF nucleus(DATOFF) . . . . . . . . . . . . . . 329

Using system provided DAT-OFF routines(DATOFF) . . . . . . . . . . . . . 330Writing user DAT-OFF routines . . . . . . 332Placing user DAT-OFF routines in the DAT-OFFnucleus . . . . . . . . . . . . . . 332

Obtaining information about CSECTs in theDAT-ON nucleus (NUCLKUP) . . . . . . . 333Customizing the nucleus region . . . . . . . 334

The NMLDEF macro . . . . . . . . . . 335Removing existing routines from IEANUC0x 335

Chapter 18. Providing recovery. . . . 337Understanding general recovery concepts . . . . 338

Deciding whether to provide recovery . . . . 339Understanding errors in MVS . . . . . . . 340Understanding recovery routine states . . . . 341Understanding the various routines in arecovery environment . . . . . . . . . 342Choosing the appropriate recovery routine . . 343Understanding recovery routine options . . . 346Understanding how routines in a recoveryenvironment interact . . . . . . . . . . 347

Writing recovery routines . . . . . . . . . 349Understanding what recovery routines do . . . 350Understanding the means of communication 358Special considerations for ESTAE-type recoveryroutines . . . . . . . . . . . . . . 367Special considerations for FRRs . . . . . . 373

Understanding the recovery environment . . . . 375Register contents . . . . . . . . . . . 375Other environmental factors in recovery . . . 383

Understanding recovery through a coded example 399

Understanding advanced recovery topics . . . . 401Providing recovery with minimal processoroverhead (FESTAE macro) . . . . . . . . 402Invoking RTM . . . . . . . . . . . . 402Providing multiple recovery routines . . . . 405Providing recovery for recovery routines . . . 411Providing recovery for multitasking programs 412Using resource managers . . . . . . . . 412

Using STAE/STAI routines . . . . . . . . . 417

Chapter 19. Processing programinterruptions (SPIE, ESPIE) . . . . . 423Interruption types . . . . . . . . . . . . 424

Chapter 20. Dumping virtual storage(SDUMPX, SDUMP, and IEATDUMPmacros) . . . . . . . . . . . . . . 425SVC dumps . . . . . . . . . . . . . . 425

Deciding when to request an SVC dump . . . 426Understanding the type of SVC dump that MVSproduces . . . . . . . . . . . . . . 427Coding parameters that produce a synchronousdump . . . . . . . . . . . . . . . 427Designing a program to handle a synchronousdump . . . . . . . . . . . . . . . 428Coding parameters that produce a scheduleddump . . . . . . . . . . . . . . . 428Designing a program to handle a scheduleddump . . . . . . . . . . . . . . . 428Synchronizing your program through an ECB orSRB . . . . . . . . . . . . . . . 428Designing your program to run asynchronouslywith dump processing . . . . . . . . . 429Identifying the data set to contain the dump 429Defining the contents of the dump . . . . . 430Identifying the address spaces or data spaces tobe dumped . . . . . . . . . . . . . 430Customizing the contents of the SVC dump . . 431Requesting the summary dump . . . . . . 431Suppressing SVC dumps that duplicate previousSVC dumps . . . . . . . . . . . . . 432Providing symptom information through theSDUMPX macro . . . . . . . . . . . 432Requesting dumps on other systems in asysplex . . . . . . . . . . . . . . 433Using dynamic exits to control dumps in asysplex . . . . . . . . . . . . . . 433IEASDUMP.QUERY dynamic exit. . . . . . 433IEASDUMP.GLOBAL and IEASDUMP.LOCALdynamic exits . . . . . . . . . . . . 437IEASDUMP.SERVER dynamic exit . . . . . 441

Transaction dumps . . . . . . . . . . . 444Deciding when to request a transaction dump 445Understanding the type of transaction dumpthat MVS produces . . . . . . . . . . 445Identifying the data set to contain the dump 445Defining the contents of the dump . . . . . 446Customizing the contents of the transactiondump . . . . . . . . . . . . . . . 446Requesting the summary dump . . . . . . 446

vi z/OS MVS Authorized Assembler Services Guide

Suppressing transaction dumps that duplicateprevious transaction dumps . . . . . . . 446Providing symptom information through theIEATDUMP macro . . . . . . . . . . 446Requesting dumps of other systems . . . . . 447

Chapter 21. Protecting the system 449System integrity . . . . . . . . . . . . 449

Documentation on system integrity . . . . . 449Installation responsibility . . . . . . . . 449Elimination of potential integrity exposures . . 449

Authorized programs. . . . . . . . . . . 453Using APF to restrict access to system functions 454

Guidelines for using APF . . . . . . . . 454APF-authorized libraries. . . . . . . . . 455APF-authorized library list . . . . . . . . 456Requesting APF list services (CSVAPF macro) 456Restricting the use of SVC routines . . . . . 457Restricting load module access . . . . . . 457Assigning APF authorization to a load module 458Overriding an authorization code - SETCODEstatement. . . . . . . . . . . . . . 458Authorization results under various conditions 458

Resource Access Control Facility (RACF) . . . . 459System Authorization Facility (SAF) . . . . . . 459

MVS router . . . . . . . . . . . . . 460Interface to the MVS router (RACROUTE). . . 460SAF interface to an external security product 462

Using the command authorization service . . . . 464Command resource names . . . . . . . . 465

Changing system status (MODESET) . . . . . 467Generating an SVC . . . . . . . . . . 467Generating inline code . . . . . . . . . 467

Chapter 22. Exit routines . . . . . . 469Using asynchronous exit routines. . . . . . . 469

Using the SCHEDIRB macro to initialize andschedule an IRB . . . . . . . . . . . 470Using the SCHEDIRB macro to schedule an IRB 470Using the CIRB macro to initialize an IRB . . . 471Using the SCHEDXIT macro to schedule an IRB 473System processing to run an asynchronous exit 474

Establishing a timer disabled interrupt exit . . . 474DIE characteristics . . . . . . . . . . . 476Timer queue element control . . . . . . . 478

Using dynamic exits services . . . . . . . . 479CSVDYNEX terminology . . . . . . . . 480Defining an exit . . . . . . . . . . . 482Calling an exit routine or routines . . . . . 484Associating an exit routine with an exit . . . 488

Chapter 23. User-written SVC routines 491Writing SVC routines . . . . . . . . . . . 491

Type 6 SVC routines . . . . . . . . . . 491Non-preemptable SVC routines . . . . . . 492Programming conventions for SVC routines . . 492

Inserting SVC routines into the control program 496Standard SVC routines . . . . . . . . . 496Extended SVC routines . . . . . . . . . 499

Subsystem SVC screening . . . . . . . . . 499

Chapter 24. Accessing unit controlblocks (UCBs) . . . . . . . . . . . 503Scanning for UCBs . . . . . . . . . . . 503Obtaining UCB addresses . . . . . . . . . 503

UCB Common Segment . . . . . . . . . 504UCB Common Extension . . . . . . . . 504UCB Prefix Extension. . . . . . . . . . 504UCB Prefix Area . . . . . . . . . . . 504UCB details . . . . . . . . . . . . . 504

Ensuring that UCBs are not deleted . . . . . . 506Pinning and unpinning UCBs . . . . . . . 506When pinning is required . . . . . . . . 507When pinning is not required . . . . . . . 509

Requesting notification of I/O configurationchanges . . . . . . . . . . . . . . . 509

Using the CONFCHG macro . . . . . . . 510Coding a configuration change user exit routine 510Coded example: CONFCHG macro invocationof configuration change user exit . . . . . . 513

Detecting I/O configuration changes . . . . . 515Retrieving the current MIH time interval . . . . 516Retrieving information about I/O hardware on anI/O path . . . . . . . . . . . . . . . 516

Length of the CDR area . . . . . . . . . 517How IOSCDR retrieves the CDR . . . . . . 517Time that IOSCDR performs I/O . . . . . . 518

Validating I/O paths . . . . . . . . . . . 518Obtaining device information for an allocationrequest . . . . . . . . . . . . . . . 518Configuring a channel path online or offline . . . 518Obtaining UCB information (general methods) . . 519

Obtaining UCB addresses for a specified devicenumber . . . . . . . . . . . . . . 519Scanning UCBs . . . . . . . . . . . . 520Examples: Using the UCB macros . . . . . 520Determining if the UCB macros (generalmethods) are available . . . . . . . . . 521

Obtaining UCB information (limited method) . . 522The UCB scan service . . . . . . . . . 522Invoking the UCB scan service . . . . . . 522Obtaining the subchannel number for a unitcontrol block (UCB) . . . . . . . . . . 526

Accessing above 16-megabyte UCBs . . . . . . 526

Chapter 25. Dynamic allocation. . . . 529An allocation overview . . . . . . . . . . 529

Choosing the type of allocation for yourprogram . . . . . . . . . . . . . . 530When to avoid using dynamic allocation . . . 530Programming considerations for using theDYNALLOC macro . . . . . . . . . . 531Selecting the type of allocation based onprogram requirements . . . . . . . . . 532

Dynamic allocation functions . . . . . . . . 533Using dynamic allocation functions in either abatch or interactive environment . . . . . . 533Using dsname or pathname allocation . . . . 534Deallocating resources . . . . . . . . . 541Concatenating resources . . . . . . . . . 544Deconcatenating resources . . . . . . . . 545

Contents vii

Obtaining allocation environment information 545Using dynamic allocation functions in aninteractive environment . . . . . . . . . 546In-use attribute . . . . . . . . . . . . 546Control limit . . . . . . . . . . . . 547Permanently allocated attribute . . . . . . 548Convertible attribute . . . . . . . . . . 548Using ddname allocation . . . . . . . . 548

Installation options for DYNALLOC macrofunctions . . . . . . . . . . . . . . . 550

Using default values . . . . . . . . . . 550Mounting volumes and bringing devices online 550Installation input validation routine for dynamicallocation. . . . . . . . . . . . . . 551

Chapter 26. Requesting dynamicallocation functions . . . . . . . . 553Building the SVC 99 parameter list . . . . . . 553

Coding a dynamic allocation request . . . . 554Obtaining storage for the parameter list . . . 555Mapping storage for the parameter list . . . . 556Setting up the request block pointer . . . . . 557Setting up the request block . . . . . . . 557Setting up the text units . . . . . . . . . 563Setting up the text unit pointer list . . . . . 564

Processing messages and reason codes fromdynamic allocation . . . . . . . . . . . 565

Setting up the request block extension . . . . 565Processing messages from dynamic allocation 590

Interpreting DYNALLOC return codes . . . . . 596Interpreting information reason codes fromDYNALLOC . . . . . . . . . . . . 597Interpreting error reason codes fromDYNALLOC . . . . . . . . . . . . 601

SVC 99 parameter list verb codes and text units, byfunction . . . . . . . . . . . . . . . 636

Coding a dsname allocation text unit . . . . 637JCL DD statement parameters and equivalenttext units . . . . . . . . . . . . . . 637Using system symbols in text units . . . . . 638Dsname allocation text units . . . . . . . 642JCL DD statement DCB subparameters andequivalent text units . . . . . . . . . . 677DCB attribute text units . . . . . . . . . 679Non-JCL dynamic allocation functions . . . . 691Dynamic unallocation text units . . . . . . 706Dynamic concatenation text units. . . . . . 711Dynamic deconcatenation text units . . . . . 713Text units for removing the in-use attributebased on task ID . . . . . . . . . . . 713Ddname allocation text units . . . . . . . 714Dynamic information retrieval text units . . . 715

Example of a Dynamic Allocation Request. . . . 735

Chapter 27. Dynamic output . . . . . 739Creating and naming output descriptors . . . . 740

System generated names . . . . . . . . 740Job step considerations . . . . . . . . . 740Output descriptors and text units. . . . . . 740Deleting output descriptors. . . . . . . . 750

Specifying SYSOUT without an outputdescriptor . . . . . . . . . . . . . 751Dynamic output programming example . . . 753

Chapter 28. Scheduler JCL facility(SJF) . . . . . . . . . . . . . . . 759Understanding SJF terms . . . . . . . . . 760

The SJF environment . . . . . . . . . . 761Retrieving output descriptor information(SJFREQ macro with RETRIEVE) . . . . . . 761Merging SWBTUs (SJFREQ macro withSWBTU_MERGE) . . . . . . . . . . . 762Validating and building text units (SJFREQmacro with VERIFY) . . . . . . . . . . 763SJFREQ VERIFY functions . . . . . . . . 763Preparing to use VERIFY for validating andbuilding text units . . . . . . . . . . . 764Examples of using SJFREQ VERIFY functions 767Freeing the SJF environment (SJFREQ macrowith TERMINATE) . . . . . . . . . . 770

Understanding the OUTDES statement . . . . . 771Operand and keyword operand abbreviations 771Comments and line continuation . . . . . . 771Delimiters . . . . . . . . . . . . . 771Rules for parsing data with and withoutquotation marks . . . . . . . . . . . 772OUTDES statement syntax . . . . . . . . 772

Chapter 29. Processing user traceentries in the system trace table . . . 785Formatting a USRn trace table entry . . . . . . 785Replacing a USRn TTE formatting routine . . . . 785

Parameters passed to the USRn formatter . . . 786Return codes from the USRn formatter . . . . 786Printing the trace output buffer contents . . . 787Handling errors during TTE formatting . . . 787

Chapter 30. Using system loggerservices. . . . . . . . . . . . . . 791What is system logger? . . . . . . . . . . 791

The log stream . . . . . . . . . . . . 792The system logger configuration . . . . . . . 795

The system logger component . . . . . . . 796Overview of authorized system logger services . . 797

Summary of system logger services . . . . . 797Coding a system logger complete exit forIXGBRWSE, IXGWRITE, and IXGDELET . . . 798Using ENF event code 48 in system loggerapplications . . . . . . . . . . . . . 801

IXGCONN: Connecting to and disconnecting froma log stream . . . . . . . . . . . . . . 802

Connecting as a resource manager . . . . . 803Using ENF event 48 when a connect request isrejected . . . . . . . . . . . . . . 804Coding a resource manager exit for IXGCONN 804

IXGDELET: Deleting log blocks from a log stream 808Delete requests and resource manager exitprocessing . . . . . . . . . . . . . 808

Setting up the system logger configuration . . . 808Writing an ENF event 48 listen exit . . . . . 808

viii z/OS MVS Authorized Assembler Services Guide

Logger server address space availabilityconsiderations . . . . . . . . . . . . . 811

ENF 48 and system logger initialization . . . 811ENF 48 event code scenarios . . . . . . . 811Considerations for logger resources temporarilyunavailable . . . . . . . . . . . . . 812Considerations for logger log streamdisconnected . . . . . . . . . . . . 814

When things go wrong: Recovery scenarios forsystem logger . . . . . . . . . . . . . 817

When a resource manager fails . . . . . . 817

Chapter 31. System REXX . . . . . . 819Planning to use system REXX . . . . . . . . 821Security . . . . . . . . . . . . . . . 825Argument and variable processing . . . . . . 825Input/output files . . . . . . . . . . . . 828Functions. . . . . . . . . . . . . . . 828Time limits and canceling a request . . . . . . 833Error handling . . . . . . . . . . . . . 833Examples . . . . . . . . . . . . . . . 834

Chapter 32. z/OS FBA services . . . . 839z/OS Distributed Data Backup (zDDB) . . . . . 839z/OS FBA devices . . . . . . . . . . . . 840

Controlling access to z/OS FBA devices . . . 841z/OS FBA services . . . . . . . . . . . 841

Querying and allocating FBA devices . . . . 842Reading from and writing to z/OS FBA devices 847Erasing data on z/OS FBA devices . . . . . 849Unallocating z/OS FBA devices . . . . . . 849Improving performance when using IOSFBAservices . . . . . . . . . . . . . . 850Providing a recovery or resource manager. . . 851

Chapter 33. Using and registeringfunctions with the IBM FunctionRegistry for z/OS . . . . . . . . . . 853Using the IBM Function Registry for z/OS . . . 853Registering functions in the IBM Function Registryfor z/OS . . . . . . . . . . . . . . . 854

Appendix A. Using the unitverification service . . . . . . . . . 857Functions. . . . . . . . . . . . . . . 857

Check groups - Function code 0 . . . . . . 857Check units - Function code 1 . . . . . . . 858Return unit name - Function code 2 . . . . . 858Return unit control block (UCB) addresses -Function code 3 . . . . . . . . . . . 858Return group ID - Function code 4 . . . . . 858Indicate unit name is a look-up value - Functioncode 5 . . . . . . . . . . . . . . . 858Return look-up value - Function code 6 . . . 858Convert device type to look-up value - Functioncode 7 . . . . . . . . . . . . . . . 858Return attributes - Function code 8 . . . . . 858Check units with no validity bit - Function code9 . . . . . . . . . . . . . . . . 859Specify subpool for returned storage - Functioncode 10 . . . . . . . . . . . . . . 859Return unit names for a device class - Functioncode 11 . . . . . . . . . . . . . . 859Callers of IEFEB4UV . . . . . . . . . . 859Callers of IEFGB4UV or IEFAB4UV . . . . . 859

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

Notices . . . . . . . . . . . . . . 879Terms and conditions for product documentation 881IBM Online Privacy Statement. . . . . . . . 882Policy for unsupported hardware. . . . . . . 882Minimum supported hardware . . . . . . . 882Programming interface information . . . . . . 883Trademarks . . . . . . . . . . . . . . 883

Index . . . . . . . . . . . . . . . 885

Contents ix

|||||||||

x z/OS MVS Authorized Assembler Services Guide

Figures

1. EXTRACT ECB Address, CIB Address, andProgram Token. . . . . . . . . . . . 9

2. EXTRACT Answer Area Fields . . . . . . 123. Example of an Interlock Environment . . . . 484. Example of Subroutine Issuing RESERVE and

DEQ Using GETDSAB . . . . . . . . . 525. Bypassing the POST Routine . . . . . . . 556. Pause and Release Example . . . . . . . 697. Release and Pause Example . . . . . . . 708. Transfer without Pause Example . . . . . 719. Work Area Contents for GQSCAN with a

Scope of STEP, SYSTEM, SYSTEMS, or ALL . . 9010. Work Area Contents for GQSCAN with a

Scope of LOCAL or GLOBAL . . . . . . 9211. Structure of Multiple Traces for an

Application . . . . . . . . . . . . 11312. Trace Features . . . . . . . . . . . 11413. Structure of Multiple Traces for an

Application . . . . . . . . . . . . 11514. Setting up Multiple Traces with CTRACE

DEFINE . . . . . . . . . . . . . 11615. Managing Buffer Status . . . . . . . . 11716. Tracing with Component Trace. . . . . . 12317. Information Passed to the Start/Stop Exit

Routine Through GPR 1 . . . . . . . . 12818. Information Passed to the Display Trace Exit

Routine Through GPR 1 . . . . . . . . 13219. Component Trace Entry in a Trace Buffer 13320. LOADWAIT Example for Defining and

Initializing a Parameter List . . . . . . . 14121. WTO Example for Issuing a Message with a

WSPARM parameter . . . . . . . . . 14122. LOADWAIT Example for Defining Storage for

a Parameter List . . . . . . . . . . 14223. LOADWAIT Example for Modifying an

Existing Parameter List . . . . . . . . 14224. WTO Example for Issuing a Message and

Loading a Wait State . . . . . . . . . 14225. LOADWAIT Example for Adding a Reason

Code to a Parameter List and Changing theType of Wait State . . . . . . . . . . 142

26. WTO Example of a Message with a WSPARMParameter. . . . . . . . . . . . . 142

27. Setting Up the Buffer for MGCR . . . . . 14528. MDB Structure . . . . . . . . . . . 16029. Managing an Extended MCS Console Session

Overview . . . . . . . . . . . . . 16430. Authorized Program without QUAL and

QMASK . . . . . . . . . . . . . 16931. Qualifier for a Program Check . . . . . . 17032. Authorized Programs with QUAL and

QMASK . . . . . . . . . . . . . 17133. Example of Scheduling an SRB. . . . . . 21534. Suspending and Resuming an SRB . . . . 21935. Low and High Private Storage Allocation 22836. Task Structure Within an Address Space 233

37. Allocated Storage Information for Subpools ina Specified Area . . . . . . . . . . 244

38. Format of Subpool Descriptor . . . . . . 24539. Format of Allocated Block Descriptor 24540. Allocated Storage Information for the Private

Area . . . . . . . . . . . . . . 24641. Allocated Storage Information for a Subpool

List . . . . . . . . . . . . . . . 24742. Format of Free Space Information . . . . . 24743. Format of Free Space Descriptor . . . . . 24744. Unallocated Storage Information for CSA and

PVT Subpools . . . . . . . . . . . 24845. Format of Region Descriptor . . . . . . 24946. Format of Unallocated Block Descriptor 24947. Retrieving an Object for an End User 26848. Mapping from an Address Space . . . . . 28749. Mapping from a Data Space or Hiperspace 28750. Multiple Mapping . . . . . . . . . . 28851. Using the Primary Level in a Cross-Memory

Environment . . . . . . . . . . . . 30552. Using the System Level in a Multiple Address

Space Environment . . . . . . . . . 30753. Data Sharing with IARVSERV . . . . . . 32054. Sharing Storage with IARVSERV . . . . . 32655. Virtual Storage Map of DAT-ON Nucleus 33456. Mainline Routine with One Recovery Routine 34857. Mainline Routine with Several Recovery

Routines . . . . . . . . . . . . . 34958. Passing Parameters to an ARR . . . . . . 37259. Routing control to recovery routines, example

1 . . . . . . . . . . . . . . . . 40760. Routing control to recovery routines, example

2 . . . . . . . . . . . . . . . . 40861. Routing control to recovery routines, example

3 . . . . . . . . . . . . . . . . 40962. Assigning Authorization via SETCODE 45863. Asynchronous Exit Data Area Configuration 47164. UCB Segments . . . . . . . . . . . 50365. Comparison of CDRLEN to CDRSIZE 51766. Device Classes . . . . . . . . . . . 52467. Structure of the SVC 99 Parameter List 55568. Structure of Input Parameter List to IEFDB476 59269. Example of a Dynamic Allocation Request 73670. Parameter List Resulting from Dynamic

Allocation Example . . . . . . . . . 73771. Text Units and Text Unit Pointers . . . . . 74172. Sample OUTPUT JCL Statement . . . . . 74273. COPIES Keyword and its Dynamic Output

Text Units. . . . . . . . . . . . . 74374. Sample OUTDES Statement for Which an

Application Wants Text Units . . . . . . 76775. OUTDES Statement with Pointers Indicating

Values To Be Processed . . . . . . . . 76876. OUTDES Statement with New Pointers

Indicating Values To Be Processed . . . . 769

Copyright IBM Corp. 1988, 2017 xi

77. OUTDES Statement with Adjusted PointersIndicating Values To Be Processed . . . . 769

78. OUTDES Statement with Adjusted Pointersfor Values To Be Processed . . . . . . . 770

79. Sample Code for Formatting USRn TraceTable Entries . . . . . . . . . . . . 788

80. System Logger Log Stream . . . . . . . 79281. Log Stream Data on the Coupling Facility and

DASD . . . . . . . . . . . . . . 79382. Log Stream Data in Local Storage Buffers and

DASD Log Data Sets . . . . . . . . . 79483. A Complete Coupling Facility Log Stream

Configuration . . . . . . . . . . . 79584. A DASD-Only Configuration . . . . . . 79685. Issuing ENFREQ to Listen for ENF Event

Code 48 . . . . . . . . . . . . . 80286. z/OS FBA for data transfer . . . . . . . 83987. z/OS Distributed Data Backup. . . . . . 84088. Visual representation of IOSFBA query 84389. Visual representation of IOSFBA allocation 84490. FBADL with three device entries . . . . . 84691. Mapping of output area from IOSFBA

QUERY and IOSFBA ALLOCATE . . . . . 84792. Visual representation of reading or writing to

z/OS FBA devices . . . . . . . . . . 84893. Controls blocks needed for FBA I/O . . . . 84994. Visual representation of unallocating z/OS

FBA devices . . . . . . . . . . . . 85095. IBM Function Registry for z/OS data

structures . . . . . . . . . . . . . 85496. Defining multiple product versions in the

product area . . . . . . . . . . . . 85697. Input Parameter List . . . . . . . . . 86098. Requesting Function Code 0 (Check Groups) 86299. Requesting Function Code 1 (Check Units) 863

100. Requesting Function Code 2 (Return UnitName) . . . . . . . . . . . . . . 863

101. Output from Function Code 2 (Return UnitName) . . . . . . . . . . . . . . 864

102. Requesting Function Code 3 (Return UCBAddresses) . . . . . . . . . . . . 864

103. Output from Function Code 3 (Return UCBAddresses) . . . . . . . . . . . . 864

104. Requesting Function Code 4 (Return GroupID) . . . . . . . . . . . . . . . 865

105. Output from Function Code 4 (Return GroupID) . . . . . . . . . . . . . . . 866

106. Requesting Function Code 5 (Indicate UnitName is a Look-up Value) . . . . . . . 866

107. Requesting Function Code 6 (Return Look-upValue) . . . . . . . . . . . . . . 867

108. Output from Function Code 6 (ReturnLook-up Value) . . . . . . . . . . . 867

109. Requesting Function Code 7 (Convert DeviceType to Look-up Value) . . . . . . . . 868

110. Output from Function Code 7 (ConvertDevice Type to Look-up Value) . . . . . 868

111. Requesting Function Code 8 (ReturnAttributes) . . . . . . . . . . . . 869

112. Requesting Function Code 10 (SpecifySubpool for Returned Storage) . . . . . . 870

113. Requesting Function Code 11 (Return UnitNames for a Device Class) . . . . . . . 870

114. Output from Function Code 11 (Return UnitNames for a Device Class) . . . . . . . 871

115. Input for Function Codes 0 and 1 . . . . . 872116. Output from Function Codes 0 and 1 872117. Input for Function Codes 3 and 10 . . . . 873118. Output from Function Codes 3 and 10 873119. Input for Function Codes 1 and 5 . . . . . 873120. Output from Function Codes 1 and 5 874

xii z/OS MVS Authorized Assembler Services Guide

||||||

Tables

1. Assembler Definition of AMODE/RMODE 142. Summary of available serialization services 343. Summary of program serialization techniques 354. Comparison of serialization services . . . . 365. Summary of Locking Characteristics . . . . 396. Valid Volume Characteristic and Device Status

Combinations . . . . . . . . . . . . 447. ECB Extension (ECBE) . . . . . . . . . 568. POST Function and Branch Entry Points 599. POST Branch Entry Input . . . . . . . . 59

10. POST Branch Entry Output . . . . . . . 5911. Pause, Release, and Transfer callable services 6512. Pause Element (PE) and Event Control Block

(ECB) . . . . . . . . . . . . . . 6613. Latch Manager IDFs . . . . . . . . . 7514. Latch Manager Services . . . . . . . . 7815. Summary of Possible Results of Calls to

Latch_Obtain . . . . . . . . . . . . 8316. GQSCAN Results with a Scope of STEP,

SYSTEM, SYSTEMS, or ALL . . . . . . . 8917. GQSCAN Results with a Scope of LOCAL or

GLOBAL . . . . . . . . . . . . . 9118. Conditions Determining When Start/Stop

Routine Runs . . . . . . . . . . . 12419. Valid Character Set . . . . . . . . . 15020. Valid EOT and EOM parameter combinations 17621. ENF macro event codes . . . . . . . . 17722. Qualifier / QMASK combinations for

contention data . . . . . . . . . . . 19823. Qualifier / QMASK combinations for RNL

change data . . . . . . . . . . . . 20024. Qualifier / QMASK combinations for Global

Resource Serialization Mode changes . . . 20125. Comparing IEAMSCHD to SCHEDULE 20826. Supervisor State and PSW Key 0 Callers and

Subpool 0 . . . . . . . . . . . . . 22627. A Comparison of Private and Common

Storage . . . . . . . . . . . . . 22728. Storage keys for selectable key subpools 23029. How the system determines the input TCB

for task owned storage . . . . . . . . 23230. Choosing Storage Ownership . . . . . . 23431. Subpools Grouped by Attributes . . . . . 23532. Storage subpools and their attributes 23633. Description of VSMLIST Work Area . . . . 24134. Return and Reason Codes for IARQD 25235. When VLF Notification is Automatic 26536. Summary of What Programs Do with

Name/Token Pairs . . . . . . . . . . 30437. Allowed Source/Target View Combinations

for Share (Requested Target View) . . . . 32338. DAT-OFF Routines Available to Users 32939. Summary of Recovery Routine States 34640. Contents of GPR 0 on Entry to a Retry

Routine . . . . . . . . . . . . . 357

41. Restoring Quiesced Restorable I/OOperations . . . . . . . . . . . . 370

42. Where to Find Register Content Information 37643. Register ContentsESTAE-Type Recovery

Routine With an SDWA . . . . . . . . 37644. Register ContentsESTAE-Type Recovery

Routine Without an SDWA . . . . . . . 37745. Register ContentsFRR . . . . . . . . 37846. Register ContentsRetry from an

ESTAE-Type Recovery Routine Without anSDWA (General Purpose Registers) . . . . 380

47. Register ContentsRetry from anESTAE-Type Recovery Routine Without anSDWA (Access Registers). . . . . . . . 380

48. Register ContentsRetry from anESTAE-Type Recovery Routine With anSDWA, RETREGS=NO, and FRESDWA=NO(General Purpose Registers) . . . . . . . 381

49. Register ContentsRetry from anESTAE-Type Recovery Routine With anSDWA, RETREGS=NO, and FRESDWA=NO(Access Registers) . . . . . . . . . . 381

50. Register ContentsRetry from anESTAE-Type Recovery Routine With anSDWA, RETREGS=NO, and FRESDWA=YES(General Purpose Registers) . . . . . . . 381

51. Register ContentsRetry from anESTAE-Type Recovery Routine With anSDWA, RETREGS=NO, and FRESDWA=YES(Access Registers) . . . . . . . . . . 381

52. Register ContentsRetry from anESTAE-Type Recovery Routine With anSDWA and RETREGS=YES (General PurposeRegisters) . . . . . . . . . . . . . 382

53. Register ContentsRetry from anESTAE-Type Recovery Routine With anSDWA and RETREGS=YES (Access Registers) . 382

54. Register ContentsRetry from anESTAE-Type Recovery Routine With anSDWA and RETREGS=64 in z/Architecturemode (General Purpose Registers) . . . . 382

55. Register ContentsRetry from anESTAE-Type Recovery Routine With anSDWA and RETREGS=64 in z/Architecturemode (Access Registers) . . . . . . . . 382

56. Register ContentsRetry from an FRR(General Purpose Registers) . . . . . . . 383

57. Register ContentsRetry from an FRR(Access Registers) . . . . . . . . . . 383

58. Register ContentsRetry from an FRR withRETREGS=64 in z/Architecture mode(General Purpose Registers) . . . . . . . 383

59. Register ContentsRetry from an FRR withRETREGS=64 in z/Architecture mode (AccessRegisters) . . . . . . . . . . . . . 383

Copyright IBM Corp. 1988, 2017 xiii

60. Environments of ESTAE-Type RecoveryRoutines and their Retry Routines . . . . 390

61. Environment on Entry to FRRs. . . . . . 39362. Retry to SETFRR Environment (Specifying

SETRP RETRY=FRR) . . . . . . . . . 39663. SDUMPX Parameters and the Type of

Summary Dump They Produce . . . . . 43164. Authorization Rules . . . . . . . . . 45965. Input Parameters to the External Security

Product Router . . . . . . . . . . . 46366. Programming Conventions for SVC Routines 49267. Comparison of macros that return addresses

of UCB segments . . . . . . . . . . 50568. Dynamic Allocation Functions in a Batch or

Interactive Environment . . . . . . . . 53369. JCL DD Statement Facilities Not Supported

by Dynamic Allocation . . . . . . . . 53570. Minimum Amount of Storage for a Dynamic

Allocation Request . . . . . . . . . . 55671. S99FLG11 First byte of S99FLAG1 55872. S99FLG12 Second byte of S99FLAG1 55973. Example of Using the S99GDGNT bit of the

S99FLAG1 field . . . . . . . . . . . 55974. Relationship of S99NOMNT, S99OFFLN and

S99MOUNT . . . . . . . . . . . . 56275. Relationship of S99NOMNT, S99OFFLN and

S99MOUNT . . . . . . . . . . . . 56376. DYNALLOC Return Codes . . . . . . . 59677. Class 2 error reason codes (unavailable

system resource - ENVIRONMENTALERROR) . . . . . . . . . . . . . 602

78. Class 3 error reason codes (invalid parameterlist - PROGRAM ERROR) . . . . . . . 611

79. Class 4 Error Reason Codes (EnvironmentalError) . . . . . . . . . . . . . . 617

80. Class 7 Error Reason Codes (System RoutineError) . . . . . . . . . . . . . . 625

81. JCL DD Statement Parameters and EquivalentText Units. . . . . . . . . . . . . 638

82. Verb code 01 (dsname allocation) Text unitkeys, mnemonics, and functions . . . . . 642

83. DALPOPT Options . . . . . . . . . 66884. DALPMDE Attributes. . . . . . . . . 66985. JCL DD Statement DCB Subparameters and

Equivalent Text Units . . . . . . . . . 67886. Verb Code 01 (DCB Attributes) Text Unit

Keys, Mnemonics, and Functions . . . . . 67987. Verb code 01 (non-JCL dynamic allocation

functions) Text units, mnemonics, andfunctions . . . . . . . . . . . . . 692

88. Verb code 02 (dynamic unallocation) Textunit keys, mnemonics, and functions. . . . 706

89. Verb code 03 (dynamic concatenation) Textunit keys, mnemonics, and functions. . . . 712

90. Verb code 04 (dynamic deconcatenation) Text unit key, mnemonic, and function . . . 713

91. Verb Code 05 (Remove In-Use ProcessingBased on Task-ID) Text Unit Keys,Mnemonics, and Functions . . . . . . . 714

92. Verb Code 06 (Ddname Allocation) TextUnit Keys, Mnemonics, and Functions . . . 714

93. Verb Code 07 (Dynamic InformationRetrieval) Text Unit Keys, Mnemonics, andFunctions . . . . . . . . . . . . . 716

94. DINRPOPT Options . . . . . . . . . 72995. DINRPMDE Attributes . . . . . . . . 72996. Dynamic Output Text Units and their JCL

Equivalents . . . . . . . . . . . . 74497. Alternate Sources of SYSOUT Processing

Options . . . . . . . . . . . . . 75298. Values for Normal- and Abnormal-Output-

Disp . . . . . . . . . . . . . . 78099. IxgenfUnion1 variation when IXGENF bit set

to 1 . . . . . . . . . . . . . . . 809100. Logger services with "temporary unavailable

type reason codes" and expected related ENF48 events . . . . . . . . . . . . . 812

xiv z/OS MVS Authorized Assembler Services Guide

About this information

This information describes the authorized services that the MVS operating systemprovides; that is, services available only to authorized programs. An authorizedprogram must meet one or more of the following requirements:v Running in supervisor statev Running under PSW key 0-7v Running APF authorized.

Some of the services included in this information are not authorized, but areincluded because they are of greater interest to the system programmer than to thegeneral applications programmer. The functions of these services are of such anature that their use should be limited to programmers who write authorizedprograms. Services are also included if they have one or more authorizedparameters parameters available only to authorized programs.

To use an MVS service, the program issues a macro. The following set ofcompanion documents provides the detailed information necessary to code themacros.v z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYNv z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXGv z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDUv z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO.

Some of the topics described in this document are also described in z/OS MVSProgramming: Assembler Services Guide, z/OS MVS Programming: Assembler ServicesReference ABE-HSP and z/OS MVS Programming: Assembler Services ReferenceIAR-XCT. However, those documents do not include the authorized services andmacros.

Who should use this informationThis information is for the programmer who is using assembler language to code asystems program, and who needs to become familiar with the MVS operatingsystem and the services that programs running under it can invoke.

Programmers using this information should have a knowledge of the computer, asdescribed in z/Architecture: Principles of Operation, as well as a knowledge ofassembler language programming.

System macros require High Level Assembler. For more information aboutassembler language programming, see High Level Assembler and Toolkit Featurein IBM Knowledge Center (www.ibm.com/support/knowledgecenter/SSENW6).

Using this information also requires you to be familiar with the operating systemand the services that programs running under it can invoke.

Copyright IBM Corp. 1988, 2017 xv

http://www.ibm.com/support/knowledgecenter/SSENW6http://www.ibm.com/support/knowledgecenter/SSENW6

How to use this informationThis information is one of the set of programming documents for MVS. This setdescribes how to write programs in assembler language or high-level languages,such as C, FORTRAN, and COBOL. For more information about the content of thisset of documents, see z/OS Information Roadmap.

z/OS informationThis information explains how z/OS references information in other documentsand on the web.

When possible, this information uses cross document links that go directly to thetopic in reference using shortened versions of the document title. For completetitles and order numbers of the documents for all products that are part of z/OS,see z/OS Information Roadmap.

To find the complete z/OS library, go to IBM Knowledge Center(www.ibm.com/support/knowledgecenter/SSLTBW/welcome).

xvi z/OS MVS Authorized Assembler Services Guide

http://www.ibm.com/support/knowledgecenter/SSLTBW/welcomehttp://www.ibm.com/support/knowledgecenter/SSLTBW/welcome

How to send your comments to IBM

We encourage you to submit comments and questions on the z/OS productdocumentation. Your valuable feedback helps to ensure accurate and high-qualityinformation.

Important: If your comment regards a technical problem, see instead If you havea technical problem.

Submit your feedback by using the appropriate method for your type of commentor question:

Feedback on z/OS functionIf your comment or question is about z/OS itself, submit a request throughthe IBM RFE Community (www.ibm.com/developerworks/rfe/).

Feedback on IBM Knowledge Center functionIf your comment or question is about the IBM Knowledge Centerfunctionality, for example search capabilities or how to arrange the browserview, send a detailed email to IBM Knowledge Center Support atibmkc@us.ibm.com.

Feedback on the z/OS product documentation and contentIf your comment or question is about the information that is provided inthe z/OS product documentation library, send a detailed email tomhvrcfs@us.ibm.com. We welcome any feedback that you have, includingcomments on the clarity, accuracy, or completeness of the information.

To help us better process your submission, include the followinginformation:v Your name, company/university/institution name, and email addressv The following deliverable title and order number: z/OS MVS Authorized

Assembler Services Guide, SA23-1371-30v The section title of the specific information to which your comment or

question relatesv The text of your comment.

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

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

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

Copyright IBM Corp. 1988, 2017 xvii

http://www.ibm.com/developerworks/rfe/mailto:ibmkc@us.ibm.commailto:mhvrcfs@us.ibm.comhttp://support.ibm.com

xviii z/OS MVS Authorized Assembler Services Guide

Summary of changes

This information includes terminology, maintenance, and editorial changes.Technical changes or additions to the text and illustrations for the current editionare indicated by a vertical line to the left of the change.

Summary of changes for z/OS Version 2 Release 3The following information has been added, changed, or deleted in z/OS Version 2Release 3 (V2R3). The most recent updates are listed at the top of each section.

New

The following information has been added:v APAR OA53640 - Event code 19 has been added to ENF event codes and

meanings on page 176.v Updates for APAR OA53660, see Registering functions in the IBM Function

Registry for z/OS on page 854.v New dsname allocation text units for read-only access were added in

DALROAC specification - Key = '8030' on page 676 and DALROA2specification - Key = '8031' on page 676.

v New dynamic information retrieval text units for read-only access were added inReturn ROACCESS specification - Key = 'C030' on page 734 and ReturnROACCESS specification - Key = 'C031' on page 735.

v New dsname allocation text units for encryption key were added in Data setkey label specification - Key = '8032' on page 677

v New sentence was added for 10-S99DSABA in Flags (S99FLAG1) on page 558.v New information was added regarding MEMLIMIT in Chapter 15, Processor

storage management, on page 311.v New subpools 133 and 134 added to The subpool table on page 236.v New notes added to The subpool table on page 236 of 22, 23, and 24.v New Return SYSOUT program name - Key '0013' in Return SYSOUT program

name - Key = '0013' on page 723.v New chapter on Chapter 33, Using and registering functions with the IBM

Function Registry for z/OS, on page 853.

Changed

The following information has been changed:v When to avoid using dynamic allocation on page 530 was updated for clarity.v APAR OA50653 - Event code 33 has been updated in ENF event codes and

meanings on page 176.v Information changed about unused space for DALRLSE in Unused space

release (RLSE) specification - Key = '000D' on page 649v Changed the description for the Program mask on page 389 section.v The DDNAME parameter of the data-in-virtual (DIV) IDENTIFY service now

supports encrypted data sets. See The IDENTIFY service on page 282.

Copyright IBM Corp. 1988, 2017 xix

Deleted

The following information has been removed:v Information about interruption type 17 has been removed from Chapter 19,

Processing program interruptions (SPIE, ESPIE), on page 423.

Summary of changes for z/OS Version 2 Release 2 (V2R2), as updatedMarch, 2016

The following changes are made for z/OS Version 2 Release 2 (V2R2), as updatedMarch, 2016. In this revision, all technical changes for z/OS V2R2 are indicated bya vertical line to the left of the change.

Newv Information about insulated DDs has been added in Insulated DD attribute on

page 549 and new text unit key X'0079' in: Dynamic allocation facilities without JCL equivalents on page 535 Characteristics prohibited in your request on page 537 Interpreting error reason codes from DYNALLOC on page 601 Non-JCL dynamic allocation functions on page 691

- Insulated DD request - Key = '0079' on page 703 Dynamic unallocation text units on page 706

- Insulated DD request - Key = '0079' on page 710 Dynamic concatenation text units on page 711

- Insulated DD request - Key = '0079' on page 712 Dynamic deconcatenation text units on page 713

- Insulated DD request - Key = '0079' on page 713 Return dynamic allocation attribute specification - Key = '000C' on page 721

v Information about bypass security processing text unit key X'007A' has beenadded in: Non-JCL dynamic allocation functions on page 691

- Bypass security processing - Key = '007A' on page 704 Dynamic unallocation text units on page 706

- Bypass security processing - Key = '007A' on page 710v Information about function AXRWTOR for System REXX has been added in

Functions on page 828.

Summary of changes for z/OS Version 2 Release 2 (V2R2), as updatedDecember, 2015

The following changes are made for z/OS Version 2 Release 2 (V2R2), as updatedDecember, 2015. In this revision, all technical changes for z/OS V2R2 are indicatedby a vertical line to the left of the change.

Newv New text units related to IEFOPZ processing have been added in Non-JCL

dynamic allocation functions on page 691.

Changedv Using the services on page 68 is modified to add two callable services for

Pause_Multiple_Elements, IEAVPME2 and IEA4PME2.

xx z/OS MVS Authorized Assembler Services Guide

Summary of changes for z/OS Version 2 Release 2The following information is new, changed, or deleted in z/OS Version 2 Release 2(V2R2).

New

The following information has been added:v Monitoring dynamic exits processing on page 24v Monitoring fetch and unfetch processing on page 27

Changed

The following information has been changed:v Modified event code 78 of ENF event codes and meanings to reference JES

instead of JES2. See ENF event codes and meanings on page 176.

Deleted

The following information has been removed:v Removed (JES2 only) from DOOUTDB and DOOUTDC of OUTDISP of Table 96

on page 744.

z/OS Version 2 Release 1 summary of changesSee the Version 2 Release 1 (V2R1) versions of the following publications for allenhancements related to z/OS V2R1:v z/OS Migrationv z/OS Planning for Installationv z/OS Summary of Message and Interface Changesv z/OS Introduction and Release Guide

Summary of changes xxi

xxii z/OS MVS Authorized Assembler Services Guide

Chapter 1. Introduction

MVS controls the flow of work through the system so that all programs obtain afair share of the processing. To make efficient use of the system, you mustunderstand the services that the system provides and observe the programmingconventions for their use.

Most services described in this information can be used by authorized programsonly. An authorized program is a program that runs with APF authorization, orruns in supervisor state, or runs with a PSW key of 0-7.

Some of the services can be used by any program, including those that runwithout APF authorization, or in problem program state, or with a PSW key of 8-F.Unless your program is authorized, you should use these services only if you havethe approval of your installations management.

The services, which you invoke by issuing macros or callable services, aredescribed in the following information:

Subtask Creation and Control:Occasionally, you can have your program executed faster and moreefficiently by dividing parts of it into subtasks that compete with eachother and with other tasks for execution time. This topic includesinformation about task creation, using an internal START, andcommunication with a problem program.

Program Management:You can use the system to aid communication between segments of aprogram. This topic includes information about the residency andaddressing mode of a module, loading a module, synchronous exits,checkpoint/restart, and re-entrant modules.

Serialization:Portions of some tasks depend on the completion of events in other tasks,which requires planned task synchronization. Planning is also requiredwhen more than one program uses a serially reusable resource. Locking,the must-complete function, shared direct access storage devices, waitingfor an event to complete, and indicating event completion are discussed inthis topic. This topic also includes information about the global resourceserialization latch manager, which authorized programs can use to serializeresources within an address space or within a single MVS system.

Reporting System Characteristics:This topic describes collecting information about resources and theirrequestors, using the SRM reporting interface, and obtainingdispatchability data about address spaces.

Tracing Applications Using Component Trace:Component trace provides common services for defining and collectingdiagnostic information about components, subsystems, or applications.

Communication:This information discusses several different forms of communication:v Interprocessor communicationv Writing operator messages

Copyright IBM Corp. 1988, 2017 1

v Issuing operator commandsv Routing operator commands in a sysplex environmentv Extended MCS consoles.

Listening for System Events:The event notification facility (ENF) allows an authorized program to listenfor the occurrence of a specific system event. For example, a programcould listen for a software record being written to the logrec data set.When the system writes the record to the logrec data set, control passes toa specified listener user exit routine. For a list of the system events that anauthorized program can listen for, see ENF event codes and meanings onpage 176.

Using a Service Request Block (SRB):Asynchronous inter-address space communication is available through theuse of an SRB and its associated SRB routine. This topic describes how youuse the macros that initiate the running of an SRB routine and provide itsrecovery. It also describes how you can serialize the processing of an SRBroutine and how to transfer control from an SRB to a TCB.

Virtual Storage Management:Virtual storage allows you to write large programs without the need forcomplex overlay structures. This topic describes how to use the GETMAIN,FREEMAIN, and STORAGE macros to allocate and free virtual storage. Italso includes descriptions of the VSM functions, available through the useof the VSMLIST, VSMLOC, and VSMREGN macros.

Accessing the Scheduler Work Area (SWA):The SWA contains information about jobs that are currently in the system.This topic explains how to write a program that can access the informationthat the system stores in the SWA.

Virtual Lookaside Facility (VLF):VLF is intended for use by authorized subsystems or major applicationsthat perform repeated DASD operations on behalf of end users. VLF is aset of services that provide an alternate fast-path method of makingfrequently used, named data objects available to many users. This topicwill help you decide whether to use VLF and will help you plan your useof the VLF macros.

Using the Cross-System Coupling Facility (XCF):This topic, which contains information about the cross-system couplingfacility, now appears in z/OS MVS Programming: Sysplex Services Guide.

Data-In-Virtual:Data-in-virtual enables you to create, read, or update external storage datawithout the traditional GET and PUT macros. The data, which is notbroken up into individual records, appears in your virtual storage as astring of contiguous bytes. You can access the data by using anyinstruction that you normally use to access data in your virtual storage.This technique also provides better performance than the traditional accessmethods for many applications.

Sharing Application Data (Name/Token Callable Services):Name/token callable services allow a user to share data between twoprograms running under the same task, or between two or more tasks oraddress spaces. This topic includes descriptions of the levels of

2 z/OS MVS Authorized Assembler Services Guide

name/token pairs, ownership and deletion of the pairs, description of thelevels for the cross memory uses of the name/token services, and anexample of using the services.

Processor Storage Management:The system administers the use of processor storage (that is, central andexpanded storage) and directs the movement of virtual pages amongauxiliary, expanded, and central storage in page size blocks. The servicesprovided allow you to release virtual storage contents, load virtual storageareas into central storage, make virtual storage pages read-only ormodifiable, and page out virtual storage areas from central storage.

Sharing Data in Virtual Storage (IARVSERV Macro):This topic describes the IARVSERV macro, which provides services thatallow programs to share virtual storage in address spaces or data spaces.The topic also includes information about the IARR2V macro, whichconverts a central storage address to a virtual storage address.

The Nucleus:This topic includes descriptions of the functions available through the useof the DATOFF and NUCLKUP macros.

Providing Recovery:When your program encounters an error, the program might endabnormally unless you provide recovery. To recover from errors, you canwrite routines called recovery routines that get control when the erroroccurs. These routines can attempt to correct the error and allow yourprogram to resume normal processing. This topic explains recoveryconcepts and how to write recovery routines.

Processing Program Interruptions:The system offers many services to detect and process abnormal conditionsduring system processing. Some conditions encountered in a programcause program interruptions or program exceptions. This topic includeshow to specify user exit routines, using the SPIE or ESPIE macros, andfunction performed in user exit routines.

Dumping Virtual Storage (SDUMPX and SDUMP Macros):This topic describes how to obtain SVC dumps using the SDUMPX andSDUMP macros. It includes deciding when to request a dump, using theSYS1.DUMPnn data set, defining the contents of the dump, andsuppressing duplicate dumps.

Protecting the System:This topic includes the maintenance of system integrity, the use of theauthorized programming facility, the use of the resource access controlfacility, changing system status, and protecting low storage.

Exit Routines:This topic contains information about asynchronous exit routines, timerdisabled interrupt exit routines, and dynamic exits services. Dynamic exitsservices allow you to define exits and control their use within a programusing the CSVDYNEX macro.

User-Written SVC Routines:

This topic contains information needed to write SVC routines. It includesthe characteristics of the SVC routines, program conventions for SVCroutines, and ways to insert SVC routines into the control program.

Chapter 1. Introduction 3

Accessing Unit Control Blocks (UCBs):This topic describes how to obtain and use information about unit controlblocks (UCBs) and about configuration changes in the system.

Dynamic Allocation:This topic describes the functions provided by dynamic allocation. Itdescribes installation options you can use to control the processing ofdynamic allocation.

Requesting Dynamic Allocation Functions:The topic includes a description of the parameter list used to requestdynamic allocation functions, the return codes, error codes, andinformation codes.

Dynamic Output:This topic explains how to use the JES2 and JES3 4.2.1 or later dynamicoutput facility. This facility enables a program to dynamically describe asystem output data set's processing options and to dynamically allocatethat data set.

Scheduler JCL Facility (SJF):This topic describes how to use the Scheduler JCL Facility to manipulatetext unit data that represents processing options for system output (sysout)data sets.

Processing User Trace Entries in the System Trace Table:This topic describes formatting a USRn trace table entry, interpreting returncodes from the formatter, and handling errors.

Using the Unit Verification Service:This topic describes using the unit verification service to obtaininformation from the eligible device table.

Note: IMPORTANT -------- READ THIS

Keep in mind how the information uses the following terms:v The term registers means general purpose registers. If general purpose registers

might be confused with other kinds of registers (such as access registers), theinformation uses the longer term general purpose registers.

v Unless otherwise specified, the address space control (ASC) mode of a programis primary mode.

v Many MVS macro services support callers in both primary ASC and accessregister (AR) ASC mode. Some of these services provide two macros thatperform the same function; one macro can generate code and addressesappropriate for callers in primary mode, and the other macro can generate codeand addresses appropriate for callers in AR mode.The names of the two macros are the same, except the macro that supports theAR mode caller ends with an X. These pairs of macros are called X-macros.SNAPX is an example of an X-macro. SNAP is for primary mode callers andSNAPX is for primary or AR mode callers. As you use the X-macros, keep inmind the following information: A parameter or function might apply only to the X-macro. (For example, the

DSPSTOR parameter is valid only on SNAPX, not SNAP.) Most of the parameters are available on both the X-macro and the

non-X-macro.

4 z/OS MVS Authorized Assembler Services Guide

Macro descriptions in the z/OS MVS Programming: Assembler Services ReferenceABE-HSP and the z/OS MVS Programming: Assembler Services Reference IAR-XCThelp you use the X-macros correctly.

Chapter 1. Introduction 5

6 z/OS MVS Authorized Assembler Services Guide

Chapter 2. Subtask creation and control

The control program creates a task when it initiates execution of the job step; thistask is the job step task. You can create additional tasks in your program. If you donot, however, the job step task is the only task in a job being executed. Thebenefits of a multiprogramming environment are still available even with only onetask in the job step; work is still being performed for other jobs when your task iswaiting for an event, such as an input operation, to occur.

The advantage in creating additional tasks within the job step is that more of yourtasks are competing for control than the single job step task. When a waitcondition occurs in one of your tasks, it is not necessarily a task from some otherjob that gets control; it might be one of your tasks, a portion of your job.

The general rule is that you should choose parallel execution of a job step (that is,more than one task in a job step) only when a significant amount of overlapbetween two or more tasks can be achieved. Both the amount of time the controlprogram takes to establish and control additional tasks and your increased effort tocoordinate the tasks and provide for communications between them must be takeninto account.

You can also use tasks in enclaves. An enclave is a transaction that can spanmultiple tasks and/or SRBs in one or more address spaces and is managed andreported as a unit. A task can join or leave an enclave. While a task is joined to anenclave, any subtasks created also belong to the enclave. For more informationabout using tasks in enclaves, see z/OS MVS Programming: Workload ManagementServices.

Most of the information concerning subtask creation and control appears in z/OSMVS Programming: Assembler Services Guide, z/OS MVS Programming: AssemblerServices Reference ABE-HSP and z/OS MVS Programming: Assembler Services ReferenceIAR-XCT. This topic provides additional information about:v Creating a task (ATTACH or ATTACHX macro)v Ensuring that a process completes (STATUS macro)v Communicating with a problem program (EXTRACT and QEDIT macros)

Creating a new task (ATTACH or ATTACHX macro)To create a new task, use the ATTACH or ATTACHX macro. Programs running inprimary ASC mode or programs running in access register ASC mode can useeither ATTACH or ATTACHX. IBM recommends, however, that programs runningin access register ASC mode use ATTACHX. The ATTACH and ATTACHX servicesfor programs that run in problem program state are described in the z/OS MVSProgramming: Assembler Services Guide and the z/OS MVS Programming: AssemblerServices Reference ABE-HSP.

When you attach a subtask, you have the option of setting its dispatchability. TheDISP parameter of the ATTACH and ATTACHX macros enables you to set theattached subtask to be dispatchable (DISP=YES) or non-dispatchable (DISP=NO).You can reset tasks that you attached with the DISP=NO parameter to dispatchableby issuing ATTACH or ATTACHX again with the DISP=RESET parameter.

Copyright IBM Corp. 1988, 2017 7

Ensuring that a process completes (STATUS macro)Complex programs, such as database managers, often include processes that usecritical resources and that must complete quickly. While it is possible to preventdelays by running the program disabled, disabled programs have certainrestrictions, such as not being able to perform I/O and not being able to referencepageable storage. If your program cannot run with the restrictions of a disabledprogram, and it cannot tolerate a process delay, issue the STATUS macro with theSET,MC,PROCESS parameter, taking into consideration the restrictions discussedlater in this topic. Issuing STATUS SET,MC,PROCESS puts the program inprocess-must-complete mode.

Issuing STATUS SET,MC,PROCESS at the start of a process postpones delays fromcertain events. The macro allows a process using critical resources to complete butallows all other tasks in the address space to continue running. Examples of eventsthat cause delays that the STATUS macro can postpone are:v Asynchronous exitsv Status stops (by issuing the STATUS macro with the STOP option)v Timer exitsv Dumpingv Swappingv Attention exits

Process-must-complete mode also prevents the CANCEL command from stoppinga program that is already running. Issuing STATUS SET,MC,PROCESS does not,however, postpone external interrupts or interrupts from I/O.

There are other restrictions to consider when deciding whether to place a processin process-must-complete mode. While in process-must-complete mode, a taskcannot:v Issue STATUS STOP,SRB or STATUS START,SRB.v Request the LOCAL lock unconditionallyv Issue an SVC or invoke services that issue SVCsv Issue the WAIT macro or invoke services that issue WAITs.

Remaining in process-must-complete mode for an extended period of time willdegrade the performance of other programs waiting to use global resources thatthe program in this mode holds. Ensure that the process that issues STATUSSET,MC,PROCESS really must complete without delay, and that you endprocess-must-complete mode as soon as the program releases the resource.

To end process-must-compete mode, issue the STATUS macro with theRESET,MC,PROCESS parameter.

STATUS also stops started subtasks and restarts them as described in z/OS MVSProgramming: Assembler Services Guide.

Communicating with a program (EXTRACT, QEDIT)The operator can pass information to the started program by issuing a STOP or aMODIFY command. In order to accept these commands, the program must be setup in the following manner.

8 z/OS MVS Authorized Assembler Services Guide

The program must issue the EXTRACT macro to obtain a pointer to thecommunications ECB and a pointer to the first command input buffer (CIB) on theCIB chain for the task. The ECB is posted whenever a STOP or a MODIFYcommand is issued. The EXTRACT macro is written as follows, and returns whatis indicated in Figure 1.EXTRACT answer area,FIELDS=COMM

The CIB contains the information specified on the STOP, START, or MODIFYcommand. If the job was started from the console, the EXTRACT macro will pointto the START CIB. If the job was not started from the console, the address of thefirst CIB will be zero. For more information on the contents of the command inputbuffer (CIB) and mapping macro IEZCIB, see z/OS MVS Data Areas in the z/OSInternet library (www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibrary).

If the address of the START CIB is present, use the QEDIT macro to free this CIBafter any parameters passed in the START command have been examined. TheQEDIT macro is written as follows:QEDIT ORIGIN=address of pointer to CIB,BLOCK=address of CIB

Note:

1. The address of the pointer to the CIB is the contents of the answer area plus 4bytes, as shown in Figure 1.

2. The address of the CIB must be the exact address returned by EXTRACT, notan address generated from copying the CIB to another location.

The CIB counter should then be set to allow CIBs to be chained and MODIFYcommands to be accepted for the job. This is also accomplished by using theQEDIT macro:QEDIT ORIGIN=address of pointer to CIB,CIBCTR=n

The value of n is any integer value from 0 to 255. If n is set to zero, no MODIFYcommands are accepted for the job. However, STOP commands are accepted forthe job regardless of the value set for CIBCTR. After a STOP command is issued,the system sets the value of CIBCTR to zero to prevent more modify CIBs frombeing chained. To continue processing modifys after a STOP command, you mustuse the QEDIT macro to set the CIBCTR to non-zero.

Note: When using the address or addresses returned from the EXTRACT macro asinput to the QEDIT macro, you must establish addressability through the COMdata area (mapped by IEZCOM), based on the address returned by the EXTRACT.For a description of the COM data area, see z/OS MVS Data Areas in the z/OSInternet library (www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibrary).

0

4

8

ECB address

CIB address

program token

Address of the

communication area

Answer area

Figure 1. EXTRACT ECB Address, CIB Address, and Program Token

Chapter 2. Subtask creation and control 9

http://www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibraryhttp://www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibraryhttp://www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibraryhttp://www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibraryhttp://www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibraryhttp://www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibrary

For the duration of the job, your program can wait on or check thecommunications ECB at any time to see if a command has been entered for theprogram. Check the verb code in the CIB to determine whether a STOP or aMODIFY command has been entered. After processing the data in the CIB, issue aQEDIT macro to free the CIB.

The communications ECB is cleared by QEDIT when no more CIBs remain. Careshould be taken if multiple subtasks are examining these fields. Any CIBs not freedby the task are unchained by the system when the task is terminated. The areaaddressed by the pointer obtained by the EXTRACT macro, the communicationsECB, and all CIBs are in protected storage and may not be altered.

The portion of the program follows the procedure outlined in the precedingparagraphs. It shows how you can code the EXTRACT and QEDIT macros toaccept MODIFY and STOP commands. The full example would use reentrant code.R1 EQU 1R7 EQU 7R9 EQU 9R10 EQU 10R14 EQU 14

USING *,R10 MODULE ADDRESSABILITYLA R9,COMADDR GET COMMUNICATIONS AREA

* ADDRESS AT COMADDR*------------------------------------------------------------------** OBTAIN ADDRESS OF THE CIB **------------------------------------------------------------------*

EXTRACT (R9),FIELDS=COMM,MF=(E,EXTRACT)* EXTRACT THE COMMUNICATIONS AREA

L R9,COMADDR GET ADDRESS OF THE AREAUSING COM,R9 USE R9 AS BASE ADDRESS OF COMM AREAICM R7,15,COMCIBPT GET CIB ADDRESS FROM COM AREABZ NOCIB NO CIB, TASK WAS NOT STARTEDBAL R14,DOCIB PROCESS THE CIB

NOCIB DS 0HQEDIT ORIGIN=COMCIBPT,CIBCTR=5 SET MODIFY LIMIT TO 5L R1,COMECBPT GET ADDRESS OF THE COMMUNICATION ECBO R1,HIBITON SET HIGH BIT - LAST ECB IN LISTST R1,MODECB PUT ADDR OF MODIFY ECB IN LIST

***WAIT DS 0H

WAIT ECBLIST=ECBS WAIT FOR A MODIFY/STOP** WHEN POSTED HERE, A MODIFY OR STOP HAS BEEN ISSUED

ICM R7,15,COMCIBPT GET CIB ADDRESS FROM COM AREAUSING CIB,R7 BASE CIB MAPPINGCLI CIBVERB,CIBMODFY WAS IT A MODIFY?BNE NOTMDFY NO, GO FREE CIBBAL R14,DOCIB IT WAS A MODIFY, GO PROCESS COMMAND

****------------------------------------------------------------------ ** FREE THE CIB **------------------------------------------------------------------ *NOTMDFY DS 0H

BAL R14,DELCIB FREE CIBCLI CIBVERB,CIBSTOP WAS IT A STOP?BE EXITRTN BRANCH TO ROUTINE HANDLING ERRORSB WAIT WAIT FOR ANOTHER MODIFY

* .* .DELCIB DS 0H

10 z/OS MVS Authorized Assembler Services Guide

* USE QEDIT TO FREE THE CIB* QEDIT WILL ALSO CLEAR THE ECB*

QEDIT ORIGIN=COMCIBPT,BLOCK=(R7) FREE THE CIBBR R14

DOCIB DS 0H*-------------------------------------------------------------------** YOUR ROUTINE TO HANDLE CIB PROCESSING WOULD GO HERE. **-------------------------------------------------------------------*****-------------------------------------------------------------------** CONSTANTS **-------------------------------------------------------------------*

DS 0F FULLWORD ALIGNMENTHIBITON DC X80000000 USED TO TURN HIGH ORDER BIT ON*-------------------------------------------------------------------** FIELDS REQUIRED IN DYNAMIC STORAGE **-------------------------------------------------------------------*ECBS DS 0CL4 ECB LIST FOR WAITMODECB DS A ADDR(MODIFY/STOP ECB)COMADDR DS F ADDR(COMAREA) FROM EXTRACTSV DS 18F SAVE AREAEXTRACT EXTRACT MF=L EXTRACT PARAMETER LIST*-------------------------------------------------------------------** REQUIRED DSECTs **-------------------------------------------------------------------*COM DSECT

IEZCOM , COM AREACIB DSECT

IEZCIB , CIBEND

Providing an EXTRACT answer areaThe EXTRACT macro provides TCB information for either the active task or one ofits subtasks. Figure 2 on page 12 shows the order in which the information fromthe requested fields is returned. If the information from a field is not requested, theassociated fullword is omitted. See z/OS MVS Programming: Authorized AssemblerServices Reference EDT-IXG for a description of the EXTRACT answer area fields.

Chapter 2. Subtask creation and control 11

You must provide an answer area consisting of contiguous fullwords, one for eachof the codes specified in the FIELDS parameter, with the exception of ALL. If ALLis specified, you must provide a 7-word area to accommodate the GRS, FRS,reserved, AETX, PRI, CMC, and TIOT fields. The ALL code does not include theCOMM, TSO, PSB, TJID, and ASID fields.

Most of the addresses are returned in the low-order three bytes of the fullword,and the high-order byte is set to zero; the fields for AETX, TIOT, and PSB couldhave a nonzero first byte. Fields for which no addresses or values are specified inthe task control block are set to zero.

For example, if you code FIELDS=(TIOT,GRS,PRI,TSO,PSB,TJID) you must providea 6-fullword answer area, and the extracted information appears in the samerelative order as shown in Figure 2. (That is, GRS is returned in the first word, PRIin the second word, TIOT in the third word, and so forth.)

If FIELDS=(ALL,TSO,PSB,COMM,ASID) is coded, you need an 11-fullword answerarea, and the extracted information appears in the answer area in the relative ordershown above.

00 00

00

00

00

00

Value

Address

Address

Address

Address

Address

Value

Completion Code

Address

Address

Value

Value

1 Byte 1 Byte 1 Byte 1 Byte

00

00

00

00

00

00

00

00

00ASID

TJID

PSB

COMM

TSO

TIO