z/OSVersion 2 Release 3

MVS Programming: AuthorizedAssembler Services Guide

IBM

SA23-1371-30

Note

Before using this information and the product it supports, read the information in “Notices” on page795.

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

Last updated: 2019-05-29© Copyright International Business Machines Corporation 1988, 2019.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

Figures................................................................................................................ xv

Tables.................................................................................................................xxi

About this information......................................................................................xxviiWho should use this information............................................................................................................xxviiHow to use this information................................................................................................................... xxviiz/OS information.................................................................................................................................... xxviii

How to send your comments to IBM................................................................... xxixIf you have a technical problem.............................................................................................................. xxix

Summary of changes......................................................................................... xxxiSummary of changes for z/OS Version 2 Release 3................................................................................xxxiSummary of changes for z/OS Version 2 Release 2 (V2R2), as updated March, 2016........................ xxxiiSummary of changes for z/OS Version 2 Release 2 (V2R2), as updated December, 2015..................xxxiiSummary of changes for z/OS Version 2 Release 2.............................................................................. xxxiiiz/OS Version 2 Release 1 summary of changes....................................................................................xxxiii

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

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

Providing an EXTRACT answer area.......................................................................................................8

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

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

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

Changing the current LNKLST set........................................................................................................ 15Monitoring dynamic LPA processing......................................................................................................... 16

Listing contents of dynamic LPA with CSVDLPAU............................................................................... 19Monitoring dynamic exits processing........................................................................................................21Monitoring fetch and unfetch processing..................................................................................................24

Chapter 4. Serialization....................................................................................... 29Choosing a serialization service................................................................................................................ 29Providing ENQ resource information on DISPLAY GRS command........................................................... 34Locking....................................................................................................................................................... 34

Categories of locks............................................................................................................................... 35

iii

Types of locks....................................................................................................................................... 35Locking hierarchy................................................................................................................................. 36CML lock considerations...................................................................................................................... 36Obtaining, releasing, and testing locks (SETLOCK)............................................................................. 37Suspend lock instrumentation data ....................................................................................................37

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

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

Serializing parallel tasks (WAIT and POST).............................................................................................. 46Asynchronous cross memory POST.....................................................................................................47Synchronous cross memory post.........................................................................................................48Bypassing the POST routine.................................................................................................................48Waiting for event completion (EVENTS).............................................................................................. 48

Writing POST exit routines.........................................................................................................................49Identifying and deleting exit routines..................................................................................................49Initializing extended ECBs and ECB extensions..................................................................................49POST interface with exit routines........................................................................................................ 50Re-entry to POST from a POST exit..................................................................................................... 51

Branch entry to the POST service routine................................................................................................. 51Branch entry to the WAIT service routine.................................................................................................53Serializing RB processing...........................................................................................................................54

Suspending an RB until an event completes (SUSPEND)....................................................................54Using the CALLDISP macro.................................................................................................................. 56Resuming execution of a suspended RB............................................................................................. 56

Synchronizing unit of work (tasks or SRBs)...............................................................................................57Pause elements and pause element tokens........................................................................................58Using the services................................................................................................................................ 60PE ownership and cleanup...................................................................................................................63

Global resource serialization latch manager.............................................................................................63Overview............................................................................................................................................... 64How to use the callable services......................................................................................................... 65

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

Guide to the latch manager callable services........................................................................................... 69Creating a latch set (ISGLCRT and ISGLCR64 services)..................................................................... 70Specifying a latch's identity or usage.................................................................................................. 71Obtaining a latch (ISGLOBT and ISGLOB64 services).........................................................................72Releasing a latch (ISGLREL and ISGRE64 services)........................................................................... 73Purging one or more latches (ISGLPRG and ISGLPR64 services)...................................................... 74Purging one or more latches in a group of latch sets for a group of requestors (ISGLPBA and

ISGLPB64 services)........................................................................................................................ 74

Chapter 5. Reporting system characteristics.........................................................77Collecting information about resources and their requestors (ISGQUERY and GQSCAN macros)......... 77

How GQSCAN returns resource information....................................................................................... 78How global resource serialization determines the scope of an ENQ or RESERVE request................82

Using the SRM reporting interface to measure subsystem activity..........................................................82Obtaining dispatchability data about address spaces (IEAMRMF3 macro).............................................83

Chapter 6. Tracing applications using component trace.........................................85Planning an application trace.................................................................................................................... 86

iv

Trace activities......................................................................................................................................87Executable macros for component tracing..........................................................................................88Operator commands for component tracing....................................................................................... 88IPCS subcommands for component tracing........................................................................................89Exit routines for component tracing.................................................................................................... 89Data areas and mapping macros for component tracing.................................................................... 89Parmlib members for component tracing............................................................................................90When to trace....................................................................................................................................... 90Where and what to trace...................................................................................................................... 90Creating trace buffers...........................................................................................................................91Using multiple traces........................................................................................................................... 93Setting up user-defined options.......................................................................................................... 93Starting, stopping and changing the trace...........................................................................................94Using parmlib members.......................................................................................................................94Externalizing trace data in a dump...................................................................................................... 95Externalizing trace data through the external writer...........................................................................96

Coding macros for application traces........................................................................................................98Using the CTRACE macro to define the application to component trace........................................... 99Using CTRACECS to manage trace buffer status...............................................................................104Deleting the application from component trace............................................................................... 106

Coding a start/stop exit routine...............................................................................................................107Exit routine environment................................................................................................................... 107Exit routine processing...................................................................................................................... 107Programming considerations.............................................................................................................109Start/stop exit routine communications............................................................................................111Entry specifications............................................................................................................................112Return specifications......................................................................................................................... 113

Coding a display trace exit routine..........................................................................................................114Exit routine environment................................................................................................................... 115Exit routine processing...................................................................................................................... 115Programming considerations.............................................................................................................116Exit routine communications............................................................................................................. 116Entry specifications............................................................................................................................116Return code specifications................................................................................................................ 117

Creating trace entries.............................................................................................................................. 117Understanding the fields in a CTE......................................................................................................118Organizing variable data in CTEs....................................................................................................... 119

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

Routing the Message..........................................................................................................................121Altering Message Text........................................................................................................................ 122Writing a Multiple-Line Message........................................................................................................122Embedding Label Lines in a Multiple-Line Message......................................................................... 123Issuing a Message and Loading a Wait State (WTO and LOADWAIT Macros).................................. 123Using the Wait State Macro (LOADWAIT).......................................................................................... 123Non-restartable and Restartable Wait States................................................................................... 123Invoking the LOADWAIT Macro......................................................................................................... 124Deleting Messages Already Written...................................................................................................125Writing to the System Log.................................................................................................................. 126

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

Rules for a command response WTO................................................................................................ 128Old code conversion...........................................................................................................................128Where to get the information.............................................................................................................129

v

Assembler example with CIB control block...................................................................................... 129Assembler example with CMDX control block, multi-line WTO........................................................130

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

Assigning a prefix............................................................................................................................... 131Persistence of the prefix.................................................................................................................... 132

What is an extended MCS console?........................................................................................................ 133Activating an extended MCS console................................................................................................ 134Receiving messages and command responses, and issuing commands......................................... 139Deactivating extended MCS consoles............................................................................................... 142Removing extended MCS consoles....................................................................................................143Example of managing an extended MCS console session................................................................ 143

Chapter 8. Listening for system events............................................................... 147Establishing a listen request................................................................................................................... 147

Qualifying events................................................................................................................................147nn filtering events...............................................................................................................................151

Coding the listener user exit routine....................................................................................................... 151Non-SRBEXIT routine........................................................................................................................ 151SRBEXIT routine.................................................................................................................................153

Passing parameters to a listener user exit routine................................................................................. 154Ending the listener user exit routine....................................................................................................... 155ENF event codes and meanings.............................................................................................................. 155ENF sample programs............................................................................................................................. 170

SMFLSTEN - Sample ENF listener......................................................................................................170Listening for global resource serialization-related system events........................................................ 175

Monitoring contention changes......................................................................................................... 175

Chapter 9. Using a service request block (SRB)................................................... 179What is an SRB?....................................................................................................................................... 179Why would you use an SRB?................................................................................................................... 179Scheduling and managing SRBs..............................................................................................................180Specifying the addressing environment of the SRB routine...................................................................181

Using the ENV parameter on IEAMSCHD.......................................................................................... 181Using the MODE parameter on SCHEDULE....................................................................................... 181

Characteristics and restrictions of SRB routines.................................................................................... 182Implications of running in SRB mode................................................................................................ 182Environment of the SRB routine at entry...........................................................................................183

Scheduling an SRB (IEAMSCHD or SCHEDULE macro).......................................................................... 183Scheduling an SRB using IEAMSCHD................................................................................................ 184Scheduling an SRB using SCHEDULE.................................................................................................185

Purging an SRB (PURGEDQ macro)......................................................................................................... 186Identifying the SRB to be purged.......................................................................................................187The resource manager termination routine (RMTR)......................................................................... 188Scenario of scheduling and purging an SRB......................................................................................188

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

Terminating a preemptable SRB............................................................................................................. 194Calling an SRB to run synchronously.......................................................................................................194Transferring control for SRB processing (TCTL macro).......................................................................... 194

Chapter 10. Virtual storage management............................................................195Allocating and freeing virtual storage (GETMAIN, FREEMAIN and STORAGE macros).........................195

Comparison of GETMAIN/FREEMAIN macros with the STORAGE macro........................................ 196

vi

Specifying branch entry to GETMAIN and FREEMAIN services........................................................196Obtaining storage in another address space.....................................................................................197Obtaining and using disabled reference (DREF) storage.................................................................. 197

Using cell pool services (CPOOL macro)................................................................................................. 197Selecting the right subpool for your virtual storage request..................................................................198

Program authorization....................................................................................................................... 199Tracking virtual storage allocation (CPOOL BUILD, GETMAIN, and STORAGE OBTAIN macros)......... 212Obtaining information about the allocation of virtual storage (VSMLIST)............................................. 212

Using the VSMLIST work area............................................................................................................213Using IARQD — The page status interface routine................................................................................. 221

Decide which entry point you want to use........................................................................................ 222Obtain storage and load register 1.................................................................................................... 222Use NUCLKUP to find the address of the entry point you want to use............................................. 223Invoke the entry point........................................................................................................................224

Chapter 11. Accessing the scheduler work area.................................................. 225Using the IEFQMREQ and the SWAREQ macros.....................................................................................225

The SWAREQ macro...........................................................................................................................226How to invoke SWAREQ..................................................................................................................... 226The IEFQMREQ macro....................................................................................................................... 228

Chapter 12. The virtual lookaside facility (VLF)................................................... 231Deciding when to use VLF....................................................................................................................... 231Planning to use VLF................................................................................................................................. 232

Data objects and classes................................................................................................................... 233Data integrity......................................................................................................................................235Recovery.............................................................................................................................................235

Using the VLF macros.............................................................................................................................. 236Defining a class of VLF objects.......................................................................................................... 237Identifying an end user to VLF...........................................................................................................238Retrieving a VLF object.......................................................................................................................239Creating a VLF object......................................................................................................................... 239Notifying VLF of a change...................................................................................................................241Removing a VLF end user...................................................................................................................241Purging a VLF class.............................................................................................................................242Modifying VLF..................................................................................................................................... 242

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

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

Using the services of data-in-virtual....................................................................................................... 245Identify............................................................................................................................................... 245Access.................................................................................................................................................245Map..................................................................................................................................................... 245Save, Savelist, and Reset................................................................................................................... 246Unmap................................................................................................................................................ 247Unaccess............................................................................................................................................ 247Unidentify........................................................................................................................................... 247

The IDENTIFY service............................................................................................................................. 247The ACCESS service.................................................................................................................................248The MAP service...................................................................................................................................... 250The SAVE service..................................................................................................................................... 254The SAVELIST service..............................................................................................................................256The RESET service................................................................................................................................... 256

Effect of RETAIN mode on RESET......................................................................................................256The UNACCESS and UNIDENTIFY services............................................................................................ 258

vii

Sharing data in an object......................................................................................................................... 258DIV macro programming examples........................................................................................................ 259

Executing an application....................................................................................................................259Processing a data-in-virtual object....................................................................................................260

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

Determining what your program can do with name/token pairs...................................................... 265Checking authorization when retrieving a token.................................................................................... 266Deciding what name/token level you need.............................................................................................266

Primary-level name/token pair.......................................................................................................... 267System-level name/token pair...........................................................................................................268

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

Chapter 15. Processor storage management.......................................................273Fixing/freeing virtual storage contents................................................................................................... 274Protecting a range of virtual storage pages............................................................................................ 275PGFIX/PGFREE completion considerations............................................................................................275Input to page services............................................................................................................................. 276

Virtual subarea list (VSL)....................................................................................................................276Page service list (PSL)........................................................................................................................ 276Short page service list (SSL).............................................................................................................. 276

Branch entry to page services.................................................................................................................277Cross memory mode.......................................................................................................................... 277Non-cross memory mode.................................................................................................................. 278

Chapter 16. Sharing data in virtual storage (IARVSERV macro)............................281Understanding the concepts of sharing data with IARVSERV................................................................ 281Storage you can use with IARVSERV.......................................................................................................282Obtaining storage for the source and target........................................................................................... 283Defining storage for sharing data and access......................................................................................... 283Changing storage access......................................................................................................................... 284How to share and unshare data.............................................................................................................. 285Accessing data in a sharing group...........................................................................................................286Example of sharing storage with IARVSERV........................................................................................... 286Use with data-in-virtual (DIV macro)...................................................................................................... 287Use with page services (PGSER macro).................................................................................................. 288Diagnosing problems with shared data...................................................................................................288Converting a central to virtual storage address (IARR2V macro).......................................................... 288

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

Using system provided DAT-OFF routines (DATOFF)........................................................................ 292Writing user DAT-OFF routines.......................................................................................................... 294Placing user DAT-OFF routines in the DAT-OFF nucleus...................................................................294

Obtaining information about CSECTs in the DAT-ON nucleus (NUCLKUP)............................................ 295Customizing the nucleus region.............................................................................................................. 296

The NMLDEF macro............................................................................................................................296Removing existing routines from IEANUC0x.....................................................................................297

Chapter 18. Providing recovery.......................................................................... 299Understanding general recovery concepts............................................................................................. 300

Deciding whether to provide recovery...............................................................................................300Understanding errors in MVS............................................................................................................. 302Understanding recovery routine states............................................................................................. 302Understanding the various routines in a recovery environment.......................................................303

viii

Choosing the appropriate recovery routine.......................................................................................304Understanding recovery routine options...........................................................................................307Understanding how routines in a recovery environment interact.................................................... 307

Writing recovery routines........................................................................................................................ 309Understanding what recovery routines do........................................................................................ 310Understanding the means of communication................................................................................... 316Special considerations for ESTAE-type recovery routines................................................................325Special considerations for FRRs........................................................................................................ 330

Understanding the recovery environment.............................................................................................. 331Register contents............................................................................................................................... 332Other environmental factors in recovery...........................................................................................340

Understanding recovery through a coded example................................................................................354Understanding advanced recovery topics...............................................................................................356

Providing recovery with minimal processor overhead (FESTAE macro)...........................................356Invoking RTM......................................................................................................................................357Providing multiple recovery routines.................................................................................................359Providing recovery for recovery routines...........................................................................................364Providing recovery for multitasking programs.................................................................................. 365Using resource managers.................................................................................................................. 365

Using STAE/STAI routines....................................................................................................................... 370

Chapter 19. Processing program interruptions (SPIE, ESPIE).............................. 375Interruption types....................................................................................................................................376

Chapter 20. Dumping virtual storage (SDUMPX, SDUMP, and IEATDUMP macros).377SVC dumps...............................................................................................................................................377

Deciding when to request an SVC dump........................................................................................... 378Understanding the type of SVC dump that MVS produces................................................................378Coding parameters that produce a synchronous dump....................................................................379Designing a program to handle a synchronous dump.......................................................................379Coding parameters that produce a scheduled dump........................................................................379Designing a program to handle a scheduled dump...........................................................................380Synchronizing your program through an ECB or SRB........................................................................380Designing your program to run asynchronously with dump processing...........................................380Identifying the data set to contain the dump....................................................................................381Defining the contents of the dump.................................................................................................... 381Identifying the address spaces or data spaces to be dumped.........................................................381Customizing the contents of the SVC dump...................................................................................... 382Requesting the summary dump.........................................................................................................382Suppressing SVC dumps that duplicate previous SVC dumps..........................................................383Providing symptom information through the SDUMPX macro..........................................................383Requesting dumps on other systems in a sysplex............................................................................ 383Using dynamic exits to control dumps in a sysplex.......................................................................... 384IEASDUMP.QUERY dynamic exit........................................................................................................384IEASDUMP.GLOBAL and IEASDUMP.LOCAL dynamic exits...............................................................388IEASDUMP.SERVER dynamic exit...................................................................................................... 391

Transaction dumps.................................................................................................................................. 394Deciding when to request a transaction dump................................................................................. 394Understanding the type of transaction dump that MVS produces................................................... 395Identifying the data set to contain the dump....................................................................................395Defining the contents of the dump.................................................................................................... 395Customizing the contents of the transaction dump.......................................................................... 395Requesting the summary dump.........................................................................................................396Suppressing transaction dumps that duplicate previous transaction dumps..................................396Providing symptom information through the IEATDUMP macro...................................................... 396Requesting dumps of other systems................................................................................................. 396

ix

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

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

Authorized programs............................................................................................................................... 402Using APF to restrict access to system functions...................................................................................403

Guidelines for using APF....................................................................................................................404APF-authorized libraries.................................................................................................................... 404APF-authorized library list................................................................................................................. 405Requesting APF list services (CSVAPF macro).................................................................................. 405Restricting the use of SVC routines................................................................................................... 405Restricting load module access.........................................................................................................406Assigning APF authorization to a load module..................................................................................406Overriding an authorization code - SETCODE statement..................................................................407Authorization results under various conditions................................................................................ 407

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

MVS router..........................................................................................................................................408Interface to the MVS router (RACROUTE)......................................................................................... 409SAF interface to an external security product...................................................................................410

Using the command authorization service............................................................................................. 412Command resource names................................................................................................................413

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

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

Using the SCHEDIRB macro to initialize and schedule an IRB.........................................................417Using the SCHEDIRB macro to schedule an IRB...............................................................................418Using the CIRB macro to initialize an IRB......................................................................................... 418Using the SCHEDXIT macro to schedule an IRB............................................................................... 420System processing to run an asynchronous exit...............................................................................421

Establishing a timer disabled interrupt exit............................................................................................422DIE characteristics............................................................................................................................. 423Timer queue element control............................................................................................................ 425

Using dynamic exits services.................................................................................................................. 426CSVDYNEX terminology..................................................................................................................... 427Defining an exit...................................................................................................................................429Calling an exit routine or routines......................................................................................................430Associating an exit routine with an exit.............................................................................................434

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

Type 6 SVC routines........................................................................................................................... 437Non-preemptable SVC routines.........................................................................................................438Programming conventions for SVC routines......................................................................................438

Inserting SVC routines into the control program....................................................................................443Standard SVC routines....................................................................................................................... 443Extended SVC routines.......................................................................................................................445

Subsystem SVC screening....................................................................................................................... 445

Chapter 24. Accessing unit control blocks (UCBs)............................................... 449Scanning for UCBs................................................................................................................................... 449Obtaining UCB addresses........................................................................................................................449

x

UCB Common Segment......................................................................................................................449UCB Common Extension.................................................................................................................... 450UCB Prefix Extension......................................................................................................................... 450UCB Prefix Area.................................................................................................................................. 450UCB details......................................................................................................................................... 450

Ensuring that UCBs are not deleted........................................................................................................ 452Pinning and unpinning UCBs..............................................................................................................452When pinning is required................................................................................................................... 453When pinning is not required.............................................................................................................454

Requesting notification of I/O configuration changes............................................................................ 454Using the CONFCHG macro................................................................................................................455Coding a configuration change user exit routine...............................................................................455Coded example: CONFCHG macro invocation of configuration change user exit............................ 457

Detecting I/O configuration changes...................................................................................................... 459Retrieving the current MIH time interval................................................................................................ 460Retrieving information about I/O hardware on an I/O path................................................................... 461

Length of the CDR area...................................................................................................................... 461How IOSCDR retrieves the CDR.........................................................................................................461Time that IOSCDR performs I/O........................................................................................................462

Validating I/O paths.................................................................................................................................462Obtaining device information for an allocation request......................................................................... 462Configuring a channel path online or offline........................................................................................... 462Obtaining UCB information (general methods).......................................................................................463

Obtaining UCB addresses for a specified device number.................................................................463Scanning UCBs................................................................................................................................... 463Examples: Using the UCB macros..................................................................................................... 464Determining if the UCB macros (general methods) are available.....................................................465

Obtaining UCB information (limited method)......................................................................................... 465The UCB scan service.........................................................................................................................465Invoking the UCB scan service.......................................................................................................... 466Obtaining the subchannel number for a unit control block (UCB)....................................................469

Accessing above 16-megabyte UCBs..................................................................................................... 469

Chapter 25. Dynamic allocation..........................................................................471An allocation overview.............................................................................................................................471

Choosing the type of allocation for your program.............................................................................471When to avoid using dynamic allocation........................................................................................... 472Programming considerations for using the DYNALLOC macro......................................................... 472Selecting the type of allocation based on program requirements................................................... 474

Dynamic allocation functions.................................................................................................................. 474Using dynamic allocation functions in either a batch or interactive environment........................... 474Using dsname or pathname allocation..............................................................................................475Deallocating resources...................................................................................................................... 482Concatenating resources................................................................................................................... 484Deconcatenating resources............................................................................................................... 485Obtaining allocation environment information................................................................................. 485Using dynamic allocation functions in an interactive environment..................................................486In-use attribute.................................................................................................................................. 486Control limit........................................................................................................................................487Permanently allocated attribute........................................................................................................487Convertible attribute.......................................................................................................................... 487Using ddname allocation................................................................................................................... 488

Installation options for DYNALLOC macro functions..............................................................................489Using default values...........................................................................................................................489Mounting volumes and bringing devices online................................................................................ 490Installation input validation routine for dynamic allocation.............................................................490

xi

Chapter 26. Requesting dynamic allocation functions......................................... 491Building the SVC 99 parameter list......................................................................................................... 491

Coding a dynamic allocation request................................................................................................ 492Obtaining storage for the parameter list........................................................................................... 493Mapping storage for the parameter list............................................................................................. 494Setting up the request block pointer................................................................................................. 495Setting up the request block..............................................................................................................495Setting up the text units.....................................................................................................................501Setting up the text unit pointer list.................................................................................................... 502

Processing messages and reason codes from dynamic allocation........................................................502Setting up the request block extension.............................................................................................503Processing messages from dynamic allocation................................................................................ 524

Interpreting DYNALLOC return codes..................................................................................................... 530Interpreting information reason codes from DYNALLOC..................................................................531Interpreting error reason codes from DYNALLOC.............................................................................535

SVC 99 parameter list verb codes and text units, by function............................................................... 572Coding a dsname allocation text unit................................................................................................ 573JCL DD statement parameters and equivalent text units................................................................. 573Using system symbols in text units................................................................................................... 573Dsname allocation text units............................................................................................................. 578JCL DD statement DCB subparameters and equivalent text units................................................... 612DCB attribute text units..................................................................................................................... 614Non-JCL dynamic allocation functions..............................................................................................628Dynamic unallocation text units........................................................................................................ 641Dynamic concatenation text units..................................................................................................... 646Dynamic deconcatenation text units................................................................................................. 647Text units for removing the in-use attribute based on task ID......................................................... 648Ddname allocation text units.............................................................................................................648Dynamic information retrieval text units........................................................................................... 649

Example of a Dynamic Allocation Request............................................................................................. 668

Chapter 27. Dynamic output...............................................................................671Creating and naming output descriptors................................................................................................ 671

System generated names.................................................................................................................. 672Job step considerations.....................................................................................................................672Output descriptors and text units......................................................................................................672Deleting output descriptors............................................................................................................... 681Specifying SYSOUT without an output descriptor.............................................................................682Dynamic output programming example............................................................................................ 685

Chapter 28. Scheduler JCL facility (SJF)............................................................. 689Understanding SJF terms........................................................................................................................690

The SJF environment......................................................................................................................... 691Retrieving output descriptor information (SJFREQ macro with RETRIEVE).................................... 691Merging SWBTUs (SJFREQ macro with SWBTU_MERGE).................................................................692Validating and building text units (SJFREQ macro with VERIFY)..................................................... 692SJFREQ VERIFY functions................................................................................................................. 692Preparing to use VERIFY for validating and building text units........................................................ 693Examples of using SJFREQ VERIFY functions...................................................................................695Freeing the SJF environment (SJFREQ macro with TERMINATE).................................................... 698

Understanding the OUTDES statement.................................................................................................. 699Operand and keyword operand abbreviations.................................................................................. 699Comments and line continuation.......................................................................................................699Delimiters........................................................................................................................................... 699Rules for parsing data with and without quotation marks................................................................699OUTDES statement syntax.................................................................................................................700

xii

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

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

Chapter 30. Using system logger services........................................................... 717What is system logger?............................................................................................................................717

The log stream....................................................................................................................................717The system logger configuration............................................................................................................. 720

The system logger component.......................................................................................................... 722Overview of authorized system logger services..................................................................................... 723

Summary of system logger services..................................................................................................723Coding a system logger complete exit for IXGBRWSE, IXGWRITE, and IXGDELET.........................724Using ENF event code 48 in system logger applications.................................................................. 726

IXGCONN: Connecting to and disconnecting from a log stream............................................................727Connecting as a resource manager................................................................................................... 727Using ENF event 48 when a connect request is rejected..................................................................728Coding a resource manager exit for IXGCONN..................................................................................729

IXGDELET: Deleting log blocks from a log stream..................................................................................732Delete requests and resource manager exit processing...................................................................732

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

Logger server address space availability considerations....................................................................... 735ENF 48 and system logger initialization............................................................................................ 735ENF 48 event code scenarios............................................................................................................ 735Considerations for logger resources temporarily unavailable ......................................................... 736Considerations for logger log stream disconnected......................................................................... 738

When things go wrong: Recovery scenarios for system logger.............................................................. 740When a resource manager fails......................................................................................................... 740

Chapter 31. System REXX.................................................................................. 741Planning to use system REXX..................................................................................................................743Security.................................................................................................................................................... 746Argument and variable processing..........................................................................................................746Input/output files.................................................................................................................................... 748Functions................................................................................................................................................. 748Time limits and canceling a request....................................................................................................... 753Error handling.......................................................................................................................................... 753Examples..................................................................................................................................................753

Chapter 32. z/OS FBA services........................................................................... 757z/OS Distributed Data Backup (zDDB).................................................................................................... 757z/OS FBA devices.....................................................................................................................................758

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

Querying and allocating FBA devices................................................................................................ 760Reading from and writing to z/OS FBA devices................................................................................. 764Erasing data on z/OS FBA devices..................................................................................................... 766Unallocating z/OS FBA devices..........................................................................................................766Improving performance when using IOSFBA services..................................................................... 767Providing a recovery or resource manager........................................................................................768

xiii

Chapter 33. Using and registering functions with the IBM Function Registry forz/OS.............................................................................................................. 769Using the IBM Function Registry for z/OS...............................................................................................769Registering functions in the IBM Function Registry for z/OS................................................................. 770

Appendix A. Using the unit verification service................................................... 773Functions................................................................................................................................................. 773

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

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

Notices..............................................................................................................795Terms and conditions for product documentation................................................................................. 796IBM Online Privacy Statement................................................................................................................ 797Policy for unsupported hardware............................................................................................................797Minimum supported hardware................................................................................................................798Programming interface information........................................................................................................798Trademarks.............................................................................................................................................. 798

Index................................................................................................................ 799

xiv

Figures

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

2. EXTRACT Answer Area Fields....................................................................................................................... 9

3. Example of an Interlock Environment........................................................................................................ 43

4. Example of Subroutine Issuing RESERVE and DEQ Using GETDSAB........................................................ 46

5. Bypassing the POST Routine.......................................................................................................................48

6. Pause and Release Example....................................................................................................................... 61

7. Release and Pause Example....................................................................................................................... 62

8. Transfer without Pause Example................................................................................................................ 63

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

10. Work Area Contents for GQSCAN with a Scope of LOCAL or GLOBAL..................................................... 81

11. Structure of Multiple Traces for an Application..................................................................................... 100

12. Trace Features........................................................................................................................................ 101

13. Structure of Multiple Traces for an Application..................................................................................... 102

14. Setting up Multiple Traces with CTRACE DEFINE.................................................................................. 103

15. Managing Buffer Status.......................................................................................................................... 104

16. Tracing with Component Trace...............................................................................................................109

17. Information Passed to the Start/Stop Exit Routine Through GPR 1......................................................113

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

19. Component Trace Entry in a Trace Buffer.............................................................................................. 118

20. LOADWAIT Example for Defining and Initializing a Parameter List.......................................................124

21. WTO Example for Issuing a Message with a WSPARM parameter........................................................ 124

22. LOADWAIT Example for Defining Storage for a Parameter List.............................................................124

23. LOADWAIT Example for Modifying an Existing Parameter List............................................................. 125

xv

24. WTO Example for Issuing a Message and Loading a Wait State............................................................125

25. LOADWAIT Example for Adding a Reason Code to a Parameter List and Changing the Type of WaitState......................................................................................................................................................... 125

26. WTO Example of a Message with a WSPARM Parameter...................................................................... 125

27. Setting Up the Buffer for MGCR..............................................................................................................127

28. MDB Structure.........................................................................................................................................140

29. Managing an Extended MCS Console Session Overview....................................................................... 144

30. Authorized Program without QUAL and QMASK.................................................................................... 149

31. Qualifier for a Program Check.................................................................................................................149

32. Authorized Programs with QUAL and QMASK........................................................................................150

33. Example of Scheduling an SRB...............................................................................................................190

34. Suspending and Resuming an SRB.........................................................................................................193

35. Low and High Private Storage Allocation............................................................................................... 201

36. Task Structure Within an Address Space............................................................................................... 205

37. Allocated Storage Information for Subpools in a Specified Area.......................................................... 215

38. Format of Subpool Descriptor................................................................................................................ 216

39. Format of Allocated Block Descriptor.................................................................................................... 216

40. Allocated Storage Information for the Private Area...............................................................................217

41. Allocated Storage Information for a Subpool List..................................................................................218

42. Format of Free Space Information......................................................................................................... 218

43. Format of Free Space