z/OSVersion 2 Release 4

MVS Programming: AuthorizedAssembler Services Guide

IBM

SA23-1371-40

Note

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

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

Last updated: 2020-05-25© Copyright International Business Machines Corporation 1988, 2020.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 4................................................................................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.................xxxiiiSummary of changes for z/OS Version 2 Release 2..............................................................................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...................................................................................................................... 37Obtaining, releasing, and testing locks (SETLOCK).............................................................................37Suspend lock instrumentation data ....................................................................................................37

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

Shared direct access storage devices (shared DASD).............................................................................. 39Volume/device status...........................................................................................................................40Volume 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......................................................................................................... 64

Planning to use the latch manager callable services................................................................................65Including a latch manager interface definition file (IDF).................................................................... 66Loading the linkage assist routines..................................................................................................... 66Providing 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............................................................................................................................. 171

SMFLSTEN - Sample ENF listener..................................................................................................... 172Listening for global resource serialization-related system events........................................................ 176

Monitoring contention changes......................................................................................................... 176

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

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

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

Scheduling an SRB (IEAMSCHD or SCHEDULE macro).......................................................................... 185Scheduling an SRB using IEAMSCHD................................................................................................ 186Scheduling an SRB using SCHEDULE.................................................................................................187

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

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

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

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

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

vi

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

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

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

Using the VSMLIST work area............................................................................................................215Using IARQD — The page status interface routine................................................................................. 224

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

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

The SWAREQ macro...........................................................................................................................230How to invoke SWAREQ..................................................................................................................... 230The IEFQMREQ macro....................................................................................................................... 232

Chapter 12. The virtual lookaside facility (VLF)...................................................235Deciding when to use VLF....................................................................................................................... 235Planning to use VLF................................................................................................................................. 236

Data objects and classes................................................................................................................... 237Data integrity......................................................................................................................................239Recovery.............................................................................................................................................239

Using the VLF macros.............................................................................................................................. 240Defining a class of VLF objects.......................................................................................................... 241Identifying an end user to VLF...........................................................................................................242Retrieving a VLF object...................................................................................................................... 243Creating a VLF object......................................................................................................................... 243Notifying VLF of a change...................................................................................................................245Removing a VLF end user...................................................................................................................245Purging a VLF class............................................................................................................................ 246Modifying VLF..................................................................................................................................... 246

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

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

Using the services of data-in-virtual....................................................................................................... 249Identify............................................................................................................................................... 249Access................................................................................................................................................ 249Map..................................................................................................................................................... 249Save, Savelist, and Reset................................................................................................................... 250Unmap................................................................................................................................................ 251Unaccess............................................................................................................................................ 251Unidentify........................................................................................................................................... 251

The IDENTIFY service............................................................................................................................. 251The ACCESS service.................................................................................................................................252The MAP service...................................................................................................................................... 254The SAVE service..................................................................................................................................... 258The SAVELIST service..............................................................................................................................260The RESET service................................................................................................................................... 260

Effect of RETAIN mode on RESET..................................................................................................... 260The UNACCESS and UNIDENTIFY services............................................................................................ 262

vii

Sharing data in an object......................................................................................................................... 262DIV macro programming examples........................................................................................................ 263

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

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

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

Primary-level name/token pair..........................................................................................................271System-level name/token pair.......................................................................................................... 272

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

Chapter 15. Processor storage management.......................................................277Fixing/freeing virtual storage contents................................................................................................... 278Protecting a range of virtual storage pages............................................................................................ 279PGFIX/PGFREE completion considerations............................................................................................279Input to page services............................................................................................................................. 280

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

Branch entry to page services.................................................................................................................281Cross memory mode.......................................................................................................................... 281Non-cross memory mode.................................................................................................................. 282

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

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

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

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

The NMLDEF macro............................................................................................................................300Removing existing routines from IEANUC0x.....................................................................................301

Chapter 18. Providing recovery.......................................................................... 303Understanding general recovery concepts............................................................................................. 304

Deciding whether to provide recovery...............................................................................................304Understanding errors in MVS............................................................................................................. 306Understanding recovery routine states............................................................................................. 306Understanding the various routines in a recovery environment.......................................................307

viii

Choosing the appropriate recovery routine.......................................................................................308Understanding recovery routine options...........................................................................................311Understanding how routines in a recovery environment interact.................................................... 311

Writing recovery routines........................................................................................................................ 313Understanding what recovery routines do........................................................................................ 314Understanding the means of communication................................................................................... 320Special considerations for ESTAE-type recovery routines............................................................... 329Special considerations for FRRs........................................................................................................ 334

Understanding the recovery environment.............................................................................................. 335Register contents............................................................................................................................... 336Other environmental factors in recovery...........................................................................................344

Understanding recovery through a coded example............................................................................... 358Understanding advanced recovery topics...............................................................................................360

Providing recovery with minimal processor overhead (FESTAE macro).......................................... 360Invoking RTM......................................................................................................................................361Providing multiple recovery routines.................................................................................................363Providing recovery for recovery routines...........................................................................................368Providing recovery for multitasking programs.................................................................................. 369Using resource managers.................................................................................................................. 369

Using STAE/STAI routines.......................................................................................................................374

Chapter 19. Processing program interruptions (SPIE, ESPIE).............................. 379Interruption types....................................................................................................................................380

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

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

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

ix

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

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

Authorized programs............................................................................................................................... 406Using APF to restrict access to system functions...................................................................................407

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

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

MVS router..........................................................................................................................................412Interface to the MVS router (RACROUTE)......................................................................................... 413SAF interface to an external security product...................................................................................414

Using the command authorization service............................................................................................. 416Command resource names................................................................................................................417

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

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

Using the SCHEDIRB macro to initialize and schedule an IRB.........................................................421Using the SCHEDIRB macro to schedule an IRB...............................................................................422Using the CIRB macro to initialize an IRB......................................................................................... 422Using the SCHEDXIT macro to schedule an IRB...............................................................................424System processing to run an asynchronous exit...............................................................................425

Establishing a timer disabled interrupt exit............................................................................................426DIE characteristics.............................................................................................................................427Timer queue element control............................................................................................................ 429

Using dynamic exits services.................................................................................................................. 430CSVDYNEX terminology..................................................................................................................... 431Defining an exit...................................................................................................................................432Calling an exit routine or routines......................................................................................................434Associating an exit routine with an exit.............................................................................................438

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

Type 6 SVC routines........................................................................................................................... 441Non-preemptable SVC routines.........................................................................................................442Programming conventions for SVC routines......................................................................................442

Inserting SVC routines into the control program....................................................................................447Standard SVC routines....................................................................................................................... 447Extended SVC routines...................................................................................................................... 449

Subsystem SVC screening.......................................................................................................................449

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

x

UCB Common Segment......................................................................................................................453UCB Common Extension.................................................................................................................... 454UCB Prefix Extension......................................................................................................................... 454UCB Prefix Area.................................................................................................................................. 454UCB details......................................................................................................................................... 454

Ensuring that UCBs are not deleted........................................................................................................456Pinning and unpinning UCBs..............................................................................................................456When pinning is required................................................................................................................... 457When pinning is not required.............................................................................................................458

Requesting notification of I/O configuration changes............................................................................458Using the CONFCHG macro................................................................................................................459Coding a configuration change user exit routine...............................................................................459Coded example: CONFCHG macro invocation of configuration change user exit............................461

Detecting I/O configuration changes...................................................................................................... 463Retrieving the current MIH time interval................................................................................................ 464Retrieving information about I/O hardware on an I/O path................................................................... 465

Length of the CDR area...................................................................................................................... 465How IOSCDR retrieves the CDR.........................................................................................................465Time that IOSCDR performs I/O........................................................................................................466

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

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

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

Accessing above 16-megabyte UCBs..................................................................................................... 473

Chapter 25. Dynamic allocation..........................................................................475An allocation overview............................................................................................................................ 475

Choosing the type of allocation for your program.............................................................................475When to avoid using dynamic allocation........................................................................................... 476Programming considerations for using the DYNALLOC macro......................................................... 476Selecting the type of allocation based on program requirements................................................... 478

Dynamic allocation functions.................................................................................................................. 478Using dynamic allocation functions in either a batch or interactive environment...........................478Using dsname or pathname allocation..............................................................................................479Deallocating resources...................................................................................................................... 486Concatenating resources................................................................................................................... 488Deconcatenating resources............................................................................................................... 489Obtaining allocation environment information................................................................................. 489Using dynamic allocation functions in an interactive environment..................................................490In-use attribute.................................................................................................................................. 490Control limit........................................................................................................................................491Permanently allocated attribute........................................................................................................491Convertible attribute.......................................................................................................................... 492Using ddname allocation................................................................................................................... 492

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

xi

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

Coding a dynamic allocation request................................................................................................ 496Obtaining storage for the parameter list........................................................................................... 497Mapping storage for the parameter list.............................................................................................498Setting up the request block pointer................................................................................................. 499Setting up the request block..............................................................................................................499Setting up the text units.....................................................................................................................505Setting up the text unit pointer list....................................................................................................506

Processing messages and reason codes from dynamic allocation........................................................506Setting up the request block extension.............................................................................................507Processing messages from dynamic allocation................................................................................ 528

Interpreting DYNALLOC return codes.....................................................................................................534Interpreting information reason codes from DYNALLOC..................................................................535Interpreting error reason codes from DYNALLOC.............................................................................539

SVC 99 parameter list verb codes and text units, by function............................................................... 576Coding a dsname allocation text unit................................................................................................ 577JCL DD statement parameters and equivalent text units................................................................. 577Using system symbols in text units................................................................................................... 577Dsname allocation text units............................................................................................................. 582JCL DD statement DCB subparameters and equivalent text units...................................................616DCB attribute text units..................................................................................................................... 618Non-JCL dynamic allocation functions..............................................................................................632Dynamic unallocation text units........................................................................................................ 644Dynamic concatenation text units..................................................................................................... 650Dynamic deconcatenation text units.................................................................................................650Text units for removing the in-use attribute based on task ID.........................................................651Ddname allocation text units.............................................................................................................652Dynamic information retrieval text units...........................................................................................653

Example of a Dynamic Allocation Request............................................................................................. 672

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

System generated names.................................................................................................................. 676Job step considerations.....................................................................................................................676Output descriptors and text units......................................................................................................676Deleting output descriptors............................................................................................................... 685Specifying SYSOUT without an output descriptor.............................................................................686Dynamic output programming example............................................................................................688

Chapter 28. Scheduler JCL facility (SJF).............................................................693Understanding SJF terms........................................................................................................................693

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

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

xii

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

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

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

The log stream....................................................................................................................................721The system logger configuration.............................................................................................................724

The system logger component.......................................................................................................... 726Overview of authorized system logger services..................................................................................... 727

Summary of system logger services..................................................................................................727Coding a system logger complete exit for IXGBRWSE, IXGWRITE, and IXGDELET........................ 728Using ENF event code 48 in system logger applications.................................................................. 730

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

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

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

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

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

Chapter 31. System REXX.................................................................................. 747Planning to use system REXX..................................................................................................................749Security.................................................................................................................................................... 752Argument and variable processing......................................................................................................... 752Input/output files.................................................................................................................................... 754Functions................................................................................................................................................. 754Time limits and canceling a request....................................................................................................... 759Error handling.......................................................................................................................................... 759Examples..................................................................................................................................................759

Chapter 32. z/OS FBA services...........................................................................763z/OS Distributed Data Backup (zDDB).................................................................................................... 763z/OS FBA devices.....................................................................................................................................764

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

Querying and allocating FBA devices................................................................................................ 766Reading from and writing to z/OS FBA devices.................................................................................770Erasing data on z/OS FBA devices..................................................................................................... 772Unallocating z/OS FBA devices..........................................................................................................772Improving performance when using IOSFBA services..................................................................... 773Providing a recovery or resource manager........................................................................................774

xiii

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

Chapter 34. IBM z/OS Workload Interaction Correlator.......................................779Workload interaction correlator exploiter exit routine...........................................................................779Workload interaction correlator exit routine services............................................................................ 781

WIC exit routine service — Get next buffer....................................................................................... 782WIC exit routine service — Clear buffer.............................................................................................783WIC exit routine service — Build and write SMF98 record............................................................... 784

Aggregate buckets...................................................................................................................................787Exception bucket..................................................................................................................................... 791

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

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

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

Notices..............................................................................................................817Terms and conditions for product documentation.................................................................................818IBM Online Privacy Statement................................................................................................................ 819Policy for unsupported hardware............................................................................................................819Minimum supported hardware................................................................................................................820Programming interface information........................................................................................................820Trademarks..............................................................................................................................................820

Index................................................................................................................ 821

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...............................................................................................................192

34. Suspending and Resuming an SRB.........................................................................................................195

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

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