version 2 release 3 z/os - ibm...contents figures xi tables xiii about this information.....xix
TRANSCRIPT
-
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 [email protected].
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 [email protected]. 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:[email protected]:[email protected]://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