z/OSVersion 2 Release 3

MVS Programming:Workload Management Services

IBM

SC34-2663-30

Note

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

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-06-24© Copyright International Business Machines Corporation 1988, 2017.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

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

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

About this information........................................................................................ xixWho should use this information.............................................................................................................. xixWhere to find more information................................................................................................................ xixInformation updates on the web...............................................................................................................xixHow to read syntax diagrams.....................................................................................................................xx

Symbols.................................................................................................................................................xxSyntax items..........................................................................................................................................xxSyntax examples.................................................................................................................................. xxi

How to send your comments to IBM................................................................... xxiiiIf you have a technical problem.............................................................................................................. xxiii

Summary of changes.......................................................................................... xxvSummary of changes for z/OS Version 2 Release 3 (V2R3).................................................................... xxvSummary of changes in z/OS Version 2 Release 2 (V2R2) as updated March 2017..............................xxvSummary of changes in z/OS Version 2 Release 2 (V2R2) as updated December 2015...................... xxviSummary of changes for z/OS Version 2 Release 2 (V2R2)................................................................... xxviChanges made in z/OS Version 2 Release 1 (V2R1) as updated December 2013................................ xxviChanges made in z/OS Version 2 Release 1............................................................................................xxvi

Part 1. Using the workload management services................................................... 1

Chapter 1. Introduction to the workload management services................................................................3Services for subsystem work managers................................................................................................ 3

Why use the work manager services................................................................................................ 3Why use the execution delay monitoring services...........................................................................4Why use the enclave services...........................................................................................................6Why use the queueing manager services.........................................................................................8Why use the routing manager services.......................................................................................... 10Why use the scheduling environment services..............................................................................11Why use the sysplex routing services............................................................................................ 12Why use the query system information service............................................................................. 12

Services for performance monitors..................................................................................................... 13Why use the workload reporting services...................................................................................... 13Getting information from SMF type 99 records............................................................................. 14

Services for application programs....................................................................................................... 15WLM services that support 64-bit addressing.....................................................................................15

Chapter 2. Using the subsystem work manager services.........................................................................19Considerations for using the services..................................................................................................19Suggested services for a single address space transaction manager................................................ 20

Using the execution delay monitoring services............................................................................. 22Suggested services for a work manager that calls a data manager....................................................24Services for multiple address space work managers..........................................................................25

Execution delay monitoring services for multiple address space work managers.......................27

iii

Services for work managers that distribute work requests................................................................ 28Determining the subsystem name and type.................................................................................. 29Using IWMWMCON when distributing work in a sysplex...............................................................29

Chapter 3. Creating and using enclaves....................................................................................................31Why would you use an enclave?.......................................................................................................... 31

SRBs in enclaves.............................................................................................................................32Tasks in enclaves............................................................................................................................ 32Comparison of enclaves and execution delay services................................................................. 33

Creating an enclave.............................................................................................................................. 33Comparison between independent, dependent, and work-dependent enclaves........................ 33Registering an enclave....................................................................................................................34Multisystem enclaves..................................................................................................................... 34Scheduling an SRB in an independent enclave..............................................................................36Joining tasks to an independent enclave.......................................................................................38Using dependent enclaves............................................................................................................. 40Using a multisystem enclave.......................................................................................................... 42Performance management of address spaces with enclaves....................................................... 44Using ENQ/DEQ or latch manager services with enclaves............................................................ 46

Enclave resource accounting............................................................................................................... 46Managing the performance of work in enclaves..................................................................................49

Using independent enclaves.......................................................................................................... 49Using dependent enclaves............................................................................................................. 50Using work-dependent enclaves.................................................................................................... 50

Querying an enclave's classification information................................................................................ 50Querying a dispatchable unit's enclave status.................................................................................... 51Deleting an enclave.............................................................................................................................. 51

Chapter 4. Participating in Enterprise Workload Management................................................................ 53Enclave Services and EWLM.................................................................................................................53

Modelling your business transactions............................................................................................54Connecting with WLM as an EWLM participant..............................................................................55Disconnecting from WLM................................................................................................................55Creating an enclave........................................................................................................................ 55Deleting an enclave.........................................................................................................................56Classifying work requests...............................................................................................................56Explicitly starting and stopping work requests..............................................................................57Continuing a work request at another application.........................................................................57Blocking and unblocking work requests........................................................................................ 57Enclave services and the ARM API.................................................................................................57

Instrumenting a C application for ARM................................................................................................58Using the ARM services for instrumenting applications and for managing ARM transactions

on z/OS.......................................................................................................................................58Compiling an ARM-instrumented application................................................................................62Binding an ARM-instrumented application.................................................................................... 63Running an ARM-instrumented application...................................................................................64

Chapter 5. Using the queueing manager services.................................................................................... 67Example of using the queueing manager services.............................................................................. 67

Managing the number of server instances per server address space...........................................72Directing work requests to a specific server region.......................................................................73

Updating a service definition with application environment information...........................................73Using the queueing manager connect exit.......................................................................................... 74

Chapter 6. Using the routing manager services........................................................................................77A routing manager model.....................................................................................................................77Using the routing server connect exit.................................................................................................. 80

iv

Chapter 7. Using the scheduling environment services........................................................................... 83Obtaining scheduling environment definitions....................................................................................83Manipulating resource state settings.................................................................................................. 84A model work flow................................................................................................................................85

Chapter 8. Using the sysplex routing services.......................................................................................... 89Why use the sysplex routing services?................................................................................................ 89When to use the sysplex routing services........................................................................................... 89

Registering as an eligible server.....................................................................................................89Determining where to route work...................................................................................................90Deregistering as an eligible server................................................................................................. 90

Example of using the sysplex routing services....................................................................................90WLM sysplex workload distribution..................................................................................................... 92Calculation of server weights...............................................................................................................92

Chapter 9. Using the workload reporting services....................................................................................95When to use the workload reporting services..................................................................................... 95Using ENF signals to guide data collection..........................................................................................95

ENF event code 41..........................................................................................................................96Using the IWMRCOLL service...............................................................................................................96

Using the information in IWMWRCAA............................................................................................ 97Using the subsystem work manager delay state information....................................................... 98Using delay states to report subsystem interactions.................................................................. 100Using the response time information...........................................................................................102Interpreting report class data...................................................................................................... 102

Using the IWMRQRY service.............................................................................................................. 103Using the IWM4QTNT service............................................................................................................104

Chapter 10. Using the administrative application services....................................................................105Installing a service definition.............................................................................................................105

Mapping a service definition.........................................................................................................105Adding program-specific extensions to a service definition....................................................... 105Checking a service definition using IWMDINST...........................................................................108Recommended validity checking................................................................................................. 108Preventing service definition overlays......................................................................................... 109Example of using IWMDINST to install a service definition........................................................ 109

Extracting a service definition........................................................................................................... 110Example of using IWMDEXTR to extract a service definition...................................................... 110

Activating a service policy..................................................................................................................111Example of activating a policy using IWMPACT...........................................................................111

Querying the active classification rules.............................................................................................111Example of IWMCQRY.................................................................................................................. 112

Chapter 11. Using SMF record type 99................................................................................................... 113When to start SMF record type 99.....................................................................................................114

Starting SMF record type 99.........................................................................................................114Identifying work in SMF type 99 records.......................................................................................... 114

Identifying server service classes................................................................................................114Identifying internal service classes............................................................................................. 114

Interpreting trace table entries......................................................................................................... 115Policy adjustment......................................................................................................................... 115Resource adjustment....................................................................................................................115Receivers and donors................................................................................................................... 115Performance index........................................................................................................................116Receiver value...............................................................................................................................116Net value....................................................................................................................................... 116Small processor consumer...........................................................................................................116

v

Storage housekeeping.................................................................................................................. 116Reverse housekeeping................................................................................................................. 117

Interpreting management policy data...............................................................................................117Dispatching priority...................................................................................................................... 117MPL targets................................................................................................................................... 117Swap protect time........................................................................................................................ 118Storage target............................................................................................................................... 118Cap slices...................................................................................................................................... 118I/O priority.................................................................................................................................... 118Number of server address spaces................................................................................................118Buffer pool management data..................................................................................................... 118

Interpreting plots............................................................................................................................... 118System paging delay plot............................................................................................................. 119Period MPL delay plot...................................................................................................................119Period ready user average plot.....................................................................................................119Period swap delay plot................................................................................................................. 120Period paging rate plot................................................................................................................. 120Period proportional aggregate speed plot................................................................................... 120I/O delay plot................................................................................................................................ 120Queue delay plot...........................................................................................................................121Address space paging plots......................................................................................................... 121I/O velocity plot............................................................................................................................ 121Buffer pool hit ratio plot............................................................................................................... 122

Interpreting priority table data.......................................................................................................... 122Interpreting lack of action................................................................................................................. 122Examples of interpreting SMF record type 99...................................................................................123

Action trace example....................................................................................................................123MPL policy example......................................................................................................................125

Part 2. Reference: Workload Management Services............................................ 129

Chapter 12. Workload management services.........................................................................................131IWMCNTN — WLM contention notification........................................................................................ 131IWMCQRY — Query classification attributes..................................................................................... 139IWMDEXTR — Extract WLM service definition...................................................................................144IWMDINST — Install a service definition...........................................................................................152IWMEBLK — Work request blocked................................................................................................... 160IWMEDREG — Deregister a WLM enclave..........................................................................................166IWMEGCOR — Retrieve a correlator.................................................................................................. 170IWMEJOIN — Join WLM enclave........................................................................................................176IWMELEAV — Leave WLM enclave..................................................................................................... 184IWMEQTME — Query enclave CPU time............................................................................................ 190IWMEREG — Register a WLM enclave................................................................................................196IWMERES — Change an enclave........................................................................................................ 201IWMESQRY — Query enclave state....................................................................................................209IWMESTOP — Stop a work request....................................................................................................213IWMESTRT — Start a work request....................................................................................................219IWMEUBLK — Work request no longer blocked................................................................................ 226IWMEXPT — Export a WLM enclave...................................................................................................232IWMGCORF — Get correlator flags.................................................................................................... 238IWMIMPT — Import an enclave......................................................................................................... 240IWMMXDC — Exit for resource data collection..................................................................................246IWMMXRA — Exit for resource adjustment....................................................................................... 251IWMPACT — Activate service policy.................................................................................................. 256IWMPQRY — Query active service policy...........................................................................................262IWMQCXIT — Queue manager connect exit......................................................................................267IWMRCOLL — Collect workload activity data.................................................................................... 272

vi

IWMRESET — Change a job................................................................................................................279IWMRQRY — Collect address space delay information.....................................................................286IWMSCORF — Set correlator flags..................................................................................................... 292IWMSCXIT — Server manager connect exit...................................................................................... 295IWMSEDES — Scheduling environments determine execution service........................................... 300IWMSEQRY — Scheduling environments query service....................................................................305IWMSESET — Scheduling environments set resource service......................................................... 310IWMSEVAL — Scheduling environments validate service.................................................................315IWMSINF — WLM server manager inform service.............................................................................320IWMSRDNS — Get sysplex routing location list.................................................................................327IWMSRDRS — Deregister a server for sysplex routing...................................................................... 332IWMSRFSV — Sysplex routing find server routine.............................................................................337IWMSRSRG — Register a server for sysplex routing......................................................................... 344IWMSRSRS — Sysplex routing information....................................................................................... 351IWMUEXPT — WLM undo export........................................................................................................361IWMUIMPT — WLM undo import....................................................................................................... 367IWMWMCON — WLM modify connect................................................................................................372IWMWQRY — Query service............................................................................................................... 378IWMWQWRK — Query work service.................................................................................................. 382IWMWSYSQ — Query system information......................................................................................... 388IWM4AEDF — WLM define dynamic application environments........................................................395IWM4CLSY — Classify work............................................................................................................... 403IWM4CON — Connect to workload management............................................................................. 416IWM4DIS — Disconnect from workload management......................................................................432IWM4ECRE — Create an enclave....................................................................................................... 438IWM4EDEL — Delete an enclave........................................................................................................451IWM4EQRY — Query an enclave........................................................................................................ 457IWM4HLTH — Setting server health indicator................................................................................... 463IWM4MABN — Monitor environment abnormal event...................................................................... 470IWM4MCHS — Change the state of a work request.......................................................................... 474IWM4MCRE — Create delay monitoring environment.......................................................................484IWM4MDEL — Delete delay monitoring environment....................................................................... 495IWM4MDRG — Deregister a resource from monitoring.....................................................................501IWM4MGDD — Define descriptions for generic delay states............................................................ 506IWM4MINI — Monitoring environment initialization.........................................................................512IWM4MNTF — Notify of work execution completion........................................................................ 526IWM4MREG — Register a resource for monitoring............................................................................534IWM4MRLT — Relate monitoring environments (PBs)......................................................................541IWM4MSTO — Stops a work unit....................................................................................................... 550IWM4MSTR — Indicate the start of a work unit................................................................................ 557IWM4MSWC — Monitoring environment switch................................................................................563IWM4MUPD — Update data for a work unit.......................................................................................570IWM4MXFR — Monitoring environment transfer...............................................................................576IWM4MXTR — Monitoring environment extract service................................................................... 583IWM4OPTQ — Query IEAOPTxx parameters.....................................................................................590IWM4QDE — Delete a request from the queue for an execution address space............................. 595IWM4QHLT — Query server health indicators................................................................................... 600IWM4QIN — Insert a request onto the queue for an execution address space...............................606IWM4QTNT — Query tenant resource group consumption...............................................................616IWM4RPT — Report response time................................................................................................... 622IWM4SLI — Application environment limit service...........................................................................634IWM4SRSC — Obtain server-specific routing information................................................................640IWM4SSL — Select a request from a caller's work manager queue.................................................649IWM4SSM — WLM server select secondary service..........................................................................655IWM4STBG — WLM begin server transaction service....................................................................... 660IWM4STEN — End a request from a caller's work manager queue.................................................. 668IWM4TAF — WLM temporal affinity service...................................................................................... 673

vii

Appendix A. SMF type 99 action codes............................................................... 681

Appendix B. Application validation reason codes................................................ 707

Appendix C. Structure of the XML service definition (DTD)...................................723

Appendix D. C language interfaces for workload management services............... 727Interfaces for sysplex routing services................................................................................................... 729Interface for querying a virtual server.................................................................................................... 730

Appendix E. WLM services supporting 31-bit addressing only............................. 731IWMAEDEF — Defining Dynamic Application Environments to Workload Management.......................731IWMCLSFY — Classify work request....................................................................................................... 738IWMCONN — Connect to workload management...................................................................................751IWMDISC — Disconnect from workload management........................................................................... 767IWMECQRY — Query enclave classification attributes........................................................................... 773IWMECREA — Create an enclave.............................................................................................................778IWMEDELE — Delete an enclave............................................................................................................. 787IWMEQRY — Enclave query..................................................................................................................... 794IWMMABNL — Record abnormal event...................................................................................................800IWMMCHST — Monitor change state of work unit.................................................................................. 804IWMMCREA — Create delay monitoring environment............................................................................ 810IWMMDELE — Delete the monitoring environment................................................................................ 818IWMMEXTR — Monitoring environment extract......................................................................................822IWMMINIT — Initialize monitoring environment....................................................................................828IWMMNTFY — Notify of work execution completion..............................................................................841IWMMRELA — Relate monitoring environment service..........................................................................848IWMMSTOP — Stop a work unit...............................................................................................................856IWMMSTRT — Indicate the start of a work unit...................................................................................... 862IWMMSWCH — Switch monitoring environment.................................................................................... 868IWMMUPD — Update data for a work unit.............................................................................................. 872IWMMXFER — Transfer monitoring environment................................................................................... 877IWMQDEL — Delete a request from the queue for an execution address space................................... 884IWMQINS — Insert a request onto the queue for an execution address space.................................... 890IWMRPT — Report on work request completion.................................................................................... 900IWMSLIM — Application environment limit service................................................................................910IWMSSEL — Select a request from a caller's work manager queue.......................................................916IWMSSEM — WLM server select secondary service............................................................................... 922IWMSTBGN — Begin a request from a caller's work manager queue....................................................927IWMSTEND — End a request from a caller's work manager queue....................................................... 934IWMTAFF — WLM temporal affinity service............................................................................................ 939

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

Notices..............................................................................................................951Terms and conditions for product documentation................................................................................. 952IBM Online Privacy Statement................................................................................................................ 953Policy for unsupported hardware............................................................................................................953Minimum supported hardware................................................................................................................954Programming interface information........................................................................................................954Trademarks.............................................................................................................................................. 954

viii

Index................................................................................................................ 955

ix

x

Figures

1. Sequence of functions in a single address space transaction manager.................................................... 20

2. Work manager services for a single address space transaction manager.................................................21

3. Work manager and delay monitoring services for a single address space transaction manager............. 23

4. Services for a work manager that uses a database manager.....................................................................24

5. Sequence of function in a multiple address space work manager............................................................ 26

6. Example of services that monitor work across multiple address spaces..................................................28

7. Creating an independent enclave and scheduling an SRB.........................................................................37

8. Creating an enclave and joining tasks to it................................................................................................. 39

9. Using dependent enclaves..........................................................................................................................41

10. Using a multisystem enclave.................................................................................................................... 42

11. Example of performance management of non-enclave work with IEAOPT parameterManageNonEnclaveWork=YES...................................................................................................................46

12. Typical synchronous application flow between applications on the same z/OS system........................59

13. Sub-buffer arm_subbuffer_zos_connect_t)............................................................................................. 60

14. Sub-buffer arm_subbuffer_zos_classify.................................................................................................. 62

15. Sample JCL for compiling an ARM-instrumented application in MVS batch...........................................63

16. Sample JCL for binding an ARM-instrumented application in MVS batch...............................................64

17. Services for a queueing manager............................................................................................................. 68

18. Exploiting IWMSINF..................................................................................................................................72

19. Example of routing manager services...................................................................................................... 78

20. Obtaining scheduling environments.........................................................................................................84

21. Manipulating resource state settings....................................................................................................... 85

22. Scheduling environment flow................................................................................................................... 86

xi

23. Example of using sysplex routing services...............................................................................................91

24. Using states for presenting CICS delay information................................................................................ 99

25. Combining state information for a sysplex view.................................................................................... 100

26. Combining state information for a service class....................................................................................101

27. Combining state information across subsystems.................................................................................. 101

28. Mixed-class-indication timestamp in relation to the time interval....................................................... 103

29. IWMSVDEF mapping for a service definition with workload extensions...............................................107

30. Subtype 2: Service class TSO period data..............................................................................................126

31. Subtype 1: Trace data output................................................................................................................. 126

32. Subtype 3: Swap delay plot.................................................................................................................... 126

33. Subtype 2: Dispatching priority data......................................................................................................127

34. MPL delay plot.........................................................................................................................................127

xii

Tables

1. Syntax examples......................................................................................................................................... xxi

2. Work manager services................................................................................................................................. 4

3. Execution delay monitoring services............................................................................................................ 5

4. Enclave services............................................................................................................................................ 7

5. Queueing manager services..........................................................................................................................9

6. Routing manager services...........................................................................................................................11

7. Scheduling environment services...............................................................................................................11

8. Sysplex routing services..............................................................................................................................12

9. Summary of workload reporting services...................................................................................................13

10. Administrative application services......................................................................................................... 15

11. Overview of WLM services supporting 64-bit and 31-bit addressing..................................................... 16

12. Performance management of address spaces with enclaves................................................................. 45

13. Enclave characteristics and resource accounting....................................................................................47

14. Starting and stopping work requests........................................................................................................55

15. WLM Enclave Services and ARM APIs...................................................................................................... 58

16. Sample commands for compiling applications under z/OS UNIX Systems Services..............................63

17. Sample commands for binding applications under z/OS UNIX............................................................... 64

18. CPU consumption table............................................................................................................................ 93

19. Using ENF event code 41 to guide data collection for policy changes....................................................96

20. Using IWMRCOLL with the workload reporting services on a single system.......................................... 97

21. Self-defining response time distributions for service class XYZ........................................................... 102

22. Using IWMRQRY with the workload reporting services.........................................................................104

23. Using IWM4QTNT with the workload reporting services.......................................................................104

xiii

24. SERVD validation reason codes..............................................................................................................108

25. Work unit IDs.......................................................................................................................................... 135

26. Return and Reason Codes for the IWMCNTN Macro............................................................................. 137

27. Return and Reason Codes for the IWMCQRY Macro..............................................................................143

28. Return and Reason Codes for the IWMDEXTR Macro............................................................................150

29. Return and Reason Codes for the IWMDINST Macro............................................................................ 158

30. Return and Reason Codes for the IWMEBLK Macro.............................................................................. 164

31. Return and Reason Codes for the IWMEDREG Macro........................................................................... 169

32. Return and Reason Codes for the IWMEGCOR Macro........................................................................... 175

33. Return and Reason Codes for the IWMEJOIN Macro............................................................................ 181

34. Return and Reason Codes for the IWMELEAV Macro.............................................................................188

35. Return and Reason Codes for the IWMEQTME Macro........................................................................... 196

36. Return and Reason Codes for the IWMEREG Macro..............................................................................200

37. Return and Reason Codes for the IWMERES Macro.............................................................................. 207

38. Return and Reason Codes for the IWMESQRY Macro............................................................................212

39. Return and Reason Codes for the IWMESTOP Macro............................................................................ 217

40. Return and Reason Codes for the IWMESTRT Macro............................................................................ 224

41. Return and Reason Codes for the IWMEUBLK Macro............................................................................231

42. Return and Reason Codes for the IWMEXPT Macro.............................................................................. 236

43. Return and Reason Codes for the IWMIMPT Macro.............................................................................. 244

44. Return and Reason Codes for the IWMMXDC Macro............................................................................. 251

45. Return and Reason Codes for the IWMMXRA Macro............................................................................. 255

46. Return and Reason Codes for the IWMPACT Macro.............................................................................. 260

47. Return and Reason Codes for the IWMPQRY Macro..............................................................................266

48. Return and Reason Codes for the IWMQCXIT Macro............................................................................ 272

xiv

49. Return and Reason Codes for the IWMRCOLL Macro............................................................................ 278

50. Return and Reason Codes for the IWMRESET Macro............................................................................ 284

51. Return and Reason Codes for the IWMRQRY Macro..............................................................................291

52. Return and Reason Codes for the IWMSCXIT Macro.............................................................................300

53. Return and Reason Codes for the IWMSEDES Macro............................................................................ 304

54. Return and Reason Codes for the IWMSEQRY Macro............................................................................309

55. Return and Reason Codes for the IWMSESET Macro............................................................................ 314

56. Return and Reason Codes for the IWMSEVAL Macro.............................................................................319

57. Return and Reason Codes for the IWMSINF Macro...............................................................................325

58. Return and Reason Codes for the IWMSRDNS Macro........................................................................... 330

59. Return and Reason Codes for the IWMSRDRS Macro............................................................................336

60. Return and Reason Codes for the IWMSRFSV Macro............................................................................ 341

61. Return and Reason Codes for the IWMSRSRG Macro............................................................................349

62. Return and Reason Codes for the IWMSRSRS Macro............................................................................ 359

63. Return and Reason Codes for the IWMUEXPT Macro............................................................................365

64. Return and Reason Codes for the IWMUIMPT Macro............................................................................370

65. Return and Reason Codes for the IWMWMCON Macro......................................................................... 376

66. Return and Reason Codes for the IWMWSYSQ Macro...........................................................................393

67. Return and Reason Codes for the IWM4AEDF Macro............................................................................401

68. Return and Reason Codes for the IWM4CLSY Macro............................................................................ 415

69. Return and Reason Codes for the IWM4CON Macro............................................................................. 427

70. Return and Reason Codes for the IWM4DIS Macro...............................................................................436

71. Return and Reason Codes for the IWM4ECRE Macro............................................................................ 447

72. Return and Reason Codes for the IWM4EDEL Macro............................................................................ 456

73. Return and Reason Codes for the IWM4EQRY Macro............................................................................462

xv

74. Return codes and reason codes for the IWM4HLTH Macro...................................................................468

75. Return and reason codes for the IWM4MABN macro............................................................................474

76. Return and Reason Codes for the IWM4MCHS Macro...........................................................................484

77. Return and Reason Codes for the IWM4MCRE Macro........................................................................... 493

78. Return and Reason Codes for the IWM4MDEL Macro........................................................................... 499

79. Return and Reason Codes for the IWM4MDRG Macro...........................................................................505

80. Return and Reason Codes for the IWM4MGDD Macro.......................................................................... 511

81. Return and Reason Codes for the IWM4MINI Macro............................................................................ 525

82. Return and Reason Codes for the IWM4MNTF Macro........................................................................... 533

83. Return and Reason Codes for the IWM4MREG Macro...........................................................................539

84. Return and Reason Codes for the IWM4MRLT Macro............................................................................548

85. Return and Reason Codes for the IWM4MSTO Macro........................................................................... 555

86. Return and Reason Codes for the IWM4MSTR Macro........................................................................... 562

87. Return and Reason Codes for the IWM4MSWC Macro.......................................................................... 569

88. Return and Reason Codes for the IWM4MUPD Macro...........................................................................575

89. Return and Reason Codes for the IWM4MXFR Macro........................................................................... 582

90. Return and Reason Codes for the IWM4MXTR Macro........................................................................... 589

91. Return codes and reason codes for the IWM4OPTQ macro..................................................................593

92. Return and Reason Codes for the IWM4QDE Macro..............................................................................598

93. Return and reason codes for the IWM4QHLT macro............................................................................. 604

94. Return and Reason Codes for the IWM4QIN Macro.............................................................................. 612

95. Return and Reason Codes for the IWM4QTNT Macro............................................................................620

96. Return and Reason Codes for the IWM4RPT Macro.............................................................................. 632

97. Return and Reason Codes for the IWM4SLI Macro............................................................................... 638

98. Return and Reason Codes for the IWM4SRSC Macro............................................................................ 648

xvi

99. Return and Reason Codes for the IWM4SSL Macro...............................................................................653

100. Return and Reason Codes for the IWM4SSM Macro........................................................................... 659

101. Return and Reason Codes for the IWM4STBG Macro..........................................................................665

102. Return and Reason Codes for the IWM4STEN Macro..........................................................................671

103. Return and Reason Codes for the IWM4TAF Macro............................................................................ 677

104. SMF record type 99 action codes.........................................................................................................681

105. SERVD application validation reason codes........................................................................................ 707

106. Valid name spaces and corresponding functionality levels................................................................ 726

107. C language interfaces........................................................................................................................... 727

108. C language interfaces for WLM sysplex routing services.....................................................................729

109. Return and Reason Codes for the IWMAEDEF Macro..........................................................................736

110. Return and Reason Codes for the IWMCLSFY Macro.......................................................................... 750

111. Return and Reason Codes for the IWMCONN Macro...........................................................................762

112. Return and Reason Codes for the IWMDISC Macro.............................................................................771

113. Return and Reason Codes for the IWMECQRY Macro......................................................................... 777

114. Return and Reason Codes for the IWMECREA Macro..........................................................................785

115. Return and Reason Codes for the IWM4EDEL Macro.......................................................................... 793

116. Return and Reason Codes for the IWMEQRY Macro............................................................................798

117. Return and Reason Codes for the IWM4MCHS Macro.........................................................................809

118. Return and Reason Codes for the IWMMCREA Macro.........................................................................817

119. Return and Reason Codes for the IWMMEXTR Macro......................................................................... 827

120. Return and Reason Codes for the IWMMINIT Macro.......................................................................... 840

121. Return and Reason Codes for the IWMMNTFY Macro......................................................................... 846

122. Return and Reason Codes for the IWMMRELA Macro......................................................................... 855

123. Return and Reason Codes for the IWMMSTOP Macro......................................................................... 861

xvii

124. Return and Reason Codes for the IWMMSTRT Macro......................................................................... 867

125. Return and Reason Codes for the IWMMUPD Macro...........................................................................877

126. Return and Reason Codes for the IWMMXFER Macro......................................................................... 883

127. Return and Reason Codes for the IWMQDEL Macro............................................................................888

128. Return and Reason Codes for the IWMQINS Macro............................................................................ 896

129. Return and Reason Codes for the IWMRPT Macro.............................................................................. 908

130. Return and Reason Codes for the IWMSLIM Macro............................................................................ 914

131. Return and Reason Codes for the IWMSSEL Macro.............................................................................920

132. Return and Reason Codes for the IWMSSEM Macro............................................................................926

133. Return and Reason Codes for the IWMSTBGN Macro......................................................................... 931

134. Return and Reason Codes for the IWMSTEND Macro......................................................................... 938

135. Return and Reason Codes for the IWMTAFF Macro.............................................................................943

xviii

About this information

This document supports z/OS (5650-ZOS). This document describes the z/OS® workload managementservices. The services are intended for programmers who write authorized programs.

This document is divided into two main parts:

• Part 1, “Using the workload management services,” on page 1, which provides an overview of theWLM services and how to use them

• Part 2, “Reference: Workload Management Services,” on page 129, which describes each service indetail, including syntax, parameters, and usage examples

Who should use this informationProgrammers using assembly language can use the macros described in this document to invoke theservices they need. This document includes some guidance information and detailed information, such asthe function, the syntax, and the parameters needed to code the macros. To understand the informationin this document, programmers should have read z/OS MVS Planning: Workload Management.

Where to find more informationWhere necessary, this document references information in other documents, using shortened versions ofthe document title. For complete titles and order numbers of the documents for all products that are partof z/OS, see z/OS Information Roadmap.

Title Order number

z/OS MVS Planning: Workload Management SC34-2662

z/OS Data Areas, Vol 1 (ABEP-DCCB) n/a

z/OS Data Areas, Vol 2 (DCCD-IEFDOKEY) n/a

z/OS Data Areas, Vol 3 (IEFDORC-ISGYQCBP) n/a

z/OS Data Areas, Vol 4 (ISGYQUAA-MCHEAD) n/a

z/OS Data Areas, Vol 5 (MCSCSA-SNAPX) n/a

z/OS MVS Initialization and Tuning Guide SA23-1379

z/OS MVS Initialization and Tuning Reference SA23-1380

z/OS MVS Programming: Authorized Assembler Services Guide SA23-1371

z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG SA23-1373

z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO SA23-1375

z/OS MVS System Management Facilities (SMF) SA38-0667

z/OS XL C/C++ Runtime Library Reference SC14-7314

Information updates on the webFor the latest information, see IBM Workload Manager for z/OS (www.ibm.com/systems/z/os/zos/features/wlm).

© Copyright IBM Corp. 1988, 2017 xix

http://www.ibm.com/systems/z/os/zos/features/wlmhttp://www.ibm.com/systems/z/os/zos/features/wlm

How to read syntax diagramsThis section describes how to read syntax diagrams. It defines syntax diagram symbols, items that maybe contained within the diagrams (keywords, variables, delimiters, operators, fragment references,operands) and provides syntax examples that contain these items.

Syntax diagrams pictorially display the order and parts (options and arguments) that comprise acommand statement. They are read from left to right and from top to bottom, following the main path ofthe horizontal line.

For users accessing the Information Center using a screen reader, syntax diagrams are provided in dotteddecimal format.

SymbolsThe following symbols may be displayed in syntax diagrams:Symbol

Definition►►───

Indicates the beginning of the syntax diagram.───►

Indicates that the syntax diagram is continued to the next line.►───

Indicates that the syntax is continued from the previous line.───►◄

Indicates the end of the syntax diagram.

Syntax itemsSyntax diagrams contain many different items. Syntax items include:

• Keywords - a command name or any other literal information.• Variables - variables are italicized, appear in lowercase, and represent the name of values you can

supply.• Delimiters - delimiters indicate the start or end of keywords, variables, or operators. For example, a left

parenthesis is a delimiter.• Operators - operators include add (+), subtract (-), multiply (*), divide (/), equal (=), and other

mathematical operations that may need to be performed.• Fragment references - a part of a syntax diagram, separated from the diagram to show greater detail.• Separators - a separator separates keywords, variables or operators. For example, a comma (,) is a

separator.

Note: If a syntax diagram shows a character that is not alphanumeric (for example, parentheses, periods,commas, equal signs, a blank space), enter the character as part of the syntax.

Keywords, variables, and operators may be displayed as required, optional, or default. Fragments,separators, and delimiters may be displayed as required or optional.Item type

DefinitionRequired

Required items are displayed on the main path of the horizontal line.Optional

Optional items are displayed below the main path of the horizontal line.Default

Default items are displayed above the main path of the horizontal line.

xx About this information

Syntax examplesThe following table provides syntax examples.

Table 1. Syntax examples

Item Syntax example

Required item.

Required items appear on the main path of thehorizontal line. You must specify these items.

KEYWORD required_item

Required choice.

A required choice (two or more items) appears ina vertical stack on the main path of the horizontalline. You must choose one of the items in thestack.

KEYWORD required_choice1

required_choice2

Optional item.

Optional items appear below the main path of thehorizontal line.

KEYWORD

optional_item

Optional choice.

An optional choice (two or more items) appearsin a vertical stack below the main path of thehorizontal line. You may choose one of the itemsin the stack.

KEYWORD

optional_choice1

optional_choice2

Default.

Default items appear above the main path of thehorizontal line. The remaining items (required oroptional) appear on (required) or below (optional)the main path of the horizontal line. The followingexample displays a default with optional items.

KEYWORD

default_choice1

optional_choice2

optional_choice3

Variable.

Variables appear in lowercase italics. Theyrepresent names or values.

KEYWORD variable

Repeatable item.

An arrow returning to the left above the mainpath of the horizontal line indicates an item thatcan be repeated.

A character within the arrow means you mustseparate repeated items with that character.

An arrow returning to the left above a group ofrepeatable items indicates that one of the itemscan be selected,or a single item can be repeated.

KEYWORD repeatable_item

KEYWORD

,

repeatable_item

Fragment.

The fragment symbol indicates that a labelledgroup is described below the main syntaxdiagram. Syntax is occasionally broken intofragments if the inclusion of the fragment wouldoverly complicate the main syntax diagram.

KEYWORD fragment

fragment

,required_choice1

,required_choice2

,default_choice

,optional_choice

About this information xxi

xxii z/OS: MVS Programming: Workload Management Services

How to send your comments to IBM

We invite you to submit comments about the z/OS product documentation. Your valuable feedback helpsto ensure accurate and high-quality information.

Important: If your comment regards a technical question or problem, see instead “If you have a technicalproblem” on page xxiii.

Submit your feedback by using the appropriate method for your type of comment or question:Feedback on z/OS function

If your comment or question is about z/OS itself, submit a request through the IBM RFE Community(www.ibm.com/developerworks/rfe/).

Feedback on IBM® Knowledge Center functionIf your comment or question is about the IBM Knowledge Center functionality, for example searchcapabilities or how to arrange the browser view, send a detailed email to IBM Knowledge CenterSupport at ibmkc@us.ibm.com.

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

To help us better process your submission, include the following information:

• Your name, company/university/institution name, and email address• The following deliverable title and order number: z/OS MVS Programming: Workload Management

Services, SC34-2663-30• The section title of the specific information to which your comment relates• The text of your comment.

When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute the commentsin any way appropriate without incurring any obligation to you.

IBM or any other organizations use the personal information that you supply to contact you only about theissues that you submit.

If you have a technical problemIf you have a technical problem or question, do not use the feedback methods that are provided forsending documentation comments. Instead, take one or more of the following actions:

• Go to the IBM Support Portal (support.ibm.com).• Contact your IBM service representative.• Call IBM technical support.

© Copyright IBM Corp. 1988, 2017 xxiii

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

xxiv z/OS: MVS Programming: Workload Management Services

Summary of changes

This information includes terminology, maintenance, and editorial changes. Technical changes oradditions to the text and illustrations for the current edition are indicated by a vertical line to the left ofthe change.

Summary of changes for z/OS Version 2 Release 3 (V2R3)The following changes are made for z/OS Version 2 Release 3 (V2R3). All technical changes for z/OS V2R3are indicated by a vertical line to the left of the change.

New

• For APAR OA52611, new SMF type 99 action code 109 is added in Appendix A, “SMF type 99 actioncodes,” on page 681.

• A functionality level in Table 106 on page 726.• The IWM4QTNT service provides CPU service consumption of tenant resource groups defined in the

WLM service definition. See “Using the IWM4QTNT service” on page 104.• IWM4QTNT is the interface reporting products should use to obtain CPU service consumption of tenant

resource groups defined in the WLM service definition. See “IWM4QTNT — Query tenant resource groupconsumption” on page 616.

Changed

• For service class periods with an average response time goal or a response time goal with percentile,the lowest goal that can be specified is changed from 15 milliseconds to 1 millisecond. The descriptionof reason code 0508, in section SVDEFPDA, is changed. See Appendix B, “Application validation reasoncodes,” on page 707.

• New fields in IWMWSYSQ describe the remaining time before capping for defined capacity limit andgroup capacity limit for all systems in the sysplex. For more information about IWMWSYSQ, see“IWMWSYSQ — Query system information” on page 388.

• Tenant report classes have been added to report class data. See “Interpreting report class data” onpage 102.

• IWMSVDEF now maps tenant report classes and tenant resource groups. See “Mapping a servicedefinition” on page 105.

• New sections SVDEFGRP, SVDEFRCL, and SVDCRRUL have been added to the Application validationreason codes. See Appendix B, “Application validation reason codes,” on page 707.

• Tenant resource groups and tenant report classes have been added to the Structure of the XML servicedefinition (DTD). See Appendix C, “Structure of the XML service definition (DTD),” on page 723.

• “IWM4CLSY — Classify work” on page 403 is updated.

Summary of changes in z/OS Version 2 Release 2 (V2R2) as updated March2017

Changed

“IWMPACT — Activate service policy” on page 256 is updated to reflect the new CHECKHISTORYparameter, which specifies the criteria that WLM applies to decide whether or not to discard historicaldata for service class periods, due to changes that come into effect with a reactivated WLM policy.

© Copyright IBM Corp. 1988, 2017 xxv

Appendix C, “Structure of the XML service definition (DTD),” on page 723 is updated to reflectHonorPriority and MemoryLimit, which support new function that allows WLM administrators to preventthe overflow of specialty-engine-intensive work, in individual service classes, to standard processors.

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

Changed

Several topics are updated for WLM support of mobile pricing. This support allows WLM administrators toclassify transactions in the WLM service definition so that they can benefit from mobile applicationpricing. The updated topics include the following:

• “Suggested services for a single address space transaction manager” on page 20• “Suggested services for a work manager that calls a data manager” on page 24• “Services for multiple address space work managers” on page 25• “Execution delay monitoring services for multiple address space work managers” on page 27• “Using the information in IWMWRCAA” on page 97• “Using the response time information” on page 102• Appendix C, “Structure of the XML service definition (DTD),” on page 723

Summary of changes for z/OS Version 2 Release 2 (V2R2)The following changes are made for z/OS Version 2 Release 2 (V2R2). All technical changes for z/OS V2R2are indicated by a vertical line to the left of the change.

New

The following new information is added in this publication:

• Service “IWM4OPTQ — Query IEAOPTxx parameters” on page 590• Service “IWM4QHLT — Query server health indicators” on page 600

Changes made in z/OS Version 2 Release 1 (V2R1) as updated December2013

Changed

• The order number for z/OS Version 2 Release 1 (5650-ZOS) has been corrected.• New SMF type 99 action codes 111-123 and 125-127 have been added in Appendix A, “SMF type 99

action codes,” on page 681.

Changes made in z/OS Version 2 Release 1See the following publications for specific enhancements for z/OS Version 2 Release 1:

• z/OS Summary of Message and Interface Changes• z/OS Introduction and Release Guide• z/OS Planning for Installation• z/OS Migration

xxvi z/OS: MVS Programming: Workload Management Services

This document contains information previously presented in z/OS MVS™ Programming: WorkloadManagement Services, SA22-7619-21 which supports z/OS Version 1 Release 13.

New information

The descriptions of the following new macros supporting 64-bit addressing were added.

• IWM4CLSY (see “IWM4CLSY — Classify work” on page 403)• IWM4EQRY (see “IWM4EQRY — Query an enclave” on page 457)• IWM4MABN (see “IWM4MABN — Monitor environment abnormal event” on page 470)• IWM4MDEL (see “IWM4MDEL — Delete delay monitoring environment” on page 495)• IWM4MXTR (see “IWM4MXTR — Monitoring environment extract service” on page 583)• IWM4MNTF (see “IWM4MNTF — Notify of work execution completion” on page 526)• IWM4MRLT (see “IWM4MRLT — Relate monitoring environments (PBs)” on page 541)• IWM4MSTO (see “IWM4MSTO — Stops a work unit” on page 550)• IWM4MSTR (see “IWM4MSTR — Indicate the start of a work unit” on page 557)• IWM4MSWC (see “IWM4MSWC — Monitoring environment switch” on page 563)• IWM4MUPD (see “IWM4MUPD — Update data for a work unit” on page 570)• IWM4MXFR (see “IWM4MXFR — Monitoring environment transfer” on page 576)• IWM4RPT (see “IWM4RPT — Report response time” on page 622)

Updated information

• The descriptions of the IWMDEXTR, IWMESTRT, IWMPACT, and IWM4ECRE macros are updated.

Moved information

The descriptions of the following macros were moved to Appendix E, “WLM services supporting 31-bitaddressing only,” on page 731.

• IWMCLSFY (see “IWMCLSFY — Classify work request” on page 738).• IWMECQRY (see “IWMECQRY — Query enclave classification attributes” on page 773).• IWMRPT (see “IWMRPT — Report on work request completion” on page 900).• IWMMABNL (see “IWMMABNL — Record abnormal event” on page 800).• IWMMDELE (see “IWMMDELE — Delete the monitoring environment” on page 818).• IWMMEXTR (see “IWMMEXTR — Monitoring environment extract” on page 822).• IWMMNTFY (see “IWMMNTFY — Notify of work execution completion” on page 841).• IWMMRELA (see “IWMMRELA — Relate monitoring environment service” on page 848).• IWMMSWCH (see “IWMMSWCH — Switch monitoring environment” on page 868).• IWMMXFER (see “IWMMXFER — Transfer monitoring environment” on page 877).• IWMMSTOP (see “IWMMSTOP — Stop a work unit” on page 856).• IWMMSTRT (see “IWMMSTRT — Indicate the start of a work unit” on page 862).• IWMMXFER (see “IWMMXFER — Transfer monitoring environment” on page 877).

Summary of changes xxvii

xxviii z/OS: MVS Programming: Workload Management Services

Part 1. Using the workload management servicesThese topics provide an overview of the workload management services.

© Copyright IBM Corp. 1988, 2017 1

2 z/OS: MVS Programming: Workload Management Services

Chapter 1. Introduction to the workload managementservices

The workload management services enable MVS to cooperate with subsystem work managers to achieveinstallation-defined goals for work, to distribute work across a sysplex, to manage servers and to providemeaningful feedback on how well workload management has achieved those goals. They also allowprograms to create an interface to define a service definition.

To change from resource-based performance management to goal-oriented workload management, manytransaction managers, data managers, and performance monitors and reporters need to take advantageof the services MVS workload management provides.

This introduction describes the services available for subsystem work managers, performance monitors,and administrative application programs.

Services for subsystem work managersThe workload management services for subsystem work managers allow an installation to process worktowards performance goals defined in a service policy. Workload management uses the informationprovided by the subsystem work managers through the services to match system resources to work tomeet goals.

A service policy contains performance goals for all kinds of MVS-managed work expressed in the sameterms. A service level administrator identifies and categorizes all of an installation's work and assigns thework performance goals in the workload management service policy. For information about how to set upand use a service policy, see z/OS MVS Planning: Workload Management.

The services provide workload management with the information it needs to dynamically adapt to matchresources to work to meet the performance goals.

Workload management matches system resources to meet the performance goal assigned to a serviceclass. This management involves handling address space-related resources, such as processor storage,multiprogramming level (MPL), dispatching, and I/O queueing.

The services for subsystem work managers can be grouped into the following categories:

• Work manager services• Execution delay services• Enclave services• Queueing manager services• Routing manager services• Scheduling environment services• Sysplex routing services• Query system information service

Why use the work manager servicesWork manager services allow MVS to recognize:

• A subsystem work manager and the transactions it processes.• The service class goals associated with the transactions.• The address spaces that are processing the transactions.

© Copyright IBM Corp. 1988, 2017 3

Based on this information, workload management can determine whether goals are being met, and whichwork needs resources to meet the goals.

The work manager services allow:

• Your customers to define performance goals to your subsystem work manager's transactions.• MVS to recognize the goals, and match resources to the work to meet the goals.• Your customers to get reports from performance monitors like RMF on how well work is executing and

whether the goals are being met.

Using the work manager services in your product allows your customers to specify goals for your work thesame way they specify them for MVS-managed work.

The work manager services allow workload management to associate incoming work with a service class.When the work is associated with a service class, MVS knows the performance goal and importance levelassociated with the work, as well as understanding which address spaces are involved in processing thework request.

If your work manager has a client-server structure and has any of the following objectives, consider usingeither the queueing manager, the routing manager, or enclave services instead of the work managerservices:

• Dynamic management of server address spaces, or• Management of server work requests as part of the originating unit of work,• Resource management and/or reporting of individual requests, or• Balancing workload among servers across a sysplex,

Table 2 on page 4 summarizes the work manager services.

Table 2. Work manager services

Service Purpose Information

IWM4CLSY Associate an arriving work request with aservice class defined in a service policy.

“IWM4CLSY — Classify work” on page403

IWMWMCON Override the subsystem name and typepreviously provided on IWM4CON.

“IWMWMCON — WLM modify connect”on page 372

IWMWQRY Obtain a service class goal. “IWMWQRY — Query service” on page378

IWM4CON Obtain token that authorizes caller touse other work manager services, andoptionally, to supply additional topologyinformation.

“IWM4CON — Connect to workloadmanagement” on page 416

IWM4DIS Disconnect from workload management. “IWM4DIS — Disconnect from workloadmanagement” on page 432

Why use the execution delay monitoring servicesFrom the execution delay monitoring services, workload management knows how well work is executing,and where any delays are occurring. The execution delay monitoring services are for complex workmanager configurations that process across systems in a sysplex, but do not allow MVS to individuallymanage resource consumption of the transactions. The services allow MVS to recognize additionaladdress spaces that are processing transactions.

When the execution delay monitoring services are used, MVS can allocate resources for address spacesbased on the behavior of the transactions being serviced by them. The services also provide executiondelay information, so that your customers can determine where work is being delayed. They can then

4 z/OS: MVS Programming: Workload Management Services

adjust the work manager configuration to consistently meet the goals. Only response time goals can beused with execution delay services. If you need to use velocity goals, discretionary goals, or period switch,consider using enclave services instead. Execution delay monitoring is mutually exclusive with enclaves inthe same address space so you must choose whichever function best suits your needs. Enclave servicesprovide more granular resource control and reporting than execution delay monito