![](http://s1.manualzz.com/store/data/047649328_1-1042b69b7b508744f09347b68530237d-128x128.png)
z/OS MVS Assembler Services Reference IAR-XCT
Add to My manuals1252 Pages
z/OS MVS Programming is a reference manual for programmers working with the IBM z/OS operating system. The manual provides detailed information on the Assembler Services available within the MVS environment. It covers topics such as addressing modes, macro versions, register usage, handling errors, and coding callable services. The manual also includes comprehensive descriptions of specific Assembler Services, including their syntax, parameters, return codes, and examples.
advertisement
![z/OS MVS Programming User Manual | Manualzz z/OS MVS Programming User Manual | Manualzz](http://s1.manualzz.com/store/data/047649328_1-1042b69b7b508744f09347b68530237d-360x466.png)
IBM z/OS
MVS Programming: Assembler Services
Reference, Volume 2 (IAR-XCT)
Version 2 Release 3
SA23-1370-30
Note
This edition applies to Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modifications until otherwise indicated in new editions.
Last updated: July 17, 2017
© Copyright IBM Corporation 1988, 2017.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . xxi
Tables . . . . . . . . . . . . . . xxiii
About this information . . . . . . . xxv
Who should use this information.
How to send your comments to IBM xxvii
If you have a technical problem.
Summary of changes. . . . . . . . xxix
Summary of changes for z/OS Version 2 Release 3 xxix
Summary of changes for z/OS Version 2 Release 2
(V2R2), as updated December, 2015 .
Summary of changes for z/OS Version 2 Release 2 xxx z/OS Version 2 Release 1 summary of changes .
||
Chapter 1. Using the services . . . . . 1
Address space control (ASC) mode .
Telling the system about the execution environment 6
Specifying a macro version number.
How to request a macro version using PLISTVER 7
Handling return codes and reason codes .
Handling environmental and system errors .
Conventional list form macros .
Alternative list form macros .
Coding the callable services .
Including equate (EQU) statements .
Link-editing linkage-assist routines .
Chapter 2. IARCP64 — 64-bit cell pool services . . . . . . . . . . . . . . 25
© Copyright IBM Corp. 1988, 2017
Chapter 4. IARST64 — 64-bit storage services . . . . . . . . . . . . . . 47
Chapter 5. IARVSERV — Request to share virtual storage . . . . . . . . . 63
iii
Chapter 6. IARV64 — 64–bit virtual storage allocation . . . . . . . . . . 77
REQUEST=GETSTOR option of IARV64 .
REQUEST=PAGEOUT option of IARV64 .
REQUEST=PAGEIN option of IARV64 .
REQUEST=DISCARDDATA option of IARV64 .
REQUEST=CHANGEGUARD option of IARV64 102
REQUEST=DETACH option of IARV64.
iv
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 7. IDENTIFY — Add an entry name . . . . . . . . . . . . . . . 115
Chapter 8. IEAARR — Establish an associated recovery routine (ARR) . . 119
Chapter 9. IEABRC — Relative branch macro . . . . . . . . . . . . . . 125
Chapter 10. IEABRCX — Relative branch macro extension. . . . . . . 127
Chapter 11. IEAFP — Floating point services. . . . . . . . . . . . . . 131
||
|
Guarded-Storage Facility services . . 135
Chapter 13. IEAINTKN — Build incident token . . . . . . . . . . . 143
Chapter 14. IEALSQRY — Linkage stack query . . . . . . . . . . . . 147
Chapter 15. IEAMETR — Query external time reference status . . . . 151
Chapter 16. IEANTCR — Create a name/token pair . . . . . . . . . . 155
Chapter 17. IEANTDL — Delete a name/token pair . . . . . . . . . . 161
Chapter 18. IEANTRT — Retrieve the token from a name/token pair . . . . 165
Chapter 19. IEAN4CR — Create a name/token pair . . . . . . . . . . 171
Chapter 20. IEAN4DL — Delete a name/token pair . . . . . . . . . . 177
Contents
v
Chapter 21. IEAN4RT — Retrieve the token from a name/token pair . . . . 181
Chapter 22. IEATDUMP — Transaction dump request . . . . . . . . . . . 185
Chapter 23. IEATXDC — Transactional execution diagnostic controls . . . . 205
Allocate_Pause_Element . . . . . . 209
vi
z/OS MVS Assembler Services Reference IAR-XCT
Allocate_Pause_Element . . . . . . 213
Deallocate_Pause_Element . . . . . 221
Deallocate_Pause_Element . . . . . 225
Chapter 28. IEAVPME2 — pause multiple elements service . . . . . . 229
Chapter 29. IEAVPSE — Pause service 237
Chapter 30. IEAVPSE2 — Pause service . . . . . . . . . . . . . . 243
Chapter 31. IEAVRLS — Release . . . 249
Chapter 32. IEAVRLS2 — Release. . . 255
Retrieve_Pause_Element_Information service . . . . . . . . . . . . . . 261
Retrieve_Pause_Element_Information service . . . . . . . . . . . . . . 267
Test_Pause_Element service . . . . . 273
Chapter 36. IEAVXFR — Transfer service . . . . . . . . . . . . . . 277
Contents
vii
Chapter 37. IEAVXFR2 — Transfer service . . . . . . . . . . . . . . 283
Allocate_Pause_Element . . . . . . 289
Allocate_Pause_Element . . . . . . 293
Deallocate_Pause_Element . . . . . 299
Deallocate_Pause_Element . . . . . 303
viii
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 42. IEA4PME2 — 64-bit pause multiple elements service . . . . . . 307
Chapter 43. IEA4PSE — Pause service 315
Chapter 44. IEA4PSE2 — Pause service . . . . . . . . . . . . . . 321
Chapter 45. IEA4RLS — Release . . . 327
Chapter 46. IEA4RLS2 — Release. . . 331
Chapter 50. IEA4XFR — Transfer service . . . . . . . . . . . . . . 353
Retrieve_Pause_Element_Information service . . . . . . . . . . . . . . 337
Chapter 51. IEA4XFR2 — Transfer service . . . . . . . . . . . . . . 359
Retrieve_Pause_Element_Information service . . . . . . . . . . . . . . 343
Chapter 52. IEFDDSRV — DD service 365
||
|
Chapter 53. IEFOPZQ — Query the
IEFOPZ configuration . . . . . . . . 379
Test_Pause_Element service . . . . . 349
Chapter 54. IEFPRMLB — Logical parmlib support . . . . . . . . . . 391
REQUEST=ALLOCATE option of IEFPRMLB.
Contents
ix
REQUEST=FREE option of IEFPRMLB .
REQUEST=LIST option of IEFPRMLB .
REQUEST=READMEMBER option of IEFPRMLB 413
Chapter 55. IEFSSI — Dynamically query a subsystem . . . . . . . . . 421
REQUEST=QUERY parameter of IEFSSI .
Parameters for REQUEST=QUERY .
Chapter 56. IOCINFO — Obtain MVS
I/O configuration information . . . . 429
Chapter 57. IOSCHPD — IOS CHPID description service . . . . . . . . . 437
x
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 58. IOSCUMOD — IOS control unit entry build service . . . . . . . 445
Chapter 59. IOSSCM — Storage class memory information . . . . . . . . 449
Chapter 60. ISGENQ — Global resource serialization ENQ service . . 455
Chapter 61. ISGQUERY — Global resource serialization query service . 489
Chapter 62. ITTUINIT — Activate external CTRACE recording . . . . . 519
Chapter 63. ITTUTERM — End external CTRACE recording . . . . . 523
Chapter 64. ITTUWRIT — Queue a group of CTRACE entries . . . . . . 527
Chapter 65. ITZEVENT — Transaction trace EVENT record . . . . . . . . 531
Chapter 66. ITZQUERY — Transaction trace query . . . . . . . . . . . . 541
Browse/read a log stream . . . . . . 547
REQUEST=START option of IXGBRWSE .
Parameters for REQUEST=START .
Syntax for REQUEST=READCURSOR .
Parameters for REQUEST=READCURSOR.
REQUEST=READBLOCK option of IXGBRWSE 562
Parameters for REQUEST=READBLOCK .
REQUEST=RESET option of IXGBRWSE .
Parameters for REQUEST=RESET .
REQUEST=END option of IXGBRWSE .
Connect/disconnect to log stream . . 593
Contents
xi
Chapter 69. IXGDELET — Deleting log data from a log stream . . . . . . . 617
Chapter 70. IXGIMPRT — Import log blocks . . . . . . . . . . . . . . 635
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set . 653
REQUEST=DEFINE TYPE=LOGSTREAM option of IXGINVNT .
REQUEST=DEFINE,TYPE=LOGSTREAM .
REQUEST=DEFINE TYPE=STRUCTURE option of IXGINVNT .
REQUEST=DEFINE,TYPE=STRUCTURE .
REQUEST=UPDATE option of IXGINVNT .
Parameters for REQUEST=UPDATE .
REQUEST=CHECKDEF option of IXGINVNT 702
Parameters for REQUEST=CHECKDEF .
xii
z/OS MVS Assembler Services Reference IAR-XCT
REQUEST=DELETE option of IXGINVNT .
Parameters for REQUEST=DELETE .
Chapter 72. IXGOFFLD — Initiate offload to DASD log data sets . . . . 759
Chapter 73. IXGQUERY — Query a log stream for information . . . . . . . 769
Chapter 74. IXGUPDAT — Update log stream control information . . . . . 781
Chapter 75. IXGWRITE — Write log data to a log stream . . . . . . . . 791
LINKX — Pass control to a program in another load module.
Chapter 77. LOAD — Bring a load module into virtual storage . . . . . 823
Chapter 78. LSEXPAND — Expand the linkage stack capacity . . . . . . . 831
Chapter 79. PGLOAD — Load virtual storage areas into central storage . . 835
Chapter 81. PGRLSE — Release virtual storage contents . . . . . . . 843
Contents
xiii
Chapter 82. PGSER — Page services 847
Chapter 83. POST — Signal event completion . . . . . . . . . . . . 853
Chapter 85. REFPAT — Define and end a reference pattern . . . . . . . 863
xiv
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 86. RESERVE — Reserve a device (shared DASD). . . . . . . . 871
Chapter 87. RETURN — Return control . . . . . . . . . . . . . . 883
Chapter 88. SAVE — Save register contents . . . . . . . . . . . . . 885
Chapter 89. SETRP — Set return parameters . . . . . . . . . . . . 887
Dump virtual storage and continue . . 895
SNAPX — Dump virtual storage and continue .
Chapter 91. SPIE — Specify program interruption exit . . . . . . . . . . 911
Chapter 92. SPLEVEL — Set macro level . . . . . . . . . . . . . . . 917
Chapter 93. STAE — Specify task abnormal exit . . . . . . . . . . . 921
Chapter 94. STATUS — Start and stop a subtask . . . . . . . . . . . . . 927
Chapter 95. STCKCONV — Store clock conversion routine . . . . . . . . . 933
Contents
xv
Chapter 96. STCKSYNC — Store clock synchronous service . . . . . . . . 941
Chapter 97. STIMER — Set interval timer . . . . . . . . . . . . . . . 945
Chapter 98. STIMERM — Set, test, cancel multiple interval timer . . . . 951
xvi
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 99. STORAGE — Obtain and release storage . . . . . . . . . . 965
Input register information for
Output register information for
Input register information for LINKAGE=SVC 967
Output register information for LINKAGE=SVC 967
Examples of the OBTAIN and RELEASE options 981
Chapter 100. SYMRBLD — Building a symptom record . . . . . . . . . . 983
Return and reason codes (for SYMRBLD
Chapter 101. SYMREC — Process a symptom record . . . . . . . . . 1003
Chapter 102. SYNCH and SYNCHX —
Take a synchronous exit to a processing program . . . . . . . . 1011
SYNCHX - Take a synchronous exit to a processing program .
SYNCH and SYNCHX—Execute form .
Chapter 103. SYSEVENT — System event . . . . . . . . . . . . . . 1019
Chapter 104. SYSSTATE — Identify system state . . . . . . . . . . . 1021
Chapter 105. TCBTOKEN — Request or translate the TTOKEN . . . . . . 1027
Chapter 106. TESTART — Tests the validity of ALETs . . . . . . . . . 1033
Chapter 107. TIME — Obtain time and date . . . . . . . . . . . . . 1037
Contents
xvii
LINKAGE=SYSTEM - Execute form .
Chapter 108. TIMEUSED — Obtain accumulated CPU or vector time . . 1049
Chapter 109. TRANMSG — Translate messages . . . . . . . . . . . . 1055
xviii
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 110. TTIMER — Test interval timer . . . . . . . . . . . . . . 1069
EBCDIC device number for a UCB . . 1073
Chapter 112. UCBINFO — Return information from a UCB . . . . . . 1077
UCBINFO DEVCOUNT—Execute form .
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
UCBINFO DEVINFO - Execute form .
UCBINFO GETCDR - Execute form .
UCBINFO HYPERPAVALIASES - List form .
UCBINFO HYPERPAVALIASES - Execute form 1100
UCBINFO PATHINFO - List form .
UCBINFO PATHINFO - Execute form .
UCBINFO PATHMAP - Execute form .
UCBINFO PAVINFO - Execute form .
UCBINFO PRFXDATA - List form .
UCBINFO PRFXDATA - Execute form .
UCBs . . . . . . . . . . . . . . 1127
Chapter 114. UPDTMPB — Update a message parameter block for substitution data . . . . . . . . . 1141
Chapter 115. VRADATA — Update variable recording area data . . . . 1147
Chapter 116. WAIT — Wait for one or more events . . . . . . . . . . . 1153
Contents
xix
Chapter 117. WTL — Write to log 1159
Chapter 118. WTO- Write to operator 1167
Chapter 119. WTOR - Write to operator with reply . . . . . . . . 1183
xx
z/OS MVS Assembler Services Reference IAR-XCT
XCTLX - Pass control to a program in another load module .
Examples of passing data to the target module 1207
Appendix. Accessibility . . . . . . 1209
Consult assistive technologies .
Keyboard navigation of the user interface .
Dotted decimal syntax diagrams .
Notices . . . . . . . . . . . . . 1213
Terms and conditions for product documentation 1215
IBM Online Privacy Statement .
Policy for unsupported hardware .
Programming interface information .
Index . . . . . . . . . . . . . . 1219
Figures
Sample User Parameter List for Callers in AR
Sample tabular syntax diagram for the TEST macro .
Return Code Area Used by RESERVE 876
© Copyright IBM Corp. 1988, 2017
xxi
xxii
z/OS MVS Assembler Services Reference IAR-XCT
Tables
||
|
||
|
Passing User Parameters in AR Mode .
Execution environment characteristics and corresponding SYSSTATE parameters and global symbols .
Return and Reason Codes for the IARCP64
Return and Reason Codes for the IARR2V
Return and Reason Codes for the IARST64
Return and Reason Codes for the IARVSERV
Return and Reason Codes for the IARV64
Return and reason codes for the IEAFP macro 133
Return and reason codes for the IEAGSF macro .
Return Codes for the IEAMETR Macro
Return and Reason Codes for the IEATDUMP
Return codes for the IEATXDC Macro 207
Checkpoint/Restart Toleration - only available when the CVTPAUS4 bit is set in the CVT. .
Checkpoint/Restart Toleration - only available when the CVTPAUS4 bit is set in the CVT. .
Checkpoint/Restart Toleration - only available when the CVTPAUS4 bit is set in the CVT. .
Return and reason codes for the IEFDDSRV macro .
Return and reason codes for the IEFOPZQ macro .
Return and Reason Codes for the IEFPRMLB
Return and Reason Codes for the IEFSSI
Return and reason codes for the IOSCHPD macro .
Return and reason codes for the IOSSCM macro .
Return and Reason Codes for the ISGENQ
Return and Reason Codes for the ISGQUERY
Return and Reason Codes for the ITZEVENT
Return and Reason Codes for the ITZQUERY
Return and Reason Codes for the IXGBRWSE
Return and reason codes for the IXGCONN macro .
Return and Reason Codes for the IXGDELET
Return and Reason Codes for the IXGIMPRT
Valid special (graphical) characters: .
Valid special (graphical) characters: .
Return and Reason Codes for the IXGINVNT
Return and Reason Codes for the IXGINVNT
Return and Reason Codes for the IXGOFFLD
Return and Reason Codes for the IXGQUERY
Return and Reason Codes for the IXGUPDAT
Return and reason codes for the IXGWRITE macro .
Return and Reason Codes for the LSEXPAND
Return Codes for the RESERVE Macro with the RET=TEST Parameter .
Return Codes for the RESERVE Macro with the RET=USE Parameter .
Return Codes for the RESERVE Macro with the RET=HAVE Parameter .
Return and Reason Codes for the STAE
Return Codes for the STATUS Macro
Return Codes for the STCKCONV Macro
Return Codes for the STCKSYNC Macro
Return Codes for the STIMERM Macro
Return Codes for STORAGE OBTAIN
Return Codes for the STORAGE RELEASE 981
Valid SDB Key Names and Literals .
Valid Section 5 Key Names and Literals
Return codes for the TCBTOKEN macro
Return Codes for the TESTART Macro
Return Codes for the TIME Macro
Return and Reason Codes for the
Return Codes for the TTIMER Macro
MCSFLAG Flag Names for WTO Macro
MCSFLAG Flag Names for WTOR Macro
© Copyright IBM Corp. 1988, 2017
xxiii
xxiv
z/OS MVS Assembler Services Reference IAR-XCT
About this information
This information describes some of the macros (or macro instructions) that the system provides. The macros described in this information are available to any assembler language program.
Programmers who code in assembler language can use these macros to invoke the system services that they need. This document includes the detailed information — such as the function, syntax, and parameters — needed to code the macros.
Who should use this information
This information is for any programmer who is coding an assembler language program. However, if the program runs with APF authorization, runs in supervisor state or runs with with system key 0-7, runs in supervisor state or with system key
0-7, or if it performs functions that are more system than application-oriented, the programmer should also refer to the following documents: v
z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
v
z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG
v
z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU
v
z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
Programmers using this information should have a knowledge of the computer, as described in Principles of Operation, as well as a knowledge of assembler language programming.
System macros require High Level Assembler. For more information about assembler language programming, see High Level Assembler and Toolkit Feature in IBM Knowledge Center (www.ibm.com/support/knowledgecenter/SSENW6).
Using this information also requires you to be familiar with the operating system and the services that programs running under it can invoke.
How to use this information
This information is one of the set of programming documents for MVS
™
. This set describes how to write programs in assembler language or high-level languages, such as C, FORTRAN, and COBOL. For more information about the content of this set of documents, see z/OS Information Roadmap.
z/OS information
This information explains how z/OS references information in other documents and on the web.
When possible, this information uses cross document links that go directly to the topic in reference using shortened versions of the document title. For complete titles and order numbers of the documents for all products that are part of z/OS, see z/OS Information Roadmap.
To find the complete z/OS
® library, go to IBM Knowledge Center
(www.ibm.com/support/knowledgecenter/SSLTBW/welcome).
© Copyright IBM Corp. 1988, 2017
xxv
xxvi
z/OS MVS Assembler Services Reference IAR-XCT
How to send your comments to IBM
We appreciate your input on this documentation. Please provide us with any feedback that you have, including comments on the clarity, accuracy, or completeness of the information.
Use one of the following methods to send your comments:
Important:
If your comment regards a technical problem, see instead “If you have a technical problem.”
v Send an email to [email protected].
v
Send an email from the Contact z/OS web page (www.ibm.com/systems/z/os/ zos/webqs.html).
Include the following information: v Your name and address v Your email address v Your phone or fax number v The publication title and order number: z/OS MVS Assembler Services Reference IAR-XCT
SA23-1370-30 v The topic and page number or URL of the specific information to which your comment relates v The text of your comment.
When you send comments to IBM
®
, you grant IBM a nonexclusive right to use or distribute the comments in 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 the issues that you submit.
If you have a technical problem
Do not use the feedback methods that are listed for sending comments. Instead, take one or more of the following actions: v
Visit the IBM Support Portal (support.ibm.com).
v Contact your IBM service representative.
v Call IBM technical support.
© Copyright IBM Corp. 1988, 2017
xxvii
xxviii
z/OS MVS Assembler Services Reference IAR-XCT
Summary of changes
This information includes terminology, maintenance, and editorial changes.
Technical changes or additions to the text and illustrations for the current edition are indicated by a vertical line to the left of the change.
Summary of changes for z/OS Version 2 Release 3
The following information is new, changed, or deleted in z/OS Version 2 Release 3
(V2R3).
New
v The USE2GTO32G and USE2GTO64G parameters have been added in
“REQUEST=GETSTOR option of IARV64” on page 80.
v
Additional AMODE descriptions has been added to “LOAD description” on page 823.
v A description has been added to the CALLRKY=YES storage key to the
“OBTAIN option of STORAGE” on page 966section.
v Programming description and access register contents for AR has been added to
the Chapter 108, “TIMEUSED — Obtain accumulated CPU or vector time,” on page 1049section.
v Added new EXECUTABLE parameter for API IARV64 to the
“REQUEST=GETSTOR option of IARV64” on page 80 section.
v
Changed
v
The DUPLEXMODE(DRXRC) is removed from “Parameters for
REQUEST=DEFINE,TYPE=LOGSTREAM” on page 659 and “Parameters for
v
The STG_SIZE is updated in “Parameters for
REQUEST=DEFINE,TYPE=LOGSTREAM” on page 659 and “Parameters for
Summary of changes for z/OS Version 2 Release 2 (V2R2), as updated
December, 2015
The following changes are made for z/OS Version 2 Release 2 (V2R2), as updated
December, 2015. In this revision, all technical changes for z/OS V2R2 are indicated by a vertical line to the left of the change.
New
v IARV64 has a new SADMP parameter for REQUEST=GETSTOR.
v The following callable services have been added:
– Chapter 28, “IEAVPME2 — pause multiple elements service,” on page 229
– Chapter 42, “IEA4PME2 — 64-bit pause multiple elements service,” on page
v
The IEFOPZQ macro has been added in Chapter 53, “IEFOPZQ — Query the
IEFOPZ configuration,” on page 379.
© Copyright IBM Corp. 1988, 2017
xxix
v IXGWRITE has a new return code 08, reason code xxxx084E.
Changed
v IARCP64 REQUEST=FREE now accepts the INPUT_CPID parameter.
v Restrictions are updated for the following callable services:
– Chapter 24, “IEAVAPE — Allocate_Pause_Element,” on page 209
– Chapter 38, “IEA4APE — Allocate_Pause_Element,” on page 289
– Chapter 25, “IEAVAPE2 — Allocate_Pause_Element,” on page 213
– Chapter 39, “IEA4APE2 — Allocate_Pause_Element,” on page 293.
Summary of changes for z/OS Version 2 Release 2
The following information is new, changed, or deleted in z/OS Version 2 Release 2
(V2R2).
New
v
The PAGEFRAMESIZE parameter has been added in “REQUEST=GETSTOR option of IARV64” on page 80.
v
v
Option REQUEST=CHECKDEF was added to Chapter 71, “IXGINVNT —
Managing the LOGR inventory couple data set,” on page 653.
Changed
v Information about the environment, parameters, and return and reason codes
has been updated in Chapter 52, “IEFDDSRV — DD service,” on page 365.
v Information about the CHPID parameter and reason codes has been updated in
Chapter 57, “IOSCHPD — IOS CHPID description service,” on page 437.
v The description of the information returned in register 1 has been updated in
Chapter 77, “LOAD — Bring a load module into virtual storage,” on page 823.
v Information is updated for the LOGSTREAM LS_ALLOCAHEAD attribute and
log stream offload processing in Chapter 71, “IXGINVNT — Managing the
LOGR inventory couple data set,” on page 653.
z/OS Version 2 Release 1 summary of changes
See the Version 2 Release 1 (V2R1) versions of the following publications for all enhancements related to z/OS V2R1: v
z/OS Migration
v
z/OS Planning for Installation
v
z/OS Summary of Message and Interface Changes
v
z/OS Introduction and Release Guide
xxx
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 1. Using the services
Macros and callable services are programming interfaces that application programs can use to access MVS system services. This chapter provides general information and guidelines about how to use the macros and callable services accurately and efficiently. For more specific and detailed information about coding a particular macro or callable service, see the individual service description in this information.
Some of the topics covered in this chapter apply only to macros, some apply only to callable services, and some apply to both. This chapter uses the word "services" when referring to information that applies to both service types. When information applies only to one type or the other, the particular service type is specified.
Note:
z/OS macros do not code to restrictions that are imposed by the
COMPAT(CASE) HLASM option or its abbreviation CPAT(CASE). Therefore, you cannot rely on using COMPAT(CASE) if you use z/OS macros.
The following table lists the topics covered in this chapter and whether the topic applies to macros, callable services, or both:
Topic
“Addressing mode (AMODE)” on page 2
“Address space control (ASC) mode” on page 3
“ALET qualification” on page 4
“Telling the system about the execution environment” on page 6
“Specifying a macro version number” on page 7
“Handling return codes and reason codes” on page 9
“Handling program errors” on page 9
“Handling environmental and system errors” on page 10
“Coding the macros” on page 13
“Coding the callable services” on page 16
“Including equate (EQU) statements” on page 17
“Link-editing linkage-assist routines” on page 17
Service Type
Macros
Both
Both
Both
Macros
Macros
Macros
Both
Both
Both
Both
Macros
Macros
Macros
Callable Services
Callable Services
Callable Services
Both
Compatibility of MVS macros
When IBM introduces a new version or a new release of an existing version, the new version or release supports all MVS macros from previous versions and releases. Programs assembled on an earlier level of MVS that issue macros will run on later levels of MVS.
In most cases, the reverse is also true. When you assemble programs that issue macros on a particular version and release of MVS, those programs can run on earlier versions and releases of MVS, provided you request only those functions
© Copyright IBM Corp. 1988, 2017
1
that are supported by the earlier version and release. This is useful for installations that write applications that might be assembled on one level of MVS, but run on a different level.
As MVS supports new architectures, addressability changes. To take best advantage of the new architectures, some macros have more than one possible expansion. You are required to have the macro expand according to the environment in which the program runs. This topic is described in this introductory information.
The problem of compatibility is not the same as selecting a macro version through the PLISTVER parameter to ensure the correct parameter list size for a macro. For
selecting a parameter list version number, see “Specifying a macro version number” on page 7.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Addressing mode (AMODE)
A program can run in addressing mode (AMODE) 24, 31, or 64. A program that executes in AMODE 24 or 31can invoke most of the services described in this information. A program that executes in AMODE 64 has a smaller group of services that it can invoke.
In general: v A program running in AMODE 24 cannot pass parameters or parameter addresses that are higher than 16 megabytes. However, there are exceptions. For example, a program running in AMODE 24 can:
– Free storage above 16 megabytes using the FREEMAIN macro
– Allocate storage above 16 megabytes using the GETMAIN macro
– Use cell pool services for cell pools located in storage above 16 megabytes using the CPOOL macro
– Use page services for storage locations above 16 megabytes using the PGSER macro v A program is allowed to call a service from AMODE 64 only if the documentation for the service indicates that it supports AMODE 64.
v A program is allowed to call a service from RMODE 64 only if the documentation for the service indicates that it supports RMODE 64.
v A program running in AMODE 64 should not call a service with data, parameters, or parameter addresses that are higher than 2 gigabytes, unless the individual service description indicates that it is allowed.
v If a program running in AMODE 31 or 64 issues a service, parameters and parameter addresses can be above or below 16 megabytes, unless otherwise stated in the individual service description.
Some macros can generate code that is appropriate for programs in either AMODE
64 or 24 or 31. These macros check a global symbol set by the SYSSTATE macro.
See “Telling the system about the execution environment” on page 6 for more
information.
When you call a callable service in AMODE 24 or 31, you must pass 31-bit addresses to the system service regardless of what addressing mode your program is running in. If your program is running in AMODE 24 and you use a callable service, you must set the high-order byte of parameter addresses to zeros.
2
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
You can invoke the following services in 64-bit addressing mode, subject to the
“SVC or PC” restrictions mentioned later in this topic, but you cannot pass parameters and parameter addresses above 2 gigabytes: ABEND, ATTACHX,
CALLDISP, CHAP, CSVQUERY, DELETE, DEQ, DETACH, DOM, DSPSERV,
DYNALLOC, ENQ, ESPIE, ESTAEX, EXCP, FREEMAIN, GETMAIN, GTRACE,
IARVSERV, IDENTIFY, IEAARR, LINKX, LOAD, MODESET, PGSER, POST,
RESERVE, SDUMPX, SETRP, STAX, STIMER, STIMERM, STORAGE, SYNCHX,
TIME, TIMEUSED, TTIMER, VRADATA, WAIT, WTO, WTOR, and XCTL.
There are many services that support AMODE 64 and parameter addresses above 2 gigabytes. Examples are IRAV64, IARST64, and ISGENQ. For details on the supported addressing mode and parameter address ranges for any specific service, see the following books: v
z/OS MVS Programming: Assembler Services Reference ABE-HSP
v
z/OS MVS Programming: Assembler Services Reference IAR-XCT
v
z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
v
z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG
v
z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU
v
z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
v
z/OS MVS Programming: Sysplex Services Reference
Before invoking a service in AMODE 64, you must inform system macros, by specifying SYSSTATE AMODE=64. You can invoke only those options that result in calling the system by an SVC or PC in AMODE 64. You cannot invoke any option that results in calling the system by a branch-entry in AMODE 64.
Unless explicitly stated otherwise, assume that a given service cannot be invoked in AMODE 64 and cannot accept data, parameters, or parameter addresses above 2 gigabytes. Such an explicit statement would include a specific reference to AMODE
64 in a macro’s environment section and additional information would mention that data, parameters, and parameter addresses could be above 2 gigabytes. By contrast, an AMODE specification of "Any" means that the macro can be invoked in either AMODE 24 or 31; it does not mean that the macro can be invoked in
AMODE 64.
For information about AMODE 64 and the 64-bit GPR, see z/OS MVS Programming:
Assembler Services Guide.
Address space control (ASC) mode
A program can run in either primary ASC mode or access register (AR) ASC mode.
In primary mode, the processor uses the contents of general purpose registers
(GPRs) to resolve an address to a specific location. In AR mode, the processor uses the contents of ARs as well as the contents of GPRs to resolve an address to a specific location. See z/OS MVS Programming: Assembler Services Guide for more detailed information about AR mode.
Some macros can generate code that is appropriate for programs in either primary mode or AR mode. These macros check a global symbol set by the SYSSTATE
macro. See “Telling the system about the execution environment” on page 6 for
more information. Table 3 on page 18 lists the macros that check the global symbol.
Some services can generate code that is appropriate for programs in primary mode only. If you write a program in AR mode that invokes one or more services, check
Chapter 1. Using the services
3
the description in this information for each service your program issues. Unless the description indicates that a service supports callers in AR mode, the service does
not support callers in AR mode. In this case, use the SAC instruction to change the
ASC mode of your program and issue the service in primary mode.
Whether the caller is in primary or AR ASC mode, the system uses ARs 0-1 and
14-15 as work registers across any service call.
ALET qualification
The address space where you can place parameters varies with the individual service: v You can place parameters in the primary address space in all service.
v You must place parameters in the primary address space in some services.
v
You can place parameters in any address space in some services.
To identify where you can locate parameters in a service, read the individual service description.
Programs in AR mode that pass parameters must use an access register and the corresponding general purpose register together (for example, access register 1 and general purpose register 1) to identify where the parameters are located. The access register must contain an access list entry token (ALET) that identifies the address space where the parameters reside. The general purpose register must identify the location of the parameters within the address space.
The only ALETs that MVS services typically accept are: v
Zero (0), which specifies that the parameters are in the caller's primary address space v An ALET for a public entry on the caller's dispatchable unit access list (DU-AL) v An ALET for a common area data space (CADS)
MVS services do not accept the following ALETs, and you cannot attempt to pass them to a service: v One (1), which signifies that the parameters are in the caller's secondary address space v An ALET that is on the caller's primary address space access list (PASN-AL) that does not represent a CADS
Throughout, this information uses the term AR/GPR n to mean an access register and its corresponding general purpose register. For example, to identify access register 1 and general purpose register 1, this information uses AR/GPR 1.
User parameters
Some macros that you can issue in AR mode include control parameters, user parameters, or both. Control parameters refer to the macro parameter list, and the parameters whose addresses are in the parameter list. Control parameters control the operation of the macro itself. User parameters are parameters that a user provides to be passed through to a user routine. For example, the PARAM parameter on the ATTACHX macro defines user parameters. The ATTACHX macro passes these parameters to the routine that it attaches. All other parameters on the
ATTACHX macro are control parameters that control the operation of the
ATTACHX macro.
Note:
4
z/OS MVS Assembler Services Reference IAR-XCT
1.
User parameters are sometimes referred to as problem program parameters.
2.
Control parameters are sometimes referred to as system parameters or control program parameters.
The macros shown in Table 1 allow a caller in AR mode to pass information in the
form of a parameter list (or parameter lists) to another routine. This table identifies the parameter that receives the ALET-qualified address of the parameter list and tells you where the target routine finds the ALET-qualified address.
Table 1. Passing User Parameters in AR Mode
Macro Parameter
PARAM,VL=1
ATTACH/ATTACHX
CALL
LINK/LINKX
XCTL/XCTLX
Location of User Parameter List Address
AR/GPR 1 contains the address of a list of addresses. When either v a 4-bytes-per-entry parameter list or v an 8-bytes-per-entry parameter list with
PLIST8ARALETS=YES
ESTAEX PARAM is being used, this list also contains the ALETs
associated with those addresses. (See Figure 1
for the format of the 4-bytes-per-entry parameter list when it contains ALETs.)
SDWAPARM contains the address of an 8-byte area, which contains the address and ALET of the parameter list.
When an AR mode caller who is using a 4-bytes-per-entry parameter list passes
ALET-qualified addresses to the called program through PARAM,VL=1 on the
ATTACH/ATTACHX, CALL, LINK/LINKX, or XCTL/XCTLX macros, the system
builds a list formatted as shown in Figure 1. The addresses passed to the called
program are at the beginning of the list, and their associated ALETs follow the addresses. The last address in the list has the high-order bit on to indicate the end
of the list. For example, Figure 1 shows the format of a list where an AR mode
issuer of ATTACHX who is using a 4-bytes-per-entry parameter list has coded the
PARAM parameter as follows:
PARAM=(A,B,C),VL=1
When an AR mode caller who is using an 8-bytes-per-entry parameter list specifies
PLIST8ARALETS=YES, the system builds a parameter list with the 8-byte addresses at the beginning of the list and their associated 4-byte ALETs following the addresses.
GPR1
AR1
@
ALET
0
@A
0 @B
1 @C
ALET A
ALET B
ALET C
Figure 1. Sample User Parameter List for Callers in AR Mode
For information about linkage conventions, see the chapter in z/OS MVS
Programming: Assembler Services Guide.
Chapter 1. Using the services
5
Telling the system about the execution environment
To generate code that is correct for the environment in which the program runs, some macros need to know one or more of the following characteristics about that environment: v The addressing mode (AMODE) at the time the macro is issued v The ASC mode of the program at the time the macro is issued v The architectural level in which the program runs
For macros that are sensitive to their environment, use the SYSSTATE macro to define the environment. During the assembly stage, SYSSTATE sets one or more global symbols. Later, in your source code, the macro checks the global symbols and generates the correct code, which might mean avoiding using a z/Architecture
®
instruction or an access register. Table 3 on page 18 lists MVS
macros and identifies macros that need to know the environmental characteristics.
IBM recommends
you issue the SYSSTATE macro before you issue other macros.
Once a program has issued SYSSTATE, there is no need to reissue it, unless the program switches from one AMODE to another or one ASC mode to another or has code paths that are isolated according to architecture level or operating system release. If you switch AMODE or ASC mode to a different architecture code path, issue SYSSTATE immediately after the switch to indicate the new state. In general, specify SYSSTATE ARCHLVL=2, and switch to SYSSTATE ARCHLVL=3 before issuing macros in sections of code that only run when z/OS 2.1 capabilities are available. If you do not issue the SYSSTATE macro, the system assumes the macro is issued as follows: v
In AMODE other than 64-bit v In primary ASC mode v Usually, in ESA/390 architectural level (but may assume z/Architecture level since all supported z/OS releases require z/Architecture level)
Table 2 describes the relevant characteristics, the corresponding parameters on the
SYSSTATE macro, and the global symbols the macro checks.
Table 2. Execution environment characteristics and corresponding SYSSTATE parameters and global symbols
Characteristic
AMODE of 64-bit, or either 24-bit or 31-bit
Primary or AR ASC mode
Architectural level of z/Architecture
Operating system release
Parameter on SYSSTATE
AMODE64=YES or NO
ASCENV=P or AR
ARCHLVL=0, 1, 2, 3 or OSREL
ZOSVvRr
Global symbol
&SYSAM64
&SYSASCE
&SYSALVL
&SYSOSREL
You can issue the SYSSTATE macro with the TEST parameter in your own user-written macro to allow your macros to generate code appropriate for their execution environment.
Callable services do not check the global symbols described in this topic. To determine whether a callable service is sensitive to the AMODE, ASC mode, or the
Architecture level, see the description of the individual callable service.
In early releases of MVS, the SPLEVEL macro performs a function similar to
SYSSTATE. The SPLEVEL macro identifies the level of the operating system, so that you can tune a macro expansion based on that level. You can use this where
6
z/OS MVS Assembler Services Reference IAR-XCT
macro expansions change incompatibly. Because SPLEVEL applies to levels that the system no longer supports, it is not described in this topic.
Specifying a macro version number
Often there is more than one version of a macro, differentiated by additional parameters or new or expanded function. For example, version 1 of the IXGCONN macro provides a connection to a log stream, while version 2 adds new parameters in support of resource manager programs. This is different than using the
SPLEVEL macro to select a macro version level to solve problems of downward compatibility.
You can request a specific version of a macro based on the parameters you need to use in your application, but you should also be attuned to the storage constraints of the program. The version of a macro might affect the length of the parameter list generated when the macro is assembled, because when you add new parameters to a macro, the parameter list must be large enough to fit them. The size of the parameter list might grow from release to release of z/OS, perhaps affecting the amount of storage your program needs.
How to request a macro version using PLISTVER
Many macros that have one or more versions supply the PLISTVER parameter. For those that do, use the PLISTVER parameter to request a version of the macro.
PLISTVER is the only parameter allowed on the list form of a macro (MF), and it determines which parameter list the system generates. PLISTVER is optional. If you omit it, the system generates a parameter list for the lowest version that will accommodate the parameters specified. This is the IMPLIED_VERSION default.
Note that on the list form, the default will cause the smallest parameter list to be created.
You can also code a specific version number using plistver, or specify MAX: v You can use plistver to code a decimal value corresponding to the version of the macro you require. The decimal value you provide determines the amount of storage allotted for the parameter list.
v You can use MAX to request that the system generate a parameter list for the highest version number currently available. The amount of storage allotted for the parameter list will depend on the level of the system on which the macro is assembled.
IBM recommends
, if your program can tolerate additional growth, that you always specify PLISTVER=MAX on the list form of the macro. MAX ensures that the list form parameter list is always long enough to hold whatever parameters might be specified on the execute form when both forms are assembled using the save level of the system.
Hints for using PLISTVER
There are some general considerations that you should keep in mind when specifying the version of a macro with PLISTVER: v If PLISTVER is omitted, the macro generates a parameter list of the lowest version that allows all the parameters specified to be processed.
v If you code PLISTVER=n and then specify any version ‘n+1’ parameter, the macro will not assemble.
v If you code PLISTVER=n and do not specify any version ‘n’ parameter, the macro will generate a version ‘n’ parameter list.
Chapter 1. Using the services
7
v If you are using the standard form of the macro (MF=S), there is no reason you need to code the PLISTVER parameter.
v
Not all macros have the same version numbers. The version numbers need not be contiguous.
The PLISTVER parameter appears in the syntax diagram and in the parameter descriptions. Within each macro description, the PLISTVER parameter description specifies the range of values and lists the parameters applicable for each version of the macro.
Register use
Some services require that the caller place information in specific general purpose registers (GPRs) or access registers (ARs) prior to issuing the service. If a service has such a requirement, the “Input Register Information” topic for the service provides that information. The topic lists only those registers that have a requirement. If a register is not specified as having a requirement, then the caller does not have to place any information in that register unless using it in register notation for a particular parameter, or using it as a base register.
Once the caller issues the service, the system can change the contents of one or more registers, and leave the contents of other registers unchanged. When control returns to the caller, each register contains one of the following values or has the following status: v The register content is preserved and is the same as it was before the service was issued.
v The register contains a value placed there by the system for the caller's use.
Examples of such values are return codes and tokens.
v The system used the register as a work register. Do not assume that the register content is the same as it was before the service was issued.
Note that the system uses ARs 0, 1, 14, and 15 as work registers for every service, regardless of whether the caller is in primary or AR address space control (ASC) mode. The system does not use ARs 2 through 13 for any service.
For more information about linkage conventions for a calling program’s registers, see the "Saving the calling program’s registers" topic in the "Linkage conventions" chapter in z/OS MVS Programming: Assembler Services Guide.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Many macros require that the caller have a program base register and assembler
USING instruction in effect when issuing the macro; that is, the caller must have
program addressability. AR mode programs also require that the AR associated with the caller's base GPR be set to zero. IBM recommends the following: v When issuing a macro, the caller should always have program addressability in effect.
v
When establishing addressability, the caller should use only registers 2 through
12.
8
z/OS MVS Assembler Services Reference IAR-XCT
Many macros can take advantage of relative branching when they are used with the IEABRC macro or with SYSSTATE ARCHLVL=1 or SYSSTATE ARCHLVL=2, if they are running on z/OS. If relative branching is used, the caller might then need addressability only to the static data portion of the program, and not to the executable code.
Handling return codes and reason codes
Most of the services described in this information provide return codes and reason codes. Return and reason codes indicate the outcome of the service in one of the following ways: v Successful completion: you do not need to take any action.
v Successful or partially successful completion, with additional information supplied: you should evaluate the additional information in light of your particular program and determine if you need to take any action.
v Unsuccessful completion: some type of error has occurred, and you must take some action to correct the error.
The errors that cause unsuccessful completion fall into three broad categories:
Program errors
Errors that your program causes: you can correct these.
Environmental errors
Errors not caused directly by your program; rather, your program's request caused a limit to be exceeded, such as a storage limit, or the limit on the size of a particular data set. You might or might not be able to correct these.
System errors
Errors caused by the system: your program did nothing to cause the error, and you probably cannot correct these.
In some cases, a return or reason code can result from some combination of these errors.
The return and reason code descriptions for the services in this information indicate whether the error is a program error, an environmental error, a system error, or some combination. Whenever possible, the return and reason code descriptions give you a specific action that you can take to fix the error.
IBM recommends
that you read all the return and reason codes for each service that your program issues. You can then design your program to handle as many errors as possible. When designing your program, you should allow for the possibility that future releases of MVS might add new return and reason codes to a service that your program issues.
Handling program errors
The actions to take in the case of program errors are usually straightforward.
Typical examples of program errors are:
1.
Breaking one of the rules of the service. For example: v Passing parameters that are either in the wrong format or not valid v
Violating one of the environment requirements (addressing mode, locking requirements, dispatchable unit mode, and so on) v Providing insufficient storage for information to be returned by the system.
Chapter 1. Using the services
9
2.
Causing errors related to the parameter list. For example: v Coding an incorrect combination of parameters v Coding one or more parameters on the service incorrectly v Inadvertently overlaying an area of the parameter list storage v Inadvertently destroying the pointer to the parameter list.
3.
Requesting a service or function for which the calling program is not authorized, or which is not available on the system on which the program is running.
In each of the first two cases, you can correct your program. For completeness, the return and reason code descriptions give you specific actions to perform, even when it might seem obvious what the action should be.
In the third case, you might have to contact your system administrator or system programmer to obtain the necessary authorization, or to request that the service or function be made available on your system, and the return or reason code description asks you to take that step.
Note:
Generally, the system does not take dumps for errors that your program causes when issuing a system service. If you require such a dump, then it is your responsibility to request one in your recovery routine. See the topic on providing recovery in z/OS MVS Programming: Assembler Services Guide for information about writing recovery routines.
Handling environmental and system errors
With environmental errors, often your first action should be to rerun your program or retry the request one or more times. The following are examples of environmental errors where rerunning your program or retrying the request is appropriate: v The request being made through the service exceeds some internal system limit.
Sometimes, rerunning your program or retrying the request results in successful completion. If the problem persists, it might be an indication of a larger problem requiring you to consult your system programmer, or possibly IBM support personnel. Your system programmer might be able to tune the system or cancel users so that the limit is no longer exceeded.
v The request exceeds an installation-defined limit. If the problem persists, the action might be to contact your system programmer and request that a specification in an installation exit or parmlib member be modified.
v
The system cannot obtain storage, or some other resource, for your request. If the problem persists, the action might be to check with the operator to see if another user in the installation is causing the problem, or to see if the entire installation is experiencing storage constraint problems.
You might be able to design your program to anticipate certain environmental errors and handle them dynamically.
With system errors, as with environmental errors, often your first action should be to rerun your program or retry the request one or more times. If the problem persists, you might have to contact IBM support personnel.
Whenever possible for environmental and system errors, the return or reason code description gives you either a specific action you can take, or a list of recommended actions you can try.
10
z/OS MVS Assembler Services Reference IAR-XCT
For some errors, providing a specific action is not possible, because the action you should take depends on your particular application, and on what is happening in your installation. In those cases, the return or reason code description gives you one or more possible causes of the error to help you to determine what action to take.
Some system errors result in return and reason codes that are provided for IBM diagnostic purposes only. In these cases, the return or reason code description asks you to record the information and provide it to the appropriate IBM support personnel.
Using X-macros
Some MVS services support callers in both primary and AR ASC mode. When the caller is in AR mode, macros must generate larger parameter lists; the increased size of the list reflects the addition of ALETs to qualify addresses, as described
under “ALET qualification” on page 4. For some MVS macros, two versions of a
particular macro are available: one for callers in primary mode and one for callers in AR mode. The name of the macro for the AR mode caller is the same as the name of the macro for primary mode callers, except the AR mode macro name ends with an “X”. This information refers to these macros as X-macros.
The X-macros described in this information are: v ATTACHX v ESTAEX v LINKX v
SNAPX v
SYNCHX v XCTLX
The only way these macros know that a caller is in AR mode is by checking the global symbol that the SYSSTATE macro sets. Each of these macros (and corresponding non-X-macro) checks the symbol. If SYSSTATE ASCENV=AR has been issued, the macro issues code that is valid for callers in AR mode. If it has not been issued, the macro generates code that is not valid for callers in AR mode.
When your program returns to primary mode, use the SYSSTATE ASCENV=P macro to reset the global symbol.
IBM recommends
that you use the X-macro regardless of whether your program is running in primary or AR mode. However, you should consider the following before deciding which macro to use:
The rules for using all X-macros, except ESTAEX, are: v Callers in primary mode can invoke either macro.
Some parameters on the X-macros, however, are not valid for callers in primary mode. Some parameters on the non-X-macros are not valid for callers in AR mode. Check the macro descriptions for these exceptions.
v Callers in AR mode should issue the X-macros.
If a caller in AR mode issues the non-X-macro, the system substitutes the
X-macro and sends a message describing the substitution.
IBM recommends
you always use ESTAEX unless your program and your recovery routine are in 24-bit addressing mode, in which case, you should use
ESTAE.
Chapter 1. Using the services
11
Macro forms
You can code most macros in three forms: standard, list, and execute. Some macros also have a modify form. When you code a macro, you use the MF parameter to select one of the forms. The list, execute and modify forms are for reenterable programs that need to change values in the parameter list of the macro. The standard form is for programs that are not reenterable, or for programs that do not change values in the parameter list.
When a program wants to change values in the parameter list of a macro, it can make the change dynamically.
However, using the standard form and changing the parameter list dynamically might cause errors. For example, after storing a new value into the inline, standard form of the parameter list, a reenterable program operating under a given task might be interrupted by the system before the program can invoke the macro. In a multiprogramming environment, another task can use the same reenterable program, and that task might change the inline parameter list again before the first task regains control. When the first task regains control, it invokes the macro.
However, the inline parameter list now has the wrong values.
Through the use of the different macro forms, a program that runs in a multiprogramming environment can avoid errors related to reenterable programs.
The techniques required for using the macro forms, however, are different for some macros, called alternative list form macros, than for most other macros. For the alternative list form macros, the list form description notes that different
Conventional list form macros
With conventional list form macros, you can use the macro forms as follows:
1.
Use the list form of the macro, which expands to the parameter list. Place the list form in the section of your program where you keep non-executable data, such as program constants. Do not code it in the instruction stream of your program.
2.
In the instruction stream, code a GETMAIN or a STORAGE macro to obtain some virtual storage.
3.
Code a move character instruction that moves the parameter list from its non-executable position in your program into the virtual storage area that you obtained.
4.
For macros that have a modify form, you can code the modify form of the macro to change the parameter list. Use the address parameter of the modify form to reference the parameter list in the virtual storage area that you obtained. Thus, the parameter list that you change is the one in the virtual storage area obtained by the GETMAIN or STORAGE macro.
5.
Invoke the macro by issuing the execute form of the macro. Use the address parameter of the execute form to reference the parameter list in the virtual storage area that you obtained.
With this technique, the parameter list is safe even if the first task is interrupted and a second task intervenes. When the program runs under the second task, it cannot access the parameter list in the virtual storage of the first task.
12
z/OS MVS Assembler Services Reference IAR-XCT
Alternative list form macros
Certain macros, called alternative list form macros, require a somewhat different technique for using the list form. With these macros, you do not move the area defined by the list form into virtual storage that you have obtained; instead, you place the area defined by the list form into a DSECT. Also, it is the list form, not the execute form, that you use to specify the address parameter that identifies the address of the storage for the parameter list. Note that no modify form is available for these macros.
You can use the macro forms for the alternative list form macros as follows:
1.
Use the list form of the macro to define an area of storage that the execute form can use to store the parameters. As with other macros, do not code the list form in the instruction stream of your program.
2.
In the instruction stream, code a GETMAIN or a STORAGE macro to obtain virtual storage for the list form expansion.
3.
Place the area defined by the list form into a DSECT that maps a portion of the virtual storage you obtained.
4.
Invoke the macro by issuing the execute form of the macro. The address parameter specified on the list form references the parameter list in the virtual storage area that you obtained.
Coding the macros
In this information, each macro description includes a syntax diagram near the beginning of the macro description. The diagram shows how to code the macro.
The syntax diagram does not explain the meanings of the parameters; the meanings are explained in the parameter descriptions that follow the syntax diagram. For most macros, the syntax diagrams are in a tabular format; however, some newer macros might have syntax diagrams in the railroad track format.
The syntax tables assume that the standard begin, end, and continue columns are used. Thus, column 1 is assumed as the begin column. To change the begin, end, and continue columns, use the ICTL instruction to establish the coding format you want to use. If you do not use ICTL, the assembler recognizes the standard columns. For more information about coding the ICTL instruction, see High Level
Assembler and Toolkit Feature in IBM Knowledge Center (www.ibm.com/ support/knowledgecenter/SSENW6).
Figure 2 on page 14 shows a sample macro called TEST and summarizes all the
coding information that is available for it. The table is divided into three zones, A,
B, and C.
Chapter 1. Using the services
13
A
B
C
A1
A2
B1
B2
name
b
TEST b
name:
symbol. Begin
name
in column 1.
One or more blanks must precede TEST.
One or more blanks must follow TEST.
MATH
HIST
GEOG
,DATA=
data addr data addr:
RX-type address, or register (2) - (12)
,LNG=
data length
data length: symbol or decimal digit, with a maximum value of 256.
,FMT=HEX
,FMT=DEC
,FMT=BIN
,PASS=
value
,grade
Default: FMT=HEX
value:
symbol, decimal digit, or register (1) or (2) - (12).
Default: PASS=65
grade: symbol, decimal digit, or register (1) or (2) - (12).
Figure 2. Sample tabular syntax diagram for the TEST macro
v Column one of the table contains zones A and B. Zone A begins at the left margin; zone B is indented from the left margin by one or more blank spaces.
Column two of the table contains zone C.
v Zone A and zone B contain those parameters that are allowed for the macro.
Zone A contains those parameters that are required; zone B contains those parameters that are optional.
v If a parameter appears on a single line in the diagram (that is, a line whose preceding line and following line are both blank), as shown in A1 and B1, then that is the only available choice for the particular parameter.
v If two or more parameters appear on adjacent lines (that is, with no intervening blank lines), as shown in A2 and B2, the parameters on those lines are mutually exclusive, that is, you can code any one of those parameters.
v A further distinction is made between mandatory and optional parameters. The parameter descriptions that follow the syntax table clearly identify those parameters which are optional.
v
Zone C (which is the second column in the syntax table), provides additional information about coding the macro.
When substitution of a variable is indicated in zone C, the following classifications are used:
Variable
Classification
14
z/OS MVS Assembler Services Reference IAR-XCT
symbol
Any symbol valid in the assembler language. The symbol can be as long as the supported maximum length of a name entry in the assembler you are using.
Decimal digit
Any decimal digit up to and including the value indicated in the parameter description. If both symbol and decimal digit are indicated, an absolute expression is also allowed.
Register (2) - (12)
One of general purpose registers 2 through 12, specified within parentheses, previously loaded with the right-adjusted value or address indicated in the parameter description. You must set the unused high-order bits to zero. You can designate the register symbolically or with an absolute expression.
Register (0)
General purpose register 0, previously loaded with the right-adjusted value or address indicated in the parameter description. You must set the unused high-order bits to zero. Designate the register as (0) only.
Register (1)
General purpose register 1, previously loaded with the right-adjusted value or address indicated in the parameter description. You must set the unused high-order bits to zero. Designate the register as (1) only.
Register (15)
General purpose register 15, previously loaded with the right-adjusted value or address indicated in the parameter description. You must set the unused high-order bits to zero. Designate the register as (15) only.
RX-type address
Any address that is valid in an RX-type instruction (for example, LA).
RS-type address
Any address that is valid in an RS-type instruction (for example, STM).
RS-type name
Any name that is valid in an RS-type instruction (for example, STM).
A-type address
Any address that can be written in an A-type address constant.
Default
A value that is used in default of a specified value; that is, the value the system assumes if the parameter is not coded.
Rules for parameters:
Use the parameters to specify the services and options to be performed, and write them according to the following rules: v If the selected parameter is written in all capital letters (for example, MATH,
HIST, or FMT=HEX), code the parameter exactly as shown.
v If the selected parameter is written in italics (for example, grade), substitute the indicated value, address, or name.
v If the selected parameter is a combination of capital letters and italics separated by an equal sign (for example, DATA=data addr), code the capital letters and equal sign as shown, and then make the indicated substitution for the italicized portion.
v Read the table from top to bottom.
v Code commas and parentheses exactly as shown.
Chapter 1. Using the services
15
v Positional parameters (parameters without equal signs) appear first; you must code them in the order shown. You may code keyword parameters (parameters with equal signs) in any order.
v If you select a parameter, read the second column (zone C) before proceeding to the next parameter. The second column often contains coding restrictions for the parameter.
Continuation lines
You can continue the parameter field of a macro on one or more additional lines according to the following rules: v Enter a continuation character (not blank, and not part of the parameter coding) in column 72 of the line.
v Continue the parameter field on the next line, starting in column 16. All columns to the left of column 16 must be blank.
You can code the parameter field being continued in one of two ways. Code the parameter field through column 71, with no blanks, and continue in column 16 of the next line; or truncate the parameter field by a comma, where a comma normally falls, with at least one blank before column 71, and then continue in
column 16 of the next line. Figure 3 shows an example of each method.
1
10 16
44 72
NAME 1
NAME 2
OP1 OPERAND1,OPERAND2,OPERAND3,OPERAND4,OPERAND5,OPERAND6,OPX
ERAND7
THIS IS ONE WAY
OP2 OPERAND1,OPERAND2
OPERAND3,OPERAND4,
THIS IS ANOTHER WAY
X
X
OPERAND5,OPERAND6,OPERAND7
Figure 3. Continuation Coding
Coding the callable services
A callable service is a programming interface that uses the CALL macro to access system services. To code a callable service, code the CALL macro followed by the name of the callable service, and a parameter list; for example:
CALL service,(parameter list)
Syntax
The syntax diagram for the sample callable service SCORE:
Description
CALL SCORE
,(test_type
,level
,data
,format_option
,return_code)
Considerations for coding callable services are:
16
z/OS MVS Assembler Services Reference IAR-XCT
v You must code all the parameters in the parameter list because parameters are positional in a callable service interface. That is, the function of each parameter is determined by its position with respect to the other parameters in the list.
Omitting a parameter, therefore, assigns the omitted parameter's function to the next parameter in the list.
v You must place values explicitly into all input parameters, because callable services do not set default values.
v You can use the list and execute forms of the CALL macro to preserve your program's reentrancy.
Including equate (EQU) statements
IBM supplies sets of equate (EQU) statements for use with some callable services.
These statements, which you may optionally include in your source code, provide constants for use in your program. IBM provides the statements as a programming convenience to save you the trouble of coding the definitions yourself.
Note:
Check the “Programming Requirements” section of the individual service description to determine if the equate statements are available for the callable service you are using. If the equate statements are available, that section will also provide a list of the statements that are provided, along with a description of how to include them in your program.
Link-editing linkage-assist routines
Linkage-assist routines provide the connection between your program and the system services that your program requests. When using callable services, link-edit the appropriate linkage-assist routines into your program module so that, during execution, the linkage-assist routines can resolve the address of, and pass control to, the requested system services. You can also dynamically link to linkage-assist routines as an alternative to link-editing. For example, issue the LOAD macro for the linkage-assist routine, then issue a CALL to the loaded addresses.
To invoke the linkage-editor or binder, code JCL as in the following example:
//userid JOB ’accounting-info’,’name’,CLASS=x,
// MSGCLASS=x,NOTIFY=userid,MSGLEVEL=(1,1),REGION=4096K
//LINKSTEP EXEC PGM=HEWL,
// PARM=’LIST,LET,XREF,REFR,RENT’
//SYSPRINT DD SYSOUT=x
//SYSLMOD DD DSN=userid.LOADLIB,DISP=OLD
//SYSLIB DD DSN=SYS1.CSSLIB,DISP=SHR
//OBJLIB DD DSN=userid.OBJLIB,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(5,2))
//SYSLIN DD *
INCLUDE OBJLIB(userpgm)
ENTRY userpgm
NAME userpgm(R)
/*
Note:
Omitting NCAL from the linkedit parameters (as the example shows) and specifying SYS1.CSSLIB in the //SYSLIB statement, as shown, causes the addresses of all required linkage-assist routines to be automatically resolved. This statement saves you the trouble of having to specify individual linkage-assist routines in
INCLUDE statements.
Chapter 1. Using the services
17
Service summary
Table 3 lists services described in the following:
v
z/OS MVS Programming: Assembler Services Reference ABE-HSP
v
z/OS MVS Programming: Assembler Services Reference IAR-XCT
For each service, the table indicates: v Whether a program in AR ASC mode can issue the service v Whether a program in cross memory mode can issue the service v Whether the macro checks the SYSSTATE global macro variables v Whether the macro can be issued in 64-bit addressing mode
Note:
1.
A program running in primary ASC mode when PASN=HASN=SASN can issue any of the services listed in the table.
2.
Cross memory mode means that at least one of the following conditions is true:
PASN¬=SASN
The primary address space (PASN) and the secondary address space
(SASN) are different.
PASN¬=HASN
The primary address space (PASN) and the home address space
(HASN) are different.
SASN¬=HASN
The secondary address space (SASN) and the home address space
(HASN) are different.
For more information about functions that are available to programs in cross memory mode, see z/OS MVS Programming: Extended Addressability Guide.
3.
Callable services do not check the SYSSTATE or SPLEVEL global variables.
Table 3. Service Summary
Service
ABEND
ALESERV
ASASYMBM
ATTACH
ATTACHX
BLDMPB
BLSABDPL
BLSACBSP
BLSADSY
BLSAPCQE
BLSQFXL
BLSQMDEF
BLSQMFLD
BLSQSHDR
Can be issued in AR ASC mode
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Can be issued in cross memory mode
Checks
SYSSTATE
Yes
Yes
No
No
Yes
No
Yes
Yes
Yes
No
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
Yes
No
No
No
No
No
No
No
No
No
Can be issued in 64-bit
AMODE
Yes
No
No
No
18
z/OS MVS Assembler Services Reference IAR-XCT
Table 3. Service Summary (continued)
Service Can be issued in AR ASC mode
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
No
Yes
Yes
No
Yes
Yes
No
Yes
Yes
Yes
No
No
Yes
No
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
CPUTIMER
CSRCESRV
CSRCMPSC
CSREVW
CSRIDAC
CSRL16J
CSRPACT
CSRPBLD
CSRPCON
CSRPDAC
CSRPDIS
CSRPEXP
CSRPFRE
CSRPFR1
CSRPGET
CSRPGT1
CSRPQCL
CSRPQEX
CSRPQPL
CSRPRFR
CSRPRFR1
CSRPRGT
BLSRDRPX
BLSRESSY
BLSRNAMP
BLSRPRD
BLSRPWHS
BLSRSASY
BLSRXMSP
BLSRXSSP
BLSUPPR2
CALL
CHAP
CNZCONV
CNZTRKR
CONVCON
CONVTOD
CPOOL
Can be issued in cross memory mode
Checks
SYSSTATE
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
No
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
Yes
No
Yes
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
No
No
No
Yes
N/A
Yes
No
No
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
Can be issued in 64-bit
AMODE
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
Yes
Yes
Yes
No
No
No
No
No
No
No
No
Chapter 1. Using the services
19
CSVINFO
CSVQUERY
DELETE
DEQ
DETACH
DIV
DOM
DSPSERV
EDTINFO
ENQ
ESPIE
ESTAE (See note
ESTAEX
EVENTS
FREEMAIN
Table 3. Service Summary (continued)
Service
CSRPRGT1
CSRREFR
CSRSAVE
CSRSCOT
CSRSI
CSRUNIC
CSRVIEW
CSVAPF
Can be issued in AR ASC mode
Yes
Yes
No
Yes
No
Yes
No
No
Yes
No
No
No
Yes
No
No
No
No
Yes
No
GETMAIN
GQSCAN
HSPSERV
Yes
No
No
Yes
No
No
No
Yes
No
Yes
No
No
Yes
No
No
No
Can be issued in cross memory mode
Checks
SYSSTATE
Yes
Yes
No
Yes
Yes
No
No
No
N/A
N/A
N/A
N/A
No
No
N/A
Yes
Yes
No
Yes
Yes
Yes
No
Yes
Yes
IARCP64
IARR2V
IARST64
IARVSERV
IARV64
IDENTIFY
IEAARR
IEABRC
IEAINTKN
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
No
Yes
No
No
Yes
No
No
Yes
Yes
No
Yes
N/A
Yes
No
Yes
No
Yes
Yes
No
No
Yes
Yes
No
No
No
Yes
Yes
Yes
No
Yes
No
Yes
Yes
No
No
Yes
Yes
No
Yes
Yes
Yes
No
Yes
Yes
No
Can be issued in 64-bit
AMODE
No
No
No
No
No
No
No
No
20
z/OS MVS Assembler Services Reference IAR-XCT
Table 3. Service Summary (continued)
Service Can be issued in AR ASC mode
No
No
No
No
No
No
No
No
No
Yes
Yes
No
No
No
No
No
No
No
No
Yes
Yes
No
No
No
No
No
No
No
No
No
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
IEAVRPI2
IEAVTPE
IEAVXFR
IEAVXFR2
IEA4APE
IEA4APE2
IEA4DPE
IEA4DPE2
IEA4PSE
IEA4PSE2
IEA4RLS
IEA4RLS2
IEA4RPI
IEA4RPI2
IEA4TPE
IEA4XFR
IEA4XFR2
IEFDDSRV
IEFSSI
IOCINFO
IOSCHPD
ITZEVENT
IEALSQRY
IEAMETR
IEANTCR
IEANTDL
IEANTRT
IEATDUMP
IEATXDC
IEAVAPE
IEAVAPE2
IEAVDPE
IEAVDPE2
IEAVPSE
IEAVPSE2
IEAVRLS
IEAVRLS2
IEAVRPI
Can be issued in cross memory mode
Checks
SYSSTATE
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
Yes
Yes
No
No
No
No
No
No
No
No
No
Yes
Yes
N/A
N/A
N/A
Yes
Yes
No
Can be issued in 64-bit
AMODE
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
No
Yes
Yes
Yes
Yes
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
No
Yes
No
No
No
No
No
Chapter 1. Using the services
21
Table 3. Service Summary (continued)
Service
ITZQUERY
IXGBRWSE
IXGCONN
IXGDELET
IXGIMPRT
IXGINVNT
IXGOFFLD
IXGQUERY
IXGUPDAT
IXGWRITE
LINK
LINKX
LOAD
LSEXPAND
PGLOAD
PGOUT
PGRLSE
PGSER
POST
QRYLANG
REFPAT
RESERVE
RETURN
SAVE
SETRP
SNAP
SNAPX
SPIE
SPLEVEL
STAE
STATUS
STCKCONV
STCKSYNC
STIMER
STIMERM
STORAGE
SYMRBLD
Can be issued in AR ASC mode
Yes
Yes
Yes
No
Yes
No
Yes
No
Yes
Yes
No
No
No
No
No
No
No
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
No
No
No
No
Yes
No
No
No
No
Yes
No
No
No
No
Yes
Yes
Yes
No
No
No
Yes
No
No
Yes
Yes
Can be issued in cross memory mode
Checks
SYSSTATE
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
No
No
No
Yes
Yes
No
No
No
No
Yes
No
No
No
No
No
Yes
No
Yes
No
No
No
No
No
Yes
22
z/OS MVS Assembler Services Reference IAR-XCT
No
No
No
Yes
No
No
No
No
Yes
Yes
No
Can be issued in 64-bit
AMODE
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
No
No
No
Yes
No
No
Yes
No
No
No
Yes
Yes
Yes
Yes
No
No
TIMEUSED
TRANMSG
TTIMER
UCBDEVN
UCBINFO
UCBSCAN
UPDTMPB
VRADATA
WAIT
WTL
WTO
WTOR
XCTL
XCTLX
Table 3. Service Summary (continued)
Service
SYMREC
SYNCH
SYNCHX
SYSSTATE
TCBTOKEN
TESTART
TIME
Can be issued in AR ASC mode
Can be issued in cross memory mode
Yes
Yes
Yes
Yes
Yes
Yes
No
No
No Yes
No
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
No
Yes
Yes
Yes
Yes
No
No
No
No
Yes
Yes Yes
Yes
No
No
No
Checks
SYSSTATE
Yes
Yes
Yes
No
No
No
No
No
No
No
No
Yes
Yes
Yes
Yes
No
Yes
No
No
No
No
Notes:
1.
Callers can use either macro in the following macro pairs:
ATTACH or ATTACHX
LINK or LINKX
SNAP or SNAPX
SYNCH or SYNCHX
XCTL or XCTLX
IBM recommends
that all callers in AR mode use the X-macros (ATTACHX,
LINKX, SNAPX, SYNCHX, and XCTLX). If a program in AR mode issues
ATTACH, LINK, SNAP, SYNCH, or XCTL after issuing SYSSTATE
ASCENV=AR, the system substitutes the corresponding X-macro and issues a message telling you that it made the substitution.
2.
The only programs that can use ESTAE are programs that are in primary mode with PASN=HASN=SASN. Callers in AR mode or in cross memory mode must use ESTAEX instead of ESTAE.
IBM recommends
you always use ESTAEX unless your program and your recovery routine are in 24-bit addressing mode, in which case, you should use
ESTAE.
3.
Problem state AR mode callers must use the STORAGE macro instead of using
GETMAIN or FREEMAIN.
Chapter 1. Using the services
23
Yes
No
Yes
Yes
Yes
No
No
No
No
No
Yes
No
Yes
No
Can be issued in 64-bit
AMODE
No
No
Yes
No
No
No
Yes
4.
PASN=HASN=SASN for a non-shared standard hiperspace for which an ALET is not used (the HSPALET parameter is omitted).
5.
If you use the HSPALET parameter, the HSPSERV macro checks SYSSTATE.
6.
Only TIME LINKAGE=SYSTEM can be issued in AR mode, and can be issued in cross memory mode. TIME LINKAGE=SVC cannot be issued in AR mode or in cross memory mode.
7.
For the QUERY request, CSVAPF can be issued only in primary mode. For all other requests, CSVAPF can be issued in primary or AR mode.
24
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 2. IARCP64 — 64-bit cell pool services
Description
Use IARCP64 to request 64-bit cell pool services.
With IARCP64, you can request to: v Build a pool (REQUEST=BUILD).
v Obtain a cell from the pool (REQUEST=GET).
v Return a cell to the pool (REQUEST=FREE).
v Delete the pool (REQUEST=DELETE).
Note:
There is diagnostic support for 64-bit cell pools in IPCS by way of the
CBFORMAT command. CBF cpid STR(IAXCPHD) formats the cell pool header, where
cpid is the cell pool identifier that was returned on IARCP64 REQUEST=BUILD. If you cannot locate your cell pool identifier in the dump, simply browse storage starting at X’100000000’ and issue a FIND on CPHD. There are multiple cell pools, so you must look at the cell contents to make sure that you have the right pool. To see details about all of the cells in the pool, use the EXIT option as follows: CBF
cpid STR(IAXCPHD) EXIT .
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and PSW key 8-15. For IARCP64
REQUEST=GET, FREE or DELETE, the caller must be able to modify the storage for the cell pool. That means the caller must be in the same key as the cell pool or the cell pool must be in the public key (key 9). Supervisor state is required for the TRACE=YES option. APF authorization has no bearing on these services.
Task or SRB
Any PASN, any HASN, any SASN
64-bit
Primary or access register (AR)
Enabled for interrupts.
For the BUILD and DELETE requests, no locks can be held.
For the GET request, the following locks must be held by the caller or must be obtainable by IARCP64: v For requests with EXPAND=NO, the caller might hold locks but is not required to hold any.
v For requests with COMMON=NO and EXPAND=YES, the caller might hold the local lock (LOCAL or CML) of the current primary address space.
For the FREE request, the caller might hold locks but is not required to hold any.
Control parameters must be in the primary address space.
© Copyright IBM Corp. 1988, 2017
25
IARCP64 macro
Programming requirements
Specify SYSSTATE AMODE64=YES before invoking this macro.
Restrictions
None.
Input register information
Before issuing the IARCP64 macro, the caller does not have to place any information into any general-purpose register (GPR) or access register (AR) unless using it in register notation for a particular parameter, or by using it as a base register.
Output register information
When control returns to the caller, the 64-bit GPRs contain:
1
2-13
14
15
For REQUEST=BUILD:
Register
Contents
0
Reason code in the low 32 bits if the return code is not 0. Otherwise, used as a work register by the system.
Used as a work register by the system.
Unchanged.
Used as a work register by the system.
Return code in the low 32 bits.
13
14
15
For REQUEST=GET:
Register
Contents
0
Reason code in the low 32 bits if the return code is not 0. Otherwise, used as a work register by the system.
1
2-12
The address of the obtained cell.
Unchanged if ReGS=SAVE was specified, used as work registers by the system if ReGS=USE was specified.
Unchanged.
Used as a work register by the system.
Return code in the low 32 bits.
For REQUEST=FREE:
Register
Contents
0-1
2-12
Used as a work register by the system.
Unchanged if ReGS=SAVE was specified, used as work registers by the system if ReGS=USE was specified.
13
Unchanged.
14-15
Used as a work register by the system.
26
z/OS MVS Assembler Services Reference IAR-XCT
⌂
Syntax
name
IARCP64 macro
For REQUEST=DELETE:
Register
Contents
0-1
2-13
Used as a work register by the system.
Unchanged.
14-15
Used as work registers by the system.
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system.
Unchanged.
14-15
Used as work registers by the system.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the IARCP64 macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede IARCP64.
IARCP64
⌂ One or more blanks must follow IARCP64.
REQUEST=BUILD
REQUEST=GET
REQUEST=FREE
REQUEST=DELETE
,HEADER=header
,CELLSIZE=cellsize
header: RS-type address or address in register (2) - (12)
cellsize: RS-type address or address in register (2) - (12)
Chapter 2. IARCP64 — 64-bit cell pool services
27
IARCP64 macro
Syntax
,OUTPUT_CPID=output_cpid
,COMMON=NO
,OWNINGTASK=CURRENT
,OWNINGTASK=MOTHER
,OWNINGTASK=IPT
,OWNINGTASK=JOBSTEP
,OWNINGTASK=CMRO
,DUMP=LIKERGN
,DUMP=LIKELSQA
,DUMP=NO
,DUMPPRIO=dumpprio
,OWNINGASID=owningasid
,FPROT=YES
,FPROT=NO
,TYPE=PAGEABLE
,CALLERKEY=YES
,TRAILER=COND
,TRAILER=YES
,TRAILER=NO
,FAILMODE=RC
,FAILMODE=ABEND
,INPUT_CPID=input_cpid
,CELLADDR=celladdr
,EXPAND=YES
,EXPAND=NO
Description
output_cpid: RS-type address or address in register (2) - (12)
dumpprio: RS-type address or address in register (2) - (12)
owningasid: RS-type address or address in register (2) - (12)
input_cpid: RS-type address or address in register (2) - (12)
celladdr: RS-type address or address in register (2) - (12)
,TRACE=YES
,TRACE=NO
28
z/OS MVS Assembler Services Reference IAR-XCT
IARCP64 macro
Syntax Description
,CELLNAME=cellname
,CELLADDR=celladdr
,REGS=SAVE
,REGS=USE
cellname: RS-type address or address in register (2) - (12)
celladdr: RS-type address or address in register (2) - (12)
,INPUT_CPID=input_cpid
,RETCODE=retcode
,RSNCODE=rsncode
input_cpid: RS-type address or address in register (2) - (12)
retcode: RS-type address or register (2) - (12), (GPR15), (REG15), or (R15).
rsncode: RS-type address or register (2) - (12), (GPR0), (GPR00), (REG0),
(REG00), or (R0).
,PLISTVER=IMPLIED_VERSION
Default:
PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
Default:
MF=S
list addr: RS-type address or register (1) - (12)
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1 that is the name on the IARCP64 macro invocation. The name must conform to the rules for an ordinary assembly language symbol.
REQUEST=BUILD
REQUEST=GET
REQUEST=FREE
REQUEST=DELETE
A required parameter that indicates the type of request.
REQUEST=BUILD
Request to build the pool. The initial pool size is 1 MB. The CELLSIZE and
TRAILER specifications determine how many available cells are in the pool.
REQUEST=GET
Request to obtain a cell from the pool.
Chapter 2. IARCP64 — 64-bit cell pool services
29
IARCP64 macro
REQUEST=FREE
Request to return a cell to the pool.
Note:
This request is unconditional and will abnormally end when a problem. No return and reason codes are provided; therefore, do not specify the RETCODE and RSNCODE parameters.
REQUEST=DELETE
Request to delete the pool.
Note:
This request is unconditional and will abnormally end when a problem. No return and reason codes are provided; therefore, do not specify the RETCODE and RSNCODE parameters.
Parameters for REQUEST=BUILD
The following parameters are valid when you specify REQUEST=BUILD:
,HEADER=header
A required input parameter that specifies information to be placed into the pool header for potential diagnostic purposes. The information helps to identify the requester and the purpose for the pool.
To code:
Specify the RS-type address, or address in register (2) - (12), of a
24-character field.
,CELLSIZE=cellsize
A required input parameter that indicates the size of a cell in the pool. The cell size can be anywhere between 1 and (1M-8192)/2 or 520,192 bytes. Cell size is rounded up to a quadword multiple for cell sizes less than a cache line. Cells larger than a cache line are rounded up to a cache line multiple. Cells larger than a page are rounded to start on a page boundary. The first cell in an extent is always on a page boundary. Specifying a cell size that is at least 4 bytes less than the size after rounding for boundary alignment makes room for a trailer to be inserted. See TRAILER=YES below.
To code:
Specify the RS-type address, or address in register (2) - (12), of a fullword field, or specify a literal decimal value.
,OUTPUT_CPID=output_cpid
A required output parameter that is to contain the cell pool ID.
To code:
Specify the RS-type address, or address in register (2) - (12), of an
8-character field.
,COMMON=NO
A required parameter that indicates if the pool is to reside in common storage.
,COMMON=NO
The pool is not to reside in common storage.
,OWNINGTASK=CURRENT
,OWNINGTASK=MOTHER
,OWNINGTASK=IPT
,OWNINGTASK=JOBSTEP
,OWNINGTASK=CMRO
A required parameter that indicates the task to be considered as the owner of the cell pool. When this task ends, the cell pool is automatically deleted.
30
z/OS MVS Assembler Services Reference IAR-XCT
IARCP64 macro
,OWNINGTASK=CURRENT
The current task is to be the owner. Do not specify this unless the program is in task mode.
,OWNINGTASK=MOTHER
The mother task of the current task is to be the owner. If the current task is the cross-memory resource owning task, the request fails. Do not specify this unless the program is in task mode.
,OWNINGTASK=IPT
The initial pthread task is to be the owner. If the current task or mother task is not the IPT, then this defaults to the current task as the owner. Do not specify this unless the program is in task mode.
,OWNINGTASK=JOBSTEP
The jobstep task of the current task (the task with TCB address in field
TCBJSTCB of the current task's TCB) is to be the owner. Do not specify this unless the program is in task mode.
,OWNINGTASK=CMRO
The cross-memory resource-owning task of the current primary address space is to be the owner.
,DUMP=LIKERGN
,DUMP=LIKELSQA
,DUMP=NO
A required parameter that indicates how to dump this pool.
When COMMON=NO is specified:
,DUMP=LIKERGN
Dump the pool according to the rules for RGN.
,DUMP=LIKELSQA
Dump the pool according to the rules for LSQA.
,DUMP=NO
Do not dump the pool based on the RGN and LSQA SDATA options.
,DUMPPRIO=dumpprio
When DUMP=LIKERGN, COMMON=NO and REQUEST=BUILD are specified, a required input parameter that contains the dump priority to be used when dumping the pool. The value can be in the range 1-99 with 1 being the highest priority. See the documentation for the GETSTOR option of the IARV64 macro for a discussion on dump priorities.
To code:
Specify the RS-type address, or address in register (2) - (12), of a
1-byte field.
,OWNINGASID=owningasid
When OWNER=BYASID, COMMON=YES and REQUEST=BUILD are specified, a required input parameter that specifies the ASID that is to be the owner. A value of 0 is equivalent to having specified OWNER=SYSTEM.
To code:
Specify the RS-type address, or address in register (2) - (12), of a halfword field.
,FPROT=YES
,FPROT=NO
A required parameter that indicates whether the pool storage is to be fetch-protected.
Chapter 2. IARCP64 — 64-bit cell pool services
31
IARCP64 macro
,FPROT=YES
The pool storage is to be fetch-protected.
,FPROT=NO
The pool storage is not to be fetch-protected.
,TYPE=PAGEABLE
A required parameter that indicates the type of storage for the pool.
,TYPE=PAGEABLE
The pool storage is to be pageable.
,CALLERKEY=YES
A required parameter that indicates whether the pool storage is to be in the key of the caller of the BUILD request.
,CALLERKEY=YES
The pool storage is to be in the key of the caller.
,TRAILER=COND
,TRAILER=YES
,TRAILER=NO
A required parameter that indicates whether the cell is to have a trailer area after the user portion of the cell, which is set on GET processing and checked on FREE processing.
Note:
Requesting a trailer can cause the cell size to be increased to provide room for the trailer. This increase in size occurs before rounding for boundary alignment. For example, requesting a cell size of 4096 and TRAILER=YES results in cells being 8192 bytes. If you do not need the entire 4096 bytes, specify a cell size of 4092 bytes and now the trailer fits in the same page.
,TRAILER=COND
The cell storage should have trailer processing in the following cases: v When the service-rounded cell size has room for the trailer without requiring a larger cell to be allocated.
v When system diagnostic controls requests that trailers be appended to cells obtained by IARCP64. If this results in trailer processing, it works as described for TRAILER=YES below.
Note:
The system diagnostic control for trailers in IARCP64 cell pools is examined at BUILD time only.
,TRAILER=YES
The cell storage is to have trailer processing. If the application writes past the end of the specified cell size, it will overrun the trailer. On a FREE request, this is detected and causes an ABEND.
,TRAILER=NO
The cell storage is not to have trailer processing, even if requested by way of a system diagnostic control.
,FAILMODE=RC
,FAILMODE=ABEND
A required parameter that indicates what to do if the request is not successful.
,FAILMODE=RC
The request should return with a failure return code when there are insufficient memory resources to satisfy the request. All errors in parameter specification or parameter access results in the request abnormally ending.
32
z/OS MVS Assembler Services Reference IAR-XCT
IARCP64 macro
,FAILMODE=ABEND
The request should abnormally end when there are insufficient memory resources to satisfy the request.
Parameters for REQUEST=GET
The following parameters are valid when you specify REQUEST=GET:
,INPUT_CPID=input_cpid
A required input parameter that contains the cell pool ID returned on the successful BUILD request.
To code:
Specify the RS-type address, or address in register (2) - (12), of an
8-character field.
,CELLADDR=celladdr
An optional output parameter of the obtained cell. If CELLADDR is not specified, the cell address is left in register 1.
To code:
Specify the RS-type address, or address in register (2) - (12), of an
8-byte pointer field.
,EXPAND=YES
,EXPAND=NO
A required parameter that indicates whether to attempt expanding the pool if there is no available cell.
,EXPAND=YES
Indicates that an attempt to expand the pool should be made. Each successful expansion results in a 1 MB increase in the pool size.
,EXPAND=NO
Indicates that no attempt to expand the pool should be made.
,TRACE=YES
,TRACE=NO
A required parameter that indicates whether the invocation is to be traced.
Note:
Tracing is available only to supervisor state callers.
,TRACE=YES
The entry is to be traced. If you are running in supervisor state, use this option, unless performance needs dictate otherwise.
Note:
TRACE=YES on GET also results in TRACE=YES on FREE, so if you use TRACE=YES, ensure that the FREE request is in supervisor state.
,TRACE=NO
The entry is not to be traced. You must use this option if running in problem state.
,FAILMODE=RC
,FAILMODE=ABEND
A required parameter that indicates what to do if the request is not successful.
,FAILMODE=RC
The request should return with a failure return code when there are insufficient memory resources to satisfy the request. All errors in parameter specification or parameter access results in the request abnormally ending.
Chapter 2. IARCP64 — 64-bit cell pool services
33
IARCP64 macro
,FAILMODE=ABEND
The request should abnormally end when there are insufficient memory resources to satisfy the request.
,REGS=SAVE
,REGS=USE
A required parameter that indicates how to deal with the registers.
,REGS=SAVE
The request should save and preserve the contents of 64-bit GPRs 2 - 12, starting at offset 40 in a 144-byte area pointed to by register 13.
,REGS=USE
The request can use registers 2 - 12.
Parameters for REQUEST=FREE
The following parameters are valid when you specify REQUEST=FREE:
,CELLNAME=cellname
,CELLADDR=celladdr
A required input parameter that identifies the cell to free.
,CELLNAME=cellname
The name of the cell to free.
To code:
Specify the RS-type address, or address in register (2) - (12), of a character field.
,CELLADDR=celladdr
The address of the cell to free.
To code:
Specify the RS-type address, or address in register (2) - (12), of an
8-byte pointer field.
,INPUT_CPID=input_cpid
An optional input parameter that contains the cell pool ID returned on the
BUILD request.
To code:
Specify the RS-type address, or address in register (2) - (12), of an
8-character field.
,REGS=SAVE
,REGS=USE
A required parameter that indicates how to deal with the registers.
,REGS=SAVE
The request should save and preserve the contents of 64-bit GPRs 2 - 12, starting at offset 40 in a 144-byte area pointed to by register 13.
,REGS=USE
The request can use registers 2 - 12.
Parameters for REQUEST=DELETE
The following parameters are valid when you specify REQUEST=DELETE:
,INPUT_CPID=input_cpid
A required input parameter that contains the cell pool ID returned on the
BUILD request.
To code:
Specify the RS-type address, or address in register (2) - (12), of an
8-character field.
34
z/OS MVS Assembler Services Reference IAR-XCT
IARCP64 macro
Optional parameters
The following parameters are optional:
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15. If you specify (GPR15), (REG15), or (R15), the value is left in GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2) - (12),
(GPR15), (REG15), or (R15).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0. If you specify (GPR0), (GPR00), (REG0), (REG00), or (R0), the value is left in GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2) - (12),
(GPR0), (GPR00), (REG0), (REG00), or (R0).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
To code:
Specify one of the following v IMPLIED_VERSION v MAX v A decimal value of 0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Chapter 2. IARCP64 — 64-bit cell pool services
35
IARCP64 macro
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and
MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
This parameter specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
ABEND codes
The IARCP64 caller might receive abend code X'DC4'. For detailed abend code information, see z/OS MVS System Codes.
Return and reason codes
When the IARCP64 macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code
RSNCODE) contains a reason code.
Macro IAXSERVC provides equated symbols for the return and reason codes.
The following table identifies the hexadecimal return and reason codes and the equated symbol associated with each reason code.
36
z/OS MVS Assembler Services Reference IAR-XCT
IARCP64 macro
Table 4. Return and Reason Codes for the IARCP64 Macro
Hexadecimal
Return Code
00
Hexadecimal
Reason Code
None
Equate Symbol Meaning and Action
Equate Symbol:
IARCP64Rc_OK
04
04
08
08
08
None xx0400xx
None xx0401xx xx0402xx
Meaning:
IARCP64 request successful.
Action:
None required.
BUILD Meaning:
Cell pool built Action: None required.
DELETE
Meaning:
Cell Pool deleted and storage freed.
Action:
None required.
GET Meaning:
Cell from pool obtained. Action: None required.
FREE Meaning:
Cell returned to the pool. Action: None required.
Equate Symbol:
IARCP64Rc_Warn
Meaning:
Warning
Action:
Refer to the action provided with the specific reason code.
Equate Symbol:
IARCP64RsnGetOutOfCells
Meaning:
The request to the IARCP64 GET service specified EXPAND=NO and the current extent is out of cells.
Action:
Either change the request to specify EXPAND=YES or write logic to deal with no cell available.
Equate Symbol:
IARCP64Rc_Fail
Meaning:
Service failed due to running out of resources.
Action:
Refer to the action provided with the specific reason code.
Equate Symbol:
IARCP64RsnMemlimitExhausted
Meaning:
The request to either the IARCP64 BUILD,
IARCP64 GET when the pool is being expanded or the
IARST64 GET when a new extent is required was not able to obtain private storage due to the address space
MEMLIMIT.
Action:
Either raise the MEMLIMIT of the address space or determine if private storage is being consumed excessively somewhere.
Equate Symbol:
IARCP64Rsn64BitCommonExhausted
Meaning:
The request to either the IARCP64 BUILD,
IARCP64 GET when the pool is being expanded or the
IARST64 GET when a new extent is required was not able to obtain common storage due to there being insufficient
64-bit common storage to satisfy the request.
Action:
For common storage, either raise the system limit on common (HVCOMMON) or determine if common storage is being consumed excessively somewhere.
Chapter 2. IARCP64 — 64-bit cell pool services
37
IARCP64 macro
Examples
1.
Build a pool according to the following specifications: v Cells 32 bytes long v In private storage v With an owning task of the current task v Dumped similar to "RGN" processing v Not fetch-protected v Pageable storage v In key 3 v Provide a diagnostic trailer.
Note:
Requesting a diagnostic trailer causes the cell size to internally be rounded up 32 - 48 bytes v Provide return code if the request is not successful
The coding sample follows
IARCP64 REQUEST=BUILD,HEADER=theHeader,
CELLSIZE=theCellsize,OUTPUT_CPID=theCPID,
COMMON=NO,OWNINGTASK=CURRENT,DUMP=LIKERGN,
FPROT=NO,TYPE=PAGEABLE,
CALLERKEY=NO,KEY00TOF0=theKEY,
TRAILER=YES,FAILMODE=RC,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,
MF=(E,IARCP64L)
( Place code to check return/reason codes here.) theHEADER DC CL24 theCellsize DC F’32’
Key00ToF0 DC X’30’
Header for pool
32-byte cells
Key 3 (bits 0-3 of the byte)
IAXSERVC
DYNAREA DSECT
LRETCODE DS
LRSNCODE DS
F
F theCPID DS D
IARCP64 MF=(L,IARCP64L)
Return/Reason code information
2.
Obtain a cell from the pool.
v Do not expand the pool if no cell is available v
Provide Return Code if the request is not successful v Save and restore registers
The coding sample follows
IARCP64 REQUEST=GET,INPUT_CPID=theCPID,
CELLADDR=theCellAddr,
EXPAND=NO,
FAILMODE=RC,
REGS=SAVE,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,
(Place code to check return/reason codes here.)
IAXSERVC
DYNAREA DSECT
LRETCODE DS
LRSNCODE DS theCPID DS D theCellAddr DS D
F
F
3.
Free a cell.
38
z/OS MVS Assembler Services Reference IAR-XCT
Return/Reason code information
v Save and restore registers
The coding sample follows
IARCP64 REQUEST=FREE,
CELLADDR=theCellAddr,
REGS=SAVE
IAXSERVC
DYNAREA DSECT theCPID DS D theCellAddr DS D
Return/Reason code information
4.
Delete the pool.
The coding sample follows
IARCP64 REQUEST=DELETE,INPUT_CPID=theCPID,
MF=(E,IARCP64L)
IAXSERVC
DYNAREA DSECT
Return/Reason code information theCPID DS D
IARCP64 MF=(L,IARCP64L)
IARCP64 macro
Chapter 2. IARCP64 — 64-bit cell pool services
39
IARCP64 macro
40
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 3. IARR2V — Convert a central storage address to a virtual storage address
Description
Use the IARR2V macro to convert a central storage address to a virtual storage address. This conversion can be useful when you have the central storage address from handling I/O or doing diagnostic support and need to know the corresponding virtual address.
When the input storage address is a central storage address that backs a single page, the system returns the ASID that indicates the address space that owns the central storage, and the STOKEN that indicates the address space or data space that uses the central storage. When a central storage address does not back any page, or backs a read-only nucleus page, the system returns a non-zero return code and reason code.
For more information on the use of the IARR2V macro, see z/OS MVS
Programming: Assembler Services Guide.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state with any PSW key.
Task or SRB
Any PASN, any HASN, any SASN
24-, 31- or 64-bit.
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
The caller may hold the local or CPU lock, but is not required to hold any locks.
None.
Programming requirements
None.
Restrictions
None.
Input register information
Before issuing the IARR2V macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
© Copyright IBM Corp. 1988, 2017
41
IARR2V macro
Syntax
0
1
2-13
14
15
ASID if return code is 0 or 4; otherwise, reason code. The ASID value is
X'FFFF' if the returned virtual address represents common storage.
Virtual storage address if return code is 0 or 4; otherwise, used as a work register by the system.
Unchanged.
Used as a work register by the system.
Return code.
When control returns to the caller, the ARs contain:
Register
Contents
0
First four bytes of STOKEN if return code is 0 or 4; otherwise, used as a work register by the system.
1
2-13
14
Last four bytes of STOKEN if return code is 0 or 4; otherwise, used as a work register by the system.
Unchanged.
15
Total shared view count if return code is 0 or 4; otherwise, used as a work register by the system.
Valid shared view count if return code is 0 or 4; otherwise, used as a work register by the system.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the IARR2V macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede IARR2V.
name
�
IARR2V
�
RSA=rsa_addr
RSA64=rsa_addr64
One or more blanks must follow IARR2V.
rsa_addr: RS-type address, or register (2) - (12).
rsa_addr64: RS-type address, or register (2) - (12).
42
z/OS MVS Assembler Services Reference IAR-XCT
IARR2V macro
Syntax
,VSA=vsa_addr
,VSA64=vsa_addr64
,ASID=asid_addr
,STOKEN=stoken_addr
,WORKREG=work_reg
,WORKREG=NONE
,NUMVIEW=view_addr
,NUMVALID=val_addr
,RETCODE=retcode
,RSNCODE=rsncode
Description
vsa_addr: RS-type address, or register (2) - (12).
vsa_addr64: RS-type address, or register (2) - (12).
asid_addr: RS-type address, or register (2) - (12).
stoken_addr: RS-type address, or register (2) - (12).
work_reg: RS-type address, or register (2) - (12).
Default
: WORKREG=NONE
view_addr: RS-type address, or register (2) - (12).
val_addr: RS-type address, or register (2) - (12).
retcode: RS-type address, or register (2) - (12).
rsncode: RS-type address, or register (2) - (12).
Parameters
The parameters are explained as follows:
RSA=rsa_addr
Specifies the name (RS-type) or address (in register 2-12) of an input fullword that contains the central storage address to be converted to a virtual storage address. This keyword is used to provide a 31–bit real address. RSA and
RSA64 are mutually exclusive keywords. You must specify one or the other.
RSA64=rsa_addr64
Specifies the name (RS-type) or address (in register 2-12) of an input double-word that contains the central storage address to be converted to a virtual storage address. This keyword is used to provide a 64–bit real address.
RSA and RSA64 are mutually exclusive keywords. You must specify one or the other. To use this keyword, the SYSTATE macro must be invoked specifying
ARCHLVL greater than 1.
,VSA=vsa_addr
Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword that the system uses to return the virtual storage address that corresponds to the input central storage address.
,VSA64=vsa_addr64
Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword that the system uses to return the 64–bit virtual storage address that corresponds to the input central storage address. VSA and VSA64 are mutually exclusive keywords. To use this keyword, the SYSTATE macro must be invoked specifying ARCHLVL greater than 1.
,ASID=asid_addr
Specifies the name (RS-type) or address (in register 2-12) of an optional output
Chapter 3. IARR2V — Convert a central storage address to a virtual storage address
43
IARR2V macro
fullword that the system uses to return the ASID of the address space associated with the output virtual storage address. The system returns the
ASID in bits 16-31 of the fullword, and clears bits 1-15 to 0. If the input central storage address backs a page that is shared through the use of the IARVSERV macro, the system sets bit 0 to 1; otherwise, bit 0 contains 0.
,STOKEN=stoken_addr
Specifies the name (RS-type) or address (in register 2-12) of an optional
8-character output field that the system uses to return the STOKEN for the address space or data space associated with the output virtual storage address.
,WORKREG=work_reg
,WORKREG=NONE
Specifies whether the system is to return a page sharing view count. If you want the system to return a page sharing view count, specify work-reg as a digit from 2 through 12 that identifies a GPR/AR pair that the system can use as work registers. WORKREG=work_reg is required if you code NUMVIEW or
NUMVALID.
WORKREG=NONE is the default and specifies that the system is not to return the sharing count.
,NUMVIEW=view_addr
Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword that the system uses to return the number of page sharing views associated with the input central storage address. This number is non-zero only if the system sets bit 0 of the ASID. NUMVIEW=view_addr is required with the
WORKREG=work_reg parameter.
,NUMVALID=val_addr
Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword that the system uses to return the number of valid page sharing views associated with the input central storage address. A valid page must be currently defined in central storage. This number is non-zero only if the system sets bit 0 of the asid_addr. NUMVALID=val_addr is required with the
WORKREG=work_reg parameter.
,RETCODE=retcode
Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword into which the system copies the return code from GPR 15.
,RSNCODE=rsncode
Specifies the name (RS-type) or address (in register 2-12) of an optional output fullword into which the system copies the a reason code from GPR 0.
ABEND codes
None.
Return and reason codes
When the IARR2V macro returns control to your program, GPR 15 (and retcode if you coded RETCODE) contains the return code. If the return code is not 0 or 4,
GPR 0 (and rsncode if you coded RSNCODE) contains the reason code.
44
z/OS MVS Assembler Services Reference IAR-XCT
IARR2V macro
Table 5. Return and Reason Codes for the IARR2V Macro
Hexadecimal
Return Code
00
Hexadecimal
Reason Code
None
Meaning and Action
Meaning
: The IARR2V request completed successfully. The address returned in the VSA parameter represents an address space page.
04
08
None xx0001xx
Action
: None required.
Meaning
: The IARR2V request completed successfully. The address returned in the VSA parameter represents a data space page.
Action
: None required.
Meaning
: Program error. The IARR2V request was unsuccessful because the input central storage address was not within the bounds of central storage.
08
08
08
08
08 xx0002xx xx0003xx xx0004xx xx0005xx xx0006xx
Action
: Check your input central storage address and rerun the program.
Meaning
: Program error. The IARR2V request was unsuccessful because the frame corresponding to the input central storage address was not assigned to a page.
Action
: Check your input central storage address and rerun the program.
Meaning
: Program error. The IARR2V request was unsuccessful because the frame corresponding to the input central storage address contains shared data, but no virtual address for any accessible address space (either home, primary, or secondary) corresponds to the frame.
Action
: Check your input central storage address and rerun the program.
Meaning
: System error. The IARR2V request was recursively invoked.
Action
: Record the return code and reason code and supply them to the appropriate IBM support personnel.
Meaning
: Program error. The IARR2V request was unsuccessful because the frame corresponding to the input central storage address was assigned, but the data space
STOKEN could not be found.
Action
: Check your input central storage address and rerun the program.
Meaning
: Program error. The IARR2V request was unsuccessful because the virtual address is above 2G and the caller did not specify VSA64.
Action
: Specify VSA64 on the IARR2V invocation.
Example 1
Convert the central storage address in variable VSA and place the result in variable
VSAOUT.
LRA 1,VSA
LR 5,1
INVOKE1 IARR2V RSA=(5),VSA=VSAOUT
.
.
VSA DS
VSAOUT DS
F
F
Chapter 3. IARR2V — Convert a central storage address to a virtual storage address
45
IARR2V macro
Example 2
Same as Example 1, but return ASID in variable ASIDO.
INVOKE2 IARR2V RSA=(5),ASID=ASIDO
.
.
ASIDO DS F
Example 3
Same as Example 1, but return STOKEN in variable STOKO.
INVOKE3 IARR2V RSA=(5),STOKEN=STOKO
.
.
STOKO DS F
Example 4
Obtain the total and valid number of page sharing views associated with the input address. WORKREG is required.
INVOKE4 IARR2V RSA=(5),WORKREG=(6),NUMVIEW=VIEWS,NUMVALID=VALS
.
.
VIEWS
VALS
DS
DS
F
F
46
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 4. IARST64 — 64-bit storage services
Description
Use IARST64 to request 64-bit Storage Services.
With IARST64, you can request services to: v Obtain storage (REQUEST=GET) v Return storage (REQUEST=FREE)
Note:
There is diagnostic support for 64-bit cell pools, which are created by
IARST64, in IPCS using the CBFORMAT command. To locate the cell pool of interest, you need to follow the pointers from HP1, to HP2, to the CPHD. For common storage, the HP1 is located in the ECVT. CBF ECVT formats the ECVT, then does a FIND on HP1. Extract the address of the HP1 from the ECVT and CBF addrhp1 STR(IAXHP1) formats the HP1. Each entry in the HP1 represents an attribute set (storage key, storage type(pageable, DREF, FIXED), and
Fetch-Protection (ON or OFF)). The output from this command contains CBF commands for any connected HP2s. Select the CBF command of interest and run it to format the HP2. The HP2 consists of pointers to cell pool headers for different sizes. Choose the size of interest and select the command that looks like this to format the cell pool header:
CBF addrchphd STR(IAXCPHD)
To see details about all of the cells in the pool, use the EXIT option as follows:
CBF addrcphd STR(IAXCPHD) EXIT
For private storage, the HP1 is anchored in the STCB. The quickest way to locate the HP1 is to run the SUMMARY FORMAT command for the address space of interest. Locate the TCB that owns the storage of interest and then scroll down to the formatted STCB. The HP1 field contains the address of the HP1. From here, the processing is the same as described for common storage.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Requirement
Use of the COMMON=YES, TYPE=DREF, TYPE=FIXED,
OWNINGTASK=RCT, or the Key00ToF0 parameter with a value other than 9 requires the caller to be running in key
0-7. Use of MEMLIMIT=NO requires key 0-7 or supervisor state. All other options have a minimum authorization of problem state and PSW key 8-15.
Task or SRB
Any PASN, any HASN, any SASN
64-bit
Primary or access register (AR) v The caller can be enabled or disabled for interrupts when requesting storage that is defined as COMMON=YES and
TYPE=DREF or TYPE=FIXED.
v For all other parameter combinations, the caller must be enabled for interrupts.
© Copyright IBM Corp. 1988, 2017
47
IARST64 macro
Environmental factor
Locks:
Control parameters:
Requirement
For the GET request, the following locks can be held by the caller or must be obtainable by IARST64: v For requests with COMMON=NO, the locking restrictions are the same as for IARV64 REQUEST=GETSTOR.
For the FREE request, the caller might hold locks but is not required to hold any.
Control parameters must be in the primary address space.
Programming requirements
None.
Restrictions
None.
Input register information
When REGS=SAVE is not used, the caller does not have to place any information into any general-purpose register (GPR) or access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.
Before issuing the IARST64 macro with REGS=SAVE, the caller must ensure that the following GPR contains the specified information:
Register
Contents
13
Address of a 144-byte area within which the 88 bytes beginning at offset 40 can be modified.
Before issuing the IARST64 macro, the caller does not have to place any information into any access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the 64-bit GPRs contain:
For REQUEST=GET
13
14
15
Register
Contents
0
Reason code in the low 32 bits if the return code is not 0. Otherwise, used as a work register by the system.
1
2-12
The address of the obtained storage.
Unchanged if REGS=SAVE was specified, used as work registers by the system if REGS=USE was specified.
Unchanged.
Used as a work register by the system.
Return code in the low 32 bits.
For REQUEST=FREE
48
z/OS MVS Assembler Services Reference IAR-XCT
⌂
Syntax
name
IARST64 macro
Register
Contents
0-1
2-12
Used as a work register by the system.
v Unchanged, if REGS=SAVE was specified.
v Used as work registers by the system, if REGS=USE was specified.
13
Unchanged.
14-15
Used as a work register by the system.
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system.
Unchanged.
14-15
Used as work registers by the system.
Some callers depend on register contents to remain the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The IARST64 macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede IARST64.
IARST64
⌂ One or more blanks must follow IARST64.
REQUEST=GET
REQUEST=FREE
,SIZE=size
,AREAADDR=areaaddr
,COMMON=NO
size: RS-type address or address in register (2) - (12)
areaaddr: RS-type address or address in register (2) - (12)
Chapter 4. IARST64 — 64-bit storage services
49
IARST64 macro
Syntax
,COMMON=YES
,OWNINGTASK=CURRENT
,OWNINGTASK=MOTHER
,OWNINGTASK=IPT
,OWNINGTASK=JOBSTEP
,OWNINGTASK=CMRO
,OWNINGTASK=RCT
,MEMLIMIT=YES
,MEMLIMIT=NO
,LOCALSYSAREA=NO
,LOCALSYSAREA=YES
,OWNER=HOME
,OWNER=PRIMARY
,OWNER=SECONDARY
,OWNER=SYSTEM
,OWNER=BYASID
,OWNINGASID=owningasid
,FPROT=YES
,FPROT=NO
,TYPE=PAGEABLE
,TYPE=DREF
,TYPE=FIXED
,CALLERKEY=YES
,CALLERKEY=NO
,KEY00TOF0=key00tof0
,FAILMODE=RC
,FAILMODE=ABEND
,REGS=SAVE
,REGS=USE
Description
Default:
MEMLIMIT=YES
Default:
LOCALSYSAREA=NO
owningasid: RS-type address or address in register (2) - (12)
key00tof0: RS-type address or address in register (2) - (12)
50
z/OS MVS Assembler Services Reference IAR-XCT
|
|
IARST64 macro
Syntax
,AREANAME=areaname
,AREAADDR=areaaddr
,REGS=SAVE
,REGS=USE
,RETCODE=retcode
Description
areaname: RS-type address or address in register (2) - (12)
areaaddr: RS-type address or address in register (2) - (12)
retcode: RS-type address or register (2) - (12), (GPR15), (REG15), or (R15).
|
|
,RSNCODE=rsncode
,EXECUTABLE=YES | NO
,EXECUTABLE=SYSTEM_RULES
rsncode: RS-type address or register (2) - (12), (GPR0), (GPR00), (REG0),
(REG00), or (R0).
Default:
EXECUTABLE=SYSTEM_RULES
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1 that is the name on the IARST64 macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
REQUEST=GET
REQUEST=FREE
A required parameter that indicates the type of request.
REQUEST=GET
This parameter gets storage.
REQUEST=FREE
This parameter returns storage.
Note:
This request is unconditional, and will abnormally end if there is a problem. No return and reason codes are provided, so do not specify the
RETCODE and RSNCODE parameters.
,SIZE=size
When REQUEST=GET is specified, a required input parameter that indicates the size of the storage to be obtained. The size can be anywhere 1 - 128 K bytes. The size is rounded up to the power of 2. So cell sizes are 64, 128, 256,
512, 1024, 2048, 4096, 8192, 16,384, 32,768, 65,536 and 131,072 bytes. The smallest cell size that contains the request is used. If the requested size is at least 4 bytes less than the rounded up cell size, a trailer will be added to check for storage overruns. For storage that is larger than what IARST64 supports, consider using IARCP64 or IARV64 GETSTOR or GETCOMMON. Do not specify a value that exceeds 128 K or incorrect results can ensue.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.
Chapter 4. IARST64 — 64-bit storage services
51
IARST64 macro
,AREAADDR=areaaddr
When REQUEST=GET is specified, an optional output parameter, of the obtained storage. If AREAADDR is not specified, the cell address is left in register 1.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-byte pointer field.
,COMMON=NO
,COMMON=YES
When REQUEST=GET is specified, a required parameter that indicates if the pool is to reside in common storage.
,COMMON=NO
This parameter indicates that the pool is not to reside in common storage.
,COMMON=YES
This parameter indicates that the pool is to reside in common storage.
,OWNINGTASK=CURRENT
,OWNINGTASK=MOTHER
,OWNINGTASK=IPT
,OWNINGTASK=JOBSTEP
,OWNINGTASK=CMRO
,OWNINGTASK=RCT
When COMMON=NO and REQUEST=GET are specified, a required parameter that indicates the task that is to be considered the owner.
,OWNINGTASK=CURRENT
This parameter indicates that the current task is to be the owner. Do not specify this parameter unless the program is in task mode.
,OWNINGTASK=MOTHER
This parameter indicates that the mother task of the current task is to be the owner. If the current task is the cross-memory resource owning task, the request will fail. Do not specify this parameter unless the program is in task mode.
,OWNINGTASK=IPT
This parameter indicates that the initial pthread task (subtask running under UNIX System Services) is to be the owner. If the current task or mother task is not the IPT, then this will default to the current task as the owner. Do not specify this unless the program is in task mode.
,OWNINGTASK=JOBSTEP
This parameter indicates that the jobstep task of the current task (the task with TCB address in field TCBJSTCB of the current task's TCB) is to be the owner. Do not specify this unless the program is in task mode.
,OWNINGTASK=CMRO
This parameter indicates that the cross-memory resource-owning task is to be the owner.
,OWNINGTASK=RCT
This parameter indicates that the region control task (RCT) is to be the owner. You must be key 0-7 to request this option.
,MEMLIMIT=YES
,MEMLIMIT=NO
When COMMON=NO and REQUEST=GET are specified, an optional parameter that indicates whether MEMLIMIT applies if an additional 1 M segment is obtained to satisfy the request. The default is MEMLIMIT=YES.
52
z/OS MVS Assembler Services Reference IAR-XCT
IARST64 macro
,MEMLIMIT=YES
This parameter indicates that MEMLIMIT applies.
,MEMLIMIT=NO
This parameter indicates that MEMLIMIT does not apply.
,LOCALSYSAREA=NO
,LOCALSYSAREA=YES
When Common=NO and request=GET are specified, an optional parameter that specifies whether this is an explicit allocation request for 64-bit virtual storage in the local system area. The LOCALSYSAREA parameter can be used only by callers running in supervisor state or with a PSW key 0-7. THE
DEFAULT IS LOCALSYSAREA=NO.
,LOCALSYSAREA=NO
The request will not be satisfied from the local system area.
,LOCALSYSAREA=YES
The request is to be satisfied from the local system area. The storage that is obtained with this keyword will not be copied during Fork processing. The use of local system area storage does not preclude checkpoint or restart from succeeding.
,OWNER=HOME
,OWNER=PRIMARY
,OWNER=SECONDARY
,OWNER=SYSTEM
,OWNER=BYASID
When COMMON=YES and REQUEST=GET are specified, a required parameter that designates the owner of the storage.
,OWNER=HOME
This parameter indicates that the home address space is to be the owner.
,OWNER=PRIMARY
This parameter indicates that the primary address space is to be the owner.
,OWNER=SECONDARY
This parameter indicates that the secondary address space is to be the owner.
,OWNER=SYSTEM
This parameter indicates that the system is to be the owner. Use this only when there is no specific address space, which can be considered the owner.
,OWNER=BYASID
This parameter indicates that the owner is the ASID specified by the
OwningASID parameter.
,OWNINGASID=owningasid
When OWNER=BYASID, COMMON=YES and REQUEST=GET are specified, a required input parameter that specifies the ASID that is to be the owner. A value of 0 is equivalent to having specified OWNER=SYSTEM. Do not specify a value which exceeds 32767 or incorrect results can ensue.
To code:
Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.
,FPROT=YES
Chapter 4. IARST64 — 64-bit storage services
53
IARST64 macro
|
|
|
|
|
|
|
|
|
,FPROT=NO
When REQUEST=GET is specified, a required parameter that indicates if the pool storage is to be fetch-protected.
,FPROT=YES
This parameter indicates that the pool storage is to be fetch-protected.
,FPROT=NO
This parameter indicates that the pool storage is not to be fetch-protected.
,TYPE=PAGEABLE
,TYPE=DREF
,TYPE=FIXED
When REQUEST=GET is specified, a required parameter that indicates the type of storage for the pool.
,TYPE=PAGEABLE
This parameter indicates that the pool storage is to be pageable.
,TYPE=DREF
This parameter indicates that the pool storage is to be disabled-reference
(DREF).
,TYPE=FIXED
This parameter indicates that the pool storage is to be page-fixed.
,CALLERKEY=YES
,CALLERKEY=NO
When REQUEST=GET is specified, a required parameter that indicates if the pool storage is to be in the key of the caller of the GET request.
,CALLERKEY=YES
This parameter indicates that the pool storage is to be in the key of the caller.
,CALLERKEY=NO
This parameter indicates that the pool storage is not to be in the key of the caller, but instead in the key specified by the Key00ToF0 parameter.
,KEY00TOF0=key00tof0
When CALLERKEY=NO and REQUEST=GET are specified, a required input parameter that indicates the key for the pool storage. The value should be in the range x'00' to x'70' (for example, the key 0-7 in the high 4 bits of the byte) for a caller that is key 0. You will not use this parameter for caller's in key 1-7.
The value x'90' is the only accepted key for a caller that is key 8-15. Be sure that the value is a multiple of 16 within the required range or incorrect results can ensue.
To code:
Specify the RS-type address, or address in register (2)-(12), of a one-byte field.
,FAILMODE=RC
,FAILMODE=ABEND
When REQUEST=GET is specified, a required parameter that indicates what to do if the GET request is not successful due to out of memory in the requested area conditions.
,FAILMODE=RC
This parameter returns with a failure return code.
Note:
There are cases for which an ABEND occurs regardless of the specification of FAILMODE=RC.
54
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
IARST64 macro
,FAILMODE=ABEND
This parameter abnormally ends.
,REGS=SAVE
,REGS=USE
When REQUEST=GET is specified, a required parameter that indicates how to deal with the registers.
,REGS=SAVE
This parameter saves and preserves the contents of 64-bit GPRs 2 - 12 starting at offset 40 in a 144-byte area pointed to by register 13.
,REGS=USE
This parameter indicates that the system uses registers 2 - 12 as work registers and does not restore them.
,AREANAME=areaname
,AREAADDR=areaaddr
When REQUEST=FREE is specified, a required input parameter.
,AREANAME=areaname
A parameter that is the area to free.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,AREAADDR=areaaddr
A parameter that contains the address of the area to free.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-byte pointer field.
,REGS=SAVE
,REGS=USE
When REQUEST=FREE is specified, a required parameter that indicates how to deal with the registers.
,REGS=SAVE
This parameter saves and preserves the contents of 64-bit GPRs 2 - 12 starting at offset 40 in a 144-byte area pointed to by register 13.
,REGS=USE
This parameter indicates that you can use registers 2 - 12.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15. If you specify 15, GPR15, or R15 (within or without parentheses), the value will be left in GPR15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12),
(GPR15), (REG15), or (R15).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR0.
To code:
Specify the RS-type address of a fullword field, or register (0) or
(2)-(12), (0), (GPR0), (GPR00), (REG0), (REG00), or (R0).
,EXECUTABLE=YES |NO
,EXECUTABLE=SYSTEM_RULES
Specifies if code can be executed from the obtained storage on a system that has implemented Instruction-Execution-Protection.
Chapter 4. IARST64 — 64-bit storage services
55
|
|
|
|
|
|
|
|
|
|
|
|
|
IARST64 macro
Note:
The default parameter is ,EXECUTABLE=SYSTEM_RULES.
,EXECUTABLE=YES
This parameter indicates that code is able to be executed from the obtained storage.
,EXECUTABLE=NO
This parameter indicates that code will not be able to be executed from the obtained storage on a system that has implemented
Instruction_Execution_Protection. The specification of NO will be ignored when executed on a system that has not implemented
Instruction_Execution_Protection or is not running an appropriate level of z/OS.
,EXECUTABLE=SYSTEM_RULES
This parameter indicates that code will obey the current system default.
ABEND codes
The IARST64 caller might receive abend code X'DC4'. For detailed abend code information, see z/OS MVS System Codes.
In the following IARST64 abend reason codes, the bytes designated "xx" are for diagnostic purposes and have no significance to the external interface. Equate
IARST64AbendRsncodeMask has been provided to let you build a mask to ignore those bytes.
Hexadecimal Reason Code
xx0410xx xx0413xx xx0419xx
Equate Symbol Meaning and Action
Equate Symbol:
IARST64AbendRsnCellAddrLow
Meaning:
The storage address passed to the IARST64
FREE service is within a megabyte used for storage pools, but the address is less than the address of the first usable storage address.
Action:
Correct the address passed to IARST64 FREE, making sure it is the same address that was returned from IARST64 GET.
Equate Symbol:
IARST64AbendRsnCellNotInExtent
Meaning:
The request was to the IARCP64 or IARST64
FREE service and the address of the storage passed in, is not within the bounds of a cell pool.
Action:
The address passed to IARST64
REQUEST=FREE must be the same as the address obtained from IARST64 REQUEST=GET.
Equate Symbol:
IARST64AbendRsnCellOverRun
Meaning:
The request was to the IARCP64 or IARST64
FREE service and the trailer data at the end of the cell was detected as being overrun. If the overrun is sufficiently large, it will cause damage to the following cell. The caller is abnormally ended so they can fix the code to not use more storage than requested.
Action:
Determine whether the storage has been overrun or whether the trailer data was overlaid by some other code. Fix the code so it only uses the amount of storage requested.
56
z/OS MVS Assembler Services Reference IAR-XCT
Hexadecimal Reason Code
xx041Axx xx041Bxx xx041Cxx xx0420xx xx0425xx xx0426xx
IARST64 macro
Equate Symbol Meaning and Action
Equate Symbol:
IARST64AbendRsnCellNotInUse
Meaning:
The request was to the IARCP64 or IARST64
FREE service and the address of the storage passed in, is already in the freed state. This will happen when an application frees the storage twice.
Action:
Determine whether the current application is freeing the storage twice or whether it is using a cell that some other storage is freeing twice.
Equate Symbol:
IARST64AbendRsnNotOnCellBoundary
Meaning:
The request was to the IARCP64 or IARST64
FREE service and the address of the storage passed in is not on a cell boundary in the cell pool from which the GET request was satisfied.
Action:
When freeing storage with IARST64
REQUEST=FREE, make sure to specify the address that was returned by IARST64 REQUEST=GET.
Equate Symbol:
IARST64AbendRsnIARV64Error
Meaning:
During processing of IARST64 GET, a call to the IARV64 service for GETSTOR, GETCOMMON,
PAGEFIX, or PROTECT failed. The failing return code from IARV64 was placed in register 2 before the abend.
The failing reason code from IARV64 was placed in register 3 before the abend.
Action:
Examine the return and reason code as documented under IARV64 to determine if the problem is one that you can resolve.
Equate Symbol:
IARST64AbendRsnCphaNotQueue
Meaning:
The cell pool header authorized area was not queued to the owning task as expected. This could happen due to storage overlays or the caller bypassing the IARST64 macro and PCing directly to the service with incorrect input parameters.
Action:
Make sure that the application is using the
IARST64 macro to request storage. If the problem persists, collect a dump and contact IBM Service.
Equate Symbol:
IARST64AbendRsnPoolNotInCallerKey
Meaning:
The request to IARST64 GET was against a storage pool that was not in the key of the caller.
Normally this will abend with an 0C4, but if the pool is out of cells and is in storage that is not fetch-protected, the pool expand routine verifies that the caller can modify this storage pool.
Action:
You must be in a key that has the ability to modify the pool storage for the request to be processed.
Equate Symbol:
IARST64AbendRsnPrimaryExtentOverlaid
Meaning:
The request to IARST64 or IARCP64 GET was against a storage pool where the primary extent control information has been overlaid.
Action:
Collect a dump and report the problem to IBM.
Chapter 4. IARST64 — 64-bit storage services
57
IARST64 macro
Hexadecimal Reason Code
xx0427xx xx0428xx xx0511xx xx0512xx xx0514xx xx0515xx xx0516xx
Equate Symbol Meaning and Action
Equate Symbol:
IARST64AbendRsnSecondaryExtentOverlaid
Meaning:
The request to IARST64 or IARCP64 GET was against a storage pool where the secondary extent control information has been overlaid.
Action:
Collect a dump and report the problem to IBM.
Equate Symbol:
IARST64AbendRsnUnexpectedError
Meaning:
During processing of IARST64 GET an unexpected abend occurred. An SDUMP should have been generated.
Action:
Collect the dump and report the problem to
IBM.
Equate Symbol:
IARST64AbendRsnKeyGT7Common
Meaning:
The request to IARST64 GET was for common storage, but the requested or caller was greater than key 7. You cannot allocate common storage in key 8 or above.
Action:
Correct the key passed to IARST64 GET or change your request to get private storage.
Equate Symbol:
IARST64AbendRsnGetMotherFromCmro
Meaning:
The request was to the IARST64 GET service and specified OWNINGTASK(MOTHER), but the caller is running on the CMRO task. You can't request the mother task be the storage owner from the CMRO task.
Action:
Either specify CMRO as the owner or specify
RCT if you want the storage to persist across termination of the CMRO.
Equate Symbol:
IARST64AbendRsnGetNotRctOrCmro
Meaning:
The request was to the IARST64 GET service for private storage and the caller was running in cross memory mode or SRB mode. In these environments, the OWNINGTASK parameter must be set to RCT or
CMRO. Neither of these were specified, so the request is failed.
Action:
Specify the OWNINGTASK parameter as RCT or CMRO.
Equate Symbol:
IARST64AbendRsnGetCellSizeZero
Meaning:
The request was to the IARST64 GET service and specified a length of zero.
Action:
Specify a length between 1 and 128 K.
Equate Symbol:
IARST64AbendRsnGetNotAuth
Meaning:
The request was to the IARST64 GET service and specified a parameter that requires the caller to be running in key 0-7. The caller is not authorized to use authorized options of COMMON, DREF, FIXED,
OWNINGTASK(RCT), CALLERKEY(NO) and
Key00ToF0 set to a system key.
Action:
Either run the code in key 0-7 or do not use authorized options.
58
z/OS MVS Assembler Services Reference IAR-XCT
Hexadecimal Reason Code
xx0517xx xx0518xx xx0529xx xx052Axx xx052Bxx xx052Cxx xx052Dxx
IARST64 macro
Equate Symbol Meaning and Action
Equate Symbol:
IARST64AbendRsnGetCellSizeTooBig
Meaning:
The request was to the IARST64 GET service and specified a length greater than 128 K.
Action:
Specify a size between 1 and 128 K. If larger storage is needed, consider using IARCP64 or IARV64
GETSTOR or GETCOMMON.
Equate Symbol:
IARST64AbendRsnGetKeyNot9
Meaning:
The request was to the IARST64 GET service and specified a CALLERKEY(NO) and a value for
Key00ToF0 that was not key 9 and the caller is not authorized.
Action:
The only key that an unauthorized user can specify is key 9. Either request key 9 or change the specification to CALLERKEY(YES).
Equate Symbol:
IARST64AbendRsnGetSizeTooBig
Meaning:
The call to the IARST64 GET service specified a cell size larger than the maximum size supported.
Action:
Specify a size between 1 and 128 K. If a larger storage area is needed, consider using IARCP64 or
IARV64 REQUEST=GETSTOR or GETCOMMON.
Equate Symbol:
IARST64AbendRsnValidationError
Meaning:
The call to the IARST64 GET service detected a validation error when locating the storage pool to be used. Possible cause is storage overlay of the storage pool control block in the caller's key.
Action:
Collect a dump and report the problem to IBM.
Equate Symbol:
IARST64AbendRsnMemLimitNoUnauth
Meaning:
The call to the IARST64 GET service requested MEMLIMIT=NO, but is running unauthorized (key 8-15 and problem program state).
Action:
Either specify MEMLIMIT=YES or call from an authorized environment.
Equate Symbol:
IARST64AbendRsnCellLT4Gig
Meaning:
The call to the IARCP64 or IARST64 FREE service was passed a cell address less than 4 Gig, so it can't possibly be a valid cell address in a 64 bit cell pool.
Action:
Only pass a storage address that was obtained with IARCP64 or IARST64 GET.
Equate Symbol:
IARST64AbendRsnLocalSysAreaYesUnauth
Meaning:
The call to the IARST64 GET service requested LOCALSYSAREA=YES, but is running unauthorized (key 8-15 and problem program state).
Action:
Either specify LOCALSYSAREA=NO or CALL from an authorized environment.
Chapter 4. IARST64 — 64-bit storage services
59
|
IARST64 macro
Hexadecimal Reason Code
xx052Exx
Equate Symbol Meaning and Action
Equate Symbol:
IARST64AbendRsnKeyGT7
Meaning:
The call to the IARST64 GET service requested private storage, with CALLERKEY (NO) and
KEY00TOF0 greater than key 7 when the CALLERKEY was less than key 8. An authorized caller cannot request unauthorized storage.
Action:
Correct the key of the requested storage or change the caller key.
Return and reason codes
When the IARST64 macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return code.
v
When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code
RSNCODE) contains a reason code.
Macro IAXSERVC provides equate symbols for the return and reason codes.
The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code.
Table 6. Return and Reason Codes for the IARST64 Macro
Hexadecimal
Return Code
00
Hexadecimal
Reason Code
None
Equate Symbol Meaning and Action
Equate Symbol:
IARST64Rc_OK
08
08
08
None xx0401xx xx0402xx
Meaning:
IARST64 request successful.
Action:
None required.
GET Meaning:
storage obtained of requested size and attributes Action: None required.
FREE Meaning:
storage freed Action: None required.
Equate Symbol:
IARST64Rc_Fail
Meaning:
Service failed due to running out of resources.
Action:
Refer to the action provided with the specific reason code.
Equate Symbol:
IARST64RsnMemlimitExhausted
Meaning:
The request to the IARST64 GET service was not able to obtain storage due to address space limits.
Action:
Either raise the MEMLIMIT of the address space or determine if private storage is being consumed excessively somewhere.
Equate Symbol:
IARST64Rsn64BitCommon Exhausted
Meaning:
The request to the IARST64 GET service was not able to obtain storage due to system limits.
Action:
For common storage, either raise the system limit on common (HVCOMMON) or determine if common storage is being consumed excessively somewhere.
60
z/OS MVS Assembler Services Reference IAR-XCT
IARST64 macro
Table 6. Return and Reason Codes for the IARST64 Macro (continued)
Hexadecimal
Return Code
08
Hexadecimal
Reason Code
xx0403xx
Equate Symbol Meaning and Action
Equate Symbol:
IARST64RsnMemlimitZero
Meaning:
The request to IARST64 GET was not able to obtain private storage due to the address space MEMLIMIT being set to zero.
Action:
Either set the MEMLIMIT of the address space to a nonzero value or if authorized, specify MEMLIMIT=NO on the IARST64 GET call to tell the service to bypass the address space MEMLIMIt.
Examples
Example 1:
Obtain storage.
Operations: v 32-byte area v In private storage v With an owning task of the current task v Dumped similar to "LSQA" processing (triggered by DREF or FIXED) v Fetch-protected v DREF storage v In Key 7 v
Provide Return Code if the request is not successful v Save and restore registers
The code is as follows:
IARST64 REQUEST=GET,
AREAADDR=theAreaAddr,
SIZE=theAreaSize,
COMMON=NO,OWNINGTASK=CURRENT,
DUMP=LIKELSQA,FPROT=YES,TYPE=DREF,
CALLERKEY=NO,KEY00TOF0=theKEY,
FAILMODE=RC,
REGS=SAVE,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,
(Place code to check return code or reason codes here.) theAreaSize DC F‘32’ theKey
IAXSERVC
DC X'70'
DYNAREA DSECT
LRETCODE DS F
LRSNCODE DS theAreaAddr DS D
F
Example 2:
Free the storage.
Operation: Save and restore registers.
The code is as follows:
Chapter 4. IARST64 — 64-bit storage services
61
IARST64 macro
IARST64 REQUEST=FREE,
AREAADDR=theAreaAddr,
REGS=SAVE,
(There is no return code or reason code from
IARST64 REQUEST=FREE.)
IAXSERVC
DYNAREA DSECT
LRETCODE DS F
LRSNCODE DS theAreaAddr DS D
F
62
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 5. IARVSERV — Request to share virtual storage
Description
Use the IARVSERV macro to define virtual storage areas to be shared by programs.
This sharing can reduce the amount of processor storage required and the I/O necessary to support many applications that process large amounts of data. It also provides a way for programs executing in 24 bit addressing mode to access data residing above 16 megabytes.
Using IARVSERV allows programs to share data in virtual storage without the central storage constraints and processor overhead of other methods of sharing data. The type of storage access is controlled so that you can choose to allow read only or writing to the shared data with several variations. The type of storage access is called a view. Data to be shared is called the source. The source is the original data or the virtual storage that contains the data to be shared. This data is made accessible through an obtained storage area called the target. The source and target form a sharing group.
Through the IARVSERV macro, you can: v Request that a virtual storage area (source) be eligible to be shared through a target view (SHARE parameter).
v Request that the source and targets no longer be shared (UNSHARE parameter).
v Request that the type of storage access to the data be changed.
See z/OS MVS Programming: Assembler Services Guide for more information about sharing data through the use of the IARVSERV macro.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state with PSW key that allows access to the source, target, or both, depending on the value specified through the TARGET_VIEW parameter. See z/OS MVS
Programming: Assembler Services Guide for additional information.
Task or SRB.
Any PASN, any HASN, any SASN.
31- or 64-bit.
Primary or access register (AR).
Enabled for I/O and external interrupts.
The caller may hold the local lock, but is not required to hold any locks.
Control parameters must be in the primary address space.
Programming requirements
v
You must specify a range list that is mapped by the IARVRL macro. This is done using the RANGLIST parameter. For information on the IARVRL macro, see
z/OS MVS Data Areas in the z/OS Internet library (www.ibm.com/systems/z/ os/zos/library/bkserv).
© Copyright IBM Corp. 1988, 2017
63
IARVSERV macro
v The calling program can use IARVSERV only to share data that resides within the address space, or in a data space that the calling program created.
v
Before your program issues the IARVSERV macro, it must use the GETMAIN,
STORAGE, or DSPSERV macro to obtain storage for the source, target, or both.
v Attributes for storage depend on the subpool specified on the GETMAIN,
STORAGE, or DSPSERV macros.
Restrictions
The following restriction apply: v For the SHARE parameter, the source area must not contain pages in the nucleus
(read-only, extended read-only, read-write and extended read-write areas).
Input register information
Before issuing the IARVSERV macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0
1
2-13
14
15
Reason code, if GPR 15 contains a non-zero return code; otherwise, used as a work register by the system.
Used as a work register by the system.
Unchanged.
Used as a work register by the system.
Return code.
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system.
Unchanged.
14-15
Used as work registers by the system.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
Take care when using the RETAIN=YES parameter value. With RETAIN=YES, storage is not returned to the system which reduces the amount available to the system and other programs, thus potentially affecting system performance.
In order to expedite the return of all internal control blocks for the shared storage back to the system, IBM recommends issuing IARVSERV UNSHARE against all
64
z/OS MVS Assembler Services Reference IAR-XCT
IARVSERV macro
views for both source and target that are originally shared. For an example of how to code the UNSHARE parameter, see the example in this book.
Syntax
The standard form of the IARVSERV macro is written as follows:
Description Syntax
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede IARVSERV.
IARVSERV
� One or more blanks must follow IARVSERV.
SHARE
UNSHARE
CHANGEACCESS
,RANGLIST=ranglist_addr
,NUMRANGE=numrange_addr
ranglist_addr: RS-type address, or register (2) - (12).
numrange_addr: RS-type address, or register (2) - (12).
Default
: 1 range
,TARGET_VIEW=READONLY
,TARGET_VIEW=SHAREDWRITE
,TARGET_VIEW=UNIQUEWRITE
,TARGET_VIEW=TARGETWRITE
,TARGET_VIEW=LIKESOURCE
,TARGET_VIEW=HIDDEN
,COPYNOW
,RETAIN=NO
,RETAIN=YES
Default
: RETAIN=NO
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default
: IMPLIED_VERSION
plistver: 0
Chapter 5. IARVSERV — Request to share virtual storage
65
IARVSERV macro
Parameters
The SHARE, UNSHARE, and CHANGEACCESS parameters designate the services of the IARVSERV macro, and are mutually exclusive.
The parameters are explained as follows:
SHARE
Requests that the source be made shareable through the target to create a sharing group. When you issue the IARVSERV macro with SHARE, you must specify the RANGLIST and the TARGET_VIEW parameters. The NUMRANGE parameter is optional.
UNSHARE
Requests that the specified virtual storage no longer be used to access shared storage. When you issue the IARVSERV macro with UNSHARE, you must specify the RANGLIST parameter. The NUMRANGE, and RETAIN parameters are optional. Using the RETAIN parameter can allow the target area data to remain available to other programs that can access the target area.
CHANGEACCESS
Requests that the type of access to the specified virtual storage be changed.
When you issue the IARVSERV macro with CHANGEACCESS, you must specify the RANGLIST and the TARGET_VIEW parameters. The NUMRANGE parameter is optional.
,RANGLIST=ranglist_addr
Specifies the name (RS-type) or address (in register 2-12) of a required input fullword that contains the address of the range list. The range list consists of a number of entries (as specified by NUMRANGE) where each entry is 28 bytes long. A mapping of each entry is provided through the mapping macro
IARVRL.
,NUMRANGE=numrange_addr
Specifies the name (RS-type) or address (in register 2-12) of an optional parameter that provides the number of entries in the supplied RANGLIST. The value specified must be no greater than 16 entries. If you do not specify
NUMRANGE, the system assumes the range list contains only one entry.
,TARGET_VIEW=READONLY
,TARGET_VIEW=SHAREDWRITE
,TARGET_VIEW=UNIQUEWRITE
,TARGET_VIEW=TARGETWRITE
,TARGET_VIEW=LIKESOURCE
,TARGET_VIEW=HIDDEN
Specifies the way you want to share storage when used on storage not already part of a sharing group, or how you want to change or add storage access to the sharing group for storage already shared.
The keywords that are valid for TARGET_VIEW and their meanings follow:
READONLY
Specifies that the target can be used only to read shared data. Any attempt to alter shared data by writing into the target will cause a program check.
SHAREDWRITE
Specifies that the target can be used to read or modify shared data.
When a program changes data in the target, the new data becomes visible among all those programs that have READONLY and
66
z/OS MVS Assembler Services Reference IAR-XCT
IARVSERV macro
SHAREDWRITE access to the source. Those programs with
UNIQUEWRITE access to the source will not see the changed data.
UNIQUEWRITE
Specifies that the target can be used to read shared data and to retain a private copy of the shared data should the source or any target get altered. When another user of the target modifies the data, the page in the target containing the modified data becomes a private copy that is unique to that user (with UNIQUEWRITE) and not accessible to any other program.
TARGETWRITE
Specifies that the target can be used to read shared data and retain a private copy of the shared data if this view of the shared data is altered. When another user of the target area writes new data into the target area, any page in the target area containing the new data becomes a private copy that is unique and is not seen by to any other user. The page is no longer a member of any sharing group. The original source data is unchanged. When a SHAREDWRITE view of the data gets altered, the TARGETWRITE view will see those changes.
LIKESOURCE
Specifies that the view type for the new target area is to be the same as the current view of the source. If the source is not currently shared, a copy of the source is made to the new target as if COPYNOW had been coded.
HIDDEN
Specifies that the data in the target area will be inaccessible until the view type is changed to READONLY, SHAREDWRITE,
UNIQUEWRITE, or TARGETWRITE. Any attempt to access a hidden target area will cause a program check.
,COPYNOW
Specifies whether the target should get a copy of the source data when using
UNIQUEWRITE or LIKESOURCE. You can use COPYNOW only when you specify TARGET_VIEW=UNIQUEWRITE or TARGET_VIEW=LIKESOURCE.
,RETAIN=YES
,RETAIN=NO
Specifies whether a copy of the shared data is to be retained in the target after the system finishes processing the UNSHARE request.
RETAIN=YES
Specifies that the target view should retain a copy of the shared data.
Using UNSHARE with RETAIN=YES requires the system to allocate new resources to back the target area.
RETAIN=NO
Specifies that the contents of the target area are unpredictable. To ensure zeroes, the user should issue a PGSER RELEASE or DSPSERV
RELEASE on the area after unsharing it. RETAIN=NO is the default.
Note: PGRLSE, PGSER RELEASE, PGSER FREE with RELEASE=Y, and
PGFREE RELEASE=Y may ignore some or all of the pages in the input range and will not notify the caller if this was done.
Any pages in the input range that match any of the following conditions will be skipped, and processing continues with the next page in the range:
Chapter 5. IARVSERV — Request to share virtual storage
67
IARVSERV macro
v Storage is not allocated or all pages in a segment have not yet been referenced.
v
Page is in PSA, SQA or LSQA.
v Page is V=R. Effectively, it's fixed.
v Page is in BLDL, (E)PLPA, or (E)MLPA.
v Page has a page fix in progress or a nonzero FIX count.
v Pages with COMMIT in progress or with DISASSOCIATE in progress.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
To code,
specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0
ABEND codes
IARVSERV might abnormally terminate with the abend code X'6C5'. See z/OS MVS
System Codes for an explanation and programmer response.
Return and reason codes
When the IARVSERV macro returns control to your program, GPR 15 contains the return code. If the return code is not 0, GPR 0 contains the reason code.
Table 7. Return and Reason Codes for the IARVSERV Macro
Hexadecimal
Return Code
00
Hexadecimal
Reason Code
None
Meaning and Action
Meaning
: The IARVSERV request completed successfully.
Action
: None required.
68
z/OS MVS Assembler Services Reference IAR-XCT
IARVSERV macro
Table 7. Return and Reason Codes for the IARVSERV Macro (continued)
Hexadecimal
Return Code
04
Hexadecimal
Reason Code
xx0101xx
Meaning and Action
Meaning
IARVSERV SHARE completed successfully.
The processor does not support SHARE for
UNIQUEWRITE. A unique copy of the target was made by the system.
04
04 xx0102xx xx0103xx
Action
: None required.
Meaning
: IARVSERV SHARE completed successfully. However, the system found a condition that would lead to a storage requirement conflict for sharing with UNIQUEWRITE. For example, the source might be in non-pageable storage. A copy of the target was made by the system to avoid this conflict.
Action
: None required. However, you might want to correct the storage conflict.
Meaning
: IARVSERV SHARE found that some source pages were not obtained using the GETMAIN or STORAGE macros, or the source and target keys do not match and the request is for a
UNIQUEWRITE target view. If the corresponding target pages were obtained using the GETMAIN or
STORAGE macro, then they have been made first reference.
04
04
04 xx0203xx xx0204xx xx0205xx
Action
: This is not necessarily an error. If you think you should not get this reason code, check program to be sure GETMAIN or STORAGE is issued and storage is of the same storage key for all source and target storage prior to using IARVSERV.
Meaning
: IARVSERV UNSHARE completed successfully. However, the system has overridden the RETAIN=NO option and kept a copy of the data in the target.
Action
: None required. However, you may want to correct your use of DIV.
Meaning
: IARVSERV UNSHARE completed successfully. The system has overridden the
RETAIN=YES option because the shared data is associated with a DIV object, and the target area is not the original window mapped to the DIV object.
The data in the target is unpredictable.
Action
: None required.
Meaning
: IARVSERV UNSHARE completed successfully. Some pages in the target area no longer belong to any sharing group. This could be due to a copy being created by UNIQUEWRITE, or a second invocation of UNSHARE on the same view.
Action
: None required.
Chapter 5. IARVSERV — Request to share virtual storage
69
IARVSERV macro
Table 7. Return and Reason Codes for the IARVSERV Macro (continued)
Hexadecimal
Return Code
04
Hexadecimal
Reason Code
xx0301xx
Meaning and Action
Meaning
: IARVSERV CHANGEACCESS completed successfully. The processor does not support
CHANGEACCESS for UNIQUEWRITE, and a unique copy of the target page was made.
04 xx030Cxx
Action
: None required.
Meaning
: IARVSERV CHANGEACCESS completed successfully. The system processed a
CHANGEACCESS request for UNIQUEWRITE or
TARGETWRITE for non-shared pages as a
SHAREDWRITE request.
08
08
08
0C
0C
0C xx0104xx xx0105xx xx0305xx xx010Axx xx013Cxx xx020Bxx
Action
: None required.
Meaning
: Environmental error. An unauthorized user attempted to share more pages than allowed by the installation.
Action
: Contact your system programmer to find out your installation limit and reduce the number of shared pages.
Meaning
: Environmental error. IARVSERV SHARE was requested with TARGETWRITE, but the SOP hardware feature was not available.
Action
: Contact your system programmer to find out when the SOP feature might become available.
Meaning
: Environmental error. IARVSERV
CHANGEACCESS was requested with
TARGETWRITE, but the SOP hardware feature was not available.
Action
: Contact your system programmer to find out when the SOP feature may become available.
Meaning
: Environmental error. IARVSERV SHARE cannot complete the request because of a shortage of resources.
Action
: Retry the request one or more times to see if resources become available. Contact the system programmer to determine resources available to you.
Meaning
: System error. IARVSERV SHARE cannot complete the request because a required page is unavailable or lost.
Action
: Check the paging data set for possible I/O errors. Refer to X'028' abend description in z/OS
MVS System Codes for paging error advice.
Meaning
: System error. IARVSERV UNSHARE cannot complete the request because of a required page being unavailable or lost.
Action
: Check the logrec data set for possible I/O errors. Refer to X'028' abend description in z/OS
MVS System Codes for paging error advice.
70
z/OS MVS Assembler Services Reference IAR-XCT
IARVSERV macro
Table 7. Return and Reason Codes for the IARVSERV Macro (continued)
Hexadecimal
Return Code
0C
Hexadecimal
Reason Code
xx030Bxx
Meaning and Action
Meaning
: System error. IARVSERV
CHANGEACCESS cannot complete the request because of a required page being unavailable or lost.
Action
: Check the logrec data set for possible I/O errors. Refer to X'028' abend description in z/OS
MVS System Codes for paging error advice.
Example 1
Issue a request to share eight pages as read-only, and use a register to specify the address of the range list.
SERV1
*
IARVSERV SHARE,RANGLIST=(4),TARGET_VIEW=READONLY
IARVRL
Example 2
Issue UNSHARE for the pages in Example 1, and specify that the system is not to retain the shared data.
SERV2
*
IARVSERV UNSHARE,RANGLIST=(4),RETAIN=NO
IARVRL
Example 3
Issue a request to share pages as read-only, and use an RS-type address to specify the location of the range list address.
SERV3
*
IARVSERV SHARE,RANGLIST=VRLPTR,TARGET_VIEW=READONLY
VRLPTR DC
MYVRL1 DS
IARVRL
A(MYVRL1)
7F
Example 4
Issue a request to share pages as target write.
SERV4
*
IARVSERV SHARE,RANGLIST=(5),TARGET_VIEW=TARGETWRITE
IARVRL
Example 5
Issue a request to change access for hidden.
SERV5
*
IARVSERV CHANGEACCESS,RANGLIST=(5),TARGET_VIEW=HIDDEN
IARVRL
Example 6
* The following example share one page of storage
* for both source and target using readonly view,
* and use a register to specify the address of the range list
* Clear the VRL share list. This will clear also the Stoken and
* the Alet fields for both Source and Target
XC VRLSHAR,VRLSHAR Clear VRL share list
Chapter 5. IARVSERV — Request to share virtual storage
71
IARVSERV macro
* Obtain storage for Source (one page only)
TITLE "IARVSERV- GET SOURCE STORAGE - ONE PAGE’
STORAGE OBTAIN,LENGTH=4096
ST 1,SADDR Store Source address
* Obtain storage for Target (one page only)
TITLE ’IARVSERV- GET TARGET STORAGE - ONE PAGE’
STORAGE OBTAIN,LENGTH=4096
ST 1,TADDR Store Target address
* Set the VRL share list
TITLE ’IARVSERV- SET VRL LIST FOR SHARE’
LA
ST
1,1
1,VRLNUMPG
Load number of pages to share
Store it in VRL share list
L
ST
L
ST
1,SADDR
1,VRLSVSA
1,TADDR
1,VRLTVSA
Load Source address
Store it in VRL share list
Load Target address
Store it in VRL share list
*
LA
ST
7,VRLSHAR
7,VRLPTR
Get address of VRLSHAR list
Store it in VRLPTR
LA 7,VRLPTR Save address of rangelist
* Now issue share for both Source and Target
TITLE ’IARVSERV- SHARE THE STORAGE’
IARVSERV SHARE,
RANGLIST=(7),
NUMRANGE=1,
TARGET_VIEW=READONLY
*
*
*
* The declares for example
*
VRLSHAR DS
VRLSVSA DS
0XL28
A
VRLSSTK1 DS
VRLSALET DS
VRLNUMPG DS
VRLTVSA DS
XL4
F
A
A
VRLTSTK1 DS
VRLTALET DS
VRLEND1 DS
VRLPTR DS
SADDR
TADDR
DS
DS
XL4
F
0F
XL4
XL4
XL4
Address for Source storage
Address for Target storage
* The following example illustrates how to expediate the return
* of all control blocks used to manage the shared storage by
* unsharing both Source and Target views which were shared in
* the previous example
TITLE ’IARVSERV- SET VRL UNSHARE LIST’
* Clear the VRL unshare list. This will clear also the Stoken
* and the Alet fields for both Source and Target in all ranges
* of the list
XC,VRLUNSH,VRLUNSH
* Set first range in the VRL unshare list
LA
ST
L
ST
1,1
1,SNUMPG1
1,TADDR
1,TVSA1
Load number of pages to unshare
Store it for first range
Get target address
Save it in the target address
* Set second range in the VRL unshare list
LA 1,1 Load number of pages to unshare
ST
L
ST
1,SNUMPG2
1,SADDR
1,TVSA2
Store it for second range
Get source address
Save it in the target address
*
LA
ST
LA
7,VRLUNSH
7,VRLPTR
7,VRLPTR
Get address of VRL unshare list
Store it in VRLPTR
Save address of rangelist
72
z/OS MVS Assembler Services Reference IAR-XCT
IARVSERV macro
* Now issue unshare for both Source and Target
TITLE ’IARVSERV- UNSHARE THE STORAGE’
IARVSERV UNSHARE,
RANGLIST=(7),
NUMRANGE=2
* The declares for example
*
VRLUNSH DS
SVSA1 DS
SSTK1 DS
SALET1 DS
SNUMPG1 DS
TVSA1 DS
TSTK1 DS
TALET1 DS
0XL56
A
XL4
F
A
A
XL4
F
SVSA2
SSTK2
DS
DS
SALET2 DS
SNUMPG2 DS
TVSA2
TSTK2
DS
DS
TALET2 DS
VRLEND2 DS
F
A
A
XL4
A
XL4
F
0F
*
*
IARVSERV—List form
Use the list form of the IARVSERV macro together with the execute form of the macro for applications that require reentrant code. The list form of the macro defines an area of storage, which the execute form of the macro uses to contain the parameters.
Syntax
The list form of the IARVSERV macro is written as follows:
Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede IARVSERV.
IARVSERV
� One or more blanks must follow IARVSERV.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default
: IMPLIED_VERSION
plistver: 0
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
list addr: symbol.
attr: 1- to 60-character input string.
Default
: 0D
Chapter 5. IARVSERV — Request to share virtual storage
73
IARVSERV macro
The parameters are explained under the standard form of the IARVSERV macro with the following exception:
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
Specifies the list form of the IARVSERV macro.
list addr is the name of a storage area to contain the parameters.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
IARVSERV - Execute form
Use the execute form of the IARVSERV macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Syntax
The execute form of the IARVSERV macro is written as follows:
Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede IARVSERV.
IARVSERV
�
One or more blanks must follow IARVSERV.
SHARE
UNSHARE
CHANGEACCESS
,RANGLIST=ranglist_addr
,NUMRANGE=numrange_addr
ranglist_addr: RS-type address, or address in register (2) - (12).
numrange_addr: RS-type address, or address in register (2) - (12).
Default
: 1 range
,TARGET_VIEW=READONLY
,TARGET_VIEW=SHAREDWRITE
,TARGET_VIEW=UNIQUEWRITE
,TARGET_VIEW=TARGETWRITE
,TARGET_VIEW=LIKESOURCE
,TARGET_VIEW=HIDDEN
74
z/OS MVS Assembler Services Reference IAR-XCT
IARVSERV macro
Syntax Description
,COPYNOW
,RETAIN=NO
,RETAIN=YES
Default
: RETAIN=NO
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default
: IMPLIED_VERSION
plistver: 0
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
list addr: RX-type address or address in register (2) - (12).
Default
: COMPLETE
The parameters are explained under the standard form of the IARVSERV macro with the following exception:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
Specifies the execute form of the IARVSERV macro.
list addr specifies the area that the system uses to contain the parameters.
COMPLETE, which is the default, specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
NOCHECK specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
Chapter 5. IARVSERV — Request to share virtual storage
75
IARVSERV macro
76
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 6. IARV64 — 64–bit virtual storage allocation
Description
The IARV64 macro allows a program to use the full range of virtual storage in an address space that is supported by 64-bit addresses. The macro creates and frees storage areas above the two gigabyte address and manages the physical frames behind the storage. Each storage area is a multiple of one megabyte in size and begins on a megabyte boundary. You can think of the IARV64 macro as the
GETMAIN/FREEMAIN, PGSER or STORAGE macro for virtual storage above the two gigabyte address.
The two gigabyte address in the address space is marked by a virtual line called the bar. The bar separates storage below the two gigabyte address, called below the bar, from storage above the two gigabyte address, called above the bar. The area above the bar is intended to be used for data only, not for executing programs. Programs use the IARV64 macro to obtain storage above the bar in
“chunks” of virtual storage called memory objects. Your installation can set a limit on the use of the address space above the bar for a single address space. The limit is called the MEMLIMIT.
When you create a memory object you can specify a guard area (not accessible) and a usable area. Later, you can change all or some of a guard area into an accessible area and vice versa.
The following services are provided:
GETSTOR
Create a memory object. (“REQUEST=GETSTOR option of IARV64” on page 80)
PAGEOUT
Notify the system that data within physical pages of one or more memory
objects will not be used in the near future. (“REQUEST=PAGEOUT option of IARV64” on page 89)
PAGEIN
Notify the system that data within physical pages of one or more memory
objects are needed in the near future. (“REQUEST=PAGEIN option of
DISCARDDATA
Discard data within physical pages of one or more memory objects.
(“REQUEST=DISCARDDATA option of IARV64” on page 97)
CHANGEGUARD
Request that a specified range in a memory object be changed from the guard state to the usable state or vice versa.
(“REQUEST=CHANGEGUARD option of IARV64” on page 102)
DETACH
Free one or more memory objects. (“REQUEST=DETACH option of
For guidance information on the use of 64–bit virtual storage allocation, see z/OS
MVS Programming: Assembler Services Guide.
© Copyright IBM Corp. 1988, 2017
77
IARV64 macro
After the separate descriptions of each individual Request are the following sections which apply to all of the Requests: v
The abend codes in “Abend and abend reason codes,”
v
The return and reason codes in “Return and reason codes,” and
v
Examples of using IARV64 in “Example” on page 79
Note:
The examples apply to REQUEST=GETSTOR and DETACH.
Facts associated with these services: v A segment represents one megabyte of virtual storage on a one megabyte boundary.
v The limit of the amount of storage per address space allowed to be used above the bar is called the MEMLIMIT. This is similar to the REGION parameter for storage below the bar. The following category of storage does not count against the MEMLIMIT:
– The guard area in a memory object.
Abend and abend reason codes
IARV64 might abnormally terminate with hexidecimal abend code DC2. See z/OS
MVS System Codes for an explanation and programmer response.
Return and reason codes
When the IARV64 macro returns control to your program: v
GPR 15 (and retcode, when you code RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code
RSNCODE) contains a reason code.
The following table identifies the hexadecimal return and reason codes. IBM support personnel may request the entire reason code, including the xx value.
Table 8. Return and Reason Codes for the IARV64 Macro
Hexadecimal
Return Code
00
Hexadecimal
Reason Code
—
Meaning and Action
Meaning
: Successful completion
02
04
06
—
—
—
Action
: None required
Meaning
: Successful completion, with exception. For a
LIST request, IARV64 requests have been issued since the previous call to LIST.
Action
: Re-issue the call if you need the information pertainining to those recent IARV64 requesets.
Meaning
: Successful completion, with exception. For a
LIST request, that there are additional MOMBs which were not returned on this calls to LIST.
Action
: Issue the LIST call again to get the additional information.
Meaning
: Successful completion, with exception. For a
LIST request, there are additional MOMBs which were not returned on this calls to LIST and IARV64 requests have been issued since the previous call to LIST.
Action
: Issue the LIST call again to get the additional information.
78
z/OS MVS Assembler Services Reference IAR-XCT
IARV64 macro
Table 8. Return and Reason Codes for the IARV64 Macro (continued)
Hexadecimal
Return Code
08
Hexadecimal
Reason Code
—
Meaning and Action
Meaning
: The request is rejected because of non-system failure.
This reason code can be issued for a conditional IARV64 request. In this case, this reason code is the same as the
DC2 reason code issued from an unconditional IARV64 request. See DC2 in z/OS MVS System Codes for an explanation and programmer response. If the reason code is not in DC2, it has one of the following meanings:
For a DETACH request, there were no memory objects deleted because none matched the user token provided.
For a LIST request, there were no memory objects returned because no memory objects match the selection criteria.
Action
: For a DETACH request, make sure that the user token was correct.
For a LIST request, no action is required.
For other requests, see DC2 in z/OS MVS System Codes for an explanation and programmer response.
Example
Operation:
1.
Get 2 MB above the bar
2.
Free the storage
The code is as follows.
SYSSTATE AMODE64=YES
*************************************************************
* Get storage above 2G *
*************************************************************
IARV64 REQUEST=GETSTOR,SEGMENTS=NUMSEG, *
ORIGIN=O,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,
MF=(E,V64L)
*
*
*
* Place code to check return/reason codes here
*
*************************************************************
* Free the storage *
*************************************************************
IARV64 REQUEST=DETACH,MEMOBJSTART=O,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,
MF=(E,V64L)
*
*
*
* Place code to check return/reason codes here
*
NUMSEG DC
ONEMEG DC
DYNAREA DSECT
AD(2)
AD(256)
LRETCODE DS
LRSNCODE DS
O DS
F
F
AD
IARV64 MF=(L,V64L)
Chapter 6. IARV64 — 64–bit virtual storage allocation
79
IARV64 macro
|
|
REQUEST=GETSTOR option of IARV64
REQUEST=GETSTOR allows you to create a memory object. To avoid an abend for exceeding a MEMLIMIT, specify the COND=YES parameter.
Note:
For more information on GETSTOR requests, see the z/OS MVS
Programming: Extended Addressability Guide.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and PSW key 8-15.
Task or SRB
Any PASN, any HASN, any SASN
A problem state caller running in PSW key 8-15 can use
GETSTOR/DETACH only when the primary address space is the home address space.
31- or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks may be held.
Control parameters must be in the primary address space.
Programming requirements
None.
Restrictions
No data space ALETs can be specified.
Input register information
Before issuing the IARV64 macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code, if GPR 15 is non-zero
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
80
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
name
IARV64 macro
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None
Syntax
The REQUEST=GETSTOR option of the IARV64 macro is written as follows:
Description
name: symbol. Begin name in column 1.
⌂
One or more blanks must precede IARV64.
IARV64
⌂
One or more blanks must follow IARV64.
REQUEST=GETSTOR
,COND=NO
,COND=YES
,SEGMENTS=segments
,FPROT=YES
,FPROT=NO
,SVCDUMPRGN=YES
,SVCDUMPRGN=NO
Default:
segments: RS-type address or address in register (2) - (12).
,PAGEFRAMESIZE=4K
,PAGEFRAMESIZE=PAGEABLE1MEG
Default:
PAGEFRAMESIZE=4K
Default:
FPROT=YES
Default:
COND=NO
SVCDUMPRGN=YES
,USERTKN=usertkn
,USERTKN=NO_USERTKN
usertkn: RS-type address or address in register (2) - (12).
Default:
USERTKN=NO_USERTKN
Chapter 6. IARV64 — 64–bit virtual storage allocation
81
IARV64 macro
Syntax
,GUARDSIZE=guardsize
,GUARDSIZE=0
,GUARDSIZE64=guardsize64
,GUARDSIZE64=0
,GUARDLOC=LOW
,GUARDLOC=HIGH
,TTOKEN=ttoken
,TTOKEN=NO_TTOKEN
,ORIGIN=origin
,SADMP=DEFAULT
,SADMP=YES
,SADMP=NO
|
|
|
||
||
||
||
||
|| ,USE2GTO32G=NO
,USE2GTO32G=YES
,USE2GTO64G=NO
,USE2GTO64G=YES
,EXECUTABLE=SYSTEM_RULES
,EXECUTABLE=YES
,EXECUTABLE=NO
,RETCODE=retcode
,RSNCODE=rsncode
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0, 1
Description
guardsize: RS-type address or address in register (2) - (12).
Default:
GUARDSIZE=0
guardsize64: RS-type address or address in register (2) - (12).
Default:
GUARDSIZE64=0
Default:
GUARDLOC=LOW
ttoken: RS-type address or address in register (2) - (12).
Default:
TTOKEN=NO_TTOKEN
origin: RS-type address or address in register (2) - (12).
Default:
SADMP=DEFAULT
Default:
USE2GTO32G=NO
Default:
USE2GTO64G=NO
Default:
EXECUTABLE=SYSTEM_RULES
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default:
PLISTVER=IMPLIED_VERSION
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Default:
MF=S
list addr: RS-type address or register (1) - (12)
82
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
IARV64 macro
Description
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IARV64 macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
REQUEST=GETSTOR
A required parameter. REQUEST=GETSTOR creates a memory object. Problem state routines running in PSW key 8-15 can use GETSTOR only when primary
= home. When the memory object owner terminates, the memory object will be freed.
,COND=NO
,COND=YES
An optional parameter that specifies whether the request is unconditional or conditional. In all cases the request will be abnormally ended for invalid requests, including violation of environmental restrictions. The default is
COND=NO.
,COND=NO
The request is unconditional. The request will be abnormally ended when the request cannot be satisfied.
,COND=YES
The request is conditional. The request will not be abnormally ended for resource unavailability.
,SEGMENTS=segments
A required input parameter that specifies the size of the memory object requested in megabytes. This must be a non-zero value. The amount of storage requested that is not in the guard state is charged against the MEMLIMIT for the address space where the memory object is to be created.
To code:
Specify the RS-type address, or address in register (2)-(12), of a doubleword field.
,PAGEFRAMESIZE=4K
,PAGEFRAMESIZE=PAGEABLE1MEG
An optional input parameter that specifies the size of the page frames to back the virtual storage mapped by the allocated memory object.
,PAGEFRAMESIZE=4K
The memory object is backed by 4 K page frames, if available. This is the default value.
,PAGEFRAMESIZE=PAGEABLE1MEG
The memory object is backed by pageable 1 M page frames at first reference, unless none are available. If none are available, the object is backed by 4 K page frames.
,FPROT=YES
,FPROT=NO
An optional parameter that specifies whether the memory object should be fetch protected. The default is FPROT=YES.
Chapter 6. IARV64 — 64–bit virtual storage allocation
83
IARV64 macro
,FPROT=YES
The entire memory object will be fetch protected. A program must have a
PSW key that matches the storage key of the memory object (or have PSW key 0) to reference data in the memory object.
,FPROT=NO
The memory object will not be fetch protected.
,SVCDUMPRGN=YES
,SVCDUMPRGN=NO
An optional parameter that specifies whether the memory object should be included in an SVC dump when region is requested. The default is
SVCDUMPRGN=YES.
,SVCDUMPRGN=YES
An SVC dump will include in its virtual storage capture for the owning address space the usable area of the memory object whenever
SDATA=RGN is specified.
,SVCDUMPRGN=NO
The SVC dump option SDATA=RGN will not include the virtual storage of this memory object in the dump.
,USERTKN=usertkn
,USERTKN=NO_USERTKN
An optional input parameter that identifies the user token to be associated with the memory object. This can be used on a later DETACH request to free all memory objects associated with this value.
To avoid inadvertent collisions in the values specified, the left word (bits 0-31) of the user token must be binary zeros for a problem state program. The system enforces this requirement. The right word (bits 32-63) should represent the virtual address of some storage related to the caller, which could be a control block address, an entry point address, and so on, which is used as an application choice.
The convention for supervisor state program is that the left word (bits 0-31) should represent an address of some storage related to the caller. The system enforces the rule that the left word is non-zero for supervisor state callers. The format for the right word (bits 32-63) is a choice left to the caller.
If you specify NO_USERTKN, the default is that no user token is supplied to associate this memory object with others. The default is NO_USERTKN.
To code:
Specify the RS-type address, or address in register (2)-(12), of a doubleword field.
,GUARDSIZE=guardsize
,GUARDSIZE=0
GUARDSIZE and GUARDSIZE64 are mutually exclusive keys. This set is optional; only one key may be specified. A fullword integer input parameter that indicates the number of megabytes of guard area to be created at the high or low end of the memory object. Guard areas cannot be referenced and when referenced will cause a program check. Guard area does not count against the
MEMLIMIT. A guard area can be reduced through CHANGEGUARD
CONVERT=FROMGUARD.
GUARDSIZE must not be larger than the size of the memory object. The default is 0.
84
z/OS MVS Assembler Services Reference IAR-XCT
IARV64 macro
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
,GUARDSIZE64=guardsize64
,GUARDSIZE64=0
GUARDSIZE64 belongs to a set of mutually exclusive keys. This set is optional; only one key may be specified. A doubleword integer input parameter that indicates the number of megabytes of guard area to be created at the high or low end of the memory object. Guard areas cannot be referenced and when referenced will cause a program check. Guard area does not count against the
MEMLIMIT. A guard area can be reduced through CHANGEGUARD
CONVERT=FROMGUARD.
GUARDSIZE64 must not be larger than the size of the memory object. The default is 0.
To code:
Specify the RS-type address, or address in register (2)-(12), of a doubleword field.
,GUARDLOC=LOW
,GUARDLOC=HIGH
An optional parameter that specifies whether the guard location is at the low virtual end of the memory object or the high virtual end. The default is
GUARDLOC=LOW.
,GUARDLOC=LOW
The guard areas are created starting from the origin of the memory object, that is, from the low virtual end.
,GUARDLOC=HIGH
The guard areas are created at the end of the memory object, that is, at the high virtual end.
,TTOKEN=ttoken
,TTOKEN=NO_TTOKEN
An optional input parameter that identifies the task to assume ownership of the memory object. The TTOKEN is returned by the TCBTOKEN macro.
If TTOKEN is specified, the task identified by the TTOKEN becomes the owner of the memory object. If TTOKEN is not specified, the currently dispatched task becomes the owner of the memory object.
The TTOKEN parameter must be used by an caller that is an SRB.
When the TTOKEN parameter is used by problem state program with PSW key 8 - 15, the target task must represent the calling task OR the jobstep task for the calling task OR the mother task. A caller cannot assign ownership to a task above the jobstep task.
A memory object will be freed when its owning task terminates.
If the TTOKEN parameter is not specified, and the caller is a task (rather than an SRB), the currently dispatched task will become the owner of the memory object. An SRB will be abnormally ended if the TTOKEN parameter does not specify a valid TTOKEN. The default is NO_TTOKEN.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,ORIGIN=origin
A required output parameter that contains the lowest address of the memory object. Note that when GUARDLOC=LOW is specified, the lowest address will
Chapter 6. IARV64 — 64–bit virtual storage allocation
85
IARV64 macro
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| point to a guard area, which will cause an ABEND if referenced. For
GUARDLOC=LOW, the first usable area is the origin plus the size of the guard area.
To code:
Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.
,SADMP=DEFAULT
,SADMP=YES
,SADMP=NO
An optional keyword input that specifies whether the memory object is to be captured in a stand-alone dump.
SADMP=DEFAULT
When PAGEFRAMESIZE is not 2G, the memory object should be captured in a stand-alone dump.
When PAGEFRAMESIZE is 2G, the memory object should not be captured in a stand-alone dump unless explicitly requested by the stand-alone dump program.
SADMP=YES
The memory object should be captured in a stand-alone dump.
SADMP=NO
The memory object should not be captured in a stand-alone dump unless explicitly requested by the stand-alone dump program.
Default:
SADMP=DEFAULT
,USE2GTO32G=NO
,USE2GTO32G=YES
An optional keyword input that specifies whether this is an explicit allocation request for 64-bit virtual storage in the 2G to 32G virtual storage area. IBM suggests that you not use this parameter because Java and other language runtimes use it. If there is not enough memory available in this range, the language runtimes could fail to start, or there could be increased memory usage and reduced performance. This parameter relates to usage of the compressed references feature, which is documented in z/OS User Guide for
IBM SDK, Java Technology Edition.
Check the RCEUSE2GTO32GAREAOK bit in the IARRCE macro to ensure that the system supports this keyword.
USE2GTO32G=NO
The request is not to be satisfied from the 2G to 32G virtual storage area.
USE2GTO32G=YES
The request is to be satisfied from the 2G to 32G virtual storage area. You cannot specify USE2GTO32G=YES with USE2GTO64G=YES. When you specify USE2GTO32G=YES, the system ignores USE2GTO64G=NO.
Default:
USE2GTO32G=NO
,USE2GTO64G=NO
,USE2GTO64G=YES
An optional keyword input that specifies whether this is an explicit allocation request for 64-bit virtual storage in the 2G to 64G virtual storage area. IBM suggests that you not use this parameter because Java and other language runtimes use it. If there is not enough memory available in this range, the language runtimes could fail to start, or there could be increased memory
86
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
IARV64 macro
usage and reduced performance. This parameter relates to usage of the compressed references feature, which is documented in z/OS User Guide for
IBM SDK, Java Technology Edition.
Check the RCE_USE2GTO64GENABLE bit in the IARRCE macro to ensure that the system supports this keyword.
USE2GTO64G=NO
The request is not to be satisfied from the 2G to 64G virtual storage area.
USE2GTO32G=YES
The request is to be satisfied from the 2G to 64G virtual storage area. You cannot specify USE2GTO64G=YES with USE2GTO32G=YES. When you specify USE2GTO64G=YES, the system ignores USE2GTO32G=NO.
Default:
USE2GTO64G=NO
,EXECUTABLE=SYSTEM_RULES
,EXECUTABLE=YES
,EXECUTABLE=NO
Specifies if code can be executed from the obtained storage on a system that has implemented instruction-execution-protection. The default parameter is
,EXECUTABLE=SYSTEM_RULES.
,EXECUTABLE=SYSTEM_RULES
This parameter indicates that code will obey the current system default.
,EXECUTABLE=YES
This parameter indicates that code is able to be executed from the obtained storage.
,EXECUTABLE=NO
This parameter indicates that code will not be able to be executed from the obtained storage on a system that has implemented instruction-executionprotection. The specification of NO will be ignored when executed on a system that has not implemented instruction-execution-protection or is not running an appropriate level of z/OS.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0, 1
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION
, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
Chapter 6. IARV64 — 64–bit virtual storage allocation
87
IARV64 macro
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
v 1 , supports both the following parameters and parameters from version 0:
– CONVERTSIZE64
– CONVERTSTART
– GUARDSIZE64
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0 or 1
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and
MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
88
z/OS MVS Assembler Services Reference IAR-XCT
IARV64 macro
REQUEST=PAGEOUT option of IARV64
REQUEST=PAGEOUT notifies the system that data within physical pages of one or more memory objects will not be used in the near future.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and PSW key 8-15.
Task or SRB
Any PASN, any HASN, any SASN
31- or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks may be held.
Control parameters must be in the primary address space and can reside both below and above the bar.
Programming requirements
None.
Restrictions
No data space ALETs can be specified.
Input register information
Before issuing the IARV64 macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code, if GPR 15 is non-zero
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Chapter 6. IARV64 — 64–bit virtual storage allocation
89
IARV64 macro
Syntax
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None
Syntax
The REQUEST=PAGEOUT option of the IARV64 macro is written as follows:
Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede IARV64.
IARV64
�
One or more blanks must follow IARV64.
REQUEST=PAGEOUT
,RANGLIST=ranglist
,NUMRANGE=numrange
,NUMRANGE=1
ranglist: RS-type address or address in register (2) - (12).
numrange: RS-type address or address in register (2) - (12).
Default:
NUMRANGE=1
,RETCODE=retcode
,RSNCODE=rsncode
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
Default:
PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0, 1
Default:
MF=S
list addr: RS-type address or register (1) - (12)
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
90
z/OS MVS Assembler Services Reference IAR-XCT
IARV64 macro
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IARV64 macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
REQUEST=PAGEOUT
A required parameter. REQUEST=PAGEOUT Notifies the system that data within the specified ranges will not be used in the near future, i.e. for time measured in seconds (or longer), and hence are good candidates for paging.
Areas of the memory object that are PAGEFIXed or are in guard areas will not be affected.
,RANGLIST=ranglist
A required input parameter. The range list consists of a number of entries (as specified by NUMRANGE) where each entry is 16 bytes long. A description of the fields in each entry is as follows:
VSA
denotes the starting address of the data to be acted on.
The address specified must be within a created memory object returned by GETSTOR
The value provided must always be on a physical page boundary.
The length of this field is 8 bytes.
NUMPAGES
contains the number of physical pages in the area.
The number of pages specified starting with the specified VSA must lie within a single memory object.
The length of this field is 8 bytes.
To code:
Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.
,NUMRANGE=numrange
,NUMRANGE=1
An optional input parameter that specifies the number of entries in the supplied range list.
The value specified must be no greater than 16. The default is 1.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
Chapter 6. IARV64 — 64–bit virtual storage allocation
91
IARV64 macro
,PLISTVER=0, 1
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
v 1 , supports both the following parameters and parameters from version 0:
– CONVERTSIZE64
– CONVERTSTART
– GUARDSIZE64
To code:
Specify one of the following: v
IMPLIED_VERSION v MAX v A decimal value of 0 or 1
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and
MF=E, this can be an RS-type address or an address in register (1)-(12).
92
z/OS MVS Assembler Services Reference IAR-XCT
IARV64 macro
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
REQUEST=PAGEIN option of IARV64
REQUEST=PAGEIN notifies the system that data within physical pages of one or more memory objects are needed in the near future.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and PSW key 8-15.
Task or SRB
Any PASN, any HASN, any SASN
31- or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks may be held.
Control parameters must be in the primary address space.
Programming requirements
None.
Restrictions
No data space ALETs can be specified.
Input register information
Before issuing the IARV64 macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code, if GPR 15 is non-zero
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Chapter 6. IARV64 — 64–bit virtual storage allocation
93
IARV64 macro
Syntax
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None
Syntax
The REQUEST=PAGEIN option of the IARV64 macro is written as follows:
Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede IARV64.
IARV64
� One or more blanks must follow IARV64.
REQUEST=PAGEIN
,RANGLIST=ranglist ranglist: RS-type address or address in register (2) - (12).
,NUMRANGE=numrange
,NUMRANGE=1
numrange: RS-type address or address in register (2) - (12).
Default:
NUMRANGE=1
retcode: RS-type address or register (2) - (12).
,RETCODE=retcode
,RSNCODE=rsncode rsncode: RS-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
Default:
PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0, 1
,MF=S
,MF=(L,list addr)
Default:
MF=S
list addr: RS-type address or register (1) - (12).
94
z/OS MVS Assembler Services Reference IAR-XCT
IARV64 macro
Syntax
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Description
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IARV64 macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
REQUEST=PAGEIN
A required parameter. REQUEST=PAGEIN notifies the system that data within the specified ranges is needed in the near future and should be, if possible, retrieved from auxillary storage. An attempt to PAGEIN a range which contains a guard area will cause an ABEND.
The caller must be in supervisor state OR system (0-7) PSW key OR be in a
PSW key which matches the key of the memory object storage to be paged out.
,RANGLIST=ranglist
A required input parameter, of a range list. The range list consists of a number of entries (as specified by NUMRANGE) where each entry is 16 bytes long. A description of the fields in each entry is as follows:
VSA
denotes the starting virtual address of the data to be acted on.
The virtual address specified must be within an allocated memory object returned by GETSTOR
It must always be on a physical page boundary.
The length of this field is 8 bytes.
NUMPAGES
contains the number of physical pages in the area.
The number of pages specified starting with the specified VSA must lie within a single memory object.
The length of this field is 8 bytes.
To code:
Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.
,NUMRANGE=numrange
,NUMRANGE=1
An optional input parameter that specifies the number of entries in the supplied range list.
The value specified must be no greater than 16. The default is 1.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
Chapter 6. IARV64 — 64–bit virtual storage allocation
95
IARV64 macro
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0, 1
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
v 1 , supports both the following parameters and parameters from version 0:
– CONVERTSIZE64
– CONVERTSTART
– GUARDSIZE64
To code:
Specify one of the following: v IMPLIED_VERSION v
MAX v A decimal value of 0 or 1
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The
96
z/OS MVS Assembler Services Reference IAR-XCT
IARV64 macro
list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and
MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
REQUEST=DISCARDDATA option of IARV64
REQUEST=DISCARDDATA allows you to discard data within physical pages of one or more memory objects.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and PSW key 8-15.
The caller must be running in supervisor state or with PSW key 0-7 or have a PSW key that matches the storage key of the memory object to be cleared by DISCARDDATA.
Task or SRB
Any PASN, any HASN, any SASN
31- or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks may be held.
Control parameters must be in the primary address space and can reside both below and above the bar.
Programming requirements
None.
Restrictions
No data space ALETs can be specified.
Chapter 6. IARV64 — 64–bit virtual storage allocation
97
IARV64 macro
Syntax
Input register information
Before issuing the IARV64 macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code, if GPR 15 is non-zero
2-13
14
15
Used as a work register by the system
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None
Syntax
The REQUEST=DISCARDDATA option of the IARV64 macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede IARV64.
IARV64
�
One or more blanks must follow IARV64.
REQUEST=DISCARDDATA
98
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,KEEPREAL=YES
,KEEPREAL=NO
,CLEAR=YES
,CLEAR=NO
,RANGLIST=ranglist
Description
Default:
Default:
KEEPREAL=YES
CLEAR=YES
ranglist: RS-type address or address in register (2) - (12).
,NUMRANGE=numrange
,NUMRANGE=1
numrange: RS-type address or address in register (2) - (12).
Default:
NUMRANGE=1
retcode: RS-type address or register (2) - (12).
,RETCODE=retcode
,RSNCODE=rsncode rsncode: RS-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
Default:
PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0, 1
Default:
MF=S
list addr: RS-type address or register (1) - (12).
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
IARV64 macro
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IARV64 macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
REQUEST=DISCARDDATA
A required parameter. REQUEST=DISCARDDATA discards the data within the specified ranges.
Areas of the memory object that are PAGEFIXed, or are guard areas in the address space identified by the input ALET will not be discarded. If the
DISCARDDATA service finds a PAGEFIXed, area or guard area in the area to be discarded, the caller will be abnormally ended. However, any prior pages processed will have data in an indeterminate state when CLEAR=NO is used, and KEEPREAL=YES is also used or set as the default.
Chapter 6. IARV64 — 64–bit virtual storage allocation
99
IARV64 macro
The caller must be in supervisor state or have PSW key 0-7 or have a PSW key that matches the storage key of the memory object to be cleared.
,KEEPREAL=YES
,KEEPREAL=NO
An optional parameter that specifies whether the real frames backing the pages to be discarded are to be freed or not. The default is KEEPREAL=YES.
,KEEPREAL=YES
The real frames backing the pages to be discarded are not to be freed unless there is shortage in real storage.
,KEEPREAL=NO
The real frames backing the pages to be discarded are to be freed. In this case, the CLEAR keyword value is ignored.
,CLEAR=YES
,CLEAR=NO
An optional parameter that specifies whether the data in the range should become binary zeros. The default is CLEAR=YES.
,CLEAR=YES
The data will become binary zeros.
,CLEAR=NO
The data will be indeterminate.
,RANGLIST=ranglist
A required input parameter, of a range list. The range list consists of a number of entries (as specified by NUMRANGE) where each entry is 16 bytes long. A description of the fields in each entry is as follows:
VSA
denotes the starting address of the data to be acted on.
The address specified must be within a created memory object returned by GETSTOR
The value provided must always be on a physical page boundary.
The length of this field is 8 bytes.
NUMPAGES
contains the number of physical pages in the area.
The number of pages specified starting with the specified VSA must lie within the memory object.
The length of this field is 8 bytes.
To code:
Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.
,NUMRANGE=numrange
,NUMRANGE=1
An optional input parameter that specifies the number of entries in the supplied range list.
The value specified must be no greater than 16. The default is 1.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
100
z/OS MVS Assembler Services Reference IAR-XCT
IARV64 macro
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0, 1
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
v 1 , supports both the following parameters and parameters from version 0:
– CONVERTSIZE64
– CONVERTSTART
– GUARDSIZE64
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0 or 1
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Chapter 6. IARV64 — 64–bit virtual storage allocation
101
IARV64 macro
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and
MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
REQUEST=CHANGEGUARD option of IARV64
REQUEST=CHANGEGUARD requests that a specified amount of a memory object be changed from the guard area to the usable area or vice versa. To avoid an abend for exceeding the MEMLIMIT, specify the COND=YES parameter.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and PSW key 8-15.
Task or SRB
PASN=HASN
A problem state caller running in PSW key 8-15 can use
CHANGEGUARD only when the primary address space is the home address space..
31- or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks may be held.
Control parameters must be in the primary address space.
Programming requirements
None.
Restrictions
No data space ALETs can be specified.
Input register information
Before issuing the IARV64 macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
102
z/OS MVS Assembler Services Reference IAR-XCT
�
Syntax
name
IARV64 macro
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code, if GPR 15 is non-zero
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None
Syntax
The REQUEST=CHANGEGUARD option of the IARV64 macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede IARV64.
IARV64
�
One or more blanks must follow IARV64.
REQUEST=CHANGEGUARD
,CONVERT=TOGUARD
,CONVERT=FROMGUARD
Chapter 6. IARV64 — 64–bit virtual storage allocation
103
IARV64 macro
Syntax
,COND=NO
,COND=YES
,MEMOBJSTART=memobjstart
,CONVERTSTART=convertstart
Description
Default:
COND=NO
memobjstart: RS-type address or address in register (2) - (12).
convertstart: RS-type address or address in register (2) - (12).
,CONVERTSIZE=convertsize
,CONVERTSIZE64=convertsize64
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
convertsize: RS-type address or address in register (2) - (12).
convertsize64: RS-type address or address in register (2) - (12).
,RETCODE=retcode retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
,RSNCODE=rsncode
,PLISTVER=IMPLIED_VERSION
Default:
PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0, 1
Default:
MF=S
list addr: RS-type address or register (1) - (12).
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IARV64 macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
REQUEST=CHANGEGUARD
A required parameter. REQUEST=CHANGEGUARD changes the amount of guard area in the specified memory object. It changes part of the memory object from a guard area to a usable area, or vice-versa.
If the CHANGEGUARD service finds a PAGEFIXed area in the area to be converted into a guard area, the caller will be abnormally ended.
When you code COND=YES and there is insufficient storage to satisfy the request, instead of the request being abnormally ended, the request will complete, but a return code will be set to indicate that the request could not be completed successfully.
104
z/OS MVS Assembler Services Reference IAR-XCT
IARV64 macro
For a problem state program running in PSW key (8–15), the PSW key of the caller must match the storage key of the memory object, and the memory object must be owned by one of the following: v The calling task v The job step task v An ancestor task up through the job step task
,CONVERT=TOGUARD
,CONVERT=FROMGUARD
A required parameter that specifies whether to add or remove guard areas.
,CONVERT=TOGUARD
Convert the specified number of usable areas to the guard areas. The data in the converted pages will be released. This operation reduces the amount of virtual storage that contributes toward the MEMLIMIT for the address space.
When GUARDLOC=LOW was specified, the first usable virtual address in the memory object is increased.
When GUARDLOC=HIGH was specified, the last usable virtual address in the memory object is decreased.
,CONVERT=FROMGUARD
Convert the specified amount of guard area to be usable area. The converted (now usable) area will appear as pages of zeros. This operation increases the amount of area that contributes toward the MEMLIMIT for the address space.
When GUARDLOC=LOW was specified, the first usable virtual address in the memory object is decreased.
When GUARDLOC=HIGH was specified, the last usable virtual address in the memory object is increased.
,COND=NO
,COND=YES
An optional parameter that specifies an unconditional or conditional request.
In all cases the request will be abnormally ended for invalid requests, including violation of environmental restrictions. The default is COND=NO.
,COND=NO
The request is unconditional. The request will be abnormally ended when the request cannot be satisfied.
,COND=YES
The request is conditional. The request will not be abnormally ended when a MEMLIMIT violation would occur.
,MEMOBJSTART=memobjstart
CONVERSTART and MEMOBJSTART are a set of mutually exclusive keys.
This set is required; only one keyword must be specified. An input parameter that belongs to a required set of mutually exclusive keys. It contains the address of the first byte in the memory object.
Specifying MEMOBJSTART will change the guard area only at the beginning or the end of the memory object. Whether the guard area is at the beginning or the end is specified on the IARV64 REQUEST=GETSTOR
GUARDLOC=[HIGH|LOW]
To code:
Specify the RS-type address, or address in register (2)-(12), of an eight byte pointer field.
Chapter 6. IARV64 — 64–bit virtual storage allocation
105
IARV64 macro
,CONVERTSTART=convertstart
CONVERSTART and MEMOBJSTART are a set of mutually exclusive keys.
This set is required; only one keyword must be specified. An input parameter that belongs to a required set of mutually exclusive keys. CONVERTSTART specifies the address to add a guard area (continuing to the virtual address specified by adding the bytes defined in CONVERTSIZE to CONVERTSTART minus one) when CONVERT(TOGUARD) is requested, and specifies the address to remove from the guard area (continuing to the virtual address space specified by adding the bytes defined by CONVERTSIZE to CONVERTSTART minus one) when CONVERT(FROMGUARD) is requested.
Two contiguous guard areas will be consolidated into one contiguous guard area whenever possible. For example, if if the guard area that was defined when the memory object was created is contiguous with a guard area created using CONVERTSTART, then the two guard areas are combined into one.
Specifying MEMOBJSTART will change the guard area only at the beginning or the end of the memory object. Whether the guard area is at the beginning or the end is specified on the IARV64 REQUEST=GETSTOR
GUARDLOC=[HIGH|LOW]
IBM recommends that if CONVERTSTART is used to manage the guard areas within a memory object that all REQUEST=CHANGEGUARD use
CONVERTSTART.
To code:
Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.
,CONVERTSIZE=convertsize
CONVERTSIZE64 and CONVERTSIZE are a set of mutually exclusive keys.
This set is required; only one key must be specified. A fullword integer input parameter, that indicates the number of contiguous megabytes that should be removed from the guard area (FROMGUARD) or that should be changed to being part of the guard area (TOGUARD).
For CONVERT=TOGUARD, CONVERTSIZE must not be larger than the number of usable pages in the memory object to allow successful completion.
For CONVERT=FROMGUARD, CONVERTSIZE must not be larger than the number of remaining pages in the guard area of the memory object to allow successful completion.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
,CONVERTSIZE64=convertsize64
CONVERTSIZE64 and CONVERTSIZE are a set of mutually exclusive keys.
This set is required; only one key must be specified. A doubleword integer input parameter, that indicates the number of contiguous megabytes that should be removed from the guard area (FROMGUARD) or that should be changed to being part of the guard area (TOGUARD).
For CONVERT=TOGUARD and MEMOBJSTART, CONVERTSIZE or
CONVERTSIZE64 must not be larger than the number of usable pages in the memory object to allow successful completion. For CONVERT=FROMGUARD,
CONVERTSIZE must not be larger than the number of remaining pages in the default guard area of the memory object to allow successful completion.
To code:
Specify the RS-type address, or address in register (2)-(12), of a doubleword field.
106
z/OS MVS Assembler Services Reference IAR-XCT
IARV64 macro
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0, 1
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
v 1 , supports both the following parameters and parameters from version 0:
– CONVERTSIZE64
– CONVERTSTART
– GUARDSIZE64
To code:
Specify one of the following: v IMPLIED_VERSION v
MAX v A decimal value of 0 or 1
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The
Chapter 6. IARV64 — 64–bit virtual storage allocation
107
IARV64 macro
list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and
MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
REQUEST=DETACH option of IARV64
REQUEST=DETACH allows you to free one or more memory objects.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and PSW key 8-15.
Task or SRB
Any PASN, any HASN, any SASN
Note:
that problem state caller running in PSW key 8-15 can use GETSTOR/DETACH only when primary = home.
31- or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks may be held.
Control parameters must be in the primary address space.
Programming requirements
None.
Restrictions
No data space ALETs can be specified.
Input register information
Before issuing the IARV64 macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
108
z/OS MVS Assembler Services Reference IAR-XCT
�
Syntax
name
IARV64 macro
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code, if GPR 15 is non-zero
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None
Syntax
The REQUEST=DETACH option of the IARV64 macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede IARV64.
IARV64
�
One or more blanks must follow IARV64.
REQUEST=DETACH
,MATCH=SINGLE
,MATCH=USERTOKEN
,MEMOBJSTART=memobjstart
Default:
MATCH=SINGLE
memobjstart: RS-type address or address in register (2) - (12).
Chapter 6. IARV64 — 64–bit virtual storage allocation
109
IARV64 macro
Syntax Description
,USERTKN=usertkn
,USERTKN=NO_USERTKN
,USERTKN=usertkn
,OWNER=YES
usertkn: RS-type address or address in register (2) - (12).
Default:
USERTKN=NO_USERTKN
usertkn: RS-type address or address in register (2) - (12).
Default:
OWNER=YES
,TTOKEN=ttoken
,TTOKEN=NO_TTOKEN
ttoken: RS-type address or address in register (2) - (12).
Default:
TTOKEN=NO_TTOKEN
Default:
COND=NO ,COND=NO
,COND=YES
,RETCODE=retcode
,RSNCODE=rsncode
,PLISTVER=IMPLIED_VERSION
Default:
PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0, 1
Default:
MF=S
list addr: RS-type address or register (1) - (12).
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IARV64 macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
REQUEST=DETACH
A required parameter. REQUEST=DETACH frees one or more memory objects.
Note that problem state programs running in PSW key (8-15) can use this function only when primary = home.
A memory object can be affected by DETACH when MATCH=SINGLE
USERTKN=NO_USERTKN is specified, even when the memory object has an
110
z/OS MVS Assembler Services Reference IAR-XCT
IARV64 macro
associated user token. Other invocations of DETACH will affect memory objects only when a matching user token is passed.
All I/O into each memory object specified must be complete before the
DETACH is requested. If the DETACH service finds a PAGEFIXed page in the memory object, the memory object will be not be freed, but any prior pages will have indeterminate data and the caller will be abnormally ended.
,MATCH=SINGLE
,MATCH=USERTOKEN
An optional parameter that indicates which memory objects are to be freed.
The default is MATCH=SINGLE.
,MATCH=SINGLE
specifies that the input contains MEMOBJSTART for a single memory object.
,MATCH=USERTOKEN
specifies that the input contains a user token that was passed to GETSTOR.
Note that memory objects not associated with a user token are not affected.
(Such objects would have to have been created using GETSTOR
NOUSERTKN). If you code MATCH=USERTOKEN, COND=YES and no matching user token exists, the system returns a return code instead of abending the caller. All memory objects associated with this user token are to be freed.
If the system encounters an error in processing a qualifying memory object
(e.g. unexpected pagefixed page), the processing ends. The system does not process that page or any further pages or memory objects and abends the caller.
,MEMOBJSTART=memobjstart
When MATCH=SINGLE is specified, a required input parameter that contains the address of the first byte in the memory object.
To code:
Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.
,USERTKN=usertkn
,USERTKN=NO_USERTKN
When MATCH=SINGLE is specified, an optional input parameter that identifies the user token to uniquely identify the memory object, as previously passed to GETSTOR.
When the memory object is not associated with the input token value, it will not be processed. The default is NO_USERTKN.
To code:
Specify the RS-type address, or address in register (2)-(12), of a doubleword field.
,USERTKN=usertkn
When MATCH=USERTOKEN is specified, a required input parameter that identifies the user token.
To code:
Specify the RS-type address, or address in register (2)-(12), of a doubleword field.
,OWNER=YES
An optional parameter that specifies whether the owning task still exists. The default is OWNER=YES.
Chapter 6. IARV64 — 64–bit virtual storage allocation
111
IARV64 macro
,OWNER=YES
The owning task must still exist (it may be in termination however). The
TTOKEN is provided or defaulted for the owning task.
,TTOKEN=ttoken
,TTOKEN=NO_TTOKEN
When OWNER=YES is specified, an optional input parameter that identifies the task that owns the memory object. The TTOKEN is returned by the
TCBTOKEN macro.
If TTOKEN is not specified, the task issuing the DETACH request must be the owner of the memory object.
When the TTOKEN parameter is used by problem state programs with PSW key 8-15, the target task must represent the calling task OR the jobstep task for the calling task OR the mother task. The mother task may not be given however when the calling task is itself a jobstep task.
If the TTOKEN parameter is not specified, and the caller is a TCB, the currently dispatched task must be the owner of the memory object. When
OWNER YES is specified by an SRB, the caller will be abnormally ended if the
TTOKEN value is not supplied. The default is NO_TTOKEN.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,COND=NO
,COND=YES
An optional parameter that specifies whether the request is unconditional or conditional. In all cases the request will be abnormally ended for invalid requests, including violation of environmental restrictions. The default is
COND=NO.
,COND=NO
The request is unconditional. The request will be abnormally ended when the request cannot be satisfied.
,COND=YES
The request is conditional. A REQUEST=DETACH, MATCH=USERTOKEN which does not select any memory objects will not be abnormally ended.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0, 1
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:
112
z/OS MVS Assembler Services Reference IAR-XCT
IARV64 macro
v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
v 1
, supports both the following parameters and parameters from version 0:
– CONVERTSIZE64
– CONVERTSTART
– GUARDSIZE64
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0 or 1
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and
MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
Chapter 6. IARV64 — 64–bit virtual storage allocation
113
IARV64 macro
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
114
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 7. IDENTIFY — Add an entry name
Description
Syntax
The IDENTIFY macro is used to add an entry name to a copy of a load module currently in virtual storage. The copy must be one of the following: v A copy that satisfied the requirements of a LOAD macro issued during the execution of the current task.
v The last load module given control, if control was passed to the load module using a LINK, LINKX, ATTACH, ATTACHX, XCTL, or XCTLX macro.
Note:
The IDENTIFY macro may not be issued by an asynchronous exit routine.
The IDENTIFY macro assigns the identified entry point as reentrant. Callers issuing this macro should be sure that their programs have been marked as reenterable.
The IDENTIFY service sets the addressing mode of the entry name that was added equal to the addressing mode of the major entry name. The system assigns the major entry name according to how the load module was constructed.
v If the load module was constructed using the linkage editor (and brought into virtual storage via program fetch or virtual fetch, the major entry name is the name of the load module in the partitioned data set directory (not an alias to that member).
v
If the load module was brought into storage by the loader, the major entry name is either the name that the user provided as input to the loader or the name that the loader used as a default.
If an authorized caller creates an entry name for a module in the link pack area, the IDENTIFY service places an entry for the alias on the active link pack area queue. If an unauthorized caller creates an entry name for a module in the link pack area, the IDENTIFY service places an entry for the alias on the task's job pack queue.
If an unauthorized caller creates an entry name for an authorized module, the
IDENTIFY service marks the new entry as unauthorized. In all other cases, the new entry name receives the same level of authorization as the main entry point.
The caller cannot have an EUT FRR established.
Syntax
The IDENTIFY macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede IDENTIFY.
IDENTIFY
© Copyright IBM Corp. 1988, 2017
115
IDENTIFY macro
Syntax
�
EP=entry name
EPLOC=entry name addr
||
,ENTRY=entry addr added
,ENTRY64=entry addr added
Description
One or more blanks must follow IDENTIFY.
entry name: Symbol
entry name addr: RX-type address, or register (0) or (2) - (12).
entry addr added: RX-type address, or register (1) or (2) - (12).
entry addr added: RX-type address, or register (1) or (2) - (12).
|
|
|
Parameters
The parameters are explained as follows:
EP=entry name
EPLOC=entry name addr
Specifies the entry name or address of the entry name. The name does not have to correspond to any symbol or name in the load module, and must not correspond to any name, alias, or added entry name for a load module in the link pack area queue, or the job pack area of the job step. If EPLOC is coded, the name must be padded to eight bytes, if necessary.
,ENTRY=entry addr added
Specifies the virtual storage address of the entry point being added. If the program that issues the IDENTIFY macro is running in 24-bit addressing mode, the value for entry addr added must be a 24-bit address.
Note:
If bit 31 of the entry point address is on, the system will turn it off.
,ENTRY64=entry addr added
Specifies the virtual storage address of the entry point being added. Use this when the virtual storage address is greater than 2G.
Return codes
When control is returned, register 15 contains one of the following return codes:
Meaning Hexadecimal
Return Code
00
04
08
0C
10
14
Successful completion of requested function.
Entry name and address already exist.
Entry name duplicates the major name of a load module currently in virtual storage; entry address was not added.
Entry address is not within an eligible load module; entry address was not added.
Request issued by an asynchronous exit routine; entry address was not added.
Entry name duplicates the name already used for a minor entry or for an entry created by another IDENTIFY request, and the entry point addresses are different; the current request is rejected.
116
z/OS MVS Assembler Services Reference IAR-XCT
34
38
24
28
2C
30
Hexadecimal
Return Code
18-1C
IDENTIFY macro
Meaning
An internal error occurred. Record the return code and contact the appropriate IBM support personnel.
An unexpected error occurred.
The address specified by the EPLOC parameter was fetch protected.
An internal error occurred. Record the return code and contact the appropriate IBM support personnel.
Unsuccessful processing due to a system queue area (SQA) storage shortage.
Unsuccessful processing due to a local system queue area (LSQA) storage shortage.
Unsuccessful processing due an error in the job pack area. Record the return code and contact the appropriate IBM support personnel.
Example
Add an entry name (PGMTAL2A) to a load module in virtual storage. Register 3 contains the entry point address.
IDENTIFY EP=PGMTAL2A,ENTRY=(R3)
Chapter 7. IDENTIFY — Add an entry name
117
IDENTIFY macro
118
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 8. IEAARR — Establish an associated recovery routine (ARR)
Description
IEAARR allows you to request that the system establish an associated recovery routine (ARR) while calling a target routine. In this case, the system performs the stacking PC instruction, then give control to your routine (the target routine).
When the target routine returns control, the system issues the corresponding PR instruction. Asynchronous exist processing will be prohibited while the ARR is running.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and PSW key 8-15
Task
Any PASN, any HASN, any SASN
31-bit or 64-bit
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
The caller is not required to hold any locks on entry. The caller may hold the local, CMS, or CPU lock.
None.
Programming requirements
The caller must include the IHAECVT mapping macro.
Restrictions
IEAARR must not be issued while a functional recovery routine (FRR) is established.
TARGETSTATE=PROB should only be issued by a caller currently running in problem state. TARGETSTATE=SUP should only be issued by a caller currently running in supervisor state.
Input register information
Before issuing the IEAARR macro, the caller does not have to place any information into any general purpose register (GPR) or access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0
The value placed in register 0 by the target routine prior to its returning to the system.
© Copyright IBM Corp. 1988, 2017
119
IEAARR macro
Syntax
1
2-13
14
15
The value placed in register 1 by the target routine prior to its returning to the system.
Unchanged
Used as a work register by the system
The value placed in register 15 by the target routine prior to its returning to the system.
When control returns to the caller, the ARs contain:
Register
Contents
0
The value placed in access register 0 by the target routine prior to its returning to the system.
1
2-13
14
15
The value placed in access register 1 by the target routine prior to its returning to the system.
Unchanged
Used as a work register by the system
The value placed in access register 15 by the target routine prior to its returning to the system.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The IEAARR macro is written as follows:
Description
name
⌂
name: symbol. Begin name in column 1.
One or more blanks must precede IEAARR.
IEAARR
⌂
ARRPTR=arrptr
ARR=arr
,DYNSTORAGE=AVAIL
,DYNSTORAGE=NOTAVAIL
One or more blanks must follow IEAARR.
arrptr: RX-type address or address in register (2) - (12).
arr: RX-type address or address in register (2) - (12).
Default:
DYNSTORAGE=AVAIL
120
z/OS MVS Assembler Services Reference IAR-XCT
IEAARR macro
Syntax Description
,ARRPARAMPTR=arrparamptr
,ARRPARAMPTR64=arrparamptr64
,ARRPARAM=arrparamp
,ARRPARAM64=arrparam64
arrparamptr: RX-type address or address in register (2) - (12).
arrparamptr64: RX-type address or address in register (2)-(12), of a 64-bit pointer field.
arrparamp: RX-type address or address in register (2) - (12).
arrparam64: RX-type address or address in register (2) - (12).
,PARAMPTR=paramptr
,PARAMPTR64=paramptr64
,PARAM=param
,PARAM64=param64
,TARGETPTR=targetptr
,TARGET=target
,TARGETSTATE=PROB
,TARGETSTATE=SUP
paramptr: RX-type address or address in register (2) - (12).
paramptr64: RX-type address or address in register (2)-(12), of a 64-bit pointer field.
param: RX-type address or address in register (2) - (12).
param64: RX-type address or address in register (2) - (12).
targetptr: RX-type address or address in register (2) - (12).
target: RX-type address or address in register (2) - (12).
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IEAARR macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
DYNSTORAGE=AVAIL
DYNSTORAGE=NOTAVAIL
An optional parameter that indicates whether this routine is sensitive to your having dynamic storage. The default is DYNSTORAGE=AVAIL.
DYNSTORAGE=AVAIL
Indicates that you have dynamic storage available.
DYNSTORAGE=NOTAVAIL
Indicates that you do not have dynamic storage available. The parameters are defined so that you can place each parameter value in a register and in so doing avoid the need to place parameter values into dynamic storage.
ARRPTR=arrptr
When DYNSTORAGE=AVAIL is in effect, a required input parameter that contains the address of the associated recovery routine. This routine gets control from RTM according to normal z/OS recovery protocols. As it is an
ARR, it will get control in AMODE 31.
To code:
Specify the RX-type address, or address in register (2)-(12), of a pointer field.
Chapter 8. IEAARR — Establish an associated recovery routine (ARR)
121
IEAARR macro
ARR=arr
When DYNSTORAGE=NOTAVAIL is specified, a required input parameter that is the associated recovery routine. This routine gets control from RTM according to normal z/OS recovery protocols. As it is an ARR, it will get control in AMODE 31.
To code:
Specify the RX-type address, or address in register (2)-(12), of the associated recovery routine.
,ARRPARAMPTR=arrparamptr
When DYNSTORAGE=AVAIL is in effect and SYSSTATE AMODE64=YES is not in effect, a required input parameter that contains the address of the parameter area that is to be passed to the ARR upon error. The address is placed in the first four bytes of the area pointed to by SDWAPARM and in
GPR 2. Note that the second four bytes of the area pointed to by SDWAPARM will not contain interface information.
To code:
Specify the RX-type address, or address in register (2)-(12), of a pointer field.
,ARRPARAM=arrparam
When DYNSTORAGE=NOTAVAIL is specified and SYSSTATE AMODE64=YES is not in effect, a required input parameter that is the parameter area that is to be passed to the ARR upon error. The address is placed in the first four bytes of the area pointed to by SDWAPARM and in GPR 2. Note that the second four bytes of the area pointed to by SDWAPARM will not contain interface information.
To code:
Specify the RX-type address, or address in register (2)-(12), of the parameter area.
,ARRPARAMPTR64=arrparamptr64
When DYNSTORAGE=AVAIL is in effect and SYSSTATE AMODE64=YES is in effect, a required 8-byte input parameter that contains the address of the parameter area that is to be passed to the ARR upon error. The address is placed in the 8-byte area pointed by SDWAPARM and in the 64-bit GPR 2.
To code:
Specify the RX-type address, or address in register (2)-(12), of a 64-bit pointer field.
,ARRPARAM64=arrparam64
When DYNSTORAGE=NOTAVAIL is specified and SYSSTATE AMODE64=YES is in effect, a required 8-byte input parameter that is the parameter area that is to be passed to the ARR upon error. The address is placed in the 8-byte area pointed by SDWAPARM and in the 64-bit GPR 2.
To code:
Specify the RX-type address, or address in register (2)-(12), of the parameter area.
,PARAMPTR=paramptr
When DYNSTORAGE=AVAIL is in effect and SYSSTATE AMODE64=YES is not in effect, a required input parameter that contains the address of a parameter that is to be passed to the target routine in GPR 1.
To code:
Specify the RX-type address, or address in register (2)-(12), of a pointer field.
,PARAM=param
When DYNSTORAGE=NOTAVAIL is specified and SYSSTATE AMODE64=YES is not in effect. a required input parameter that is the parameter that is to be passed to the target routine in GPR 1.
122
z/OS MVS Assembler Services Reference IAR-XCT
IEAARR macro
To code:
Specify the RX-type address, or address in register (2)-(12), of the parameter.
,PARAMPTR64=paramptr64
When DYNSTORAGE=AVAIL is in effect and SYSSTATE AMODE64=YES is in effect, a required 8-byte input parameter that contains the address of the parameter that is to be passed to the target routine in 64-bit GPR 1.
To code:
Specify the RX-type address, or address in register (2)-(12), of a 64-bit pointer field.
,PARAM64=param64
When DYNSTORAGE=NOTAVAIL is specified and SYSSTATE AMODE64=YES is in effect, a required 8-byte input parameter that is to be passed to the target routine in 64-bit GPR 1.
To code:
Specify the RX-type address, or address in register (2)-(12), of the parameter.
,TARGETPTR=targetptr
When DYNSTORAGE=AVAIL is in effect, a required input parameter that contains the address of the routine to which the system is to branch after establishing the ARR. The target routine will get control in the same key and state as the IEAARR caller, in AMODE 31, with the following input registers:
General Purpose Registers:
Register
Contents
0
1
Not part of the intended interface
Address of parameter area provided by IEAARR caller
2-13
Unchanged from the IEAARR caller
14
Tne return address
15
The address of the target routine
Access Registers:
Register
Contents
0-1
Not part of the intended interface
2-13
Unchanged from the IEAARR caller
14
15
Not part of the intended interface
Not part of the intended interface
The target routine gets control with one more entry on the linkage stack than existed when IEAARR was called. That linkage stack entry contains the caller's registers 2-13 which can be extracted using the EREG instruction if needed.
The target routine need not save any registers, but is expected to return to the address provided in GPR 14 on entry. The target routine can pass information back to the caller of IEAARR by placing it in GPR/AR 0, 1, and/or 15. The
IEAARR caller will resume immediately after the IEAARR macro expansion.
The target routine gets control with its primary and secondary ASNs, which are both the same as the primary ASN when IEAARR was invoked.
To code:
Specify the RX-type address, or address in register (2)-(12), of a pointer field.
Chapter 8. IEAARR — Establish an associated recovery routine (ARR)
123
IEAARR macro
,TARGET=target
When DYNSTORAGE=NOTAVAIL is specified. a required input parameter that is the routine to which the system is to branch after establishing the ARR. The target routine interface is identical to that described under the TARGETPTR parameter.
To code:
Specify the RX-type address, or address in register (2)-(12), of the target routine.
,TARGETSTATE=PROB
,TARGETSTATE=SUP
A required parameter that indicates the requested PSW state of the target routine.
,TARGETSTATE=PROB
indicates the target routine is to get control in problem state. This should only be used by a caller currently in problem state.
,TARGETSTATE=SUP
indicates the target routine is to get control in supervisor state. This should only be used by a caller currently in supervisor state.
ABEND codes
The caller may get the following abend code:
0C2-02
TARGETSTATE=SUP was requested by a caller currently running in problems tate.
Return codes
None.
Example
Branch to the target routine pointed to by field TP, and establish as an ARR the routine pointed to by field AP. Pass to the target area in register 1 the contents of field PP. Make sure that the ARR will get access to the contents of field APP
(which ordinarily would contain the address of a parameter area). Make sure that the target routine gets control in problem state (which implies that the caller of
IEARR should currently be running in problem state).
The code is as follows.
IEAARR TARGETPTR=TP,ARRPTR=AP,PARAMPTR=PP,
ARRPARAMPTR=APP,TARGETSTATE=PROB
...
124
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 9. IEABRC — Relative branch macro
Description
The IEABRC macro defines macros to intercept and change various base-displacement branch instructions to their relative branch equivalents. Many macros contain base-displacement branches that could functionally be relative branches. In order to write an assembler routine that both uses these macros and uses relative branching, you can use IEABRC to enable those macros to use relative branches. Changing base-displacement branch instructions to their relative branch equivalents can eliminate code addressability issues.
Note:
Using IEABRC does not guarantee that all macros can be invoked without code addressability. Some macros still require addressability to the location where the macro is invoked.
Environment
Because IEABRC is not an executable macro, there are no specific environment requirements.
Programming requirements
None.
Restrictions
IEABRC converts branch condition instructions to relative branch condition instructions except when both of the following conditions are true: v The branch target ends with ")" v A "(" in the 2nd or subsequent characters of the branch target is not preceded by
"+" or "-"
For example:
B X(15)
Remains a base/displacement branch
B X+(15)
Converted to a relative branch
B X+Y
Converted to a relative branch
Register information
Because IEABRC is not an executable macro, there is no need to save and restore register contents.
Performance implications
None.
Syntax
The IEABRC macro is written prior to any base/displacement branch that needs to be converted to a relative branch as follows:
© Copyright IBM Corp. 1988, 2017
125
IEABRC macro
Syntax
�
COPY IEABRC
�
Description
One or more blanks must precede COPY.
One or more blanks must follow IEABRC.
Parameters
IEABRC has no parameters of its own.
Example
The following example converts a base/displacement branch to a relative branch:
TEST
R12
CSECT
EQU 12
USING STATICAREA,R12
COPY IEABRC
ENQ (QNAME,RNAME,E,RNAMELEN,SYSTEM)
STATICAREA DC D’0’
QNAME
RNAME
DC
DC
CL8’THEQNAME’
CL8’THERNAME’
RNAMELEN EQU L’RNAME
END TEST
126
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 10. IEABRCX — Relative branch macro extension
Description
The IEABRCX macro defines macros to intercept and change various base-displacement branch instructions to their relative branch equivalents. Many macros contain base-displacement branches that could functionally be relative branches. In order to write an assembler routine that both uses these macros and uses relative branching, you can use IEABRCX to enable those macros to use relative branches. Changing base-displacement branch instructions to their relative branch equivalents can eliminate code addressability issues.
Note:
1.
Using IEABRCX does not guarantee that all macros can be invoked without code addressability. Some macros still require addressability to the location where the macro is invoked.
2.
IBM recommends using IEABRCX instead of IEABRC because IEABRCX provides additional functionality. Using IEABRCX DEFINE is equivalent to using COPY IEABRC.
Environment
There are no specific environment requirements.
Programming requirements
None.
Restrictions
IEABRCX converts branch condition instructions to relative branch condition instructions except when both of the following conditions are true: v The branch target ends with ")" v A "(" in the 2nd or subsequent characters of the branch target is not preceded by
"+" or "-"
For example:
B X(15)
Remains a base/displacement branch
B X+(15)
Converted to a relative branch
B X+Y
Converted to a relative branch
Register information
IEABRCX changes no registers, so there is no need to save and restore register contents.
Performance implications
None.
© Copyright IBM Corp. 1988, 2017
127
IEABRCX macro
Syntax
Syntax
The IEABRCX macro is written prior to any base/displacement branch that needs to be converted to a relative branch as follows:
Description
� One or more blanks must precede IEABRCX.
IEABRCX
� One or more blanks must follow IEABRCX.
DEFINE
PUSH
DISABLE
ENABLE
POP
Parameters
The parameters are explained as follows:
DEFINE
Defines and enables the conversion. It must be placed prior to any base/displacement branch that needs to be converted to a relative branch.
It must precede any uses of IEABRCX with other options. At the point of issuing IEABRCX DEFINE, the state of conversions is enabled.
PUSH
Saves the current state (enabled or disabled). At any point in the assembly, the number of PUSH's must not exceed the number of POP's by 255 or an assembler error might result. You must have issued IEABRCX DEFINE prior to this.
DISABLE
Disables the conversions so that subsequent base-displacement branches revert to their normal form. You must have issued IEABRCX DEFINE prior to this.
ENABLE
Enables the conversions so that subsequent base-displacement branches are converted. You must have issued IEABRCX DEFINE prior to this.
POP
Restores to the previous state. A corresponding PUSH must exist or an assembler error might result. You must have issued IEABRCX DEFINE prior to this.
Example
The following example enables conversion of a base/displacement branch to a relative branch, saves the current state, disables the conversion, then restores the previous state.
128
z/OS MVS Assembler Services Reference IAR-XCT
TEST
R12
CSECT
EQU 12
USING STATICAREA,R12
IEABRCX DEFINE
ENQ (QNAME,RNAME,E,RNAMELEN,SYSTEM)
IEABRCX PUSH Save the current state
IEABRCX DISABLE Disable conversion
-- base/displacement branches not converted
IEABRCX POP Restore the previous state
ENQ (QNAME,RNAME2,E,RNAME2LEN,SYSTEM)
STATICAREA DC D’0’
QNAME DC CL8’THEQNAME’
RNAME DC CL8’THERNAME’
RNAMELEN EQU L’RNAME
RNAME2 DC CL9’THERNAME2’
RNAME2LEN EQU L’RNAME2
END TEST
IEABRCX macro
Chapter 10. IEABRCX — Relative branch macro extension
129
IEABRCX macro
130
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 11. IEAFP — Floating point services
Description
IEAFP allows you to request that, for your work unit, the system will stop saving additional floating point status. This status consists of the additional floating point registers (FPRs) 1, 3, 5, 7-15 and the floating point control (FPC) register. In addition, the system will stop saving vector register status.
You would typically use this service only when you are a server task which
"subdispatches" unrelated units of work (that is, CICS transactions). To avoid subsequent units of work being penalized by the floating point actions of previous units of work, the additional FP status saving function of the operating system can be turned off. When a unit of work actually begins to use FP, all appropriate status saving will be resumed.
IEAFP allows you to request that the system stop saving vector register status, while continuing to save additional floating point status.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and PSW key 8-15
Task or SRB
Any PASN, any HASN, any SASN
31-bit
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
The caller is not required to hold any locks on entry. The caller may hold the local, CMS, or CPU lock.
None
Programming requirements
The caller can include the IHAFPRET mapping macro to get equate symbols for the return and reason codes provided by the IEAFP macro.
Restrictions
IEAFP must not be issued from an asynchronous exit routine.
Input register information
Before issuing the IEAFP macro, the caller does not have to place any information into any general purpose register (GPR) or access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
© Copyright IBM Corp. 1988, 2017
131
⌂
Syntax
name
0
1
Reason code, when GPR 15 is non-zero
Used as a work register by the system
2-13
Unchanged
14-15
Used as a work register by the system
15
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The IEAFP macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede IEAFP.
IEAFP
⌂ One or more blanks must follow IEAFP.
STOP
STOPVECTOR
,RETCODE=retcode
,RSNCODE=rsncode
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Parameters
The parameters are explained as follows:
132
z/OS MVS Assembler Services Reference IAR-XCT
name
An optional symbol, starting in column 1, that is the name on the IEAFP macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
STOP
STOPVECTOR
A required input parameter that specifies the type of request.
STOP
Indicates to stop saving additional floating point status and vector register status until such time as new operations require it.
STOPVECTOR
Indicates to stop saving vector register status while continuing the saving of floating point status.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
ABEND codes
None.
Return and reason codes
When the IEAFP macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code
RSNCODE) contains a reason code.
Macro IHAFPRET provides equate symbols for the return and reason codes.
The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code. IBM support personnel may request the entire reason code, including the xxxx value.
Table 9. Return and reason codes for the IEAFP macro
Return code
0
Reason code
—
Equate symbol, meaning, and action
Equate symbol
: IeafpRc_OK
8 —
Meaning
: IEAFP request successful.
Action
: None required.
Equate symbol
: IeafpRc_InvParm
Meaning
: IEAFP request specifies parmeters that are not valid.
Action
: Refer to the action provided with the specific reason code.
Chapter 11. IEAFP — Floating point services
133
Table 9. Return and reason codes for the IEAFP macro (continued)
Return code
8
Reason code
xxxx0801
Equate symbol, meaning, and action
Equate symbol
: IeafpRsnBadFunction
C
C
—
xxxx0C01
Meaning
: Incorrect value passed to target routine.
Action
: Check for possible storage overlay.
Equate symbol
: IeafpRc_Env
Meaning
: Environmental error
Action
: Refer to the action provided with the specific reason code.
Equate symbol
: IeafpRsnFromAsynchExit
Meaning
: IEAFP was issued from an asynchronous exit routine.
Action
: Avoid issuing IEAFP from an asynchronous exit routine.
Example
Operation:
1.
Stop additional status saving.
The code is as follows:
IEAFP STOP
134
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
||
|
||
||
||
||
||
|
||
||
|||
|
|
|
|
|
|
|
Chapter 12. IEAGSF — Guarded-Storage Facility services
Environment
The requirements for the caller are:
Environmental Factor Requirement
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Problem state and PSW key 8-15
Task
For START and STOP: Any PASN, any HASN, any SASN.
For UPDATE: PASN=HASN
31- or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
The caller is not required to hold any locks on entry, but may hold the LOCAL lock.
Control parameters must be in the primary address space.
Programming Requirements
Control parameters must be below the 2G line.
Include the IHAGSRET mapping macro to get equate symbols for the return and reason codes provided by the IEAGSF macro.
Restrictions
IEAGSF is only available if the CVTGSF bit is on.
IEAGSF must not be issued from an SRB or an asynchronous exit routine (IRB).
IEAGSF must not be issued for a task above the jobstep program TCB.
Supervisor-state or system key users must not use this facility if unauthorized programs can run in the same address space because unauthorized programs have the ability to change the GSF controls.
The caller must not have an FRR established when invoking IEAGSF UPDATE.
Input Register Information
Before issuing the IEAGSF macro, the caller does not have to place any information into any general purpose register (GPR) or access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.
Output Register Information
When control returns to the caller, the GPRs contain:
Register
Contents
© Copyright IBM Corp. 1988, 2017
135
|
|
|
|
|
||
||
||
|
|
|
|
|
|
|
||
||
||
||
||
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |
|
||||||||||||||||
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
0
1
Reason code, when GPR 15 is non-zero
Used as a work register by the system
2-13
Unchanged
14-15
Used as a work register by the system
15
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance Implications
None.
Syntax main diagram
► ►►
name
� IEAGSF �
►
, INITIALCONTROLS = 0.
START
, INITIALCONTROLS =
initialcontrols
STOP
UPDATE , TCBTOKEN =
tcbtoken
, UPDATECONTROLS =
updatecontrols
►
, RETCODE =
retcode
, RSNCODE =
rsncode
, UPDATEMASK = 0001
, UPDATEMASK = 0010
, UPDATEMASK = 0011
, UPDATEMASK = 0100
, UPDATEMASK = 0101
, UPDATEMASK = 0110
, UPDATEMASK = 0111
, UPDATEMASK = 1000
, UPDATEMASK = 1001
, UPDATEMASK = 1010
, UPDATEMASK = 1011
, UPDATEMASK = 1100
, UPDATEMASK = 1101
, UPDATEMASK = 1110
, UPDATEMASK = 1111
, PLISTVER = IMPLIED_VERSION
, PLISTVER = MAX
, PLISTVER = 0
, MF = S
►
,
,
,
MF
MF
MF
=
=
=
(
(
(
L
E
M
,
,
,
list addr list addr list addr
, 0D
,
attr
, COMPLETE
)
, NOCHECK
, COMPLETE
, NOCHECK
)
)
►
►
►◄
136
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IEAGSF macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
,INITIALCONTROLS=initialcontrols
,INITIALCONTROLS=0.
When START is specified, an optional input parameter, which contains the initial GSF controls (GSCB) to be used. See the description of the
Guarded-Storage Control Block in the z/Architecture Principles of Operation manual. The default is 0. The initial GSCB will be set to zeros.
To code:
Specify the RS-type address, or address in register (2) - (12), of a
32-character field.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms of IEAGSF in the following order: v Use IEAGSF ...MF=(M,list-addr,COMPLETE) specifying appropriate parameters, including all required ones.
v Use IEAGSF ...MF=(M,list-addr,NOCHECK), specifying the parameters that you want to change.
v Use IEAGSF ...MF=(E,list-addr,NOCHECK), to execute the macro.
Chapter 12. IEAGSF — Guarded-Storage Facility services
137
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
,list addr
The name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this can be an RS-type address or an address in register (1) -
(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters. When using the
NOCHECK option, be sure that it is preceded by a modify or execute form invocation that specifies or defaults to the COMPLETE option. This ensures that the parameter list is initialized completely.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2) - (12) or
(15), (GPR15), (REG15), or (R15). Do not specify with MF=M.
138
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (0) or (2) -
(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0). Do not specify with
MF=M.
START
A required input parameter keyword that indicates that the system should start the Guarded-Storage Facility and start the saving of Guarded-Storage Facility control information for the current TCB.
To code:
Specify a value.
,STOP
A required input parameter keyword that indicates that the system should stop the saving of Guarded-Storage Facility control information and stop the
Guarded-Storage Facility for the current TCB. Note that MF= is not supported
(or needed) for IEAGSF STOP.
To code:
Specify a value.
,TCBTOKEN=tcbtoken
When UPDATE is specified, a required input parameter, which contains the
TCBTOKEN of the task to be updated. All of that task's subtasks will also be updated. The TCBTOKEN must be valid and must represent the jobstep program task or a subtask of the jobstep program task.
To code:
Specify the RS-type address, or address in register (2) - (12), of a
16-character field.
,UPDATE
A required input parameter keyword that indicates that the system should synchronously update the Guarded-Storage Facility control information for the input TCB and all of its subtasks. Any tasks which have not issued IEAGSF
START will be ignored.
To code:
Specify a value.
,UPDATECONTROLS=updatecontrols
When UPDATE is specified, a required input parameter, which contains a new
GSF Control Block ('GSCB') to be used. See the description of the
Guarded-Storage Control Block in the z/Architecture Principles of Operation manual.
To code:
Specify the RS-type address, or address in register (2) - (12), of a
32-character field.
,UPDATEMASK=0001
,UPDATEMASK=0010
,UPDATEMASK=0011
,UPDATEMASK=0100
,UPDATEMASK=0101
,UPDATEMASK=0110
,UPDATEMASK=0111
,UPDATEMASK=1000
,UPDATEMASK=1001
,UPDATEMASK=1010
,UPDATEMASK=1011
,UPDATEMASK=1100
Chapter 12. IEAGSF — Guarded-Storage Facility services
139
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
,UPDATEMASK=1101
,UPDATEMASK=1110
,UPDATEMASK=1111
When UPDATE is specified, a required parameter, which specifies a mask that describes which of the 4 doublewords of each task's GSCB are to be updated using the new GSCB specified by UPDATECONTROLS. Use caution when updating the fourth doubleword - you may not want multiple tasks sharing the GSEPL that it points to.
,UPDATEMASK=0001
specifies that only the fourth doubleword is to be updated.
,UPDATEMASK=0010
specifies that only the third doubleword is to be updated.
,UPDATEMASK=0011
specifies that only the third and fourth doubleword are to be updated.
,UPDATEMASK=0100
specifies that only the second doubleword is to be updated.
,UPDATEMASK=0101
specifies that only the second and fourth doubleword are to be updated.
,UPDATEMASK=0110
specifies that only the second and third doublewords are to be updated.
,UPDATEMASK=0111
specifies that only the second, third, and fourth doublewords are to be updated.
,UPDATEMASK=1000
specifies that only the first doubleword is to be updated.
,UPDATEMASK=1001
specifies that only the first and fourth doublewords are to be updated.
,UPDATEMASK=1010
specifies that only the first and third doublewords are to be updated.
,UPDATEMASK=1011
specifies that only the first and third and fourth doublewords are to be updated.
,UPDATEMASK=1100
specifies that only the first and second doublewords are to be updated.
,UPDATEMASK=1101
specifies that only the first and second and fourth doublewords are to be updated.
,UPDATEMASK=1110
specifies that only the first and second and third doublewords are to be updated.
,UPDATEMASK=1111
specifies that all four doublewords are to be updated.
ABEND Codes
None.
140
z/OS MVS Assembler Services Reference IAR-XCT
|
Return and Reason codes
|
|
|
|
|
When the IEAGSF macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code
RSNCODE) contains a reason code.
Macro IHAGSRET provides equate symbols for the return and reason codes.
|||
|
|
|||
|
|
|
|
|||
|
|
| ||
|
||
|||
|
|
|
|||
|
|
|
|
|
|||
|
|||
|
|
The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code. IBM support personnel may request the entire reason code, including the xxxx value.
Table 10. Return and reason codes for the IEAGSF macro
Return code
0
Reason code
–
Equate symbol, meaning and action
Equate symbol
: IeaGsfRc_OK
8
8
8
C
C
C
–
xxxx0801
xxxx0802
–
xxxx0C01
xxxx0C02
Meaning
: IEAGSF request successful.
Action
: None required.
Equate symbol
: IeaGsfRc_InvParm
Meaning
: IEAGSF request specifies parameters that are not valid.
Action
: Refer to the action provided with the specific reason code.
Equate symbol
: IeaGsfRsnBadFunction
Meaning
: Incorrect value passed to target routine.
Action
: Check for possible storage overlay.
Equate symbol
: IeaGsfRsnUpdateTcbBad
Meaning
: The TCB specified by the TTOKEN for an IEAGSF UPDATE request is no longer valid, or is terminating, or is neither the jobstep program task nor a subtask of the jobstep program task.
Action
: N/A
Equate symbol
: IeaGsfRc_Env
Meaning
: Environmental error
Action
: Refer to the action provided with the specific reason code.
Equate symbol
: IeaGsfRsnFromAsynchExit
Meaning
: IEAGSF was issued from an asynchronous exit routine.
Action
: Avoid issuing IEAGSF from an asynchronous exit routine.
Equate symbol
: IeaGsfRsnFromSRB
Meaning
: IEAGSF was issued from an SRB.
Action
: Avoid issuing IEAGSF from an SRB.
Chapter 12. IEAGSF — Guarded-Storage Facility services
141
|
|
|
|
|
|
|
|||
|
|
|
|||
|
|
|
|
|
|
|||
|
|
|
|||
|
|
| ||
|
|
|||
|||
|
|
|
Table 10. Return and reason codes for the IEAGSF macro (continued)
Return code
C
Reason code
xxxx0C03
Equate symbol, meaning and action
Equate symbol
: IeaGsfRsnFromNotBITCB
Meaning
: IEAGSF was issued from a task that was neither the jobstep program task nor a subtask of the jobstep task.
C
C
C
C
xxxx0C04
xxxx0C05
xxxx0C06
xxxx0C07
Action
: Only issue IEAGSF from the jobstep program task or a subtask of that task.
Equate symbol
: IeaGsfRsnLocked
Meaning
: IEAGSF was issued while holding a lock other than the LOCAL lock.
Action
: Avoid issuing IEAGSF while holding a lock other than the LOCAL lock.
Equate symbol
: IeaGsfRsnNoStorage
Meaning
: Necessary system storage could not be obtained from LSQA.
Action
: Use IEAGSF START at an earlier time in the jobstep.
Equate symbol
: IeaGsfRsnSuperBit
Meaning
: IEAGSF was issued from a work unit with at least one bit on in the
PSASUPER word.
Action
: Avoid issuing IEAGSF from a work unit running with a PSASUPER bit on.
Equate symbol
: IeaGsfRsnNotAvailable
C xxxx0C08
Meaning
: The Guarded-Storage Facility is not available on this system.
Action
: Ensure that the hardware supports this facility.
Equate symbol
: IeaGsfRsnUpdateInXM
Meaning
: IEAGSF UPDATE has been called with a Primary address space that is different than the Home address space.
Action
: Only invoke IEAGSF UPDATE with the Primary address space equal to the Home address space.
Example
Start using the Guarded-Storage Facility with an initial GSCB:
The code is as follows.
IEAGSF START,INITIALCONTROLS=MYGSCB
142
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 13. IEAINTKN — Build incident token
Description
Use the IEAINTKN macro to build an incident token. You can pass the token to other routines to identify related pieces of problem data.
Normally you will not need to use an IEAINTKN macro because the system generates an incident token when an SVC dump is requested and an incident token is not provided. For example, the system provides an incident token when it processes an SDUMPX macro without an INTOKEN parameter.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt Status
:
Locks
:
Requirement
Problem state with PSW key 8-15
Task or SRB
Any PASN, any HASN, any SASN
24- or 31- bit
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
The caller may hold locks, but is not required to hold any.
Programming requirements
v Place the TOKEN area in the primary address space or, for AR-mode callers, in an address space or data space that is addressable through an ALET that you provide.
v Include the CVT mapping macro.
Restrictions
None.
Input register information
Before issuing the IEAINTKN macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
When control returns to the caller, the access registers (ARs) contain:
© Copyright IBM Corp. 1988, 2017
143
IEAINTKN macro
Syntax
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the IEAINTKN macro is written as follows:
Description
name
�
IEAINTKN
�
,TOKEN=inctoken addr
name: Symbol. Begin name in column 1.
One or more blanks must precede IEAINTKN.
One or more blanks must follow IEAINTKN.
inctoken addr: RX-type address or register (2) - (12).
Parameters
The parameters are explained as follows:
TOKEN=inctoken addr
Specifies the address of a 32-character area where the system builds the incident token. The area must begin on a doubleword boundary.
ABEND codes
None.
Return and reason codes
None.
Example
Provide an incident token in the area named MYTOKEN.
IEAINTKN TOKEN=MYTOKEN
.
.
144
z/OS MVS Assembler Services Reference IAR-XCT
.
DS 0D
MYTOKEN DS CL32
CVT ,
Align parameter on double word boundary
Incident token
CVT mapping
IEAINTKN macro
Chapter 13. IEAINTKN — Build incident token
145
IEAINTKN macro
146
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 14. IEALSQRY — Linkage stack query
Description
The linkage stack query macro IEALSQRY checks the level of the current entry on the linkage stack relative to the level of the entry associated with the most recent recovery routine. The output of the macro is a value (in the TOKEN parameter) a recovery routine can use to ensure that a retry routine runs with the appropriate linkage stack entry. If the return code is not zero, the value in TOKEN is not valid.
Your program is to pass the value in TOKEN to a recovery routine. When the recovery routine gets control, it can place that value in the SDWA field
SDWALSLV. That action ensures that, when a retry routine gets control, it has the correct linkage stack level. For information about how to use the value in TOKEN, see the topic about the linkage stack at a retry routine in z/OS MVS Programming:
Assembler Services Guide.
The output of IEALSQRY depends upon the current environment and on the recovery environment that exists: v If at least one ESTAE-type recovery routine is in effect, the output depends on the most recently activated routine:
– If it is a STAE or STAI routine, a return code of 8 is returned.
– If it is an ESTAE or ESTAEX for the current RB, the value returned is the difference between the current level of the linkage stack and the level of the stack at the time the ESTAE or ESTAEX was activated.
– If it is an ESTAI, the value returned is the difference between the current level of the linkage stack and the level of the stack at the time the newest PRB that is older than the oldest non-PRB was created (or simply the newest PRB if all the RBs are PRBs).
v If no STAEs, ESTAEXs, ESTAEs exist for this RB and no ESTAI or STAIs are in effect, a return code of 8 is returned.
See z/OS MVS Programming: Assembler Services Guide for further information about the use of the SDWALSLV field.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
Amode
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state, PSW key 8-15
Task
Any PASN, any HASN, any SASN
24- or 31-bit
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
No locks are required.
Control parameters must be in the primary address space.
Programming requirements
None.
© Copyright IBM Corp. 1988, 2017
147
IEALSQRY macro
Syntax
Restrictions
None.
Input register information
Before issuing the IEALSQRY macro, the caller does not have to place any information into a general purpose register (GPR) or access register (AR).
Output register information
When control returns to the caller from IEALSQRY, the GPRs contain:
Register
Contents
0
Output token value, which is copied to the area specified by the TOKEN parameter.
1
2-13
14
15
Used as a work register by the system.
Unchanged.
Used as a work register by the system.
Return code.
When control returns to the caller from IEALSQRY, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system.
Unchanged.
14 and 15
Used as work registers by the system.
Performance implications
This macro should not be used in a performance-sensitive program.
Syntax
The standard form of the IEALSQRY macro is written as follows:
Description
name
�
IEALSQRY
�
name: symbol. Begin name in column 1.
One or more blanks must precede IEALSQRY.
TOKEN=token
One or more blanks must follow IEALSQRY.
Valid parameters
token: RS-type address or register (1) - (12).
Default
: Leave token in GPR 0.
148
z/OS MVS Assembler Services Reference IAR-XCT
IEALSQRY macro
Syntax
,RETCODE=retcode
Description
retcode: RS-type address, or register (2) - (12).
Default
: No retcode processing.
The parameters are explained as follows:
TOKEN=token
Specifies a halfword area (or the address of the area in register (1)-(12)) where the system places a value that indicates the difference between the number of linkage stack entries present when the recovery routine was activated and the number that are currently present. A recovery routine can place this value in field SDWALSLV (in mapping macro IHASDWA) to ensure that the retry routine runs with the proper level of the linkage stack. If you do not use
TOKEN, you can find the value in GPR 0.
RETCODE=retcode
Specifies a fullword output variable (or register (2)-(12)) into which the system copies the return code GPR 15. If you do not use RETCODE, you can find the return code in GPR 15.
ABEND codes
The IEALSQRY caller might receive abend code X'B78'. For detailed abend code information, see z/OS MVS System Codes.
Return codes
When control returns to the caller, register 15 contains one of the following decimal return codes (hexadecimal values are shown in parentheses):
Table 11. Return Codes for IEALSQRY
Return Code
0 (0)
Meaning and Action
Meaning
: Successful completion. A valid value is in the TOKEN parameter.
4 (4)
8 (8)
16 (10)
Action
: None required.
Meaning
: The system encountered a linkage stack entry that violates the authorization or stacking-PC conditions that are required for successful retry.
Action
: Avoid using the token when retrying. You cannot retry to the current linkage stack level.
Meaning
: No recovery routine of the proper type exists. Either no recovery routine exists or the most recently activated recovery routine is STAE or STAI.
Action
: Avoid using the token when retrying. You cannot retry to the current linkage stack level.
Meaning
: System error.
Action
: Report the problem to IBM. Avoid using the token when retrying. You cannot retry to the current linkage stack level.
Chapter 14. IEALSQRY — Linkage stack query
149
IEALSQRY macro
Example
Obtain the value that a recovery routine can place in SDWALSLV:
IEALSQRY TOKEN=MYTOKEN
.
.
MYTOKEN DS H Output TOKEN
150
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 15. IEAMETR — Query external time reference status
Description
IEAMETR can be used to query external time reference (ETR) status and connection information for the current MVS image. This information is returned in the output area specified by the OUTAREA keyword.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Any state or key
Task mode
Any PASN, any HASN, any SASN
31-bit
Primary or access register
Enabled for I/O and external interrupts
None
Must be in the primary address space
Programming requirements
None.
Restrictions
None.
Input register information
Before issuing the IEAMETR macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Before issuing the IEAMETR macro, the caller does not have to place any information into any AR unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
© Copyright IBM Corp. 1988, 2017
151
IEAMETR macro
Syntax
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Performance implications
None.
Syntax
The IEAMETR macro is written as follows:
Description
xlabel
�
xlabel: Optional symbol. Begin xlabel in column 1. The name must conform to the rules for an ordinary assembler language symbol. DEFAULT: No name.
One or more blanks must precede IEAMETR.
IEAMETR
� One or more blanks must follow IEAMETR.
OUTADDR=xoutaddr
,MF=S
,MF=(L,xmfctrl,xmfattr | 0D)
,MF=(E,xmfctrl,COMPLETE)
Default
: S
Parameters
The parameters are explained as follows:
OUTADDR=xoutaddr
A required input parameter that contains the address of the 24-byte output area to receive the output. The area is mapped by macro IHAETRI.
To code: Specify the RS-type address, or address in register (2)-(12), of a pointer field.
,MF=S | L | E
Optional keyword input that specifies the macro form.
S
Specifies the standard form of the macro. Generates code to put the parameters into an in-line parameter list and invoke the desired service.
Full checking for required macro keys is done along with supplying defaults for omitted optional parameters.
DEFAULT: S
152
z/OS MVS Assembler Services Reference IAR-XCT
IEAMETR macro
L
Specifies the list form of the macro. Defines an area to be used for the parameter list. Any other macro parameters are flagged as errors.
E
Specifies the execute form of the macro. Generates code to put the parameters into the parameter list specified by xmfctrl and provides syntax checking with default setting.
,xmfctrl
Required input. It is the name of a storage for the parameter list.
,xmfattr | 0D
Optional 60 character input string that varies from 1 to 60 characters. It can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list.
DEFAULT: 0D. 0D forces the parameter list to a doubleword boundary.
,xmfctrl
Required input. It is the name (RS-type), or address in register (1)-(12), of a storage area for the parameter list.
,COMPLETE
Optional keyword input that specifies the degree of macro parameter syntax checking.
DEFAULT: COMPLETE. Checking for required macro keys is done, and defaults are supplied for omitted optional parameters.
Return codes
Table 12. Return Codes for the IEAMETR Macro
Hexadecimal
Return Code
Meaning and Action
00
Meaning
: ETR status and port data was successfully obtained.
04
Action
: None.
Meaning
: ETR status information is available, but port is not.
08
0C
Action
: None.
Meaning
: No status or port data is available.
Action
: None.
Meaning
: The parameter list is not in the user's primary address space.
Action
: Use a parameter list in the primary address space.
Chapter 15. IEAMETR — Query external time reference status
153
IEAMETR macro
154
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 16. IEANTCR — Create a name/token pair
Description
Call the IEANTCR service to create a name/token pair.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state, with any PSW key
Task
Any PASN, any HASN, any SASN
31-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks held
The parameter list and all parameters must reside in the caller's primary address space.
Programming requirements
Before you use name/token services, you can optionally include the IEANTASM macro to invoke name/token services equate (EQU) statements. IEANTASM provides the following constants for use in your program:
* Name/Token Level Constants
*
IEANT_TASK_LEVEL
IEANT_HOME_LEVEL
IEANT_PRIMARY_LEVEL
IEANT_SYSTEM_LEVEL
IEANT_TASKAUTH_LEVEL
IEANT_HOMEAUTH_LEVEL
EQU
EQU
EQU
EQU
EQU
EQU
EQU IEANT_PRIMARYAUTH_LEVEL
*
* Name/Token Persistence Constants
*
IEANT_NOPERSIST
IEANT_PERSIST
IEANT_NOCHECKPOINT
IEANT_CHECKPOINTOK
EQU
EQU
EQU
EQU
*
* Name/Token Return Code Constants
*
IEANT_OK EQU
EQU IEANT_DUP_NAME
IEANT_NOT_FOUND
IEANT_24BITMODE
EQU
EQU
IEANT_NOT_AUTH
IEANT_SRB_MODE
IEANT_LOCK_HELD
IEANT_LEVEL_INVALID
EQU
EQU
EQU
EQU
IEANT_NAME_INVALID
IEANT_PERSIST_INVALID
IEANT_AR_INVALID
IEANT_UNEXPECTED_ERR
EQU
EQU
EQU
EQU
16
20
24
28
0
4
4
8
32
36
40
64
3
4
1
2
11
12
13
0
2
0
1
© Copyright IBM Corp. 1988, 2017
155
IEANTCR callable service
Syntax
Restrictions
None.
Input register information
Before issuing the IEANTCR callable service, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.
Description
CALL IEANTCR
,(level
,user_name
,user_token
,persist_option
,return_code)
Link edit your program with a linkage-assist routine (also called a stub) in
SYS1.CSSLIB unless you use one of the following techniques as an alternative to
CALL IEANTCR:
156
z/OS MVS Assembler Services Reference IAR-XCT
IEANTCR callable service
1.
LOAD EP=IEANTCR
Save the entry point address
...
Put the saved entry point address into R15
CALL (15),(...)
2.
L
L
L
L
15,X’10’
15,X’220’(15,0)
15,X’14’(15,0)
15,X’04’(15,0)
CALL (15),(...)
This second technique requires AMODE=31, and, before the CALL is issued, verification that the IEANTCR service is supported by the system (in the CVT, both the CVTOSEXT and the CVTOS390 bits are set on).
Parameters
The parameters are explained as follows:
(level
Specifies a fullword that contains an integer indicating the level of the name/token pair: v 1 - Task v 2 - Home address space v 3 - Primary address space.
,user_name
Specifies the 16-byte area containing the name of the name/token pair that the user creates. The bytes of the name may have any value. The name may contain blanks, integers, or addresses.
Names must be unique within a level. Here are some examples.
v Two task-level name/token pairs owned by the same task cannot have the same name. However, two task-level name/token pairs owned by different tasks can have the same name.
v Two home-address-space-level name/token pairs in the same address space cannot have the same name. However, two home-address-space-level name/token pairs in different address spaces can have the same name.
Because of these unique requirements you must avoid using the same names that IBM uses for name/token pairs. Do not use the following names: v Names that begin with A through I v
Names that begin with X'00'.
,user_token
Specifies the 16-byte area containing the token of the name/token pair that the user creates.
,persist_option
Specifies a fullword that contains an integer indicating if Checkpoint/Restart can be issued if the program has this task-level name/token pair.
v 0 - checkpoint is not permitted v 2 - checkpoint is permitted.
Note:
Only task-level name/token pairs can permit checkpoint. You must specify 0 for all other levels.
Chapter 16. IEANTCR — Create a name/token pair
157
IEANTCR callable service
,return_code)
Specifies a fullword to contain the return code from the IEANTCR service.
ABEND codes
The caller might encounter abend X'AC7' with a reason code of either X'00030000' or X'00030001'. See z/OS MVS System Codes for an explanation and responses for these codes.
Return and reason codes
When IEANTCR returns control to your program, GPR 15 and return_code contain a return code. The following table identifies return codes in hexadecimal and decimal, tells what each means, and recommends an action that you should take:
Meaning and Action Hexadecimal
Return Code
00
Decimal Return
Code
0
04
08
10
18
1C
20
24
28
4
8
16
24
28
32
36
40
Meaning
: The operation was successful.
Action
: None.
Meaning
: The user_name specified already exists.
Action
: Choose a different user_name.
Meaning
: The request is rejected because the caller is in 24-bit addressing mode.
Action
: Change your program to 31-bit addressing mode.
Meaning
: An unauthorized caller attempted to create a system-level name/token pair.
Action
: Check which level of name/token pair you are creating.
Meaning
: The caller held locks.
Action
: Release all locks before issuing IEANTCR.
Meaning
: The caller specified an incorrect level.
Action
: Respecify the correct level. Valid values are 1,
2, or 3.
Meaning
: The caller specified an incorrect user_name.
Action
: Respecify the correct user_name.
Meaning
: The caller specified an incorrect
persist_option.
Action
: v For task-level name/token pairs, you must specify zero or two for the persist_option.
v For home or primary address space level name/token pairs, you must specify zero for the
persist_option.
Meaning
: The caller was in AR ASC mode and AR1 was not zero.
Action
: Change your program to primary mode or make sure the parameter list is in the primary address space.
158
z/OS MVS Assembler Services Reference IAR-XCT
Hexadecimal
Return Code
40
IEANTCR callable service
Decimal Return
Code
64
Meaning and Action
Meaning
: A system error occurred while handling the request.
Action
: Retry the request.
Example
Initialize the name/token fields, and create, retrieve, and delete a task-level name/token pair.
TITLE ’NAME/TOKEN EXAMPLE PROGRAM’
NTIDSAMP CSECT
NTIDSAMP AMODE 31
NTIDSAMP RMODE ANY
*
BAKR R14,0 SAVE CALLING PROGRAM’S
REGISTERS AND RETURN LOCATION
LR R12,R15
USING NTIDSAMP,R12
ESTABLISH BASE REG
***********************************************************************
* INITIALIZE THE NAME AND TOKEN FIELDS *
***********************************************************************
MVC NAME,=CL16’NTIDSAMP NAME ’ INITIALIZE NAME FIELD
*
MVC TOKEN,NAME FOR EXAMPLE, MAKE TOKEN THE
SAME AS THE NAME
***********************************************************************
* TASK LEVEL CREATE EXAMPLE *
***********************************************************************
CALL IEANTCR,(LEVEL,NAME,TOKEN,PERSOPT,RETCODE)
***********************************************************************
CLC RETCODE,=F’0’
BNE ABEND
IS RETURN CODE 0?
NO, GO ABEND
EJECT
***********************************************************************
* TASK LEVEL RETRIEVE EXAMPLE *
***********************************************************************
CALL IEANTRT,(LEVEL,NAME,TOKEN,RETCODE)
***********************************************************************
CLC RETCODE,=F’0’ IS RETURN CODE 0?
BNE
EJECT
ABEND NO, GO ABEND
***********************************************************************
* TASK LEVEL DELETE EXAMPLE *
***********************************************************************
CALL IEANTDL,(LEVEL,NAME,RETCODE)
***********************************************************************
CLC RETCODE,=F’0’ IS RETURN CODE 0?
BNE
EJECT
ABEND NO, GO ABEND
EXIT
SLR R15,R15
PR
EJECT
ABEND X’BAD’
SET RETURN CODE OF ZERO
RETURN TO CALLER
ABEND ABEND IF NONZERO RETURN CODE
EJECT
***********************************************************************
* NAME/TOKEN VARIABLE DECLARES
***********************************************************************
IEANTASM
EJECT
***********************************************************************
* Constants and data areas *
***********************************************************************
LEVEL DC A(IEANT_TASK_LEVEL) Task level
NAME DS CL16 Name for name/token pair
Chapter 16. IEANTCR — Create a name/token pair
159
IEANTCR callable service
TOKEN DS
PERSOPT DC
XL16
A(IEANT_NOPERSIST)
Token for name/token pair
Persist option
RETCODE DS F Return code
***********************************************************************
* EQUATES
***********************************************************************
R1
R12
EQU
EQU
1
12
R13
R14
R15
EQU 13
EQU 14
EQU 15
END NTIDSAMP
160
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 17. IEANTDL — Delete a name/token pair
Description
Call the IEANTDL service to delete a name/token pair.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Note:
Problem-state programs with PSW key 8 - 15 cannot delete name/token pairs created by supervisor-state or PSW key 0 - 7 programs.
Task
Any PASN, any HASN, any SASN
31-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks held
The parameter list and all parameters must reside in the caller's primary address space.
Programming requirements
Before you use name/token services, you can optionally include the IEANTASM macro to invoke name/token services equate (EQU) statements. IEANTASM provides the following constants for use in your program:
* Name/Token Level Constants
*
IEANT_TASK_LEVEL
IEANT_HOME_LEVEL
IEANT_PRIMARY_LEVEL
IEANT_SYSTEM_LEVEL
IEANT_TASKAUTH_LEVEL
IEANT_HOMEAUTH_LEVEL
EQU
EQU
EQU
EQU
EQU
EQU
EQU IEANT_PRIMARYAUTH_LEVEL
*
* Name/Token Persistence Constants
*
IEANT_NOPERSIST
IEANT_PERSIST
EQU
EQU
*
* Name/Token Return Code Constants
*
IEANT_OK
IEANT_DUP_NAME
IEANT_NOT_FOUND
IEANT_24BITMODE
IEANT_NOT_AUTH
IEANT_SRB_MODE
IEANT_LOCK_HELD
IEANT_LEVEL_INVALID
IEANT_NAME_INVALID
IEANT_PERSIST_INVALID
IEANT_AR_INVALID
IEANT_UNEXPECTED_ERR
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
0
1
16
20
24
28
4
8
0
4
32
36
40
64
3
4
1
2
11
12
13
© Copyright IBM Corp. 1988, 2017
161
IEANTDL callable service
Syntax
Restrictions
None.
Input register information
Before issuing the IEANTDL callable service, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.
Description
CALL IEANTDL
,(level
,user_name
,return_code)
Link edit your program with a linkage-assist routine (also called a stub) in
SYS1.CSSLIB unless you use one of the following techniques as an alternative to
CALL IEANTDL:
162
z/OS MVS Assembler Services Reference IAR-XCT
IEANTDL callable service
1.
LOAD EP=IEANTDL
Save the entry point address
...
Put the saved entry point address into R15
CALL (15),(...)
2.
L
L
L
L
15,X’10’
15,X’220’(15,0)
15,X’14’(15,0)
15,X’0C’(15,0)
CALL (15),(...)
This second technique requires AMODE=31, and, before the CALL is issued, verification that the IEANTDL service is supported by the system (in the CVT, both the CVTOSEXT and the CVTOS390 bits are set on).
Parameters
The parameters are explained as follows:
(level
Specifies a fullword that contains an integer indicating the level of the name/token pair you wish to delete: v 1 - Task v 2 - Home address space v 3 - Primary address space.
,user_name
Specifies the 16-byte area containing the name of the name/token pair to be deleted.
,return_code)
Specifies a fullword to contain the return code from the IEANTDL service.
ABEND codes
The caller might encounter abend X'AC7' with a reason code of either X'00030000' or X'00030001'. See z/OS MVS System Codes for an explanation and responses to these codes.
Return and reason codes
When IEANTDL returns control to your program, GPR 15 and return_code contain a return code. The following table identifies return codes in hexadecimal and decimal, tells what each means, and recommends an action that you should take:
Hexadecimal
Return Code
00
04
08
Decimal Return
Code
0
Meaning and Action
4
8
Meaning
: The operation was successful.
Action
: None.
Meaning
: The request is rejected because the system could not find the requested name/token pair.
Action
: Check the user_name you specified.
Meaning
: The request is rejected because the caller is in 24-bit addressing mode.
Action
: Change your program to 31-bit addressing mode.
Chapter 17. IEANTDL — Delete a name/token pair
163
IEANTDL callable service
Hexadecimal
Return Code
10
18
1C
20
28
40
Decimal Return
Code
16
Meaning and Action
24
28
32
40
64
Meaning
: An unauthorized caller attempted to delete a system-level name/token pair or a name/token pair created by an authorized program.
Action
: Check which level of name/token pair you are deleting.
Meaning
: The caller held locks.
Action
: Release all locks before issuing IEANTDL.
Meaning
: The caller specified an incorrect level.
Action
: Respecify the correct level. Valid values are 1,
2, or 3.
Meaning
: The caller specified an incorrect user_name.
Action
: Respecify the correct user_name.
Meaning
: The caller was in AR ASC mode and AR1 was not zero.
Action
: Change your program to primary mode or make sure the parameter list is in the primary address space.
Meaning
: A system error occurred while handling the request.
Action
: Retry the request.
Example
For a complete example of creating, retrieving, and deleting a task-level name/token pair, see the IEANTCR callable service.
164
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 18. IEANTRT — Retrieve the token from a name/token pair
Description
Call the IEANTRT service to retrieve the token from a name/token pair. For example, you can use IEANTRT to obtain the name of the logrec recording medium, which is either the name of the logrec data set or the name of the logrec log stream.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
Any PASN, any HASN, any SASN
31-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
The caller can hold a local, CML, or CMS lock; however, no locks are required.
The parameter list and all parameters must reside in the caller's primary address space.
Programming requirements
Before you use name/token services, you can optionally include macro
IEANTASM to invoke name/token services equate (EQU) statements. IEANTASM provides the following constants for use in your program:
* Name/Token Level Constants
*
IEANT_TASK_LEVEL
IEANT_HOME_LEVEL
IEANT_PRIMARY_LEVEL
IEANT_SYSTEM_LEVEL
IEANT_TASKAUTH_LEVEL
IEANT_HOMEAUTH_LEVEL
EQU
EQU
EQU
EQU
EQU
EQU
EQU IEANT_PRIMARYAUTH_LEVEL
*
* Name/Token Persistence Constants
*
IEANT_NOPERSIST
IEANT_PERSIST
EQU
EQU
*
* Name/Token Return Code Constants
*
IEANT_OK
IEANT_DUP_NAME
IEANT_NOT_FOUND
IEANT_24BITMODE
IEANT_NOT_AUTH
IEANT_SRB_MODE
IEANT_LOCK_HELD
IEANT_LEVEL_INVALID
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
0
1
16
20
24
28
4
8
0
4
3
4
1
2
11
12
13
© Copyright IBM Corp. 1988, 2017
165
IEANTRT callable service
IEANT_NAME_INVALID
IEANT_PERSIST_INVALID
IEANT_AR_INVALID
IEANT_UNEXPECTED_ERR
EQU
EQU
EQU
EQU
32
36
40
64
To obtain the name of the logrec data set or the name of the logrec log stream, you can include the IFBNTASM macro, as well as the IEANTASM macro, in your
program. See “Example 2” on page 168 for the list of definitions IFBNTASM
provides.
Restrictions
Do not call the IEANTRT callable service with the user_name and user_token parameters in the same storage location.
Input register information
Before issuing the IEANTRT callable service, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.
166
z/OS MVS Assembler Services Reference IAR-XCT
IEANTRT callable service
Syntax
CALL IEANTRT
Description
,(level
,user_name
,user_token
,return_code)
Link edit your program with a linkage-assist routine (also called a stub) in
SYS1.CSSLIB unless you use one of the following techniques as an alternative to
CALL IEANTRT:
1.
LOAD EP=IEANTRT
Save the entry point address
...
Put the saved entry point address into R15
CALL (15),(...)
2.
L
L
L
L
15,X’10’
15,X’220’(15,0)
15,X’14’(15,0)
15,X’08’(15,0)
CALL (15),(...)
This second technique requires AMODE=31, and, before the CALL is issued, verification that the IEANTCR service is supported by the system (in the CVT, both the CVTOSEXT and the CVTOS390 bits are set on).
Parameters
The parameters are explained as follows:
(level
Specifies a fullword that contains an integer indicating the level of the name/token pair from which you want to retrieve the token: v 1 - Task v 2 - Home address space v 3 - Primary address space v 4 - System.
,user_name
Specifies the 16-byte area containing the name of the requested name/token pair.
,user_token
Specifies the 16-byte area to contain the token of the requested name/token pair.
,return_code)
Specifies a fullword to contain the return code from the IEANTRT service.
ABEND codes
None.
Return and reason codes
When IEANTRT returns control to your program, GPR 15 and return_code contain a return code. The following table identifies return codes in hexadecimal and decimal, tells what each means, and recommends an action that you should take:
Chapter 18. IEANTRT — Retrieve the token from a name/token pair
167
IEANTRT callable service
Hexadecimal
Return Code
00
04
08
1C
40
Decimal Return
Code
0
Meaning and Action
4
8
28
64
Meaning
: The operation was successful.
Action
: None.
Meaning
: The request is rejected because the system could not find the requested name/token pair.
Action
: Check the user_name you specified.
Meaning
: The request is rejected because the caller is in 24-bit addressing mode.
Action
: Change your program to 31-bit addressing mode.
Meaning
: The caller specified an incorrect level.
Action
: Respecify the correct level. Valid values are 1,
2, 3, or 4.
Meaning
: A system error occurred while handling the request.
Action
: Retry the request.
Example 1
For a complete example of creating, retrieving, and deleting a task-level name/token pair, see the IEANTCR callable service.
Example 2
Following is an example of using Name/Token services to obtain the name of the logrec data set or logrec log stream. (Note that because the routine is not reentrant, module IEANTRT is first loaded and then called.) IEANTRT returns a token that contains a pointer to the name of the logrec data set or logrec log stream.
Before you use name/token services, you can optionally include macro IFBNTASM which provides the following definitions for use in your program:
* IFBNTASM Parameters
IFBNT_DSNLOGREC
*
IFBNT_VERSION1
IFBNT_VERSION2
DC
EQU
EQU
IFBNT_LATEST_VERSION EQU
*
IFBNT_TOKEN DSECT ,
IFBNT_LOGREC_NAME_PTR DS A
*
IFBNT_VERSION
IFBNT_RESV1
IFBNT_LENGTH
IFBNT_RESV2
*
DS
DS
DS
DS
X
X
XL2
CL8
DSECT , IFBNT_LOGREC
*
IFBNT_LOGREC_NAME
*
DS
CL16’DSNLOGREC ’ System level
DSNLOGREC name
X’01’
X’02’
X’02’
First version of IFBNT_TOKEN
Second version of IFBNT_TOKEN
Latest version of IFBNT_TOKEN
CL44
Token area
Address of the LOGREC data set name area
Version of IFBNT_LOGREC
Reserved for IBM
Length of IFBNT_LOGREC area
Reserved for IBM
Pointed to by
IFBNT_LOGREC_NAME_PTR
LOGREC data set name or no data set name string (see
*
IFBNT_LOGREC_CURRENT DS
*
XL1 comments at end of mapping)
Current Logrec recording medium
168
z/OS MVS Assembler Services Reference IAR-XCT
IEANTRT callable service
IFBNT_LOGREC_PREVIOUS DS
*
IFBNT_LOGREC_LOGSTREAM DS
*
*
*
IFBNT_LOGREC_LEN
*
EQU
XL1
CL26
Previous Logrec recording medium
Logrec log stream name, only filled in when
IFBNT_USE_LOGSTREAM is the current medium
*-IFBNT_LOGREC Length of IFBNT_LOGREC
********************************************************************
* The following values are used in the following fields:
* IFBNT_LOGREC_CURRENT
* IFBNT_LOGREC_PREVIOUS
********************************************************************
IFBNT_USE_DATASET EQU X’01’ Logrec data set being used
IFBNT_USE_LOGSTREAM EQU
IFBNT_IGNORE_RECORDS EQU
X’02’
X’03’
Logrec log stream being used
Logrec recording is ignored
*
********************************************************************
* If a Logrec data set was not defined during the IPL of the system
* then the following string will appear in field
* IFBNT_LOGREC_NAME = ’...NO.LOGREC.DATA.SET.DEFINED...
’
********************************************************************
IFBNT_TOKEN provides a DSECT to map the returned token area.
IFBNT_LOGREC_NAME_PTR contains the address of the logrec data set name.
IFBNT_LOGREC provides a DSECT to map the logrec recording medium.
IFBNT_LOGREC_NAME contains the name of the installation-defined logrec data set or no data set name, if the recording medium is other than a data set.
TITLE ’DSNLOGREC Name/Token Retrieve Example Routine’
IFBNTXMP AMODE 31
IFBNTXMP RMODE ANY
IFBNTXMP CSECT
*
BAKR R14,0 Save calling program’s registers and return location
LR R12,R15
USING IFBNTXMP,R12
Establish base ref
Set addressability
MODID BRANCH=YES
*********************************************************************
* Initialize the NAME field
*********************************************************************
MVC NAME,IFBNT_DSNLOGREC Request DSNLOGREC name
*********************************************************************
* System level DSNLOGREC Retrieve example
*********************************************************************
LOAD EP=IEANTRT
LR R15,R0
Get address of IEANTRT routine
Set address for Call
CALL (15),(LEVEL,NAME,TOKEN,RETCODE)
*
LA
C
R15,IEANT_OK
R15,RETCODE
BNE ABEND
EJECT
Get successful return code value
Was TOKEN Returned?
No, Go ABEND
*********************************************************************
* Get the installation specified LOGREC data set name
*********************************************************************
LA R2,TOKEN Set pointer to TOKEN area
*
USING IFBNT_TOKEN,R2 Set addressability
DSNLOGREC TOKEN area
*
L R2,IFBNT_LOGREC_NAME_PTR Get pointer to data set name
DROP R2 Free up register 2
USING IFBNT_LOGREC,R2 Set addressability to
LOGREC data set name area
Chapter 18. IEANTRT — Retrieve the token from a name/token pair
169
IEANTRT callable service
*********************************************************************
* If you are interested in obtaining the log stream name, reference
* IFBNT_LOGREC_LOGSTREAM instead of IFBNT_LOGREC_NAME here,
* using the MVC command to move the log stream name to your
* own program’s area.
*********************************************************************
*
MVC LOGRNAME,IFBNT_LOGREC_NAME Move LOGREC data set name to own area
EXIT
ABEND
DROP
DS
PR
R2
0H
SLR R15,R15
EJECT
ABEND X’BAD’
EJECT
Free up register 2
Return point
Set return code of zero
Return to caller
ABEND if non-zero return code
*********************************************************************
* Local working storage declares
*********************************************************************
NAME DS CL16 Name for Name/Token pair
TOKEN
RETCODE
*
DS
DS
LOGRNAME DS
XL16
F
CL44
Token for Name/Token Pair
Return code from IEANTRT
Area for LOGREC data set name
*********************************************************************
* Constant and Equates
*********************************************************************
LEVEL DC A(IEANT_SYSTEM_LEVEL) SYSTEM LEVEL
R0
R1
R2
R11
EQU
EQU
EQU
EQU
0
1
2
11
R12
R13
R14
R15
EQU 12
EQU 13
EQU 14
EQU 15
EJECT
*********************************************************************
* NAME/TOKEN SYSTEM LEVEL DSNLOGREC VARIABLE DECLARES
*********************************************************************
IFBNTASM
EJECT
*********************************************************************
* NAME/TOKEN VARIABLE DECLARES
*********************************************************************
IEANTASM
END IFBNTXMP
170
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 19. IEAN4CR — Create a name/token pair
Description
Call the IEAN4CR service to create a name/token pair.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state, with any PSW key
Task
Any PASN, any HASN, any SASN
64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks held
The parameter list and all parameters must reside in the caller's primary address space.
Programming requirements
Before you use name/token services, you can optionally include the IEANTASM macro to invoke name/token services equate (EQU) statements. IEANTASM provides the following constants for use in your program:
* Name/Token Level Constants
*
IEANT_TASK_LEVEL
IEANT_HOME_LEVEL
IEANT_PRIMARY_LEVEL
IEANT_SYSTEM_LEVEL
IEANT_TASKAUTH_LEVEL
IEANT_HOMEAUTH_LEVEL
EQU
EQU
EQU
EQU
EQU
EQU
EQU IEANT_PRIMARYAUTH_LEVEL
*
* Name/Token Persistence Constants
*
IEANT_NOPERSIST
IEANT_PERSIST
IEANT_NOCHECKPOINT
IEANT_CHECKPOINTOK
EQU
EQU
EQU
EQU
*
* Name/Token Return Code Constants
*
IEANT_OK EQU
EQU IEANT_DUP_NAME
IEANT_NOT_FOUND
IEANT_24BITMODE
EQU
EQU
IEANT_NOT_AUTH
IEANT_SRB_MODE
IEANT_LOCK_HELD
IEANT_LEVEL_INVALID
EQU
EQU
EQU
EQU
IEANT_NAME_INVALID
IEANT_PERSIST_INVALID
IEANT_AR_INVALID
IEANT_UNEXPECTED_ERR
EQU
EQU
EQU
EQU
16
20
24
28
0
4
4
8
32
36
40
64
3
4
1
2
11
12
13
0
2
0
1
© Copyright IBM Corp. 1988, 2017
171
IEAN4CR callable service
Restrictions
None.
Input register information
Before issuing the IEAN4CR callable service, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEAN4CR
,(level
,user_name
,user_token
,persist_option
,return_code)
172
z/OS MVS Assembler Services Reference IAR-XCT
IEAN4CR callable service
Link edit your program with a linkage-assist routine (also called a stub) in
SYS1.CSSLIB unless you use one of the following techniques as an alternative to
CALL IEAN4CR:
1.
LOAD EP=IEAN4CR
Save the 8-byte entry point address with bit 63 changed to 0
...
Put the saved entry point address with bit 63 changed to 0 into 64-bit R15
CALL (15),(...)
2.
LLGT 15,X’10’
L 15,X’220’(15,0)
L
L
15,X’14’(15,0)
15,X’7C’(15,0)
CALL (15),(...)
Both of these alternate techniques require verification that the IEAN4CR service is available (in the CVT, bit CVTZOS_V1R11 is on indicating that the program is running on z/OS V1R11 or a later release).
Parameters
The parameters are explained as follows:
(level
Specifies a fullword that contains an integer indicating the level of the name/token pair: v 1 - Task v 2 - Home address space v
3 - Primary address space.
,user_name
Specifies the 16-byte area containing the name of the name/token pair that the user creates. The bytes of the name may have any value. The name may contain blanks, integers, or addresses.
Names must be unique within a level. Here are some examples.
v Two task-level name/token pairs owned by the same task cannot have the same name. However, two task-level name/token pairs owned by different tasks can have the same name.
v Two home-address-space-level name/token pairs in the same address space cannot have the same name. However, two home-address-space-level name/token pairs in different address spaces can have the same name.
Because of these unique requirements you must avoid using the same names that IBM uses for name/token pairs. Do not use the following names: v Names that begin with A through I v Names that begin with X'00'.
,user_token
Specifies the 16-byte area containing the token of the name/token pair that the user creates.
,persist_option
Specifies a fullword that contains an integer indicating if Checkpoint/Restart can be issued if the program has this task-level name/token pair.
v 0 - checkpoint is not permitted v 2 - checkpoint is permitted.
Chapter 19. IEAN4CR — Create a name/token pair
173
IEAN4CR callable service
Note:
Only task-level name/token pairs can permit checkpoint. You must specify 0 for all other levels.
,return_code)
Specifies a fullword to contain the return code from the IEAN4CR service.
ABEND codes
The caller might encounter abend X'AC7' with a reason code of either X'00030000' or X'00030001'. See z/OS MVS System Codes for an explanation and responses for these codes.
Return and reason codes
When IEAN4CR returns control to your program, GPR 15 and return_code contain a return code. The following table identifies return codes in hexadecimal and decimal, tells what each means, and recommends an action that you should take:
Hexadecimal
Return Code
00
04
08
10
18
1C
20
24
Decimal Return
Code
0
Meaning and Action
4
8
16
24
28
32
36
Meaning
: The operation was successful.
Action
: None.
Meaning
: The user_name specified already exists.
Action
: Choose a different user_name.
Meaning
: The request is rejected because the caller is in 24-bit addressing mode.
Action
: Change your program to 64-bit addressing mode.
Meaning
: An unauthorized caller attempted to create a system-level name/token pair.
Action
: Check which level of name/token pair you are creating.
Meaning
: The caller held locks.
Action
: Release all locks before issuing IEAN4CR.
Meaning
: The caller specified an incorrect level.
Action
: Respecify the correct level. Valid values are 1,
2, or 3.
Meaning
: The caller specified an incorrect user_name.
Action
: Respecify the correct user_name.
Meaning
: The caller specified an incorrect
persist_option.
Action
: v For task-level name/token pairs, you must specify zero or two for the persist_option.
v For home or primary address space level name/token pairs, you must specify zero for the
persist_option.
174
z/OS MVS Assembler Services Reference IAR-XCT
Hexadecimal
Return Code
28
40
IEAN4CR callable service
Decimal Return
Code
40
Meaning and Action
64
Meaning
: The caller was in AR ASC mode and AR1 was not zero.
Action
: Change your program to primary mode or make sure the parameter list is in the primary address space.
Meaning
: A system error occurred while handling the request.
Action
: Retry the request.
Chapter 19. IEAN4CR — Create a name/token pair
175
IEAN4CR callable service
176
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 20. IEAN4DL — Delete a name/token pair
Description
Call the IEAN4DL service to delete a name/token pair.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Note:
Problem-state programs with PSW key 8 - 15 cannot delete name/token pairs created by supervisor-state or PSW key 0 - 7 programs.
Task
Any PASN, any HASN, any SASN
64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks held
The parameter list and all parameters must reside in the caller's primary address space.
Programming requirements
Before you use name/token services, you can optionally include the IEANTASM macro to invoke name/token services equate (EQU) statements. IEANTASM provides the following constants for use in your program:
* Name/Token Level Constants
*
IEANT_TASK_LEVEL
IEANT_HOME_LEVEL
IEANT_PRIMARY_LEVEL
IEANT_SYSTEM_LEVEL
IEANT_TASKAUTH_LEVEL
IEANT_HOMEAUTH_LEVEL
EQU
EQU
EQU
EQU
EQU
EQU
EQU IEANT_PRIMARYAUTH_LEVEL
*
* Name/Token Persistence Constants
*
IEANT_NOPERSIST
IEANT_PERSIST
EQU
EQU
*
* Name/Token Return Code Constants
*
IEANT_OK
IEANT_DUP_NAME
IEANT_NOT_FOUND
IEANT_24BITMODE
IEANT_NOT_AUTH
IEANT_SRB_MODE
IEANT_LOCK_HELD
IEANT_LEVEL_INVALID
IEANT_NAME_INVALID
IEANT_PERSIST_INVALID
IEANT_AR_INVALID
IEANT_UNEXPECTED_ERR
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
0
1
16
20
24
28
4
8
0
4
32
36
40
64
3
4
1
2
11
12
13
© Copyright IBM Corp. 1988, 2017
177
IEAN4DL callable service
Restrictions
None.
Input register information
Before issuing the IEAN4DL callable service, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEAN4DL
,(level
,user_name
,return_code)
Link edit your program with a linkage-assist routine (also called a stub) in
SYS1.CSSLIB unless you use one of the following techniques as an alternative to
CALL IEAN4DL:
178
z/OS MVS Assembler Services Reference IAR-XCT
IEAN4DL callable service
1.
LOAD EP=IEAN4DL
Save the 8-byte entry point address with bit 63 changed to 0
...
Put the saved entry point address with bit 63 changed to 0 into 64-bit R15
CALL (15),(...)
2.
LLGT 15,X’10’
L 15,X’220’(15,0)
L
L
15,X’14’(15,0)
15,X’84’(15,0)
CALL (15),(...)
Both of these alternate techniques require verification that the IEAN4DL service is available (in the CVT, bit CVTZOS_V1R11 is on indicating that the program is running on z/OS V1R11 or a later release).
Parameters
The parameters are explained as follows:
(level
Specifies a fullword that contains an integer indicating the level of the name/token pair you wish to delete: v 1 - Task v 2 - Home address space v 3 - Primary address space.
,user_name
Specifies the 16-byte area containing the name of the name/token pair to be deleted.
,return_code)
Specifies a fullword to contain the return code from the IEAN4DL service.
ABEND codes
The caller might encounter abend X'AC7' with a reason code of either X'00030000' or X'00030001'. See z/OS MVS System Codes for an explanation and responses to these codes.
Return and reason codes
When IEAN4DL returns control to your program, GPR 15 and return_code contain a return code. The following table identifies return codes in hexadecimal and decimal, tells what each means, and recommends an action that you should take:
Hexadecimal
Return Code
00
04
08
Decimal Return
Code
0
Meaning and Action
4
8
Meaning
: The operation was successful.
Action
: None.
Meaning
: The request is rejected because the system could not find the requested name/token pair.
Action
: Check the user_name you specified.
Meaning
: The request is rejected because the caller is in 24-bit addressing mode.
Action
: Change your program to 64-bit addressing mode.
Chapter 20. IEAN4DL — Delete a name/token pair
179
IEAN4DL callable service
Hexadecimal
Return Code
10
18
1C
20
28
40
Decimal Return
Code
16
Meaning and Action
24
28
32
40
64
Meaning
: An unauthorized caller attempted to delete a system-level name/token pair or a name/token pair created by an authorized program.
Action
: Check which level of name/token pair you are deleting.
Meaning
: The caller held locks.
Action
: Release all locks before issuing IEAN4DL.
Meaning
: The caller specified an incorrect level.
Action
: Respecify the correct level. Valid values are 1,
2, or 3.
Meaning
: The caller specified an incorrect user_name.
Action
: Respecify the correct user_name.
Meaning
: The caller was in AR ASC mode and AR1 was not zero.
Action
: Change your program to primary mode or make sure the parameter list is in the primary address space.
Meaning
: A system error occurred while handling the request.
Action
: Retry the request.
180
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 21. IEAN4RT — Retrieve the token from a name/token pair
Description
Call the IEAN4RT service to retrieve the token from a name/token pair. For example, you can use IEAN4RT to obtain the name of the logrec recording medium, which is either the name of the logrec data set or the name of the logrec log stream.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
Any PASN, any HASN, any SASN
64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
The caller can hold a local, CML, or CMS lock; however, no locks are required.
The parameter list and all parameters must reside in the caller's primary address space.
Programming requirements
Before you use name/token services, you can optionally include macro
IEANTASM to invoke name/token services equate (EQU) statements. IEANTASM provides the following constants for use in your program:
* Name/Token Level Constants
*
IEANT_TASK_LEVEL
IEANT_HOME_LEVEL
IEANT_PRIMARY_LEVEL
IEANT_SYSTEM_LEVEL
IEANT_TASKAUTH_LEVEL
IEANT_HOMEAUTH_LEVEL
EQU
EQU
EQU
EQU
EQU
EQU
EQU IEANT_PRIMARYAUTH_LEVEL
*
* Name/Token Persistence Constants
*
IEANT_NOPERSIST
IEANT_PERSIST
EQU
EQU
*
* Name/Token Return Code Constants
*
IEANT_OK
IEANT_DUP_NAME
IEANT_NOT_FOUND
IEANT_24BITMODE
IEANT_NOT_AUTH
IEANT_SRB_MODE
IEANT_LOCK_HELD
IEANT_LEVEL_INVALID
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
0
1
16
20
24
28
4
8
0
4
3
4
1
2
11
12
13
© Copyright IBM Corp. 1988, 2017
181
IEAN4RT callable service
IEANT_NAME_INVALID
IEANT_PERSIST_INVALID
IEANT_AR_INVALID
IEANT_UNEXPECTED_ERR
EQU
EQU
EQU
EQU
32
36
40
64
To obtain the name of the logrec data set or the name of the logrec log stream, you can include the IFBNTASM macro, as well as the IEANTASM macro, in your
program. See “Example 2” on page 168 for the list of definitions IFBNTASM
provides.
Restrictions
Do not call the IEAN4RT callable service with the user_name and user_token parameters in the same storage location.
Input register information
Before issuing the IEAN4RT callable service, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.
Syntax
SYSSTATE AMODE64=YES
Description
182
z/OS MVS Assembler Services Reference IAR-XCT
IEAN4RT callable service
Syntax
CALL IEAN4RT
Description
,(level
,user_name
,user_token
,return_code)
Link edit your program with a linkage-assist routine (also called a stub) in
SYS1.CSSLIB unless you use one of the following techniques as an alternative to
CALL IEAN4RT:
1.
LOAD EP=IEAN4RT
Save the 8-byte entry point address with bit 63 changed to 0
...
Put the saved entry point address with bit 63 changed to 0 into 64-bit R15
CALL (15),(...)
2.
LLGT 15,X’10’
L 15,X’220’(15,0)
L
L
15,X’14’(15,0)
15,X’80’(15,0)
CALL (15),(...)
Both of these alternate techniques require verification that the IEAN4RT service is available (in the CVT, bit CVTZOS_V1R11 is on indicating that the program is running on z/OS V1R11 or a later release).
Parameters
The parameters are explained as follows:
(level
Specifies a fullword that contains an integer indicating the level of the name/token pair from which you want to retrieve the token: v 1 - Task v 2 - Home address space v 3 - Primary address space v 4 - System.
,user_name
Specifies the 16-byte area containing the name of the requested name/token pair.
,user_token
Specifies the 16-byte area to contain the token of the requested name/token pair.
,return_code)
Specifies a fullword to contain the return code from the IEAN4RT service.
ABEND codes
None.
Return and reason codes
When IEAN4RT returns control to your program, GPR 15 and return_code contain a return code. The following table identifies return codes in hexadecimal and decimal, tells what each means, and recommends an action that you should take:
Chapter 21. IEAN4RT — Retrieve the token from a name/token pair
183
IEAN4RT callable service
Hexadecimal
Return Code
00
04
08
1C
40
Decimal Return
Code
0
Meaning and Action
4
8
28
64
Meaning
: The operation was successful.
Action
: None.
Meaning
: The request is rejected because the system could not find the requested name/token pair.
Action
: Check the user_name you specified.
Meaning
: The request is rejected because the caller is in 24-bit addressing mode.
Action
: Change your program to 64-bit addressing mode.
Meaning
: The caller specified an incorrect level.
Action
: Respecify the correct level. Valid values are 1,
2, 3, or 4.
Meaning
: A system error occurred while handling the request.
Action
: Retry the request.
184
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 22. IEATDUMP — Transaction dump request
Description
Transaction dump is a service used to request an unformatted dump of virtual storage to a data set, similar to a SYSMDUMP. It is invoked with the IEATDUMP assembler macro, which issues SVC 51. The service is available to both authorized and unauthorized callers; however, not all functions are available to unauthorized callers. If an unauthorized caller requests a transaction dump with authorized keywords, the request will be rejected and message IEA820I will be issued indicating this condition. The transaction dump can be written to one or more automatically allocated data sets by specifying a data set name pattern, similar to the pattern used for the operator DUMPDS NAME=parameter. Automatic allocation reduces the exposure that a dump is truncated because of space constraints, and is done using the generic allocation unit name of SYSALLDA.
When a dump is written, messages IEA822I or IEA827I are issued indicating whether the dump is complete or partial.
When a transaction dump is written, a dump directory record describing the dump may be written. The dump directory to be used is specified on the dump request using the IDX keyword. If no dump directory is specified on the request, the directory allocated to IPCSDDIR in the current job step will be used. If no dump directory is specified and IPCSDDIR is not allocated, no record describing the dump will be written.
Dump suppression occurs using symptoms available in the current SDWA or a symptom string may be provided (via the SYMREC keyword). If a symptom string is provided and an SDWA exists, the symptom string is used for suppression purposes. Statistics for dump suppression are contained in the DAE data set and are not differentiated from SYSMDUMPs. If a dump is requested but not taken because it was suppressed, message IEA820I is issued indicating this condition.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Requirement
Problem state and PSW key 8-15. Use of some keywords is restricted to authorized callers (supervisor state, PSW key
0-7 or APF-authorized).
Task
PASN=HASN=SASN
24- or 31-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
The caller must not hold any locks.
© Copyright IBM Corp. 1988, 2017
185
IEATDUMP transaction dump
Environmental factor
Control parameters:
Requirement
Control parameters must be in the primary address space or, for AR-mode callers, must be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
The caller-provided title, data set name, dump index name, symptom record, incident token, problem description area and storage list area all have the same requirements and restrictions as the control parameters.
Programming requirements
None.
Restrictions
The caller may not have any FRRs established.
An IEATDUMP cannot succeed when another process within the task is exclusively holding the SYSZTIOT enqueue. Instead, a SVC dump would probably occur.
Input register information
Before issuing the IEATDUMP macro, the caller does not have to place any information into any general purpose register (GPR) unless using it in register notation for a particular parameter, or using it as a base register.
Before issuing the IEATDUMP macro, the caller does not have to place any information into any access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code
Used as a work register by the system
2-14
15
Unchanged
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Performance implications
None.
186
z/OS MVS Assembler Services Reference IAR-XCT
DSNAD=dsnad
DSN=dsn
DDNAME=ddname
,HDRAD=hdrad
,HDR=hdr
,IDXAD=idxad
,IDX=idx
,SYMRECAD=symrecad
,SYMREC=symrec
,INTOKENAD=intokenad
,INTOKEN=intoken
,PROBDESCAD=probdescad
,PROBDESC=probdesc
,LISTAD=listad
,LIST=list
,SUBPLSTAD=subplstad
,SUBPLST=subplst
,DSPLISTAD=dsplistad
,DSPLIST=dsplist
⌂
Syntax
name
IEATDUMP transaction dump
Syntax
The parameters DCB, DCBAD, and ASYNC=YES are no longer supported.
The IEATDUMP macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede IEATDUMP.
IEATDUMP
⌂ One or more blanks must follow IEATDUMP.
dsnad: RS-type address or register (2) - (12).
dsn: RS-type address or register (2) - (12).
ddname: RS-type address or register (2) - (12).
hdrad: RS-type address or register (2) - (12).
hdr: RS-type address or register (2) - (12).
idxad: RS-type address or register (2) - (12).
idx: RS-type address or register (2) - (12).
symrecad: RS-type address or register (2) - (12).
symrec: RS-type address or register (2) - (12).
intokenad: RS-type address or register (2) - (12).
intoken: RS-type address or register (2) - (12).
probdescad: RS-type address or register (2) - (12).
probdesc: RS-type address or register (2) - (12).
listad: RS-type address or register (2) - (12).
list: RS-type address or register (2) - (12).
subplstad: RS-type address or register (2) - (12).
subplst: RS-type address or register (2) - (12).
dsplistad: RS-type address or register (2) - (12).
dsplist: RS-type address or register (2) - (12).
Chapter 22. IEATDUMP — Transaction dump request
187
IEATDUMP transaction dump
Syntax
,SDATA=DEFS
,SDATA=ALLNUC
,SDATA=CSA
,SDATA=GRSQ
,SDATA=LPA
,SDATA=LSQA
,SDATA=NUC
,SDATA=RGN
,SDATA=SQA
,SDATA=SUM
,SDATA=SWA
,SDATA=TRT
,SDATA=PSA
,ASYNC=NO
,ECBAD=ecbad
,ECB=ecb
Description
Default
: SDATA=DEFS
,RETCODE=retcode
,RSNCODE=rsncode
Default
: ASYNC=NO
ecbad: RS-type address or register (2) - (12).
ecb: RS-type address or register (2) - (12).
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
Default
: PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=1
Default
: MF=S
list addr: RS-type address or register (1) - (12).
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
188
z/OS MVS Assembler Services Reference IAR-XCT
IEATDUMP transaction dump
Parameters
The parameters DCB, DCBAD, and ASYNC=YES are no longer supported, and are removed from this information.
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IEATDUMP macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
DSNAD=dsnad
DSN=dsn
DDNAME=ddname
A required input parameter. The output dump data set should have the attributes of RECFM=FB and LRECL=4160.
DSNAD=dsnad
A 4-byte field which contains the address of the area of the name pattern used to create the data set that is to contain the dump. The format of the area is described in the DSN field which follows.
To code
: Specify the RS-type address, or address in register (2) - (12), of a pointer field.
DSN=dsn
A 2- to 101-character input area that contains the name pattern used to create the data set that is to contain the dump. The format of the area begins with a single byte specifying the length of the name pattern, which must not be greater than 100. The name pattern immediately follows that byte. The name pattern has a series of attributes: it is similar to that used by the operator DUMPDS NAME= parameter, except that &SEQ is not supported, and there is no default name pattern available; the use of system symbols is supported; and it must resolve to a valid data set name which can be allocated from the caller's task. When used with the
REMOTE= parameter, the generated name must be unique for each requested address space (&JOBNAME is one recommended addition to the pattern to accomplish this).
In addition, IEATDUMP also recognizes the symbol &DS. (Dump Section) on the end of the name pattern. When present, IEATDUMP allocates the first data set for dumping, ending with “001”. If this runs out of disk space or uses up all 16 extents before the dump is completed, dumping will be continued to data sets with the same name, but ending in “002”,”003”, and so on, until the entire dump is written. Each of these data sets are allocated with a primary extent size of 500M and a secondary extent size of 500M, but it is possible to change these values by providing ACS routines that are driven by DFSMS.
Remember to combine all of the data sets into one data set by using IPCS
COPYDUMP, before using IPCS to view the diagnostic data.
To code
: Specify the RS-type address, or address in register (2) - (12), of a
2- to 101-character field.
DDNAME=ddname
An 8-character input field that is the name of the DD representing the data set that is to contain the dump. The DD must be allocated when
IEATDUMP is invoked. The system will open this DD.
Chapter 22. IEATDUMP — Transaction dump request
189
IEATDUMP transaction dump
To code
: Specify the RS-type address, or address in register (2) - (12), of an
8-character field.
,HDRAD=hdrad
,HDR=hdr
A required input parameter.
,HDRAD=hdrad
A 4-byte field which contains the address of a parameter of the dump title.
The format of the area is a single byte specifying the length of the title followed by the title itself.
To code
: Specify the RS-type address, or address in register (2) - (12), of a pointer field.
,HDR=hdr
A 2- to 101-character input area that contains the dump title. The format of the area is a single byte specifying the length of the title followed by the title itself. The title has a maximum length of 100 characters.
To code
: Specify the RS-type address, or address in register (2) - (12), of a
2- to 101-character field.
,IDXAD=idxad
,IDX=idx
An optional input parameter.
,IDXAD=idxad
A 4-byte field which contains the address of a parameter of an area that contains the name of the dump index which is to contain information about the dump after the dump is written. The format of the area is a single byte specifying the length of the dump index data set name followed by the name itself. The data set must be an existing IPCS dump directory. The data set will be allocated from the caller's address space.
To code
: Specify the RS-type address, or address in register (2) - (12), of a pointer field.
,IDX=idx
A 2- to 45-character input area that contains the name of the dump index which is to contain information about the dump after the dump is written.
The format of the area is a single byte specifying the length of the dump index data set name followed by the name itself. The name of the dump index data set has a maximum length of 44 characters. The data set must be an existing IPCS dump directory. The data set will be allocated from the caller's address space.
To code
: Specify the RS-type address, or address in register (2) - (12), of a
2- to 45-character field.
,SYMRECAD=symrecad
,SYMREC=symrec
An optional input parameter.
,SYMRECAD=symrecad
A 4-byte field which contains the address of a parameter of a valid symptom record for DAE to use for dump suppression. This area is built using SYMRBLD and mapped by ADSR. This area has a maximum length of 1900 bytes.
To code
: Specify the RS-type address, or address in register (2) - (12), of a pointer field.
190
z/OS MVS Assembler Services Reference IAR-XCT
IEATDUMP transaction dump
,SYMREC=symrec
A parameter of a valid symptom record for DAE to use for dump suppression. This area is built using SYMRBLD and mapped by ADSR.
This area has a maximum length of 1900 bytes.
To code
: Specify the RS-type address, or address in register (2) - (12), of a character field.
,INTOKENAD=intokenad
,INTOKEN=intoken
An optional input parameter.
,INTOKENAD=intokenad
A 4-byte field which contains the address of a parameter of a 32-byte area that contains an incident token previously built by the IEAINTKN macro.
To code
: Specify the RS-type address, or address in register (2) - (12), of a pointer field.
,INTOKEN=intoken
A parameter of a 32-byte area that contains an incident token previously built by the IEAINTKN macro.
To code
: Specify the RS-type address, or address in register (2) - (12), of a
32-character field.
,PROBDESCAD=probdescad
,PROBDESC=probdesc
An optional input parameter.
,PROBDESCAD=probdescad
A 4-byte field which contains the address of a parameter of an area that contains information describing the problem. This area has a maximum length of 1024 bytes.
To code
: Specify the RS-type address, or address in register (2) - (12), of a pointer field.
,PROBDESC=probdesc
A parameter of an area that contains information describing the problem.
This area has a maximum length of 1024 bytes.
To code
: Specify the RS-type address, or address in register (2) - (12), of a character field.
,LISTAD=listad
,LIST=list
An optional input parameter.
,LISTAD=listad
A 4-byte field which contains the address of a parameter of a list of starting and ending addresses of areas to be dumped. The high-order bit of the last ending address is set to 1; the high-order bit of all other addresses is 0. This area has a maximum length of 240 bytes.
To code
: Specify the RS-type address, or address in register (2) - (12), of a pointer field.
,LIST=list
A parameter of a list of starting and ending addresses of areas to be dumped. The high-order bit of the last ending address is set to 1; the high-order bit of all other addresses is 0. This area has a maximum length of 240 bytes.
Chapter 22. IEATDUMP — Transaction dump request
191
IEATDUMP transaction dump
To code
: Specify the RS-type address, or address in register (2) - (12), of a character field.
,SUBPLSTAD=subplstad
,SUBPLST=subplst
An optional input parameter.
,SUBPLSTAD=subplstad
A 4-byte field which contains the address of a parameter of a list of subpool numbers to be dumped. The first halfword is the number subpools in the list and must be on a fullword boundary. Each entry is two bytes.
To code
: Specify the RS-type address, or address in register (2) - (12), of a pointer field.
,SUBPLST=subplst
A parameter of a list of subpool numbers to be dumped. The first halfword is the number subpools in the list and must be on a fullword boundary.
Each entry is two bytes.
To code
: Specify the RS-type address, or address in register (2) - (12), of a character field.
,DSPLISTAD=dsplistad
,DSPLIST=dsplist
An optional input parameter.
,DSPLISTAD=dsplistad
A 4-byte field which contains the address of a parameter of a list of data space storage to be dumped. The first word is the total size of the
DSPLIST. The next eight characters is the STOKEN of the data space to be dumped. A full word indicates the number of ranges to be dumped for that STOKEN. Then, 2 full words for each range, which are the starting and ending addresses of the range. More than one STOKEN may be specified per DSPLIST.
To code
: Specify the RS-type address, or address in register (2) - (12), of a pointer field.
,DSPLIST=dsplist
A parameter of a list of data space storage to be dumped. The first word is the total size of the DSPLIST. The next eight characters is the STOKEN of the data space to be dumped. A full word indicates the number of ranges to be dumped for that STOKEN. Then, 2 full words for each range, which are the staring and ending addresses of the range. More than one STOKEN may be specified per DSPLIST.
To code
: Specify the RS-type address, or address in register (2) - (12), of a character field.
,SDATA=DEFS
,SDATA=ALLNUC
,SDATA=CSA
,SDATA=GRSQ
,SDATA=LPA
,SDATA=LSQA
,SDATA=NUC
,SDATA=RGN
,SDATA=SQA
,SDATA=SUM
,SDATA=SWA
192
z/OS MVS Assembler Services Reference IAR-XCT
IEATDUMP transaction dump
,SDATA=TRT
,SDATA=PSA
An optional parameter that specifies what system data should be provided in the transaction dump. No fetch-protected storage which is inaccessible in the caller's key will be dumped. The default is SDATA=DEFS.
,SDATA=DEFS
The following SDATA options are included in the dump: LSQA, NUC,
PSA, RGN, SQA, SUM, SWA, and TRT.
,SDATA=ALLNUC
All of DAT-on nucleus, including page-protected areas, and all of the
DAT-off nucleus.
,SDATA=CSA
Common storage area and virtual storage for 64-bit addressable memory objects created using one of the following services: v IARV64 REQUEST=GETCOMMON,DUMP=LIKECSA v IARCP64 COMMON=YES,DUMP=LIKECSA v IARST64 COMMON=YES,TYPE=PAGEABLE
,SDATA=GRSQ
Global resource serialization (ENQ/DEQ/RESERVE) queues.
,SDATA=LPA
Link pack area for this job.
,SDATA=LSQA
Local system queue area and virtual storage for 64-bit addressable memory objects created using one of the following services: v IARV64 REQUEST=GETSTOR,DUMP=LIKELSQA v IARCP64 COMMON=NO,DUMP=LIKELSQA v IARST64 COMMON=NO
,SDATA=NUC
Non-page-protected areas of the DAT-on nucleus.
,SDATA=RGN
Entire private area and virtual storage for 64-bit addressable memory objects created using one of the following services: v IARV64 REQUEST=GETSTOR,DUMP=LIKERGN v IARV64 REQUEST=GETSTOR,SVCDUMPRGN=YES v IARCP64 COMMON=NO,DUMP=LIKERGN v IARST64 COMMON=NO
,SDATA=SQA
System queue area and virtual storage for 64-bit addressable memory objects created using one of the following services: v IARV64 REQUEST=GETCOMMON,DUMP=LIKESQA v IARCP64 COMMON=YES,DUMP=LIKESQA v IARST64 COMMON=YES,TYPE=FIXED v IARST64 COMMON=YES,TYPE=DREF
,SDATA=SUM
Requests the summary dump function.
,SDATA=SWA
Scheduler work area.
,SDATA=TRT
System trace data.
Chapter 22. IEATDUMP — Transaction dump request
193
IEATDUMP transaction dump
,SDATA=PSA
Prefixed save area.
One or more values may be specified for the SDATA parameter. If more than one value is specified, group the values within parentheses.
,ASYNC=NO
An optional parameter that specifies whether the transaction dump should be taken synchronously. The default is ASYNC=NO.
,ASYNC=NO
The transaction dump should be taken synchronously.
,ECBAD=ecbad
,ECB=ecb
An optional input parameter.
,ECBAD=ecbad
A 4-byte field which contains the address of a parameter of an ECB to be posted when the entire dump has been written. This area must be on a word boundary.
To code
: Specify the RS-type address, or address in register (2) - (12), of a pointer field.
,ECB=ecb
A parameter of an ECB to be posted when the entire dump has been written. This area must be on a word boundary.
To code
: Specify the RS-type address, or address in register (2) - (12), of a
4-character field.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code
: Specify the RS-type address of a fullword field, or register (2) - (12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code
: Specify the RS-type address of a fullword field, or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=1
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all
194
z/OS MVS Assembler Services Reference IAR-XCT
IEATDUMP transaction dump
the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 1
, if you use the currently available parameters.
To code
: Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 1
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms of IEATDUMP in the following order: v Use IEATDUMP ...MF=(M,list-addr,COMPLETE) specifying appropriate parameters, including all required ones.
v Use IEATDUMP ...MF=(M,list-addr,NOCHECK), specifying the parameters that you want to change.
v Use IEATDUMP ...MF=(E,list-addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this can be an RS-type address or an address in register
(1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter
Chapter 22. IEATDUMP — Transaction dump request
195
IEATDUMP transaction dump
list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When the IEATDUMP macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded
RSNCODE) contains a reason code.
X'00000000'
A complete dump was written.
X'00000004'
A partial dump was written.
X'00000008'
No dump was written.
X'0000000C'
Internal processing error. No dump was written.
X'00000010'
Unexpected return code from IEAVAD00.
Table 13. Return and Reason Codes for the IEATDUMP Macro
Return Code
00000000
Reason Code
00000000
Meaning and Action
Meaning
: A complete dump was written.
00000004
00000004
00000004
00000004
00000001
00000002
00000003
00000004
Action
: None.
Meaning
: The dump was truncated because the data set was too small.
Action
: Reissue IEATDUMP with a larger data set or use the DSN|DSNAD parameter to allocate the dump data set automatically.
Meaning
: Contention detected when attempting to set tasks in the address space non-dispatchable.
Action
: Data in dump may be inconsistent. Reissue
IEATDUMP.
Meaning
: Unable to add dump data set to dump index.
Action
: Verify that the dump index specified on the IDX parameter is correct and reissue IEATDUMP.
Meaning
: Unable to allocate transaction dump data set.
Action
: See allocation failure messages. Reissue
IEATDUMP.
196
z/OS MVS Assembler Services Reference IAR-XCT
IEATDUMP transaction dump
Table 13. Return and Reason Codes for the IEATDUMP Macro (continued)
Return Code
00000004
Reason Code
00000006
Meaning and Action
Meaning
: Maximum amount of dump sections reached
(999).
00000004
00000004
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000007
00000008
00000001
00000002
00000003
00000004
00000005
00000006
00000007
Action
: Dump less memory, or use ACS routines to increase the size of the data sets. Reissue IEATDUMP.
Meaning
: The system has filled one of the range tables.
Action
: Dump less memory. If the problem still exists, contact the IBM Support Center.
Meaning
: The data space used for the IEATDUMP has been filled. No more then 2 gigabytes of data can be collected.
Action
: Do one of the following: v
Remove unnecessary dump options.
v Specify smaller memory ranges.
v Use the extended data set support by either:
– Preallocating a large capacity data set and use the
DDNAME parameter.
– Refer to the use of the &DS symbol for the DSN parameter's data set name pattern.
Meaning
: The address of the transaction dump parameter list was zero.
Action
: Ensure register 1 is non-zero when the transaction dump is requested. Reissue IEATDUMP.
Meaning
: The dump was suppressed by CHNGDUMP.
Action
: Issue CHNGDUMP SET,SYSMDUMP or
CHNGDUMP RESET,SYSMDUMP. Reissue IEATDUMP.
Meaning
: The dump was suppressed by SLIP.
Action
: Delete SLIP trap with SLIP DEL command. Reissue
IEATDUMP.
Meaning
: The ALET for the transaction dump parameter list was not valid.
Action
: Ensure that access register 1 has a valid ALET when the transaction dump is requested. Reissue
IEATDUMP.
Meaning
: The transaction dump parameter list was not addressable.
Action
: Ensure that the entire transaction dump parameter list is addressable via register 1 (and access register 1 if running in AR ASC mode) when the transaction dump is requested. Reissue IEATDUMP.
Meaning
: The transaction dump parameter list version number was not valid.
Action
: Ensure the transaction dump request was built using the IEATDUMP macro for the system on which the dump was requested. Reissue IEATDUMP.
Meaning
: The length of the transaction dump parameter list did not match the parameter list version number.
Action
: Ensure the transaction dump request was built using the IEATDUMP macro for the system on which the dump was requested. Reissue IEATDUMP.
Chapter 22. IEATDUMP — Transaction dump request
197
IEATDUMP transaction dump
Table 13. Return and Reason Codes for the IEATDUMP Macro (continued)
Return Code
00000008
Reason Code
00000008
Meaning and Action
Meaning
: No DDNAME, DSN(AD), or DSP_STOKEN was specified.
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000009
0000000C
0000000D
0000000E
0000000F
00000010
00000011
00000012
00000013
00000014
Action
: Reissue IEATDUMP with the DDNAME, DSN(AD) or DSP_STOKEN keyword.
Meaning
: Both DDNAME and DSN(AD) keywords were specified.
Action
: Reissue IEATDUMP with either the DDNAME or
DSN(AD) keyword.
Meaning
: The ALET for the DSN(AD) keyword was not valid.
Action
: Ensure that the access register for the DSN(AD) has a valid ALET when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The DSN(AD) was not addressable.
Action
: Ensure that the entire DSN(AD) is addressable using the specified address (and ALET if running in AR
ASC mode) when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: No HDR(AD) keyword was specified.
Action
: Reissue IEATDUMP with the HDR(AD) keyword.
Meaning
: The ALET for the HDR(AD) keyword was not valid.
Action
: Ensure that the access register for the HDR(AD) has a valid ALET when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The HDR(AD) was not addressable.
Action
: Ensure that the entire HDR(AD) is addressable using the specified address (and ALET if running in AR
ASC mode) when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The specified HDR(AD) was longer than 100 characters.
Action
: Reissue IEATDUMP with a shorter header.
Meaning
: The ALET for the IDX(AD) keyword was not valid.
Action
: Ensure that the access register for the IDX(AD) has a valid ALET when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The IDX(AD) was not addressable.
Action
: Ensure that the entire IDX(AD) is addressable using the specified address (and ALET if running in AR
ASC mode) when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The IDX(AD) keyword did not specify a valid data set name after symbol substitution.
Action
: Reissue IEATDUMP with an IDX keyword that resolves to a valid dump index data set name.
198
z/OS MVS Assembler Services Reference IAR-XCT
IEATDUMP transaction dump
Table 13. Return and Reason Codes for the IEATDUMP Macro (continued)
Return Code
00000008
Reason Code
00000015
Meaning and Action
Meaning
: The ALET for the SYMREC(AD) keyword was not valid.
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000016
00000017
00000018
00000019
0000001A
0000001B
0000001C
0000001D
0000001E
0000001F
Action
: Ensure that the access register for the
SYMREC(AD) has a valid ALET when the transaction dump is requested. Reissue IEATDUMP.
Meaning
: The SYMREC(AD) was not addressable.
Action
: Ensure that the entire SYMREC(AD) is addressable using the specified address (and ALET if running in AR
ASC mode) when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The specified SYMREC(AD) was not valid. Either
ADSRID not set to 'SR' or primary symptom string offset or length not initialized.
Action
: Reissue IEATDUMP with a valid symptom record.
Meaning
: The ALET for the INTOKEN(AD) keyword was not valid.
Action
: Ensure that the access register for the
INTOKEN(AD) has a valid ALET when the transaction dump is requested. Reissue IEATDUMP.
Meaning
: The INTOKEN(AD) was not addressable.
Action
: Ensure that the entire INTOKEN(AD) is addressable using the specified address (and ALET if running in AR ASC mode) when the transaction dump is requested. Reissue IEATDUMP.
Meaning
: The ALET for the REMOTE(AD) keyword was not valid.
Action
: Ensure that the access register for the
REMOTE(AD) has a valid ALET when the transaction dump is requested. Reissue IEATDUMP.
Meaning
: The REMOTE(AD) was not addressable.
Action
: Ensure that the entire REMOTE(AD) is addressable using the specified address (and ALET if running in AR
ASC mode) when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The specified REMOTE(AD) was not valid.
Action
: Reissue IEATDUMP with a valid remote area.
Meaning
: The ALET for the LIST(AD) keyword was not valid.
Action
: Ensure that the access register for the LIST(AD) has a valid ALET when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The LIST(AD) was not addressable.
Action
: Ensure that the entire LIST(AD) is addressable using the specified address (and ALET if running in AR
ASC mode) when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The specified LIST(AD) was not valid. A range in the storage list had a start address greater than its ending address.
Action
: Reissue IEATDUMP with a valid storage list.
Chapter 22. IEATDUMP — Transaction dump request
199
IEATDUMP transaction dump
Table 13. Return and Reason Codes for the IEATDUMP Macro (continued)
Return Code
00000008
Reason Code
00000020
Meaning and Action
Meaning
: The dump was rejected because the caller's authorization was insufficient for requested function(s).
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000021
00000022
00000023
00000024
00000025
00000026
00000027
00000028
00000029
Action
: Verify authorization and requested functions.
Reissue IEATDUMP.
Meaning
: The DSN(AD) keyword did not specify a valid data set name after symbol substitution.
Action
: Reissue IEATDUMP with a DSN keyword that resolves to a valid dump data set name.
Meaning
: The DSN(AD) keyword specified a data set name that was too long.
Action
: Reissue IEATDUMP with a DSN(AD) keyword that resolves to a shorter dump data set name.
Meaning
: The DSN(AD) keyword specified a data set name that contained a bad symbol.
Action
: Reissue IEATDUMP with a DSN(AD) keyword that does not contain bad symbols.
Meaning
: Unable to create data space to capture transaction dump.
Action
: Remedy cause of DSPSERV CREATE failure or request transaction dump specifying DDNAME or including the &DS. symbol in the DSN template.
Meaning
: Unable to add transaction dump data space to access list.
Action
: Remedy cause of ALESERV ADD failure or request transaction dump specifying DDNAME. Reissue
IEATDUMP.
Meaning
: Unable to allocate transaction dump data set.
Action
: Look at allocation failure messages. Reissue
IEATDUMP.
Meaning
: The transaction dump was suppressed by DAE.
Action
: If you do not wish transaction dumps to be suppressed on an installation basis, issue the SET DAE=xx console command specifying an ADYSETxx member that does not specify SYSMDUMP(SUPPRESS).
If you do not wish transaction dumps to be suppressed on an application basis, include the VRANODAE key in the
VRADATA of your recovery routine.
Reissue IEATDUMP.
Meaning
: An error occurred writing the first record to the data space or dump data set.
Action
: Ensure the STOKEN and origin for the specified data space are correctly specified. Ensure that the specified
DD is allocated when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The ALET for the PROBDESC(AD) keyword was not valid.
Action
: Ensure that the access register for the
PROBDESC(AD) has a valid ALET when the transaction dump is requested. Reissue IEATDUMP.
200
z/OS MVS Assembler Services Reference IAR-XCT
IEATDUMP transaction dump
Table 13. Return and Reason Codes for the IEATDUMP Macro (continued)
Return Code
00000008
Reason Code
0000002A
Meaning and Action
Meaning
: The PROBDESC(AD) was not addressable.
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000008
00000008
0000002B
0000002C
0000002D
0000002E
0000002F
00000030
00000031
00000032
00000033
00000034
Action
: Ensure that the entire PROBDESC(AD) is addressable using the specified address (and ALET if running in AR ASC mode) when the transaction dump is requested. Reissue IEATDUMP.
Meaning
: The specified PROBDESC(AD) was not valid.
Action
: Reissue IEATDUMP with a valid problem description area.
Meaning
: The ALET for the SUBPLST(AD) keyword was not valid.
Action
: Ensure that the access register for the
SUBPLST(AD) has a valid ALET when the transaction dump is requested. Reissue IEATDUMP.
Meaning
: The SUBPLST(AD) was not addressable.
Action
: Ensure that the entire SUBPLST(AD) is addressable using the specified address (and ALET if running in AR
ASC mode) when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The specified SUBPLST(AD) was not valid. An invalid subpool was specified.
Action
: Reissue IEATDUMP with a valid subpool list.
Meaning
: The ALET for the DSPLIST(AD) keyword was not valid.
Action
: Ensure that the access register for the DSPLIST(AD) has a valid ALET when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The DSPLIST(AD) was not addressable.
Action
: Ensure that the entire DSPLIST(AD) is addressable using the specified address (and ALET if running in AR
ASC mode) when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The specified DSPLIST(AD) was not valid. An invalid data space was specified.
Action
: Reissue IEATDUMP with a valid data space list.
Meaning
: The ALET for the ECB(AD) keyword was not valid.
Action
: Ensure that the access register for the ECB(AD) has a valid ALET when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The ECB(AD) was not addressable.
Action
: Ensure that the entire ECB(AD) is addressable using the specified address (and ALET if running in AR
ASC mode) when the transaction dump is requested.
Reissue IEATDUMP.
Meaning
: The specified ECB(AD) was not valid. The ECB was not on a fullword boundary.
Action
: Reissue IEATDUMP with an ECB.
Chapter 22. IEATDUMP — Transaction dump request
201
|
IEATDUMP transaction dump
Table 13. Return and Reason Codes for the IEATDUMP Macro (continued)
Return Code
00000008
Reason Code
00000035
Meaning and Action
Meaning
: OPEN failed for the dump data set.
00000008
00000008
00000008
00000008
00000036
00000037
00000038
00000039
Action
: Determine why OPEN failed and reissue
IEATDUMP.
Meaning
: Dump data set has invalid block size.
Action
: Correct the block size and reissue IEATDUMP.
Meaning
: The DSP_RECORDS@ field was not accessible.
Action
: Correct the problem and reissue IEATDUMP.
Meaning
: The DCB parameter is not supported on
IEATDUMP.
Action
: Remove the DCB parameter and reissue
IEATDUMP.
Meaning
: The ASYNC=YES is not supported on
IEATDUMP.
00000008
00000008
0000000C
0000000C
0000000C
0000000C
0000000C
0000000C
0000003A
0000003B
00000001
00000002
00000003
00000004
00000005
00000006
Action
: Change to ASYNC=NO and reissue IEATDUMP.
Meaning
: The &DS. symbol was found in the midst of the dump DSN name pattern.
Action
: Place the &DS symbol at the end of the DSN name pattern and reissue IEATDUMP.
Meaning
: This IEATDUMP was not taken because another dump was already running in the address space.
Action
: None.
Meaning
: Unable to obtain storage for transaction dump from subpool 230 below the line.
Action
: Determine why storage is not available and reissue
IEATDUMP.
Meaning
: Unable to establish recovery environment for transaction dump.
Action
: Determine why ESTAEX failed and reissue
IEATDUMP.
Meaning
: Unable to obtain storage for transaction dump from subpool 245 above the line.
Action
: Determine why storage is not available and reissue
IEATDUMP.
Meaning
: Unable to obtain storage for transaction dump from subpool 231 above the line.
Action
: Determine why storage is not available and reissue
IEATDUMP.
Meaning
: Unable to obtain storage for transaction dump from subpool 239 above the line.
Action
: Determine why storage is not available and reissue
IEATDUMP.
Meaning
: Unable to obtain storage for transaction dump from subpool 239 above the line.
Action
: Determine why storage is not available and reissue
IEATDUMP.
202
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|||
|
|||
|
|
IEATDUMP transaction dump
Table 13. Return and Reason Codes for the IEATDUMP Macro (continued)
Return Code
0000000C
Reason Code
00000007
Meaning and Action
Meaning
: Unable to obtain storage for transaction dump from subpool 239 above the line.
0000000C
0000000C
0000000C
0000000C
0000000C
0000000C
0000000C
00000010
00000008
00000009
0000000A
0000000B
0000000C
0000000D
000000FF xxxxxxxx
Action
: Determine why storage is not available and reissue
IEATDUMP.
Meaning
: Unable to obtain storage for transaction dump from subpool 250 above the line.
Action
: Determine why storage is not available and reissue
IEATDUMP.
Meaning
: Unable to obtain storage for transaction dump from subpool 230 above the line.
Action
: Determine why storage is not available and reissue
IEATDUMP.
Meaning
: Unable to obtain storage for transaction dump from subpool 230 below the line.
Action
: Determine why storage is not available and reissue
IEATDUMP.
Meaning
: Unable to obtain storage for transaction dump from subpool 253 above the line.
Action
: Determine why storage is not available and reissue
IEATDUMP.
Meaning
: Unable to obtain high virtual private storage for transaction dump.
Action
: Determine why an authorized IARV64
MEMLIMIT(NO) request failed to get storage and reissue
IEATDUMP.
Meaning
: Unable to obtain high virtual common storage for transaction dump.
Action
: Determine why storage is not available and reissue
IEATDUMP.
Meaning
: IEAVTDMP's recovery received control. One possible reason is that the SYSZTIOT enqueue is being held exclusively by another process running under this task. It is not possible for the IEATDUMP to successfully complete.
Action
: The assistance of a system programmer is needed for associated SVC dumps. In the case of a SYSZTIOT enqueue, the problem is not in IEATDUMP processing. The diagnosis of any issues requires data collection using SLIP and/or SDUMPX, and not IEATDUMP.
Meaning
: Unexpected return code from IEAVAD00. Return code from IEAVAD00 returned as reason code.
Action
: Inform the system programmer.
Examples
An example using DSN:
.
.
IEATDUMP DSN=DUMPDSN,HDR=DUMPTTL2
.
DUMPDSN DC
S2 DC
AL1(E2-S2)
C’HLQ.TDUMP.D&&YYMMDD..T&&HHMMSS..&&SYSNAME..&&JOBNAME.’
Chapter 22. IEATDUMP — Transaction dump request
203
IEATDUMP transaction dump
E2 EQU *
DUMPTTL2 DC AL1(E3-S3)
S3
E3
DC
EQU
C’IEADUMP TO AUTOMATICALLY ALLOCATED DATA SET’
*
204
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 23. IEATXDC — Transactional execution diagnostic controls
Description
In support of the diagnostic controls of transactional execution, as defined in the
z/Architecture Principles of Operation, the following services are provided:
For the current task, v Indicate the scope of the diagnostic controls.
v Set the diagnostic controls for "no abort".
v
Set the diagnostic controls for "abort every".
v Set the diagnostic controls for "abort random".
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state with PSW key 8-15.
Task
Any PASN, any HASN, any SASN
31- or 64-bit
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
None.
None.
Programming requirements
None.
Restrictions
None.
Input register information
Before issuing the IEATXDC macro, the caller does not have to place any information into any general purpose register (GPR).
Before issuing the IEATXDC macro, the caller does not have to place any information into any access register (AR).
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
14
Used as work registers by the system
Unchanged
Used as a work register by the system
© Copyright IBM Corp. 1988, 2017
205
IEATXDC macro
Syntax
15
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Performance implications
None.
Syntax
The IEATXDC macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede IEATXDC.
IEATXDC
� One or more blanks must follow IEATXDC.
SCOPE=PROBLEM
SCOPE=ALL
,OPERATION=NO_ABORT
,OPERATION=SET_EVERY
,OPERATION=SET_RANDOM
,RETCODE=retcode retcode: RS-type address or register (2) - (12) or (15), (GPR15), (REG15), or
(R15).
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IEATXDC macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
SCOPE=PROBLEM
SCOPE=ALL
A required parameter that identifies the scope of the diagnostic controls.
206
z/OS MVS Assembler Services Reference IAR-XCT
IEATXDC macro
SCOPE=PROBLEM
indicates that the diagnostic controls apply only for problem state transactional execution.
SCOPE=ALL
is treated the same as SCOPE=PROBLEM.
,OPERATION=NO_ABORT
,OPERATION=SET_EVERY
,OPERATION=SET_RANDOM
A required parameter that identifies the type of operation to perform.
,OPERATION=NO_ABORT
indicates to set the transactional diagnostic controls for this task so that the system will not apply its SET_EVERY or SET_RANDOM rules.
Transactions themselves may still abort for all the defined architectural reasons.
,OPERATION=SET_EVERY
indicates to set the transactional diagnostic controls for this task to request abort of every nonconstrained transaction.
,OPERATION=SET_RANDOM
indicates to set the transactional diagnostic controls for this task to request abort of random nonconstrained transactions.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12) or
(15), (GPR15), (REG15), or (R15).
ABEND codes
None.
Return codes
When the IEATXDC macro returns control to your program, GPR 15 (and retcode, when you code RETCODE) contains a return code.
The following table identifies the hexadecimal return and reason codes.
Table 14. Return codes for the IEATXDC Macro
Return Code
0
Meaning and Action
Meaning
: Successful completion. Diagnostic controls are set to the requested value
4
8
Action
: None required.
Meaning
: Warning. The machine does not support transactional execution. Diagnostic controls are not set.
Action
: Avoid calling IEATXDC when the machine does not support transactional execution.
Meaning
: Unexpected input.
Action
: Check for possible storage overlay.
Chapter 23. IEATXDC — Transactional execution diagnostic controls
207
IEATXDC macro
Table 14. Return codes for the IEATXDC Macro (continued)
Return Code
12
Meaning and Action
Meaning
: Service called in SRB mode.
Action
: Avoid using IEATXDC in SRB mode.
Examples
None.
208
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 24. IEAVAPE — Allocate_Pause_Element
Description
Allocate_Pause_Element obtains a pause element token (PET), which uniquely identifies a pause element. The PET is used as input to the following services: v Pause v Release v Transfer v Deallocate_Pause_Element
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
31-bit
Primary
Enabled for I/O and external interrupts
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine (IEACSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
When the calling program specifies auth_level=IEA_UNAUTHORIZED, the caller must be in task mode and can only release another task in its home address space.
All pause element tokens (PETs) used when auth_level=IEA_UNAUTHORIZED must have been obtained using an authorization level of IEA_UNAUTHORIZED.
Only 2040 unauthorized PETs may be allocated at any one time in an address space.
Input register information
Before calling Allocate_Pause_Element, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
© Copyright IBM Corp. 1988, 2017
209
IEAVAPE callable service
Syntax
1
13
Address of the parameter address list.
Address of a 72-byte register save area.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as work registers by the system
Return Code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Performance implications
None.
Syntax
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Description
CALL IEAVAPE
(return_code
,auth_level
,pause_element_token)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return code from the Allocate_Pause_Element service.
,auth_level
Supplied parameter
210
z/OS MVS Assembler Services Reference IAR-XCT
IEAVAPE callable service
v Type: Integer v
Character Set: N/A v Length: 4 bytes
Represents one or more possible levels of the pause element being allocated.
The calling program can use the constants defined in IEAASM or IEAC, as appropriate. The level desired results from adding the values of the required types together. The authorization type is not optional.
For instance, the level to allocate authorized pause elements that are checkpoint/restart tolerant is IEA_AUTHORIZED + IEA_CHECKPOINTOK, or
3.
The following levels are supported:
Table 15. Authorization
IEAASM and IEAC defined constants Value (hexadecimal)
IEA_UNAUTHORIZED 0
IEA_AUTHORIZED 1
Meaning
When using the allocated pause element through other services, either auth_level
IEA_UNAUTHORIZED or IEA_AUTHORIZED can be used.
When using the allocated pause element through other services, auth_level=IEA_AUTHORIZED will be required. Caller must be both key 0 and supervisor state.
Table 16. Checkpoint/Restart Toleration - only available when the CVTPAUS4 bit is set in the CVT.
IEAASM and IEAC defined constants Value (hexadecimal)
IEA_CHECKPOINTOK 2
Meaning
The application can tolerate the pause elements' not being restored upon a restart after a checkpoint.
Note:
If the IEA_CHECKPOINTOK value is not added to the authorization value, checkpoints cannot be taken when an allocated pause element exists.
,pause_element_token
Returned parameter v
Type: Character string v Character Set: N/A v Length: 16 bytes
Contains the pause element token that identifies the pause element which you can use to synchronize the processing of a task.
ABEND codes
None.
Return code in:
Decimal (Hex)
Equate symbol
00 (0)
Return codes
When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.
Meaning and Action
Meaning
: Successful completion.
Action
: None.
IEA_SUCCESS
Chapter 24. IEAVAPE — Allocate_Pause_Element
211
IEAVAPE callable service
Return code in:
Decimal (Hex)
Equate symbol
24 (18)
IEA_LOCK_HELD
36 (24)
IEA_UNSUPPORTED_MVS_RELEASE
40 (28)
IEA_PE_NOT_HOME
44 (2C)
IEA_XFER_TO_SELF
48 (30)
IEA_XFER_FAILED
56 (38)
IEA_NO_PETS_AVAILABLE
4095 (FFF)
IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning:
Program error. If the auth_level indicates AUTHORIZED, locks other than the local lock are held. If the auth_level indicates UNAUTHORIZED, locks are held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The auth_level value specified in the call is not valid.
The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Environmental error. The system could not obtain storage for a pause element. The system rejects the service call.
Action
: Retry the request later. If the problem persists, consult your system programmer.
Meaning
: There are no pause element tokens available.
Action
: Retry the request later.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action
: Contact IBM support.
212
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 25. IEAVAPE2 — Allocate_Pause_Element
Description
Allocate_Pause_Element obtains a pause element token (PET), which uniquely identifies a pause element. The PET is used as input to the following services: v Pause v Release v Transfer v Deallocate_Pause_Element
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
31-bit
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine (IEACSS from SYS1.CSSLIB) or have the calling program LOAD and then CALL the service.
The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Only 2040 unauthorized PETs may be allocated at any one time in an address space.
Allocate_Pause_Element cannot be used by tasks that are higher in the task tree than the cross memory resource owning task (the top, or first, job step task in the address space).
Key 1-15 or problem state callers must specify linkage as IEA_LINKAGE_SVC and pause_element_owner_stoken as binary zero.
© Copyright IBM Corp. 1988, 2017
213
IEAVAPE2 callable service
Syntax
Input register information
Before calling Allocate_Pause_Element, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Address of a 72-byte register save area.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Description
CALL IEAVAPE2
,(return_code
,pause_element_auth_level
,pause_element_token
,pause_element_owner_stoken
,owner_termination_release_code
,linkage)
Parameters
The parameters are explained as follows:
214
z/OS MVS Assembler Services Reference IAR-XCT
IEAVAPE2 callable service return_code
Returned parameter v
Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return code from the Allocate_Pause_Element service.
,pause_element_auth_level
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Represents one or more possible levels of the pause element being allocated.
The calling program can use the constants defined in IEAASM or IEAC, as appropriate. The level desired results from adding the values of the required types together. The authorization type is not optional.
For instance, the level to allocate authorized pause elements that are checkpoint/restart tolerant is IEA_AUTHORIZED + IEA_CHECKPOINTOK, or
3.
The following levels are supported:
Table 17. Authorization
IEAASM and IEAC defined constants Value (hexadecimal)
IEA_UNAUTHORIZED 0
IEA_AUTHORIZED 1
Meaning
When using the allocated pause element through other services, either pause_element_auth_level
IEA_UNAUTHORIZED or IEA_AUTHORIZED can be used.
When using the allocated pause element through other services, pause_element_auth_level
=IEA_AUTHORIZED is required. Caller must be both key 0 and supervisor state.
Table 18. Checkpoint/Restart Toleration - only available when the CVTPAUS4 bit is set in the CVT.
IEAASM and IEAC defined constants Value (hexadecimal)
IEA_CHECKPOINTOK 2
Meaning
The application can tolerate the pause elements' not being restored upon a restart after a checkpoint.
Note:
If the IEA_CHECKPOINTOK value is not added to the authorization value, checkpoints cannot be taken when an allocated pause element exists.
,pause_element_token
Returned parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains the pause element token that identifies a pause element which you can use to synchronize the processing of a task or SRB.
,pause_element_owner_stoken
Supplied parameter v Type: Character string v Character Set: N/A
Chapter 25. IEAVAPE2 — Allocate_Pause_Element
215
IEAVAPE2 callable service
v Length: 8 bytes
Specifies the space token (STOKEN) of the address space which is to be considered the owner of the Pause Element being allocated. Specify one of the following values: v Binary zero: indicate the system should make the current primary address space the owner of the Pause Element. This is the only value valid for key
8-15 problem state callers.
v A valid STOKEN, indicate the system should make the address space with the matching STOKEN the owner for the pause element.
When the CMRO task (the first job step task) of an address space terminates, the system will release and deallocate any pause elements owned by the
CMRO task's home address space. The table below describes exactly when the system will release and/or deallocate a Pause Element:
Allocation Service version:
IEAVAPE
Deallocation Rules
The PE will be deallocated by the system when one of the following events occurs: v The PE was never used to pause a task or
SRB and the CMRO task for the space which allocated it terminates.
v The PE is being used to pause a task or
SRB which is asynchronously terminated via CALLRTM TYPE=ABTERM (for example, cancel or detach) or a
PURGEDQ.
v The CMRO task of the home address space of the task or SRB which last used the PE terminates and the PE is not being used to pause an SRB.
The home address space of the task or SRB which last used the PE terminates
216
z/OS MVS Assembler Services Reference IAR-XCT
IEAVAPE2 callable service
Allocation Service version:
IEAVAPE2
Deallocation Rules
The PE will be deallocated by the system when one of the following events occurs: v The CMRO task of the address space specified by pause_element_owner_stoken terminates. If the PE is being used to pause a DU when the CMRO task terminates, the system will release the DU using the owner_termination_release_code before the PE is deallocated. Note that in this case, the UPET returned will be 16 bytes of binary zeros, an invalid value.
v The PE is being used to pause a task or
SRB which is asynchronously terminated via CALLRTM TYPE=ABTERM (for example, cancel or detach) or a
PURGEDQ.
v The PE is being used to pause a task or
SRB when the home address space of the task or SRB is terminated v The CMRO task of the home address space of the task or SRB which last used the PE terminates and the PE is not being used to pause an SRB
The home address space of the task or SRB which last used the PE terminates.Note: A
PE is considered as "being used to pause a task or SRB," when the PE is not Reset or
Prereleased.
,owner_termination_release_code
Supplied parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
Specifies the release code which will be returned to a paused DU if the system deallocates the pause element while it is being used to pause a task or SRB, due to the CMRO task of its owning address space terminating.
Note:
If the system deallocates a PE due to its owner terminating while the PE was not being used to pause a task or SRB, future attempts to use the PE will fail with a return code indicating the PETOKEN was stale or the PE is in an invalid state.
linkage
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Specifies how the Allocate_Pause_Element service routine is to be invoked. The following options are supported:
Chapter 25. IEAVAPE2 — Allocate_Pause_Element
217
IEAVAPE2 callable service
Table 19. Linkage option
Variable
IEA_LINKAGE_SVC
Value (hexadecimal)
0
IEA_LINKAGE_BRANCH 1
Meaning
The Allocate_Pause_Element service routine will be invoked via an SVC linkage. This option can be used when in non-cross memory task mode, any key, and either problem state or supervisor state.
The Allocate_Pause_Element service routine will be invoked via a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in SRB mode.
ABEND codes
None.
Return codes
When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.
Equate Symbol Meaning and Action Return code in: Decimal
(Hex)
00 (0) IEA_SUCCESS
24 (18)
36 (24)
40 (28)
44 (2C)
IEA_LOCK_HELD
IEA_UNSUPPORTED_MVS_RELEASE
IEA_INVALID_AUTHCODE
IEA_INVALID_MODE
Meaning:
Successful completion.
Action:
None.
Meaning:
Program error. One or more locks other than the local lock are held. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Environmental error. The system release does not support this service. The system rejects the service call.
Action:
Run the program on a system that supports the service.
Meaning:
Program error. The pause_element_auth_level value specified in the call is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The calling program is not in primary ASC mode, which this service requires.
The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
218
z/OS MVS Assembler Services Reference IAR-XCT
IEAVAPE2 callable service
Return code in: Decimal
(Hex)
48 (30)
Equate Symbol
56 (38)
4095 (FFF)
84 (54)
88 (58)
96 (60)
100 (64)
Meaning and Action
IEA_OUT_OF_STORAGE
IEA_NO_PETS_AVAILABLE
IEA_UNEXPECTED_ERROR
IEA_INVALID_LINKAGE
Meaning:
Environmental error. The system could not obtain storage for a pause element. The system rejects the service call.
Action:
Retry the request later. If the problem persists, consult your system programmer.
Meaning:
There are no pause element tokens available.
Action:
Retry the request later.
Meaning:
This service routine encountered an unexpected error.
The system rejects this service request.
Action:
Contact IBM support.
Meaning:
Program error. The linkage value specified is not valid. The system rejects the service call
IEA_INVALID_OWNER_STOKEN
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The stoken specified for pause_element_owner_stoken is not valid.
Action:
Obtain the correct stoken of the target and reissue the call
IEA_UNAUTH_NONZERO_OWNER_STOKEN Meaning: Program error. A key 8-15 problem state caller specified a nonzero value for pause_element_owner_stoken
IEA_INVALID_AUTHLVL_AUTHCODE
Action:
Check the calliing program for a probable coding error. Correct the program and rerun it.
Meaning:
The pause_element_auth_level value specified in the call is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 25. IEAVAPE2 — Allocate_Pause_Element
219
IEAVAPE2 callable service
220
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 26. IEAVDPE — Deallocate_Pause_Element
Description
Deallocate_Pause_Element frees a pause element that is no longer needed.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
31-bit addressing mode.
Primary mode.
Enabled for I/O and external interrupts
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine (IEACSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
When the calling program specifies auth_level=IEA_UNAUTHORIZED, the caller must be in task mode and can only release another task in its home address space.
All pause element tokens (PETs) used when auth_level=IEA_UNAUTHORIZED must have been obtained using an authorization level of IEA_UNAUTHORIZED.
Input register information
Before calling Deallocate_Pause_Element, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Address of a 72-byte register save area.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
© Copyright IBM Corp. 1988, 2017
221
IEAVDPE callable service
Syntax
0-1
2-13
14
15
Used as work registers by the system
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.
Description
CALL IEAVDPE
,(return_code
,auth_level
,pause_element_token)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return code from the Deallocate_Pause_Element service.
,auth_level
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
222
z/OS MVS Assembler Services Reference IAR-XCT
IEAVDPE callable service
Variable
IEA_UNAUTHORIZED
Indicates the maximum authorization level of the pause element being deallocated. IEAASM and IEAC define constants IEA_UNAUTHORIZED and
IEA_AUTHORIZED, which the calling program can use. The following levels are supported:
Meaning Value
(HEX)
0 This pause element being deallocated must have been allocated with auth_level=IEA_UNAUTHORIZED.
,pause_element_token
Supplied parameter v Type: Character string v
Character Set: N/A v Length: 16 bytes
Contains the pause element token that identifies the pause element that is no longer needed.
ABEND codes
None.
Return code in:
Decimal (Hex)
Equate symbol
00 (00)
Return codes
When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.
Meaning and Action
IEA_SUCCESS
04 (04)
08 (08)
IEA_PE_TOKEN_STALE
24 (18)
IEA_LOCK_HELD
32 (20)
IEA_PE_BAD_STATE
Meaning
: Successful completion
Action
: None.
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error.
Correct the program and rerun it.
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET returned on Pause or Transfer.
Action
: Check the calling program for a probable coding error.
Correct the program and rerun it.
Meaning
: Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action
: Check the calling program for a probable coding error.
Correct the program and rerun it.
Meaning
: Program error. The pause element associated with the specified pause element token is not valid or has already been paused. A paused PE must be released before it is deallocated. This return code also can indicate that the address space associated with the pause element is ending or has ended and that the system freed the pause element.
Action
: Check the calling program for a probable coding error.
Correct the program and rerun it.
Chapter 26. IEAVDPE — Deallocate_Pause_Element
223
IEAVDPE callable service
Return code in:
Decimal (Hex)
Equate symbol
36 (24)
IEA_UNSUPPORTED_MVS_RELEASE
40 (28)
IEA_INVALID_AUTHCODE
44 (2C)
IEA_INVALID_MODE
60 (3C)
IEA_AUTH_TOKEN
64 (40)
IEA_PE_NOT_HOME
4095 (FFF)
IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The auth_level value specified in the call is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error.
Correct the program and rerun it.
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error.
Correct the program and rerun it.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was allocated with auth_level=AUTHORIZED. The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was for a pause element allocated to another address.
Action
: Check the calling program for a probable coding error.
Correct the program and rerun it.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action
: Contact IBM support.
224
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 27. IEAVDPE2 — Deallocate_Pause_Element
Description
Deallocate_Pause_Element frees a pause element that is no longer needed.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
31-bit addressing mode.
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEACSS from SYS1.CSSLIB) or have the calling program LOAD and then CALL the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Key 1-15 or problem state callers must specify linkage as IEA_LINKAGE_SVC.
Input register information
Before calling Deallocate_Pause_Element, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Address of a 72-byte register save area.
Output register information
When control returns to the caller, the GPRs contain:
© Copyright IBM Corp. 1988, 2017
225
IEAVDPE2 callable service
Syntax
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.
Description
CALL IEAVDPE2
,(return_code
,pause_element_token
,linkage)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return code from the Deallocate_Pause_Element service.
,pause_element_token
Supplied parameter v Type: Character string v
Character Set: N/A v Length: 16 bytes
226
z/OS MVS Assembler Services Reference IAR-XCT
IEAVDPE2 callable service
Contains the pause element token that identifies the pause element that is no longer needed.
linkage
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Specifies how the Deallocate_Pause_Element service routine is to be invoked.
The following options are supported:
Variable
IEA_LINKAGE_SVC
IEA_LINKAGE_BRANCH
Value (hexadecimal) Meaning
0
1
The Deallocate_Pause_Element service routine will be invoked by an SVC linkage. This option can be used when in non-cross memory task mode, in any key, and in either problem state or supervisor state.
The Deallocate_Pause_Element service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in
SRB mode.
ABEND codes
None.
Return codes
When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.
Meaning and Action Return code in: Decimal
(Hex)
00 (00)
Equate symbol
IEA_SUCCESS
04 (04)
08 (08)
24 (18)
IEA_PE_TOKEN_BAD
IEA_PE_TOKEN_STALE
IEA_LOCK_HELD
Meaning:
Successful completion
Action:
None.
Meaning:
Program error. The specified pause element token is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET returned on Pause or Transfer.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. One or more locks other than the local lock are held. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 27. IEAVDPE2 — Deallocate_Pause_Element
227
IEAVDPE2 callable service
Return code in: Decimal
(Hex)
32 (20)
Equate symbol
IEA_PE_BAD_STATE
36 (24)
44 (2C)
Meaning and Action
IEA_INVALID_MODE
Meaning:
Program error. The pause element associated with the specified pause element token is invalid or has already been paused.
A paused PE must be released before it is deallocated. This return code also can indicate that the address space associated with the pause element is ending or has ended and that the system freed the pause element.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
IEA_UNSUPPORTED_MVS_RELEASE
Meaning:
Environmental error. The system release does not support this service. The system rejects the service call.
Action:
Run the program on a system that supports the service.
Meaning:
Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
64 (40)
84 (54)
IEA_PE_NOT_HOME
IEA_INVALID_LINKAGE
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The pause element token was for an unauthorized pause element allocated to another address space.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The linkage value specified is not valid. The system rejects the service call.
4095 (FFF) IEA_UNEXPECTED_ERROR
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
This service routine encountered an unexpected error. The system rejects this service request.
Action:
Contact IBM support.
228
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 28. IEAVPME2 — pause multiple elements service
Description
IEAVPME2 is a callable service that can be used to pause on one or more pause element tokens (PETs). When the specified number of pause elements (PEs) represented by PETs has been released, you receive control back with the following: v A list of PETs that you can use to pause on again v An indication of which PEs were released v
Their release codes.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
v Pproblem state and any PSW key.
v For LINKAGE=BRANCH: Task or SRB v For LINKAGE=SVC: Task v For LINKAGE=BRANCH: any PASN, any HASN, any
SASN v
For LINKAGE=SVC: PASN=SASN=HASN
31-bit addressing mode.
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine (IEACSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Key 1-15 or problem state callers must specify linkage as IEA_LINKAGE_SVC.
IEA_LINKAGE_SVC is limited to pausing upon no more than 1000 PETs.
Pause cannot be used by tasks that are higher in the task tree than the cross memory resource owning task (the EXEC PGM=xxx task).
© Copyright IBM Corp. 1988, 2017
229
IEAVPME2 callable service
Input register information
Before calling the Pause service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Note that register 13 is not required to contain any particular value. See the
workarea
parameter description.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
14
15
Unchanged
Used as work registers by the system
Return code.
Note that this service saves and restores full 64-bit GPRs.
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
There is a maximum number of PETs which can be processed very quickly by
IEAVPME2 without doing additional GETMAINs and FREEMAINs. That number is currently 16.
230
z/OS MVS Assembler Services Reference IAR-XCT
IEAVPME2 callable service
Syntax
Syntax
CALL IEAVPME2
Description
(return_code
,pause_element_token_list
,updated_pause_element_token_list
,release_code_list
,number_of_PETs_in_each_list
,number_of_PEs_to_release
,linkage
,workarea)
Link-edit your program with a linkage-assist routine (also called a stub) in
SYS1.CSSLIB unless you use one of the following techniques as an alternative to
CALL IEAVPME2:
1.
LOAD EP=IEAVPME2
Save the entry point address...
Put the saved entry point address into R15
CALL (15),(...)
2.
L
L
L
15,X’10’(0,0)
15,X’220’(15,0)
L
15,X’14’(15,0)
15,X’100’(15,0)
CALL (15),(...)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the highest return code from the Pause service (multiple return codes are possible when more than one PET has been specified – seerelease_code_list).
When the low-order bit of the return code is on, release_code_list contains the return codes for individual PETs rather than release codes.
Note that no pause has actually occurred if the return code is non-zero. In this situation, any PETs which have been released remain released.
,pause_element_token_list
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes times the number of PEs you want to pause on
A list of the PETs identifying the PEs you want to pause on.
Number_of_PETs_in_each_list specifies how many PETs are in the list.
,updated_pause_element_token_list
Returned parameter v
Type: Character string v Character Set: N/A v Length: 16 bytes times the number of PEs you want to pause on
Chapter 28. IEAVPME2 — pause multiple elements service
231
IEAVPME2 callable service
If return_code is 0, a list of the PETs returned by Pause Multiple Elements. Each entry corresponds to an entry in the pause_element_token_list. For each PE that was released, the system puts an updated PET into this list. For PEs that are not released, the entry contains the PET from the original
pause_element_token_list. These new PETs must be used in place of the PETs specified in pause_element_token_list or pause_element_token on future calls to the
Pause, Release, Transfer, or Deallocate_Pause_Element service. The first byte of each entry in release_code_list identifies which PEs were released.
Number_of_PETs_in_each_list specifies how many PETs are in the list.
If return_code is not 0, the PETs are not updated and this list is not returned.
If the paused workunit was released by the system (the release code is the
owner_termination_release_code specified on the IEAVAPE2 allocation), the PET returned in that slot will be 16 bytes of binary zeros, an invalid value.
,release_code_list
Returned parameter v Type: Fullword v Character Set: N/A v Length: 4 bytes times the number of PEs you want to pause on
Each entry corresponds to an entry in the pause_element_token_list.
If return_code is 0, the pause was successful and has been released. For each PE that was Released, the system puts X'01' into the first byte and the release code for that PET into the second through fourth bytes of the full-word entry for that PET. For PEs which are not released, the entry contains binary zeroes.
If return_code is 5, 9, D, 21, 35, 3D, or 41, a problem was found with at least one of the PETs specified in pause_element_token_list and the pause request did not complete. The individual return code for each PET is in the second through fourth bytes of the release_code_list entry for that PET. Each PET with a return code of 0 would have been paused on if all the other PETs in the list had received return codes of 0.
Note:
These return codes are the equivalent of return codes 4, 8, C, 20, 34, 3C, and 40 for IEAVPSE2 (Pause single), with the addition of a low-order bit to signify that the release_code_list contains individual PET return codes.
If return_code contains any other value, the pause request did not complete and
release_code_list does not contain any meaningful information.
,number_of_PETs_in_each_list
Supplied parameter
Number_of_PETs_in_each_list specifies how many entries are in release_code_list.
v Type: Integer v Character Set: N/A v Length: 4 bytes
This number specifies how many PETs you want to Pause on. This number also specifies the number of entries in pause_element_token_list,
updated_pause_element_token_list , and release_code_list. For SVC entry callers, the maximum number that can be specified is 1000.
,number_of_PEs_to_release
Supplied parameter
Number_of_PETs_in_each_list specifies how many entries are in release_code_list.
232
z/OS MVS Assembler Services Reference IAR-XCT
IEAVPME2 callable service
v Type: Integer v
Character Set: N/A v Length: 4 bytes
This number specifies how many PEs must be released before control is returned back to the issuer of Pause Multiple Elements. This number must be at least 1 and no more than number_of_PETs_in_each_list.
Note that if more PEs than this number were released before IEAVPME2 was issued (pre-released), the number of updated PETs in
updated_pause_element_token_list will be the actual number released.
,linkage
Supplied parameter v Type: Integer v
Character Set: N/A v Length: 4 bytes
Specifies how the Pause service routine is to be invoked. The following options are supported:
Table 20. Linkages
Variable
IEA_LINKAGE_SVC
IEA_LINKAGE_BRANCH
Value
0
1
Meaning
The Pause service routine will be invoked by an SVC linkage. This option can be used when in non-cross memory task mode, in any key, and in either problem state or supervisor state.
The Pause service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in SRB mode.
,workarea
Supplied parameter v Type: Character string v Character Set: N/A v Length: 216 bytes
Specifies a work area on a doubleword boundary in which the Pause service routine will save information about the caller including the caller's registers.
This can be the same area that R13 points to if the first 216 bytes of that area can be used as an F7SA savearea.
ABEND codes
None. However, note that you may receive a GETMAIN abend if this service is unable to obtain storage needed to process the PETs.
Return codes
When IEAVPME2 returns control to your program, if GPR 15 contains 0, 5, 9, D,
21, 35, 3D, or 41, release_code_list contains information about the status of each PET that was specified. If GPR 15 contains any other value, release_code_list does not contain any meaningful information.
Chapter 28. IEAVPME2 — pause multiple elements service
233
IEAVPME2 callable service
Return code in: Decimal
(Hex)
00 (0)
Equate Symbol
IEA_SUCCESS
05 (05)
09 (09)
13 (0D)
24 (18)
33 (21)
IEA_PE_TOKEN_BAD
IEA_PE_TOKEN_STALE
IEA_LOCK_HELD
IEA_PE_BAD_STATE
36 (24) IEA_UNSUPPORTED_MVS_
RELEASE
44 (2C)
IEA_DUPLICATE PAUSE
IEA_INVALID_MODE
Meaning and Action
Meaning:
Successful completion.
Action:
None.
Meaning:
Program error. The specified pause element token is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET returned on Pause or Transfer.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The work unit has already been paused using the specified pause element token. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The caller is holding one or more locks; no locks may be held. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The pause element associated with the pause element token specified in the call is not in a valid state. The system rejects the service call.
Action:
Check the calling program for a probable coding error, such as attempting to perform a pause or transfer using a pause element token that has already been used to pause or transfer by another unit of work.
Correct the program and rerun it.
Meaning:
Environmental error. The system release does not support this service. The system rejects the service call.
Action:
Run the program on a system that supports the service.
Meaning:
Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
234
z/OS MVS Assembler Services Reference IAR-XCT
IEAVPME2 callable service
Return code in: Decimal
(Hex)
53 (35)
Equate Symbol
IEA_ALREADY_SUSPENDED
61 (3D)
65 (41)
76 (4C)
80 (50)
84 (54)
104(68)
108(6C)
Meaning and Action
IEA_AUTH_LEVEL_MISMATCH
IEA_PE_NOT_HOME
IEA_ABENDED_47B
IEA_INSUSPEND_EXIT
IEA_INVALID_LINKAGE
IEA_INVALID_NUMBER_OF_PETS
IEA_INVALID_NUMBER_TO_
RELEASE
Meaning:
The pause element was already paused.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The caller was in problem state or key 8, but the pause element token was allocated with
pause_element_auth_level=IEA_AUTHORIZED. The system rejects the service call.
Action:
Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning:
Program error. The pause element token was for a pause element allocated with
pause_element_auth_level=IEA_AUTHORIZED to another address space.
Action:
Check the calling program for a probable coding error. Correct eht program and rerun it.
Meaning:
After an SRB received abend 47B, it invoked IEAVPSE. It is not valid to invoke
IEAVPME2 after receiving abend 47B.
Action:
Update the calling program to not invoke IEAVPME2 after abend 47B.
Meaning:
The suspend exit specified on
SUSPEND with SPTOKEN of an SRB invoked
IEAVPME2. It is not valid to invoke
IEAVPME2 from a suspend exit.
Action:
Update the calling program to not invoke IEAVPME2 from a suspend exit.
Meaning:
Program error. The linkage value specified is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The number of PETs specified for Pause Multiple was 0 or for SVC entry users more than 1000. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The number of PEs to release is 0 or greater than the number of
PETs specified for Pause Multiple. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 28. IEAVPME2 — pause multiple elements service
235
IEAVPME2 callable service
Return code in: Decimal
(Hex)
4094(FFE)
Equate Symbol
IEA_ERROR_PETS_INVALIDATED
4095(FFF) IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning:
Pause processing has encountered an error and cannot complete the Pause request. This input PETs have been invalidated. This return code is only issued for
Pause Multiple requests.
Action:
Do not return the PETs to the system using the Deallocate Pause Elements services.
Note that new PEs must be obtained before attempting to pause again.
Meaning:
This service routine encountered an unexpected error. The system rejects this service request.
Action:
Contact IBM support.
236
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 29. IEAVPSE — Pause service
Description
Call Pause to make the current task non-dispatchable. Once you pause a task, it remains non-dispatchable until a Release service specifying the same PET is called.
That is, the program issuing the Pause does not receive control back until after the
Release occurs.
If a Release service specifying the same PET is called before Pause, the system returns control immediately to the calling program, and the task is not paused.
When you use Pause, it returns an updated PET; you use this updated PET to either deallocate or reuse the Process Engine.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and any PSW key.
Task or SRB
PASN=HASN=SASN
31-bit addressing mode.
Primary mode.
Enabled for I/O and external interrupts
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine (IEACSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
When the calling program is running auth_level=IEA_UNAUTHORIZED, the caller must be in task mode and can only pause another task in its home address space.
All pause element tokens (PETs) used when auth_level=IEA_UNAUTHORIZED must have been obtained using an authorization level of IEA_UNAUTHORIZED.
Input register information
Before calling the Pause service, the caller must ensure that the following general-purpose registers (GPRs) contain the specified information:
Register
Contents
© Copyright IBM Corp. 1988, 2017
237
IEAVPSE callable service
Syntax
1
13
Address of the parameter address list.
Address of a 72-byte register save area.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
Used as work registers by the system.
Unchanged
14
15
Used as work registers by the system.
Return code.
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system.
Unchanged
14-15
Used as a work register by the system.
Performance implications
None.
Syntax
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Description
CALL IEAVPSE
,(return_code
,auth_level
,pause_element_token
,updated_pause_element_token
,release_code)
Parameters
The parameters are explained as follows:
return_code
Returned parameter: v Type: Integer v Character Set: N/A v
Length: 4 bytes
Contains the return code from the Pause service.
238
z/OS MVS Assembler Services Reference IAR-XCT
IEAVPSE callable service
,auth_level
Supplied parameter: v
Type: Integer v Character Set: N/A v Length: 4 bytes
Indicates the maximum level that the specified pause element was allocated with. IEAASM and IEAC define constant IEA_UNAUTHORIZED, which the calling program can use. The following levels are supported:
Variable
IEA_UNAUTHORIZED
Value
(HEX)
0
Meaning
The pause element being paused must have been allocated with auth_level=IEA_UNAUTHORIZED.
,pause_element_token
Supplied parameter: v Type: Character string v Character Set: N/A v Length: 16 bytes
A pause element token that identifies the pause element being used to pause the current task. You obtain the PET from the Allocate_Pause_Element service.
Once you use a PET in a call to the Pause service, you cannot reuse the PET on a second call to Pause or on a call to Transfer. The Pause service returns a new
PET in updated_pause_element_token. The new PET now identifies the pause element used to Pause the task; use the new PET the next time you make a
Pause request using the same Pause element.
,updated_pause_element_token
Returned parameter: v Type: Character string v
Character Set: N/A v Length: 16 bytes
A new pause element token that identifies the pause element that is originally identified by the PET specified in pause_element_token, which cannot be reused after a successful call to Pause.
,release_code
Returned parameter: v Type: Character string v Character Set: N/A v Length: 3 bytes
The release code, which is specified by the issuer of the Release service. A
Release that specified this code released the task from the paused condition.
ABEND codes
Abend Code
AC7
Reason Code
001A0001
Description
This is an internal error. Contact IBM support.
Chapter 29. IEAVPSE — Pause service
239
IEAVPSE callable service
Return codes
When the service returns control to your program, GPR 15 contains one of the following return codes:
Meaning and Action Return code in:
Decimal (Hex)
Equate symbol
00 (00)
IEA_SUCCESS
04 (04)
08 (08)
IEA_PE_TOKEN_STALE
12 (0C)
IEA_DUPLICATE_PAUSE
24 (18)
IEA_LOCK_HELD
32 (20)
IEA_PE_BAD_STATE
36 (24)
IEA_UNSUPPORTED_MVS_RELEASE
40 (28)
IEA_INVALID_AUTHCODE
44 (2C)
IEA_INVALID_MODE
Meaning:
Successful completion.
Action:
None
Meaning:
Program error. The specified pause element token is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The specified pause element token is stale; that is, it was valid but has been used on the Pause or
Transfer service. This service requires the updated PET be returned on Pause or Transfer.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The work unit has already been paused using the specified pause element token. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The pause element associated with the pause element token specified in the call is not in a valid state. The system rejects the service call.
Action:
Check the calling program for a probable coding error, such as attempting to perform a Pause or
Transfer using a pause element token that has already been used to Pause or Transfer by another unit of work. Correct the program and rerun it.
Meaning:
Environmental error. The system release does not support this service. The system rejects the service call.
Action:
Run the program on a system that supports the service.
Meaning:
Program error. The auth_level value specified in the call is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
240
z/OS MVS Assembler Services Reference IAR-XCT
Return code in:
Decimal (Hex)
Equate symbol
52 (34)
IEA_ALREADY_SUSPENDED
60 (3C)
IEA_AUTH_TOKEN
64 (40)
IEA_PE_NOT_HOME
4095 (FFF)
IEA_UNEXPECTED_ERROR
IEAVPSE callable service
Meaning and Action
Meaning:
The pause element was already paused.
Action:
Check the calling program for a probable coding error and correct the program and rerun it.
Meaning:
Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was allocated with auth_level=AUTHORIZED.
The system rejects the service call. Rejects the service call.
Action:
Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning:
Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was for a pause element allocated to another address.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
This service routine encountered an unexpected error. The system rejects this service request.
Action:
Contact IBM support.
Chapter 29. IEAVPSE — Pause service
241
IEAVPSE callable service
242
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 30. IEAVPSE2 — Pause service
Description
Call Pause to make the current task or SRB nondispatchable. When you pause a task or SRB, it remains nondispatchable until a Release or Transfer specifying the same PET is called. That is, the program issuing the Pause does not receive control back until after the Release or Transfer occurs. Then, the returned release_code contains a value supplied by the associated Release or Transfer request.
If a Release service specifying the same PET is called before Pause, the system returns control immediately to the calling program, and the task or SRB is not paused.
When you use Pause, it returns an updated PET; you use this updated PET to either deallocate or reuse the Process Engine (PE).
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
31-bit addressing mode.
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEACSS from SYS1.CSSLIB) or have the calling program LOAD and then CALL the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED can be used only by callers in task mode and can be released only from a task in their home address space.
Key 1-15 or problem state callers must specify linkage as IEA_LINKAGE_SVC.
Pause cannot be used by tasks that are higher in the task tree than the cross memory resource owning task (the top, or first, job step task in the address space).
© Copyright IBM Corp. 1988, 2017
243
IEAVPSE2 callable service
Syntax
Input register information
Before calling the Pause service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Address of a 72-byte register save area.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
14
15
Unchanged
Used as work registers by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Description
CALL IEAVPSE2
,(return_code
,pause_element_token
,updated_pause_element_token
,release_code
,linkage)
Parameters
The parameters are explained as follows:
return_code
Returned parameter
244
z/OS MVS Assembler Services Reference IAR-XCT
IEAVPSE2 callable service
v Type: Integer v
Character Set: N/A v Length: 4 bytes
Contains the return code from the Pause service.
,pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
A pause element token that identifies the pause element being used to pause the current task or SRB. You obtain the PET from the Allocate_Pause_Element service.
When you use a PET in a call to the Pause service, you cannot reuse the PET on a second call to Pause or on a call to Transfer. The Pause service returns a new PET in updated_pause_element_token. The new PET now identifies the pause element used to pause the task or SRB; use the new PET the next time you make a Pause request using the same Pause element.
,updated_pause_element_token
Returned parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
A new pause element token that identifies the pause element originally identified by the PET specified in pause_element_token. This new PET must be used in place of the PET specified in pause_element_token on future calls to the Pause, Release, Transfer, or Deallocate_Pause_Element service. If the paused workunit was released by the system (the release code is the owner_termination_release_code specified on the IEAVAPE1 allocation), the
PET returned will be 16 bytes of binary zeros, an invalid value.
,release_code
Returned parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
The release code, specified by the issuer of the Release service. A Release that specified this code released the task or SRB from its paused condition.
linkage
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Specifies how the Pause service routine is to be invoked. The following options are supported:
Chapter 30. IEAVPSE2 — Pause service
245
IEAVPSE2 callable service
Variable
IEA_LINKAGE_SVC
IEA_LINKAGE_BRANCH
Value (hexadecimal) Meaning
0
1
The Pause service routine will be invoked by an SVC linkage. This option can be used when in non-cross memory task mode, in any key, and either problem state or supervisor state.
The Pause service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in SRB mode.
ABEND codes
Abend Code
AC7
Reason Code
001A0001
Description
This is an internal error.
Contact IBM support.
Return code in:
Decimal (Hex)
00 (00)
Return codes
When the service returns control to your program, GPR 15 contains one of the following return codes:
Equate symbol Meaning and Action
IEA_SUCCESS
04 (04)
08 (08)
12 (0C)
24 (18)
32 (20)
IEA_PE_TOKEN_BAD
IEA_PE_TOKEN_STALE
IEA_DUPLICATE_PAUSE
IEA_LOCK_HELD
IEA_PE_BAD_STATE
Meaning:
Successful completion.
Action:
None
Meaning:
Program error. The specified pause element token is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET returned on
Pause or Transfer.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The work unit has already been paused using the specified pause element token. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The pause element associated with the pause element token specified in the call is not in a valid state. The system rejects the service call.
Action
: Check the calling program for a probable coding error, such as attempting to perform a Pause or Transfer using a pause element token that has already been used to
Pause or Transfer by another unit of work. Correct the program and rerun it.
246
z/OS MVS Assembler Services Reference IAR-XCT
Return code in:
Decimal (Hex)
36 (24)
Equate symbol
IEA_UNSUPPORTED_MVS_RELEASE
44 (2C) IEA_INVALID_MODE
52 (34)
60 (3C)
IEA_ALREADY_SUSPENDED
IEA_AUTH_TOKEN
64 (40) IEA_PE_NOT_HOME
76 (4C) IEA_ABENDED_47B
80 (50) IEA_IN_SUSPEND_EXIT
84 (54) IEA_INVALID_LINKAGE
4095 (FFF) IEA_UNEXPECTED_ERROR
IEAVPSE2 callable service
Meaning and Action
Meaning:
Environmental error. The system release does not support this service. The system rejects the service call.
Action:
Run the program on a system that supports the service.
Meaning:
Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The pause element was already paused.
Action:
Check the calling program for a probable coding error and correct the program and rerun it.
Meaning:
Program error. The caller was in Problem state or key 8, but the pause element token was allocated with pause_element_auth_level=IEA_AUTHORIZED. The system rejects the service call.
Action:
Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning:
Program error. The pause element token was for a pause element allocated with pause_element_auth_level=IEA_UNAUTHORIZED to another address space.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
After an SRB received ABEND 47B, it invoked
IEAVPSE2. It is not valid to invoke IEAVPSE2 after receiving ABEND 47B.
Action:
Update the calling program to not invoke
IEAVPSE2 after ABEND 47B.
Meaning:
The suspend exit specified on SUSPEND with
SPTOKEN of an SRB invoked IEAVPSE2. It is not valid to invoke IEAVPSE2 from a suspend exit.
Action:
Update the calling program to not invoke
IEAVPSE2 from a suspend exit.
Meaning:
Program error. The linkage value specified is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
This service routine encountered an unexpected error. The system rejects this service request.
Action:
Contact IBM support.
Chapter 30. IEAVPSE2 — Pause service
247
IEAVPSE2 callable service
248
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 31. IEAVRLS — Release
Description
Call Release to remove a task that has been paused, or to keep a task from being paused. Although a pause element can be used multiple times to pause a task, a pause element token can be used to successfully pause and release a task only once. Each time a pause element is used, the system generates a new PET to identify the pause element. The system returns the new updated PET on calls to the Pause and Transfer services.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
31-bit addressing mode.
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine (IEACSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
When the calling program specifies auth_level=IEA_UNAUTHORIZED, the caller must be in task mode and can only release another task in its home address space.
All pause element tokens (PETs) used when auth_level=IEA_UNAUTHORIZED must have been obtained using an authorization level of IEA_UNAUTHORIZED.
Input register information
Before calling the Release service, the caller must ensure that the following general purpose (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Address of a 72-byte register save area.
© Copyright IBM Corp. 1988, 2017
249
IEAVRLS callable service
Syntax
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Description
CALL IEAVRLS
,(return_code
,auth_level
,target_du_pause_element_token
,target_du_release_code)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return from the Release service.
,auth_level
Supplied Parameter v Type: Integer v Character Set: N/A
250
z/OS MVS Assembler Services Reference IAR-XCT
IEAVRLS callable service
v Length: 4 bytes
Indicates the maximum authorization level that the specified pause element was allocated with. IEAASM and IEAC define constants
IEA_UNAUTHORIZED and IEA_AUTHORIZED, which the calling program can use. The following levels are supported:
Variable
IEA_UNAUTHORIZED
Value
(HEX)
0
Meaning
The pause element being released must have been allocated with auth_level=IEA_UNAUTHORIZED.
,target_du_pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains the pause element token that identifies the pause element used to pause the task. If the PET identifies a pause element that has not been paused
(that is, the task has not been paused), the task will not be paused. However, the value specified in target_du_release_code will be returned to the caller of
Pause.
,target_du_release_code
Supplied parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
Contains the release code returned to the caller of Pause or Transfer service that used (or will use) the same PET to pause a task. If your program is not using this code for communication, set this field to zero.
ABEND codes
None.
Return codes
When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.
Meaning and Action Return code in:
Decimal (Hex)
Equate symbol
00 (00)
IEA_SUCCESS
04 (04)
IEA_PE_TOKEN_BAD
Meaning
: Successful completion.
Action
: None.
Meaning
: The specified pause element token is not valid.
The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 31. IEAVRLS — Release
251
IEAVRLS callable service
Return code in:
Decimal (Hex)
Equate symbol
08 (08)
IEA_PE_TOKEN_STALE
16 (10)
IEA_SLEEP_DISRUPTED
20 (14)
IEA_SPACE_TERMINATING
24 (18)
IEA_LOCK_HELD
32 (20)
IEA_PE_BAD_STATE
36 (24)
IEA_UNSUPPORTED_MVS_RELEASE
40 (28)
IEA_INVALID_AUTHCODE
44 (2C)
IEA_INVALID_MODE
60 (3C)
IEA_AUTH_TOKEN
64 (40)
IEA_PE_NOT_HOME
4095 (FFF)
IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET be returned on Pause or Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: RTM has terminated the task; no release is necessary.
Action
: None
Meaning
: The address space that contains the task that is terminating; no release is necessary.
Action
: None
Meaning
: Program error. The caller is holding one o r more locks; no locks must be held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The pause element associated with the pause element token specified is invalid or has already been prereleased.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The auth_level value specified in the call is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was allocated with auth_level=AUTHORIZED. The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was for a pause element allocated to another address.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action
: Contact IBM support.
252
z/OS MVS Assembler Services Reference IAR-XCT
IEAVRLS callable service
Chapter 31. IEAVRLS — Release
253
IEAVRLS callable service
254
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 32. IEAVRLS2 — Release
Description
Call Release to remove a task or SRB that has been paused, or to keep a task or
SRB from being paused.
Although a pause element can be used multiple times to pause a task or SRB, a pause element token can be used to successfully pause and release a task or SRB only once. Each time a pause element is used, the system generates a new PET to identify the pause element. The system returns the new updated PET on calls to the Pause and Transfer services.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
31-bit addressing mode.
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEACSS from SYS1.CSSLIB) or have the calling program LOAD and then CALL the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Key 1-15 or problem state callers must specify linkage as IEA_LINKAGE_SVC.
Release cannot be used by tasks that are higher in the task tree than the cross memory resource owning task (the top, or first, job step task in the address space).
Input register information
Before calling the Release service, the caller must ensure that the following general purpose (GPRs) contain the specified information:
© Copyright IBM Corp. 1988, 2017
255
IEAVRLS2 callable service
Syntax
Register
Contents
1
13
Address of the parameter address list.
Address of a 72-byte register save area.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
14
15
Used as work registers by the system
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Description
CALL IEAVRLS2
,(return_code
,,target_du_pause_element_token
,target_du_release_code
,linkage)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v
Character Set: N/A v Length: 4 bytes
256
z/OS MVS Assembler Services Reference IAR-XCT
IEAVRLS2 callable service
Contains the return from the Release service.
,target_du_pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains the pause element token that identifies the pause element used to pause a task or SRB. You obtain the PET from the Allocate_Pause_Element service.
When you use a PET in a call to the Pause service, you cannot reuse the PET on a second call to Pause or on a call to Transfer. The Pause service returns a new PET in updated_pause_element_token. The new PET now identifies the pause element used to pause the task or SRB; use the new PET the next time you make a Pause request using the same Pause element.
,target_du_release_code
Supplied parameter v Type: Character string v Character Set: N/A v Length: 4 bytes
Contains the release code returned to the caller of Pause or Transfer service that used (or will use) the same PET to pause a task or SRB. If your program is not using this code for communication, set this field to zero.
linkage
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Specifies how the Release service routine is to be invoked. The following options are supported:
Variable
IEA_LINKAGE_SVC
IEA_LINKAGE_BRANCH
Value (hexadecimal) Meaning
0
1
The Release service routine will be invoked by an SVC linkage. This option can be used when in non-cross memory task mode, in any key, and either problem state or supervisor state.
The Release service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in SRB mode.
ABEND codes
None.
Return codes
When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.
Chapter 32. IEAVRLS2 — Release
257
IEAVRLS2 callable service
Return code:
Decimal (Hex)
00 (00)
Equate symbol
IEA_SUCCESS
04 (04) IEA_PE_TOKEN_BAD
08 (08) IEA_PE_TOKEN_STALE
16 (10)
20 (14)
24 (18)
32 (20)
IEA_SLEEP_DISRUPTED
IEA_SPACE_TERMINATING
IEA_LOCK_HELD
36 (24) IEA_UNSUPPORTED_MVS_RELEASE
44 (2C) IEA_INVALID_MODE
60 (3C)
64 (40)
IEA_PE_BAD_STATE
IEA_AUTH_TOKEN
IEA_PE_NOT_HOME
Meaning and Action
Meaning:
Successful completion.
Action:
None.
Meaning:
The specified pause element token is not valid.
The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET returned on
Pause or Transfer.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
RTM has terminated the task or SRB; no release is necessary.
Action:
None
Meaning:
The address space that contains the task or SRB is terminating; no release is necessary.
Action:
None
Meaning:
Program error. The caller is holding one or more locks; other than the local lock, CMS, or CPU lock, no locks may be held. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The pause element associated with the pause element token specified is invalid or has already been prereleased.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Environmental error. The system release does not support this service. The system rejects the service call.
Action:
Run the program on a system that supports the service.
Meaning:
Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The caller was in Problem state or key 8, but the pause element token was allocated with pause_element_auth_level=IEA_AUTHORIZED. The system rejects the service call.
Action:
Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning:
Program error. The pause element token was for a pause element allocated with pause_element_auth_level=IEA_UNAUTHORIZED to another address space.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
258
z/OS MVS Assembler Services Reference IAR-XCT
Return code:
Decimal (Hex)
84 (54)
Equate symbol
IEA_INVALID_LINKAGE
4095 (FFF) IEA_UNEXPECTED_ERROR
IEAVRLS2 callable service
Meaning and Action
Meaning:
Program error. The linkage value specified is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
This service routine encountered an unexpected error. The system rejects this service request.
Action:
Contact IBM support.
Chapter 32. IEAVRLS2 — Release
259
IEAVRLS2 callable service
260
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 33. IEAVRPI — Retrieve_Pause_Element_Information service
Description
Call Retrieve_Pause_Element_Information to get information about a pause element. The information returned includes: v Its authorization level v The address space that currently owns it v Its current state (Reset, Prereleased, Paused, or Released) v If its state is Prereleased or Released, its Release Code
An authorized program can use Retrieve_Pause_Element_Information to test the validity of a pause element passed by an unauthorized program. The authorized program can do this to ensure that it does not perform any operation, such as releasing the pause element, unless the unauthorized program is also able to perform the same operation.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
31-bit addressing mode
Primary mode
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine (IEACSS from SYS1.CSSLIB) or have the calling program LOAD and then CALL the service.
The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
None.
Input register information
Before calling the Retrieve_Pause_Element_Information service, the caller does not need to place any information into any register, unless using it in register notation for the parameters, or using it as a base register.
© Copyright IBM Corp. 1988, 2017
261
IEAVRPI callable service
Syntax
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Description
CALL IEAVRPI
,(return_code
,auth_level
,pause_element_token
,authorization
,owner
,state
,release_code)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v
Length: 4 bytes
Contains the return code from the Retrieve_Pause_Element_Information service.
262
z/OS MVS Assembler Services Reference IAR-XCT
IEAVRPI callable service
,auth_level
Supplied parameter v
Type: Integer v Character Set: N/A v Length: 4 bytes
Indicates the caller's authorization level. The following levels are supported:
IEAASM and IEAC define constants IEA_UNAUTHORIZED and
IEA_AUTHORIZED, which can be used by the calling program.
Variable
IEA_UNAUTHORIZED
IEA_AUTHORIZED
Value (hexadecimal) Meaning
0
1
The caller is not key 0 and supervisor state.
The caller is both key 0 and supervisor state.
,pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
A pause element token that identifies the pause element for which information will be returned. You obtain the PET from the Allocate_Pause_Element service.
,authorization
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
The authorization level of the creator of the pause element specified by the input PET.
One of the following values:
IEAASM and IEAC defined constants Value (hexadecimal) Meaning
IEA_UNAUTHORIZED 0 The caller is not key 0 and supervisor state.
IEA_AUTHORIZED 1
IEA_UNAUTHORIZED +
IEA_CHECKPOINTOK
IEA_AUTHORIZED +
IEA_CHECKPOINTOK
2
3
The caller is not key 0 and supervisor state.
Unauthorized PET that can tolerate the pause elements' not being restored upon a restart after a checkpoint.
Authorized PET that can tolerate the pause elements' not being restored upon a restart after a checkpoint.
,owner
Returned parameter v
Type: Character string v Character Set: N/A v Length: 8 bytes
The Stoken of the address space that currently owns the pause element specified by the input PET.
Chapter 33. IEAVRPI — Retrieve_Pause_Element_Information service
263
IEAVRPI callable service
,state
Returned parameter v
Type: Integer v Character Set: N/A v Length: 4 bytes
The state of the pause element specified by the input PET.
Note:
The value returned is the state at the time the service obtained it. The state may have changed after it was obtained.
Meaning State Constant
Hexadecimal
(Decimal)
IEAV_PET_PRERELEASED
1
(1)
IEAV_PET_RESET
2
(2)
The PE was released before any task or SRB was suspended on it, and no task or SRB has attempted to pause it.
IEAV_PET_RELEASED
40
(64)
IEAV_PET_PAUSED
80
(128)
The PE is not being used to make any task or SRB nondispatchable. If the PE is used in an attempt to pause the current task or SRB, the task or SRB will be made nondispatchable.
The task RB or SRB is currently dispatchable, but control has not been returned to the task or SRB following a call to the Pause or Transfer service.
A call to the Release or Transfer service has released the task or SRB. In either case, control has not been returned to the caller of the Pause or Transfer service. The system has not transitioned the PE into the RESET state.
A task RB or SRB is currently nondispatchable. Its dispatchability is controlled by the PE.
,release_code
Returned parameter v Type: Character string v Character Set: N/A v
Length: 3 bytes
The release code, specified by the issuer of the Release service. A Release that specified this code released the task or SRB from its paused condition.
Note:
The returned value is random if the state parameter is not
IEAV_PET_RELEASED or IEAV_PET_PRERELEASED.
ABEND codes
None.
Return codes
When the service returns control to your program, GPR 15 contains one of the following return codes:
264
z/OS MVS Assembler Services Reference IAR-XCT
IEAVRPI callable service
Return code in: Decimal
(Hex)
00 (00)
Equate symbol
IEA_SUCCESS
04 (04)
08 (08)
24 (18)
36 (24)
44 (2C)
60 (3C)
64 (40)
Meaning and Action
IEA_PE_TOKEN_BAD
IEA_PE_TOKEN_STALE
IEA_LOCK_HELD
IEA_UNSUPPORTED_MVS_RELEASE
IEA_INVALID_MODE
IEA_AUTH_TOKEN
IEA_PE_NOT_HOME
Meaning
: Successful completion.
Action
: None
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated
PET returned on Pause or Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The caller specified an unauthorized auth_level type, but a pause element token allocated with an authorized auth_level type was encountered. The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning
: Program error. The caller specified an unauthorized auth_level type, but a pause element token for a pause element allocated to another address space was specified.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 33. IEAVRPI — Retrieve_Pause_Element_Information service
265
IEAVRPI callable service
Return code in: Decimal
(Hex)
4095 (FFF)
Equate symbol
IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action
: Contact IBM support.
266
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 34. IEAVRPI2 — Retrieve_Pause_Element_Information service
Description
Call Retrieve_Pause_Element_Information to get information about a pause element. The information returned includes: v Its authorization level v Its current state (Reset, Prereleased, Paused, or Released) v If its state is Prereleased or Released, its Release Code v The stoken of the owner of the pause element (See IEAVAPE —
Allocate_Pause_Element for details of ownership).
v The stoken of the home address space of the task or SRB which is paused by the pause element.
An authorized program can use Retrieve_Pause_Element_Information to test the validity of a pause element passed by an unauthorized program. The authorized program may do this to ensure that it does not perform any operation, such as releasing the pause element, unless the unauthorized program is also able to perform the same operation.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
31-bit addressing mode.
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine (IEACSS from SYS1.CSSLIB) or have the calling program LOAD and then CALL the service.
The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Key 2-15 or problem state callers must specify linkage as IEA_LINKAGE_SVC.
© Copyright IBM Corp. 1988, 2017
267
IEAVRPI2 callable service
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Input register information
Before calling the Retrieve_Pause_Element_Information service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list
Address of a 72-byte register save area
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
268
z/OS MVS Assembler Services Reference IAR-XCT
IEAVRPI2 callable service
Syntax
Syntax
CALL IEAVRPI2
Description
,(return_code
,pause_element_auth_level
,pause_element_token
,linkage
,owner_stoken
,current_stoken
,state
,release_code)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return code from the Retrieve_Pause_Element_Information service.
,pause_element_auth_level
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Indicates the authorization level with which the pause element specified by the input PET was allocated. The following levels are supported:
Variable Value
(hexadecimal)
IEA_PET_UNAUTHORIZED 0
Meaning
IEA__PET_AUTHORIZED 1
The pause element was allocated with pause_element_auth_level=IEA_UNAUTHORIZED.
The pause element was allocated with pause_element_auth_level=IEA_AUTHORIZED.
,pause_element_token
Supplied parameter v Type: Character string v
Character Set: N/A v Length: 16 bytes
A pause element token that identifies the pause element for which information will be returned. You obtain the PET from the Allocate_Pause_Element service.
linkage
Supplied parameter v Type: Integer v Character Set: N/A
Chapter 34. IEAVRPI2 — Retrieve_Pause_Element_Information service
269
IEAVRPI2 callable service
v Length: 4 bytes
Specifies how the Retrieve_Pause_Element_Information service routine is to be invoked. The following options are supported:
Variable
IEA_LINKAGE_SVC
IEA_LINKAGE_BRANCH
Value (hexadecimal) Meaning
0 The
Retrieve_Pause_Element_Information service routine will be invoked by an
SVC linkage. This option can be used when in non-cross memory task mode, in any key, and in either problem state or supervisor state.
1 The
Retrieve_Pause_Element_Information service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state.
This option must be selected when in
SRB mode.
,owner_stoken
Returned parameter v
Type: Character string v Character Set: N/A v Length: 8 bytes
Specifies the stoken of the address space that currently owns the pause element specified by the input PET. The owner of a PE allocated by IEAVAPE2 is static and specified on the IAVEAPE2 call. The owner of a PE allocated by IEAVAPE is dynamic. See IEAVAPE — Allocate_Pause_Element for details.
,current_stoken
Returned parameter v Type: Character string v Character Set: N/A v
Length: 8 bytes
If the value returned in state is IEA_PET_PAUSED, The stoken of the home address space of the task or SRB which is paused by the specified pause element. If the value in state is not IEA_PET_PAUSED, the information returned in this parameter is undefined.
,state
Returned parameter v Type: Integer v Character Set: N/A v
Length: 4 bytes
The state of the pause element specified by the input PET.
Note:
The value returned is the state at the time the service obtained it. The state may have changed after it was obtained.
270
z/OS MVS Assembler Services Reference IAR-XCT
IEAVRPI2 callable service
State Constant
Hexadecimal
(Decimal)
IEAV_PET_PRERELEASED
1
(1)
IEAV_PET_RESET
2
(2)
IEAV_PET_RELEASED
40
(64)
Meaning
IEAV_PET_PAUSED
80
(128)
The PE was released before any task or SRB was suspended on it, and no task or SRB has attempted to pause it.
The PE is not being used to make any task or SRB nondispatchable. If the PE is used in an attempt to pause the current task or SRB, the task or SRB will be made nondispatchable.
The task RB or SRB is currently dispatchable, but control has not been returned to the task or SRB following a call to the Pause or Transfer service.
A call to the Release or Transfer service has released the task or SRB. In either case, control has not been returned to the caller of the Pause or Transfer service. The system has not transitioned the PE into the RESET state.
A task RB or SRB is currently nondispatchable. Its dispatchability is controlled by the PE.
,release_code
Returned parameter v
Type: Character string v Character Set: N/A v Length: 3 bytes
The release code, specified by the issuer of the Release service. A Release that specified this code released the task or SRB from its paused condition.
Note:
The returned value is random if the state parameter is not
IEAV_PET_RELEASED or IEAV_PET_PRERELEASED.
ABEND codes
None.
Return code:
Decimal (Hex)
00 (00)
Return codes
When the service returns control to your program, GPR 15 contains one of the following return codes:
Equate symbol Meaning and Action
IEA_SUCCESS
04 (04) IEA_PE_TOKEN_BAD
Meaning
: Successful completion.
Action
: None
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 34. IEAVRPI2 — Retrieve_Pause_Element_Information service
271
IEAVRPI2 callable service
Return code:
Decimal (Hex)
08 (08)
Equate symbol
IEA_PE_TOKEN_STALE
24 (18) IEA_LOCK_HELD
36 (24) IEA_UNSUPPORTED_MVS_RELEASE
40 (28) IEA_INVALID_AUTHCODE
44 (2C)
60 (3C)
84 (54)
4095 (FFF)
IEA_INVALID_MODE
IEA_AUTH_LEVEL_MISMATCH
IEA_INVALID_LINKAGE
IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET returned on
Pause or Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning:
Program error. The pause_element_auth_level value specified in the call is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The caller was in Problem state or key 8, but the pause element token was allocated with pause_element_auth_level=IEA_AUTHORIZED. The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning
: Program error. The linkage value specified is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action
: Contact IBM support.
272
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 35. IEAVTPE — Test_Pause_Element service
Description
Call Test_Pause_Element to test a pause element and determine its state. If its state is Prereleased or Released, the pause element's release code will also be returned.
To ensure minimal overhead when you use the service, Test_Pause_Element establishes no recovery. You are responsible for supplying any needed recovery to handle errors that occur due to invalid input pause element Tokens or call state errors.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
31-bit addressing mode.
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine (IEACSS from SYS1.CSSLIB) or have the calling program LOAD and then CALL the service.
The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
None.
Input register information
Before calling the Test_Pause_Element service, the caller does not have to place any information into any register, unless using it in register notation for the parameters, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
Used as work registers by the system
© Copyright IBM Corp. 1988, 2017
273
IEAVTPE callable service
Syntax
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Description
CALL IEAVTPE
,(return_code
,pause_element_token
,state
,release_code)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v
Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return code from the Test_Pause_Element service.
,pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
A pause element token that identifies the pause element for which information is to be returned. You obtain the PET from the Allocate_Pause_Element service.
,state
Returned parameter v Type: Integer
274
z/OS MVS Assembler Services Reference IAR-XCT
IEAVTPE callable service
v Character Set: N/A v
Length: 4 bytes
The state of the pause element specified by the input PET.
Note:
The value returned is the state at the time the service obtained it. The state may have changed after it was obtained.
Meaning State Constant
Hexadecimal
(Decimal)
IEAV_PET_PRERELEASED
1
(1)
IEAV_PET_RESET
2
(2)
The PE was released before any task or SRB was suspended on it, and no task or SRB has attempted to pause it.
IEAV_PET_RELEASED
40
(64)
IEAV_PET_PAUSED
80
(128)
The PE is not being used to make any task or SRB nondispatchable. If the PE is used in an attempt to pause the current task or SRB, the task or SRB will be made nondispatchable.
The task RB or SRB is currently dispatchable, but control has not been returned to the task or SRB following a call to the Pause or Transfer service.
A call to the Release or Transfer service has released the task or SRB. In either case, control has not been returned to the caller of the Pause or Transfer service. The system has not transitioned the PE into the RESET state.
A task RB or SRB is currently nondispatchable. Its dispatchability is controlled by the PE.
,release_code
Returned parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
The release code, specified by the issuer of the Release service. A Release that specified this code released the task or SRB from its paused condition.
Note:
The returned value is random if the state parameter is not
IEAV_PET_RELEASED or IEAV_PET_PRERELEASED.
ABEND codes
None.
Return codes
When the service returns control to your program, GPR 15 contains one of the following return codes:
Equate symbol Meaning and Action Return code in: Decimal
(Hex)
00 (00) IEA_SUCCESS
Meaning
: Successful completion.
Action
: None
Chapter 35. IEAVTPE — Test_Pause_Element service
275
IEAVTPE callable service
Return code in: Decimal
(Hex)
04 (04)
Equate symbol
IEA_PE_TOKEN_BAD
08 (08) IEA_PE_TOKEN_STALE
Meaning and Action
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated
PET returned on Pause or Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
276
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 36. IEAVXFR — Transfer service
Description
Call the Transfer service to release a paused task, and, when possible, give it immediate control. This service can also, optionally, pause the task under which the Transfer request is made. If the caller does not request that its task be paused, the caller's task remains dispatchable.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
31-bit addressing mode.
Primary mode.
Enabled for I/O and external interrupts
No Locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine (IEACSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
When the calling program specifies auth_level=IEA_UNAUTHORIZED, the caller must be in task mode and can only transfer to another task in its home address space. All pause element tokens (PETs) used when auth_level=IEA_UNAUTHORIZED must have been obtained using an authorization level of IEA_UNAUTHORIZED.
Input register information
Before calling the Transfer service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Address of a 72-byte register save area.
© Copyright IBM Corp. 1988, 2017
277
IEAVXFR callable service
Syntax
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-14
15
Unchanged
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Description
CALL IEAVXFR
,(return_code
,auth_level
,current_du_pause_element_token
,updated_pause_element_token
,current_du_release_code
,target_du_pause_element_token
,target_du_release_code)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v
Length: 4 bytes
Contains the return code from the Transfer service.
,auth_level
Supplied parameter
278
z/OS MVS Assembler Services Reference IAR-XCT
IEAVXFR callable service
v Type: Integer v
Character Set: N/A v Length: 4 bytes
Indicates the maximum authorization level of the pause element being deallocated. IEAASM and IEAC define constants IEA_UNAUTHORIZED and
IEA_AUTHORIZED, which the calling program can use. The following levels are supported:
Variable
IEA_UNAUTHORIZED
Value (HEX) Meaning
0 The pause elements must have been allocated with auth_level=_UNAUTHORIZED.
,current_du_pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains a pause element token that identifies the pause element used to pause the current task. Once a PET is used on a call to the Pause service, it cannot be reused on a second call to Pause or as a current_du_pause_element_token on Transfer. A new PET is returned to updated_pause_element_token. The new PET now properly defines the pause element and should be used the next time a pause, transfer, release, or deallocate_pause_element request is made using the same pause element.
If the value specified is 16-bytes of binary zeros, the current task will not be paused. The updated_pause_element_token and current_du_release_code will be unpredictable.
CAUTION:
Do not specify the same PET for both current_du_pause_element_token and target_pause_element_token.
,updated_pause_element_token
Returned parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains a new pause element token that identifies the pause element originally identified by the PET specified in current_du_pause_element_token.
The PET originally specified in current_du_pause_element_token cannot be reused after a successful call to Pause or Transfer.
If you set the current_du_pause_element_token to zeros, the contents of updated_pause_element_token are unpredictable.
,current_du_release_code
Returned parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
Chapter 36. IEAVXFR — Transfer service
279
IEAVXFR callable service
Contains the release code set by the issuer of the Release or Transfer service that released the current task from its paused condition.
If you set the current_du_pause_element_token to zero, the contents are unpredictable.
,target_du_pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains a pause element token that identifies the pause element to release the target task. Any PET that specifies a pause element not currently being used to pause a task is valid. When a PET for a previously released pause element is used to try to pause a task, the task is not paused; however, the value specified in target_du_release_code will still be returned to the caller of Pause or
Transfer.
If the task was paused and is now dispatchable, the task will immediately be given control on the current processor.
CAUTION:
Do not use the same PET for both current_du_pause_element_token and target_du_pause_element_token.
,target_du_release_code
Supplied parameter v Type: Character string v
Character Set: N/A v Length: 3 bytes
Contains the release code returned to the issuer of the Pause or Transfer service that is used (or will use) the same PET to pause a task.
ABEND codes
None.
Return codes
When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.
Meaning and Action Return Code in: Decimal
(Hex)
00 (00)
Equate symbol
IEA_SUCCESS
04 (04) IEA_PE_TOKEN_BAD
Meaning
: Successful completion.
Action
: None
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
280
z/OS MVS Assembler Services Reference IAR-XCT
IEAVXFR callable service
Return Code in: Decimal
(Hex)
08 (08)
Equate symbol
IEA_PE_TOKEN_STALE
12 (0C)
16 (10)
20 (14)
24 (18)
32 (20)
36 (24)
40 (28)
Meaning and Action
IEA_DUPLICATE_PAUSE
IEA_SLEEP_DISRUPTED
IEA_SPACE_TERMINATING
IEA_LOCK_HELD
IEA_PE_BAD_STATE
IEA_UNSUPPORTED_MVS_RELEASE
IEA_INVALID_AUTHCODE
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET returned on Pause or
Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The work unit has already been paused using the specified pause element token. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: RTM has terminated the task; no release is necessary.
Action
: None
Meaning
: The address space that contains the task is terminating; no release is necessary.
Action
: None
Meaning
: Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The pause element associated with the pause element token specified in the call is not in a valid state. The system rejects the service call.
Action
: Check the calling program for a probable coding error, such as attempting to perform a Pause or
Transfer using a pause element token that has already been used to Pause or
Transfer by another unit of work.
Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The auth_level value specified in the call is not valid.
The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 36. IEAVXFR — Transfer service
281
IEAVXFR callable service
Return Code in: Decimal
(Hex)
44 (2C)
Equate symbol
IEA_INVALID_MODE
52 (34) IEA_ALREADY_SUSPENDED
60 (3C) IEA_AUTH_TOKEN
64 (40)
68 (44)
72 (48)
4095 (FFF)
IEA_PE_NOT_HOME
IEA_XFER_TO_SELF
IEA_XFER_FAILED
IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The pause element was already paused.
Action
: Check the calling program for a probable coding error and correct the program and rerun it.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was allocated with auth_level=AUTHORIZED. The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was for a pause element allocated to another address. Action: Check the calling program for a probable coding error.
Correct the program and rerun it.
Meaning:
Program error. The specified current_du_pause_element_token and target_du_pause_element_token are the same.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The transfer failed, and the current_du_pause_element_token is no longer useable.
Action
: Reissue the transfer request using the updated_du_pause_element_token.
Deallocate the current_du_pause_element_token.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action
: Contact IBM support.
282
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 37. IEAVXFR2 — Transfer service
Description
Call the Transfer service to release a paused task or SRB, and, when possible, give it immediate control. This service can also, optionally, pause the task or SRB under which the Transfer request is made. If the caller does not request that its task or
SRB be paused, the caller's task or SRB remains dispatchable.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
31-bit addressing mode.
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEACSS from SYS1.CSSLIB) or have the calling program LOAD and then CALL the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Key 1-15 or problem state callers must specify linkage as IEA_LINKAGE_SVC.
Transfer cannot be used by tasks that are higher in the task tree than the cross memory resource owning task (the top, or first, job step task in the address space).
Input register information
Before calling the Transfer service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
Address of the parameter address list.
© Copyright IBM Corp. 1988, 2017
283
IEAVXFR2 callable service
Syntax
13
Address of a 72-byte register save area.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-14
15
Used as work registers by the system
Unchanged
Used as a work register by the system
Performance implications
None.
Syntax
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Description
CALL IEAVXFR2
,(return_code
,current_du_pause_element_token
,updated_pause_element_token
,current_du_release_code
,target_du_pause_element_token
,target_du_release_code
,linkage)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v
Length: 4 bytes
Contains the return code from the Transfer service.
284
z/OS MVS Assembler Services Reference IAR-XCT
IEAVXFR2 callable service
,current_du_pause_element_token
Supplied parameter v
Type: Character string v Character Set: N/A v Length: 16 bytes
Contains a pause element token that identifies the pause element that is being or will be used to pause a task or SRB. When a PET is used on a call to the
Pause service, it cannot be reused on a second call to Pause or as a current_du_pause_element_token on Transfer. A new PET is returned to update_pause_element_token. The new PET properly defines the pause element and should be used the next time a pause, transfer, release, or deallocate_pause_element request is made using the same pause element.
If the value specified is 16-bytes of binary zeros, the current task or SRB is not paused. The updated_pause_element_token and current_du_release_code will be unpredictable.
CAUTION:
Do not specify the same PET for both current_du_pause_element_token and target_du_pause_element_token.
,updated_pause_element_token
Returned parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains a new pause element token that identifies the pause element originally identified by the PET specified in current_du_pause_element_token.
The PET originally specified in current_du_pause_element_token cannot be reused after a successful call to Pause or Transfer.
If you set the current_du_pause_element_token to zeros, the contents of updated_pause_element_token are unpredictable.
,current_du_release_code
Returned parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
Contains the release code set by the issuer of the Release or Transfer service that released the current task or SRB from its paused condition.
If you set the current_du_pause_element_token to zero, the contents are unpredictable.
,target_du_pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains a pause element token that identifies a pause element that is being or will be used to pause a task or SRB. If the task or SRB is paused, it will be released, and, if possible, be given control. If the task or SRB is not paused
Chapter 37. IEAVXFR2 — Transfer service
285
IEAVXFR2 callable service
using the specified pause element, it will not be paused when an attempt to pause is made. In either case the task or SRB will be returned the value specified in target_du_release_code.
CAUTION:
Do not use the same PET for both current_du_pause_element_token and target_du_pause_element_token.
,target_du_release_code
Supplied parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
Contains the release code returned to the issuer of the Pause or Transfer service used (or will use) the PET specified in target_du_pause_element_token to pause a task or SRB.
linkage
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Specifies how the Transfer service routine is to be invoked. The following options are supported:
Variable
IEA_LINKAGE_SVC
IEA_LINKAGE_BRANCH
Value (hexadecimal) Meaning
0 The Transfer service routine will be invoked by an SVC linkage. This option can be used when in non-cross memory task mode, in any key, and either problem state or supervisor state.
1 The Transfer service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in SRB mode.
ABEND codes
None.
Return codes
When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.
Meaning and Action Return Code in:
Decimal (Hex)
00 (00)
Equate symbol
IEA_SUCCESS
04 (04) IEA_PE_TOKEN_BAD
Meaning
: Successful completion.
Action
: None
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
286
z/OS MVS Assembler Services Reference IAR-XCT
Return Code in:
Decimal (Hex)
08 (08)
Equate symbol
IEA_PE_TOKEN_STALE
12 (0C) IEA_DUPLICATE_PAUSE
16 (10)
20 (14)
24 (18)
IEA_SLEEP_DISRUPTED
IEA_SPACE_TERMINATING
IEA_LOCK_HELD
32 (20) IEA_PE_BAD_STATE
36 (24)
44 (2C)
IEA_UNSUPPORTED_MVS_RELEASE
IEA_INVALID_MODE
52 (34)
60 (3C)
IEA_ALREADY_SUSPENDED
IEA_AUTH_TOKEN
IEAVXFR2 callable service
Meaning and Action
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET returned on
Pause or Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The work unit has already been paused using the specified pause element token. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: RTM has terminated the task or SRB; no release is necessary.
Action
: None
Meaning
: The address space that contains the task or SRB is terminating; no release is necessary.
Action
: None
Meaning
: Program error. If a current_du_pause_element_token of 16 bytes of binary zeros is specified, one or more locks other than the local lock are held. Otherwise, one or more locks are held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The pause element associated with the pause element token specified in the call is not in a valid state. The system rejects the service call.
Action
: Check the calling program for a probable coding error, such as attempting to perform a Pause or Transfer using a pause element token that has already been used to
Pause or Transfer by another unit of work. Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The pause element was already paused.
Action
: Check the calling program for a probable coding error and correct the program and rerun it.
Meaning:
Program error. The caller was in Problem state or key 8, but the pause element token was allocated with pause_element_auth_level=IEA_AUTHORIZED. The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Chapter 37. IEAVXFR2 — Transfer service
287
IEAVXFR2 callable service
Return Code in:
Decimal (Hex)
64 (40)
Equate symbol
IEA_PE_NOT_HOME
68 (44) IEA_XFER_TO_SELF
72 (48) IEA_XFER_FAILED
84 (54) IEA_INVALID_LINKAGE
4095 (FFF) IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning:
Program error. The pause element token was for a pause element allocated with pause_element_auth_level=IEA_UNAUTHORIZED to another address space.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The specified current_du_pause_element_token and target_du_pause_element_token are the same.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The transfer failed, and the current_du_pause_element_token is no longer usable.
Action
: Reissue the transfer request using the updated_du_pause_element_token. Deallocate the current_du_pause_element_token.
Meaning:
Program error. The linkage value specified is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action
: Contact IBM support.
288
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 38. IEA4APE — Allocate_Pause_Element
|
Description
Allocate_Pause_Element obtains a pause element token (PET), which uniquely identifies a pause element. The PET is used as input to the following services: v Pause v Release v Transfer v Deallocate_Pause_Element
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
RMODE:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
64-bit
Includes 64-bit
Primary
Enabled for I/O and external interrupts
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
When the calling program specifies auth_level=IEA_UNAUTHORIZED, the caller must be in task mode and can only release another task in its home address space.
All pause element tokens (PETs) used when auth_level=IEA_UNAUTHORIZED must have been obtained using an authorization level of IEA_UNAUTHORIZED.
Only 2040 unauthorized PETs may be allocated at any one time in an address space.
Input register information
Before calling Allocate_Pause_Element, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
© Copyright IBM Corp. 1988, 2017
289
IEA4APE callable service
Register
Contents
1
13
Address of the parameter address list.
Address of a 144-byte register save area.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
14
15
Used as work registers by the system
Unchanged
Used as work registers by the system
Return Code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4APE
,(return_code
,auth_level
,pause_element_token)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v
Type: Integer v Character Set: N/A v Length: 4 bytes
290
z/OS MVS Assembler Services Reference IAR-XCT
IEA4APE callable service
Contains the return code from the Allocate_Pause_Element service.
,auth_level
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Represents one or more possible levels of the pause element being allocated.
The calling program can use the constants that are defined in IEAASM or
IEAC. The level needed is derived by adding the values of the required types together. The authorization type is required.
For example, the level to allocate authorized pause elements that are checkpoint- or restart-tolerant is IEA_AUTHORIZED + IEA_CHECKPOINTOK, or 3.
The following levels are supported:
Table 21. Authorization
IEAASM and IEAC defined constants
IEA_UNAUTHORIZED
Value (hexadecimal)
0
Meaning
IEA_AUTHORIZED 1
When using the allocated pause element through other services, either auth_level
IEA_UNAUTHORIZED or
IEA_AUTHORIZED can be used.
When using the allocated pause element through other services, auth_level=IEA_AUTHORIZED will be required. Caller must be both key 0 and supervisor state.
Table 22. Checkpoint/Restart Toleration - only available when the CVTPAUS4 bit is set in the CVT.
Value (hexadecimal) Meaning IEAASM and IEAC defined constants
IEA_CHECKPOINTOK 2 The application can tolerate the pause elements' not being restored upon a restart after a checkpoint.
Note:
If the IEA_CHECKPOINTOK value is not added to the authorization value, checkpoints cannot be taken when an allocated pause element exists.
,pause_element_token
Returned parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains the pause element token that identifies the pause element that you can use to synchronize the processing of a task.
ABEND codes
None.
Chapter 38. IEA4APE — Allocate_Pause_Element
291
IEA4APE callable service
Return codes
When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.
Meaning and Action Return code in:
Decimal (Hex)
Equate symbol
00 (0)
IEA_SUCCESS
24 (18)
IEA_LOCK_HELD
36 (24)
IEA_UNSUPPORTED_MVS_RELEASE
40 (28)
IEA_PE_NOT_HOME
44 (2C)
IEA_XFER_TO_SELF
48 (30)
IEA_XFER_FAILED
56 (38)
IEA_NO_PETS_AVAILABLE
4095 (FFF)
IEA_UNEXPECTED_ERROR
Meaning
: Successful completion.
Action
: None.
Meaning:
Program error. If the auth_level indicates
AUTHORIZED, locks other than the local lock are held. If the auth_level indicates UNAUTHORIZED, locks are held.
The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The auth_level value specified in the call is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Environmental error. The system could not obtain storage for a pause element. The system rejects the service call.
Action
: Retry the request later. If the problem persists, consult your system programmer.
Meaning
: There are no pause element tokens available.
Action
: Retry the request later.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action:
Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center.
292
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 39. IEA4APE2 — Allocate_Pause_Element
|
Description
Allocate_Pause_Element obtains a pause element token (PET), which uniquely identifies a pause element. The PET is used as input to the following services: v Pause v Release v Transfer v Deallocate_Pause_Element
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
RMODE:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
64-bit
Includes 64-bit
Primary
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB) or load the calling program and then call the service.
The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Only 2040 unauthorized PETs may be allocated at any one time in an address space.
Allocate_Pause_Element cannot be used by tasks that are higher in the task tree than the cross memory resource owning task (the top, or first, job step task in the address space).
© Copyright IBM Corp. 1988, 2017
293
IEA4APE2 callable service
Input register information
Before calling Allocate_Pause_Element, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Address of a 144-byte register save area.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4APE2
,(return_code
,pause_element_token
,pause_element_owner_stoken
,owner_termination_release_code
,linkage)
Parameters
The parameters are explained as follows:
294
z/OS MVS Assembler Services Reference IAR-XCT
IEA4APE2 callable service return_code
Returned parameter v
Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return code from the Allocate_Pause_Element service.
,pause_element_token
Returned parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains the pause element token that identifies a pause element that you can use to synchronize the processing of a task or SRB.
,pause_element_owner_stoken
Supplied parameter v Type: Character string v Character Set: N/A v Length: 8 bytes
Specifies the space token (STOKEN) of the address space which is to be considered the owner of the Pause Element being allocated. Specify one of the following values: v Binary zero: indicate the system should make the current primary address space the owner of the Pause Element. This is the only value valid for key
8-15 problem state callers.
v A valid STOKEN, indicate the system should make the address space with the matching STOKEN the owner for the pause element.
When the CMRO task (the first job step task) of an address space terminates, the system will release and deallocate any pause elements owned by the
CMRO task's home address space. The table below describes exactly when the system will release and/or deallocate a Pause Element:
Allocation Service version:
IEA4APE
Deallocation Rules
The PE will be deallocated by the system when one of the following events occurs: v The PE was never used to pause a task or
SRB and the CMRO task for the space which allocated it terminates.
v The PE is being used to pause a task or
SRB which is asynchronously terminated via CALLRTM TYPE=ABTERM (for example, cancel or detach) or a
PURGEDQ.
v The CMRO task of the home address space of the task or SRB which last used the PE terminates and the PE is not being used to pause an SRB.
The home address space of the task or SRB which last used the PE terminates
Chapter 39. IEA4APE2 — Allocate_Pause_Element
295
IEA4APE2 callable service
Allocation Service version:
IEA4APE2
Deallocation Rules
The PE will be deallocated by the system when one of the following events occurs: v The CMRO task of the address space specified by pause_element_owner_stoken terminates. If the PE is being used to pause a DU when the CMRO task terminates, the system will release the DU using the owner_termination_release_code before the PE is deallocated. Note that in this case, the UPET returned will be 16 bytes of binary zeros, an invalid value.
v The PE is being used to pause a task or
SRB which is asynchronously terminated via CALLRTM TYPE=ABTERM (for example, cancel or detach) or a
PURGEDQ.
v The PE is being used to pause a task or
SRB when the home address space of the task or SRB is terminated v The CMRO task of the home address space of the task or SRB which last used the PE terminates and the PE is not being used to pause an SRB
The home address space of the task or SRB which last used the PE terminates.Note: A
PE is considered as "being used to pause a task or SRB," when the PE is not Reset or
Prereleased.
,owner_termination_release_code
Supplied parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
Specifies the release code which will be returned to a paused DU if the system deallocates the pause element while it is being used to pause a task or SRB, due to the CMRO task of its owning address space terminating.
Note:
If the system deallocates a PE due to its owner terminating while the PE was not being used to pause a task or SRB, future attempts to use the PE will fail with a return code indicating the PETOKEN was stale or the PE is in an invalid state.
linkage
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Specifies how the Allocate_Pause_Element service routine is to be invoked. The following options are supported:
296
z/OS MVS Assembler Services Reference IAR-XCT
IEA4APE2 callable service
Table 23. Linkage option
Variable
IEA_LINKAGE_SVC
IEA_LINKAGE_BRANCH
Value (hexadecimal)
0
1
Meaning
The Allocate_Pause_Element service routine will be invoked via an SVC linkage. This option can be used when in non-cross memory task mode, any key, and either problem state or supervisor state.
The Allocate_Pause_Element service routine will be invoked via a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in SRB mode.
ABEND codes
None.
Return codes
When the service returns control to the resource manager, GPR 15 and the return_code parameter contain a hexadecimal return code.
Equate Symbol Meaning and Action Return code in: Decimal
(Hex)
00 (0) IEA_SUCCESS
24 (18)
36 (24)
40 (28)
44 (2C)
IEA_LOCK_HELD
IEA_UNSUPPORTED_MVS_RELEASE
IEA_INVALID_AUTHCODE
IEA_INVALID_MODE
Meaning:
Successful completion.
Action:
None.
Meaning:
Program error. One or more locks other than the local lock are held.
The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Environmental error. The system release does not support this service. The system rejects the service call.
Action:
Run the program on a system that supports the service.
Meaning:
Program error. The pause_element_auth_level value specified in the call is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 39. IEA4APE2 — Allocate_Pause_Element
297
IEA4APE2 callable service
Return code in: Decimal
(Hex)
48 (30)
Equate Symbol
IEA_OUT_OF_STORAGE
56 (38) IEA_NO_PETS_AVAILABLE
4095 (FFF) IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning:
Environmental error. The system could not obtain storage for a pause element. The system rejects the service call.
Action:
Retry the request later. If the problem persists, consult your system programmer.
Meaning:
There are no pause element tokens available.
Action:
Try the request again later.
Meaning:
This service routine encountered an unexpected error. The system rejects this service request.
Action:
Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center.
298
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 40. IEA4DPE - Deallocate_Pause_Element
|
Description
Deallocate_Pause_Element frees a pause element that is no longer needed.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
RMODE:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
64-bit
Includes 64-bit
Primary mode.
Enabled for I/O and external interrupts
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
When the calling program specifies auth_level=IEA_UNAUTHORIZED, the caller must be in task mode and can only release another task in its home address space.
All pause element tokens (PETs) used when auth_level=IEA_UNAUTHORIZED must have been obtained using an authorization level of IEA_UNAUTHORIZED.
Input register information
Before calling Deallocate_Pause_Element, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Address of a 144-byte register save area.
Output register information
When control returns to the caller, the GPRs contain:
© Copyright IBM Corp. 1988, 2017
299
IEA4DPE callable service
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4DPE
,(return_code
,auth_level
,pause_element_token)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return code from the Deallocate_Pause_Element service.
,auth_level
Supplied parameter v Type: Integer v Character Set: N/A
300
z/OS MVS Assembler Services Reference IAR-XCT
IEA4DPE callable service
v Length: 4 bytes
Indicates the maximum authorization level of the pause element being deallocated. The calling program can use constant IEA_UNAUTHORIZED defined by IEAASM and IEAC. The following levels are supported:
Variable
IEA_UNAUTHORIZED
Value
(HEX)
0
Meaning
This pause element being deallocated must have been allocated with auth_level=IEA_UNAUTHORIZED.
,pause_element_token
Supplied parameter v
Type: Character string v Character Set: N/A v Length: 16 bytes
Contains the pause element token that identifies the pause element that is no longer needed.
ABEND codes
None.
Return codes
When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.
Meaning and Action Return code in:
Decimal (Hex)
Equate symbol
00 (00)
IEA_SUCCESS
04 (04)
08 (08)
IEA_PE_TOKEN_STALE
24 (18)
IEA_LOCK_HELD
Meaning
: Successful completion.
Action
: None.
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or
Transfer service. This service requires the updated
PET be returned on Pause or Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 40. IEA4DPE - Deallocate_Pause_Element
301
IEA4DPE callable service
Return code in:
Decimal (Hex)
Equate symbol
32 (20)
IEA_PE_BAD_STATE
36 (24)
IEA_UNSUPPORTED_MVS_RELEASE
40 (28)
IEA_INVALID_AUTHCODE
44 (2C)
IEA_INVALID_MODE
60 (3C)
IEA_AUTH_TOKEN
64 (40)
IEA_PE_NOT_HOME
4095 (FFF)
IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning
: Program error. The pause element associated with the specified pause element token specified is invalid or has already been paused. A paused PE must be released before it is deallocated.
This return code also can indicate that the address space associated with the pause element is ending or has ended and that the system freed the pause element.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The auth_level value specified in the call is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires.
The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was allocated with auth_level=AUTHORIZED.
The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was for a pause element allocated to another address.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action:
Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM
Support Center.
302
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 41. IEA4DPE2 — Deallocate_Pause_Element
|
Description
Deallocate_Pause_Element frees a pause element that is no longer needed.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
RMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
64-bit
Includes 64-bit
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB) or load the calling program and then call the service.
The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Input register information
Before calling Deallocate_Pause_Element, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Address of a 144-byte register save area.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
© Copyright IBM Corp. 1988, 2017
303
IEA4DPE2 callable service
0-1
2-13
14
15
Used as work registers by the system
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4DPE2
,(return_code
,pause_element_token
,linkage)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return code from the Deallocate_Pause_Element service.
,pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v
Length: 16 bytes
Contains the pause element token that identifies the pause element that is no longer needed.
304
z/OS MVS Assembler Services Reference IAR-XCT
IEA4DPE2 callable service linkage
Supplied parameter v
Type: Integer v Character Set: N/A v Length: 4 bytes
Specifies how the Deallocate_Pause_Element service routine is to be invoked.
The following options are supported:
Variable
IEA_LINKAGE_SVC
IEA_LINKAGE_BRANCH
Value (hexadecimal) Meaning
0 The Deallocate_Pause_Element service routine will be invoked by an SVC linkage. This option can be used when in non-cross memory task mode, in any key, and in either problem state or supervisor state.
1 The Deallocate_Pause_Element service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in
SRB mode.
ABEND codes
None.
Return codes
When the service returns control to the resource manager, GPR 15 and the return_code parameter contain a hexadecimal return code.
Equate symbol Meaning and Action Return code in: Decimal
(Hex)
00 (00) IEA_SUCCESS
04 (04)
08 (08)
24 (18)
IEA_PE_TOKEN_BAD
IEA_PE_TOKEN_STALE
IEA_LOCK_HELD
Meaning:
Successful completion
Action:
None.
Meaning:
Program error. The specified pause element token is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated
PET returned on Pause or Transfer.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. One or more locks other than the local lock are held.
The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 41. IEA4DPE2 — Deallocate_Pause_Element
305
IEA4DPE2 callable service
Return code in: Decimal
(Hex)
32 (20)
Equate symbol
IEA_PE_BAD_STATE
36 (24)
44 (2C)
64 (40)
4095 (FFF)
IEA_UNSUPPORTED_MVS_RELEASE
IEA_INVALID_MODE
IEA_PE_NOT_HOME
IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning:
Program error. The pause element associated with the specified pause element token is invalid or has already been paused. A paused PE must be released before it is deallocated. This return code also can indicate that the address space associated with the pause element is ending or has ended and that the system freed the pause element.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Environmental error. The system release does not support this service. The system rejects the service call.
Action:
Run the program on a system that supports the service.
Meaning:
Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The pause element token was for an unauthorized pause element allocated to another address space.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
This service routine encountered an unexpected error. The system rejects this service request.
Action:
Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center.
306
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 42. IEA4PME2 — 64-bit pause multiple elements service
Description
IEA4PME2 is a callable service that can be used to pause on one or more pause element tokens (PETs). It is entered in 64-bit mode and the addresses in the parameter list are 64 bits long. When the specified number of pause elements (PEs) represented by PETs has been released, you receive control back with the following: v
A list of PETs that you can use to pause on again v An indication of which PEs were released v Their release codes.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
v Problem state and any PSW key.
v For LINKAGE=BRANCH: Task or SRB v
For LINKAGE=SVC: Task v For LINKAGE=BRANCH: any PASN, any HASN, any
SASN v For LINKAGE=SVC: PASN=SASN=HASN
31-bit addressing mode.
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine (IEACSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Key 1-15 or problem state callers must specify linkage as IEA_LINKAGE_SVC.
IEA_LINKAGE_SVC is limited to pausing upon no more than 1000 PETs.
© Copyright IBM Corp. 1988, 2017
307
IEA4PME2 callable service
Pause cannot be used by tasks that are higher in the task tree than the cross memory resource owning task (the EXEC PGM=xxx task).
Input register information
Before calling the Pause service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Note that register 13 is not required to contain any particular value. See the
workarea
parameter description.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as work registers by the system
Return code.
Note that this service saves and restores full 64-bit GPRs.
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
There is a maximum number of PETs which can be processed very quickly by
IEAVPME2 without doing additional GETMAINs and FREEMAINs. That number is currently 16.
308
z/OS MVS Assembler Services Reference IAR-XCT
IEA4PME2 callable service
Syntax
Syntax
CALL IEA4PME2
Description
(return_code
,pause_element_token_list
,updated_pause_element_token_list
,release_code_list
,number_of_PETs_in_each_list
,number_of_PEs_to_release
,linkage
,workarea)
Link-edit your program with a linkage-assist routine (also called a stub) in
SYS1.CSSLIB unless you use one of the following techniques as an alternative to
CALL IEA4PME2:
1.
LOAD EP=IEA4PME2
Save the 8-byte entry point address with bit 63 changed to 0 (...)
Put the saved entry point address with bit 63 changed to 0 into 64-bit R15
CALL (15),(...)
2.
L
L
L
15,X’10’(0,0)
15,X’220’(15,0)
L
15,X’14’(15,0)
15,X’100’(15,0)
CALL (15),(...)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the highest return code from the Pause service (multiple return codes are possible when more than one PET has been specified – seerelease_code_list).
When the low-order bit of the return code is on, release_code_list contains the return codes for individual PETs rather than release codes.
Note that no pause has actually occurred if the return code is non-zero. In this situation, any PETs which have been released remain released.
,pause_element_token_list
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes times the number of PEs you want to pause on
A list of the PETs identifying the PEs you want to pause on.
Number_of_PETs_in_each_list specifies how many PETs are in the list.
,updated_pause_element_token_list
Returned parameter v
Type: Character string v Character Set: N/A v Length: 16 bytes times the number of PEs you want to pause on
Chapter 42. IEA4PME2 — 64-bit pause multiple elements service
309
IEA4PME2 callable service
If return_code is 0, a list of the PETs returned by Pause Multiple Elements. Each entry corresponds to an entry in the pause_element_token_list. For each PE that was released, the system puts an updated PET into this list. For PEs that are not released, the entry contains the PET from the original
pause_element_token_list.
These new PETs must be used in place of the PETs specified in
pause_element_token_list or pause_element_token on future calls to the Pause,
Release, Transfer, or Deallocate_Pause_Element service. The first byte of each entry in release_code_list identifies which PEs were released.
Number_of_PETs_in_each_list specifies how many PETs are in the list.
If return_code is not 0, the PETs are not updated and this list is not returned.
If the paused workunit was released by the system (the release code is the
owner_termination_release_code specified on the IEAVAPE2 allocation), the PET returned in that slot will be 16 bytes of binary zeros, an invalid value.
,release_code_list
Returned parameter v Type: Fullword v Character Set: N/A v Length: 4 bytes times the number of PEs you want to pause on
Each entry corresponds to an entry in the pause_element_token_list.
If return_code is 0, the pause was successful and has been released. For each PE that was Released, the system puts X'01' into the first byte and the release code for that PET into the second through fourth bytes of the full-word entry for that PET. For PEs which are not released, the entry contains binary zeroes.
If return_code is 5, 9, D, 21, 35, 3D, or 41, a problem was found with at least one of the PETs specified in pause_element_token_list and the pause request did not complete.
The individual return code for each PET is in the second through fourth bytes of the release_code_list entry for that PET. Each PET with a return code of 0 would have been paused on if all the other PETs in the list had received return codes of 0. If return_code contains any other value, the pause request did not complete and release_code_list does not contain any meaningful information.
Note:
These return codes are the equivalent of return codes 4, 8, C, 20, 34, 3C, and 40 for IEAVPSE2 (Pause single), with the addition of a low-order bit to signify that the release_code_list contains individual PET return codes.
,number_of_PETs_in_each_list
Supplied parameter
Number_of_PETs_in_each_list specifies how many entries are in release_code_list.
v Type: Integer v Character Set: N/A v Length: 4 bytes
This number specifies how many PETs you want to Pause on. This number also specifies the number of entries in pause_element_token_list,
updated_pause_element_token_list , and release_code_list. For SVC entry callers, the maximum number that can be specified is 1000.
,number_of_PEs_to_release
Supplied parameter
310
z/OS MVS Assembler Services Reference IAR-XCT
IEA4PME2 callable service
Number_of_PETs_in_each_list specifies how many entries are in release_code_list.
v
Type: Integer v Character Set: N/A v Length: 4 bytes
This number specifies how many PEs must be released before control is returned back to the issuer of Pause Multiple Elements. This number must be at least 1 and no more than number_of_PETs_in_each_list.
Note that if more PEs than this number were released before IEAVPME2 was issued (pre-released), the number of updated PETs in
updated_pause_element_token_list will be the actual number released.
,linkage
Supplied parameter v
Type: Integer v Character Set: N/A v Length: 4 bytes
Specifies how the Pause service routine is to be invoked. The following options are supported:
Table 24. Linkages
Variable
IEA_LINKAGE_SVC
IEA_LINKAGE_BRANCH
Value
0
1
Meaning
The Pause service routine will be invoked by an SVC linkage. This option can be used when in non-cross memory task mode, in any key, and in either problem state or supervisor state.
The Pause service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in SRB mode.
,workarea
Supplied parameter v Type: Character string v Character Set: N/A v Length: 216 bytes
Specifies a work area on a doubleword boundary in which the Pause service routine will save information about the caller including the caller's registers.
This can be the same area that R13 points to if the first 216 bytes of that area can be used as an F7SA savearea.
ABEND codes
None. However, note that you may receive a GETMAIN abend if this service is unable to obtain storage needed to process the PETs.
Return codes
When IEAVPME2 returns control to your program, if GPR 15 contains 0, 5, 9, D,
21, 35, 3D, or 41, release_code_list contains information about the status of each PET that was specified. If GPR 15 contains any other value, release_code_listdoes not contain any meaningful information.
Chapter 42. IEA4PME2 — 64-bit pause multiple elements service
311
IEA4PME2 callable service
Return code in: Decimal
(Hex)
00 (0)
Equate Symbol
IEA_SUCCESS
05 (05)
09 (09)
13 (0D)
24 (18)
33 (21)
IEA_PE_TOKEN_BAD
IEA_PE_TOKEN_STALE
IEA_LOCK_HELD
IEA_PE_BAD_STATE
36 (24) IEA_UNSUPPORTED_MVS_
RELEASE
44 (2C)
IEA_DUPLICATE PAUSE
IEA_INVALID_MODE
Meaning and Action
Meaning:
Successful completion.
Action:
None.
Meaning:
Program error. The specified pause element token is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET returned on Pause or Transfer.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The work unit has already been paused using the specified pause element token. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The caller is holding one or more locks; no locks may be held. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The pause element associated with the pause element token specified in the call is not in a valid state. The system rejects the service call.
Action:
Check the calling program for a probable coding error, such as attempting to perform a pause or transfer using a pause element token that has already been used to pause or transfer by another unit of work.
Correct the program and rerun it.
Meaning:
Environmental error. The system release does not support this service. The system rejects the service call.
Action:
Run the program on a system that supports the service.
Meaning:
Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
312
z/OS MVS Assembler Services Reference IAR-XCT
IEA4PME2 callable service
Return code in: Decimal
(Hex)
53 (35)
Equate Symbol
IEA_ALREADY_SUSPENDED
61 (3D)
65 (41)
76 (4C)
80 (50)
84 (54)
104(68)
108(6C)
Meaning and Action
IEA_AUTH_LEVEL_MISMATCH
IEA_PE_NOT_HOME
IEA_ABENDED_47B
IEA_INSUSPEND_EXIT
IEA_INVALID_LINKAGE
IEA_INVALID_NUMBER_OF_PETS
IEA_INVALID_NUMBER_TO_
RELEASE
Meaning:
The pause element was already paused.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The caller was in problem state or key 8, but the pause element token was allocated with
pause_element_auth_level=IEA_AUTHORIZED. The system rejects the service call.
Action:
Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning:
Program error. The pause element token was for a pause element allocated with
pause_element_auth_level=IEA_AUTHORIZED to another address space.
Action:
Check the calling program for a probable coding error. Correct eht program and rerun it.
Meaning:
After an SRB received abend 47B, it invoked IEA4PME2. It is not valid to invoke
IEA4PME2 after receiving abend 47B.
Action:
Update the calliing program to not invoke IEA4PME2 after abend 47B.
Meaning:
The suspend exit specified on
SUSPEND with SPTOKEN of an SRB invoked
IEA4PME2. It is not valid to invoke IEA4PME2 from a suspend exit.
Action:
Update the calling program to not invoke IEA4PME2 from a suspend exit.
Meaning:
Program error. The linkage value specified is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The number of PETs specified for Pause Multiple was 0 or for SVC entry users more than 1000. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The number of PEs to release is 0 or greater than the number of
PETs specified for Pause Multiple. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 42. IEA4PME2 — 64-bit pause multiple elements service
313
IEA4PME2 callable service
Return code in: Decimal
(Hex)
4094(FFE)
Equate Symbol
IEA_ERROR_PETS_INVALIDATED
4095(FFF) IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning:
Pause processing has encountered an error and cannot complete the Pause request. This input PETs have been invalidated. This return code is only issued for
Pause Multiple requests.
Action:
Do not return the PETs to the system using the Deallocate Pause Elements services.
Note that new PEs must be obtained before attempting to pause again.
Meaning:
This service routine encountered an unexpected error. The system rejects this service request.
Action:
Contact IBM support.
314
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 43. IEA4PSE — Pause service
|
Description
Call IEA4PSE service to make the current task nondispatchable. After you pause a task, it remains nondispatchable until a release service specifying the same PET is called. That is, the program issuing the pause does not receive control back until after the release occurs.
If a release service specifying the same PET is called before pause, the system returns control immediately to the calling program, and the task is not paused.
When you use pause, it returns an updated PET. Use this updated PET to either deallocate or reuse the PE.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
RMODE:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
64-bit
Includes 64-bit
Primary mode
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
When the calling program is running auth_level=IEA_UNAUTHORIZED, the caller must be in task mode and can only pause another task in its home address space.
All pause element tokens (PETs) used when auth_level=IEA_UNAUTHORIZED must have been obtained using an authorization level of IEA_UNAUTHORIZED.
Input register information
Before calling the Pause service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
© Copyright IBM Corp. 1988, 2017
315
IEA4PSE callable service
Register
Contents
1
13
Address of the parameter address list.
Address of a 144-byte register save area.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
14
15
Used as work registers by the system
Unchanged
Used as work registers by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4PSE
,(return_code
,auth_level
,pause_element_token
,updated_pause_element_token
,release_code)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v
Type: Integer v Character Set: N/A v Length: 4 bytes
316
z/OS MVS Assembler Services Reference IAR-XCT
IEA4PSE callable service
Contains the return code from the Pause service.
,auth_level
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Indicates the maximum level that the specified pause element was allocated with. IEAASM and IEAC define constants IEA_UNAUTHORIZED and
IEA_AUTHORIZED, which the calling program can use. The following levels are supported:
Variable
IEA_UNAUTHORIZED
Value
(HEX)
0
Meaning
IEA_AUTHORIZED 1
The pause element being paused must have been allocated with auth_level=IEA_UNAUTHORIZED.
The pause element being paused must have been allocated with auth_level=IEA_AUTHORIZED.
,pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
A pause element token that identifies the pause element being used to pause the current task. You can obtain the PET from the Allocate_Pause_Element service.
When you use a PET in a call to the pause service, you cannot reuse the PET on a second call to pause or on a call to transfer. The pause service returns a new PET in updated_pause_element_token. The new PET now identifies the pause element used to pause the task; use the new PET the next time when you make a pause request using the same pause element.
,updated_pause_element_token
Returned parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
A new pause element token that identifies the pause element originally identified by the PET specified in pause_element_token, which cannot be reused after a successful call to Pause.
,release_code
Returned parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
The release code, specified by the issuer of the Release service. A Release that specified this code released the task from its paused condition.
Chapter 43. IEA4PSE — Pause service
317
IEA4PSE callable service
ABEND codes
Abend Code
AC7
Reason Code
001A0001
Description
This is an internal error. Contact IBM support.
Return codes
When the service returns control to your program, GPR 15 contains one of the following return codes:
Meaning and Action Return code in:
Decimal (Hex)
Equate symbol
00 (00)
IEA_SUCCESS
04 (04)
08 (08)
IEA_PE_TOKEN_STALE
12 (0C)
IEA_DUPLICATE_PAUSE
24 (18)
IEA_LOCK_HELD
32 (20)
IEA_PE_BAD_STATE
36 (24)
IEA_UNSUPPORTED_MVS_RELEASE
40 (28)
IEA_INVALID_AUTHCODE
Meaning
: Successful completion.
Action
: None.
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or
Transfer service. This service requires the updated PET be returned on Pause or Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The work unit has already been paused using the specified pause element token. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The pause element associated with the pause element token specified in the call is not in a valid state. The system rejects the service call.
Action
: Check the calling program for a probable coding error, such as attempting to perform a Pause or
Transfer using a pause element token that has already been used to Pause or Transfer by another unit of work. Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The auth_level value specified in the call is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
318
z/OS MVS Assembler Services Reference IAR-XCT
Return code in:
Decimal (Hex)
Equate symbol
44 (2C)
IEA_INVALID_MODE
52 (34)
IEA_ALREADY_SUSPENDED
60 (3C)
IEA_AUTH_TOKEN
64 (40)
IEA_PE_NOT_HOME
4095 (FFF)
IEA_UNEXPECTED_ERROR
IEA4PSE callable service
Meaning and Action
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The pause element was already paused.
Action
: Check the calling program for a probable coding error and correct the program and rerun it.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was allocated with auth_level=AUTHORIZED.
The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was for a pause element allocated to another address.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action:
Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM
Support Center.
Chapter 43. IEA4PSE — Pause service
319
IEA4PSE callable service
320
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 44. IEA4PSE2 — Pause service
|
Description
Call IEA4PSE2 service to make the current task or SRB nondispatchable. After you pause a task or SRB, it remains nondispatchable until a release or transfer specifying the same PET is called. That is, the program issuing the pause does not receive control back until after the RELEASE or TRANSFER occurs. At that time, the returned release_code contains a value supplied by the associated release or transfer request.
If a release service specifying the same PET is called before pause, the system returns control immediately to the calling program, and the task or SRB is not paused.
When you use pause, it returns an updated PET. Use this updated PET to either deallocate or reuse the PE.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
RMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
64-bit
Includes 64-bit
Primary mode
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB) or load the calling program and then call the service.
The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Pause cannot be used by tasks that are higher in the task tree than the cross memory resource owning task (the top, or first, job step task in the address space).
© Copyright IBM Corp. 1988, 2017
321
IEA4PSE2 callable service
Input register information
Before calling the Pause service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Address of a 144-byte register save area.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
14
15
Unchanged
Used as work registers by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4PSE2
,(return_code
,pause_element_token
,updated_pause_element_token
,release_code
,linkage)
Parameters
The parameters are explained as follows:
return_code
Returned parameter
322
z/OS MVS Assembler Services Reference IAR-XCT
IEA4PSE2 callable service
v Type: Integer v
Character Set: N/A v Length: 4 bytes
Contains the return code from the Pause service.
,pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
A pause element token that identifies the pause element being used to pause the current task or SRB. You obtain the PET from the Allocate_Pause_Element service.
When you use a PET in a call to the pause service, you cannot reuse the PET on a second call to pause or on a call to Transfer. The pause service returns a new PET in updated_pause_element_token. The new PET now identifies the pause element used to pause the task or SRB; use the new PET the next time when you make a Pause request using the same pause element.
,updated_pause_element_token
Returned parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
A new pause element token that identifies the pause element originally identified by the PET specified in pause_element_token. This new PET must be used in place of the PET specified in pause_element_token on future calls to the Pause, Release, Transfer, or Deallocate_Pause_Element service.
,release_code
Returned parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
The release code is specified by the issuer of the release service, which can release the task or SRB of the paused condition.
,linkage
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Specifies how the Pause service routine is to be invoked. The following options are supported:
Variable
IEA_LINKAGE_SVC
Value (hexadecimal) Meaning
0 The Pause service routine will be invoked by an SVC linkage. This option can be used when in non-cross memory task mode, in any key, and either problem state or supervisor state.
Chapter 44. IEA4PSE2 — Pause service
323
IEA4PSE2 callable service
Variable
IEA_LINKAGE_BRANCH
Value (hexadecimal) Meaning
1 The Pause service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in SRB mode.
ABEND codes
Abend Code
AC7
Reason Code
001A0001
Description
This is an internal error.
Contact IBM support.
Return code in:
Decimal (Hex)
00 (00)
Return codes
When the service returns control to your program, GPR 15 contains one of the following return codes:
Equate symbol Meaning and Action
IEA_SUCCESS
04 (04)
08 (08)
12 (0C)
24 (18)
32 (20)
IEA_PE_TOKEN_BAD
IEA_PE_TOKEN_STALE
IEA_DUPLICATE_PAUSE
IEA_LOCK_HELD
IEA_PE_BAD_STATE
Meaning:
Successful completion.
Action:
None
Meaning:
Program error. The specified pause element token is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The specified pause element token is stale; that is, it was valid but has been used on the Pause or
Transfer service. This service requires the updated
PET returned on Pause or Transfer.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The work unit has already been paused using the specified pause element token. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The pause element associated with the pause element token specified in the call is not in a valid state. The system rejects the service call.
Action
: Check the calling program for a probable coding error, such as attempting to perform a Pause or
Transfer using a pause element token that has already been used to Pause or Transfer by another unit of work. Correct the program and rerun it.
324
z/OS MVS Assembler Services Reference IAR-XCT
Return code in:
Decimal (Hex)
36 (24)
Equate symbol
IEA_UNSUPPORTED_MVS_RELEASE
44 (2C) IEA_INVALID_MODE
52 (34)
60 (3C)
IEA_ALREADY_SUSPENDED
IEA_AUTH_TOKEN
64 (40) IEA_PE_NOT_HOME
76 (4C) IEA_ABENDED_47B
80 (50) IEA_IN_SUSPEND_EXIT
4095 (FFF) IEA_UNEXPECTED_ERROR
IEA4PSE2 callable service
Meaning and Action
Meaning:
Environmental error. The system release does not support this service. The system rejects the service call.
Action:
Run the program on a system that supports the service.
Meaning:
Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The pause element was already paused.
Action:
Check the calling program for a probable coding error and correct the program and rerun it.
Meaning:
Program error. The caller was in Problem state or key 8, but the pause element token was allocated with pause_element_auth_level=IEA_AUTHORIZED. The system rejects the service call.
Action:
Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning:
Program error. The pause element token was for a pause element allocated with pause_element_auth_level=IEA_UNAUTHORIZED to another address space.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
After an SRB received ABEND 47B, it invoked IEA4PSE2. It is not valid to invoke IEA4PSE2 after receiving ABEND 47B.
Action:
Update the calling program to not invoke
IEA4PSE2 after ABEND 47B.
Meaning:
The suspend exit specified on SUSPEND with SPTOKEN of an SRB invoked IEA4PSE2. It is not valid to invoke IEA4PSE2 from a suspend exit.
Action:
Update the calling program to not invoke
IEA4PSE2 from a suspend exit.
Meaning:
This service routine encountered an unexpected error. The system rejects this service request.
Action:
Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM
Support Center.
Chapter 44. IEA4PSE2 — Pause service
325
IEA4PSE2 callable service
326
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 45. IEA4RLS — Release
Description
Call IEA4RLS service to remove a task that has been paused, or to keep a task from being paused. Although a pause element can be used multiple times to pause a task, a pause element token can be used to successfully pause and release a task only once. Each time a pause element is used, the system generates a new PET to identify the pause element. The system returns the new updated PET on calls to the pause and transfer services.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
64-bit
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
When the calling program specifies auth_level=IEA_UNAUTHORIZED, the caller must be in task mode and can only release another task in its home address space.
All pause element tokens (PETs) used when auth_level=IEA_UNAUTHORIZED must have been obtained using an authorization level of IEA_UNAUTHORIZED.
Input register information
Before calling the Release service, the caller must ensure that the following general purpose (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Address of a 144-byte register save area.
© Copyright IBM Corp. 1988, 2017
327
IEA4RLS callable service
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4RLS
,(return_code
,auth_level
,target_du_pause_element_token
,target_du_release_code)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return from the Release service.
,auth_level
Supplied Parameter v Type: Integer
328
z/OS MVS Assembler Services Reference IAR-XCT
IEA4RLS callable service
v Character Set: N/A v
Length: 4 bytes
Indicates the maximum authorization level that the specified pause element was allocated with. The calling program can use constant
IEA_UNAUTHORIZED defined by IEAASM and IEAC. The following levels are supported:
Variable
IEA_UNAUTHORIZED
Value
(HEX)
0
Meaning
The pause element being released must have been allocated with auth_level=IEA_UNAUTHORIZED.
,target_du_pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains the pause element token that identifies the pause element used to pause the task. If the PET identifies a pause element that has not been paused, the task is paused. However, the value specified in target_du_release_code is returned to the caller of pause.
,target_du_release_code
Supplied parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
Contains the release code returned to the caller of pause or transfer service that used or will use the same PET to pause a task. If your program is not using this code for communication, set this field to zero.
ABEND codes
None.
Return codes
When the service returns control to the resource manager, GPR 15 and the return_code parameter contain a hexadecimal return code.
Meaning and Action Return code in:
Decimal (Hex)
Equate symbol
00 (00)
IEA_SUCCESS
04 (04)
IEA_PE_TOKEN_BAD
Meaning
: Successful completion.
Action
: None.
Meaning
: The specified pause element token is not valid.
The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 45. IEA4RLS — Release
329
IEA4RLS callable service
Return code in:
Decimal (Hex)
Equate symbol
08 (08)
IEA_PE_TOKEN_STALE
16 (10)
IEA_SLEEP_DISRUPTED
20 (14)
IEA_SPACE_TERMINATING
24 (18)
IEA_LOCK_HELD
32 (20)
IEA_PE_BAD_STATE
36 (24)
IEA_UNSUPPORTED_MVS_RELEASE
40 (28)
IEA_INVALID_AUTHCODE
44 (2C)
IEA_INVALID_MODE
60 (3C)
IEA_AUTH_TOKEN
64 (40)
IEA_PE_NOT_HOME
4095 (FFF)
IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET be returned on Pause or Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: RTM has ended the task; no release is necessary.
Action
: None.
Meaning
: The address space that contains the task is terminating; no release is necessary.
Action
: None.
Meaning
: Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The pause element associated with the pause element token specified is not valid or has already been prereleased.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The auth_level value specified in the call is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was allocated with auth_level=AUTHORIZED. The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was for a pause element allocated to another address.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action
: Contact IBM support.
330
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 46. IEA4RLS2 — Release
Description
Call IEA4RLS2 service to remove a task or SRB that has been paused, or to keep a task or SRB from being paused.
Although a pause element can be used multiple times to pause a task or SRB, a pause element token can be used to successfully pause and release a task or SRB only once. Each time a pause element is used, the system generates a new PET to identify the pause element. The system returns the new updated PET on calls to the pause and transfer services.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
64-bit
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB) or load the calling program and then call the service.
The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Release cannot be used by tasks that are higher in the task tree than the cross memory resource owning task (the top, or first, job step task in the address space).
Input register information
Before calling the Release service, the caller must ensure that the following general purpose (GPRs) contain the specified information:
Register
Contents
© Copyright IBM Corp. 1988, 2017
331
IEA4RLS2 callable service
1
13
Address of the parameter address list.
Address of a 144-byte register save area.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4RLS2
,(return_code
,target_du_pause_element_token
,target_du_release_code
,linkage)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v
Length: 4 bytes
Contains the return from the Release service.
332
z/OS MVS Assembler Services Reference IAR-XCT
IEA4RLS2 callable service
,target_du_pause_element_token
Supplied parameter v
Type: Character string v Character Set: N/A v Length: 16 bytes
Contains the pause element token that identifies the pause element used to pause a task or SRB. If the PET identifies a pause element that has not been paused, the task is paused. However, the value specified in target_du_release_code is returned to the caller of pause.
,target_du_release_code
Supplied parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
Contains the release code returned to the caller of pause or transfer service that used or will use the same PET to pause a task or SRB. If the program is not using this code for communication, set this field to zero.
linkage
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Specifies how the Release service routine is to be invoked. The following options are supported:
Variable
IEA_LINKAGE_SVC
IEA_LINKAGE_BRANCH
Value (hexadecimal) Meaning
0 The Release service routine will be invoked by an SVC linkage. This option can be used when in non-cross memory task mode, in any key, and either problem state or supervisor state.
1 The Release service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in SRB mode.
ABEND codes
None.
Return code in:
Decimal (Hex)
00 (00)
Return codes
When the service returns control to the resource manager, GPR 15 and the return_code parameter contain a hexadecimal return code.
Equate symbol Meaning and Action
IEA_SUCCESS
Meaning:
Successful completion.
Action:
None.
Chapter 46. IEA4RLS2 — Release
333
IEA4RLS2 callable service
Return code in:
Decimal (Hex)
04 (04)
Equate symbol
IEA_PE_TOKEN_BAD
08 (08) IEA_PE_TOKEN_STALE
16 (10)
20 (14)
24 (18)
IEA_SLEEP_DISRUPTED
IEA_SPACE_TERMINATING
IEA_LOCK_HELD
32 (20) IEA_PE_BAD_STATE
36 (24) IEA_UNSUPPORTED_MVS_RELEASE
44 (2C) IEA_INVALID_MODE
60 (3C) IEA_AUTH_TOKEN
64 (40) IEA_PE_NOT_HOME
Meaning and Action
Meaning:
The specified pause element token is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
The specified pause element token is stale; that is, it was valid but has been used on the Pause or
Transfer service. This service requires the updated
PET returned on Pause or Transfer.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
RTM has terminated the task or SRB; no release is necessary.
Action:
None
Meaning:
The address space that contains the task or
SRB is terminating; no release is necessary.
Action:
None
Meaning:
Program error. The caller is holding one or more locks; other than the local lock, CMS, or CPU lock, no locks may be held. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The pause element associated with the pause element token specified is invalid or has already been prereleased.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Environmental error. The system release does not support this service. The system rejects the service call.
Action:
Run the program on a system that supports the service.
Meaning:
Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The caller was in Problem state or key 8, but the pause element token was allocated with pause_element_auth_level=IEA_AUTHORIZED. The system rejects the service call.
Action:
Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning:
Program error. The pause element token was for a pause element allocated with pause_element_auth_level=IEA_UNAUTHORIZED to another address space.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
334
z/OS MVS Assembler Services Reference IAR-XCT
Return code in:
Decimal (Hex)
4095 (FFF)
Equate symbol
IEA_UNEXPECTED_ERROR
IEA4RLS2 callable service
Meaning and Action
Meaning:
This service routine encountered an unexpected error. The system rejects this service request.
Action:
Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM
Support Center.
Chapter 46. IEA4RLS2 — Release
335
IEA4RLS2 callable service
336
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 47. IEA4RPI — Retrieve_Pause_Element_Information service
|
Description
Call Retrieve_Pause_Element_Information to get information about a pause element. The information returned includes: v The authorization level of the pause element v The address space that currently owns the pause element v The current state (reset, prereleased, paused, or released) of the pause element v If the state of the pause element is prereleased or released, the release code of the pause element
An authorized program can use Retrieve_Pause_Element_Information to test the validity of a pause element passed by an unauthorized program. The authorized program can do this to ensure that it does not perform any operation, such as releasing the pause element, unless the unauthorized program is also able to perform the same operation.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
RMODE:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
64-bit
Includes 64-bit
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of calling program with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
None.
© Copyright IBM Corp. 1988, 2017
337
IEA4RPI callable service
Input register information
Before calling the Retrieve_Pause_Element_Information service, the caller does not need to place any information into any register, unless using it in register notation for the parameters, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
14
15
Used as work registers by the system
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4RPI
,(return_code
,auth_level
,pause_element_token
,authorization
,owner
,state
,release_code)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer
338
z/OS MVS Assembler Services Reference IAR-XCT
IEA4RPI callable service
v Character Set: N/A v
Length: 4 bytes
Contains the return code from the Retrieve_Pause_Element_Information service.
,auth_level
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Indicates the caller's authorization level. The following levels are supported:
IEAASM and IEAC define constants IEA_UNAUTHORIZED and
IEA_AUTHORIZED, which can be used by the calling program.
Variable
IEA_UNAUTHORIZED
IEA_AUTHORIZED
Value (hexadecimal) Meaning
0 The caller is not key 0 and supervisor state.
1 The caller is both key 0 and supervisor state.
,pause_element_token
Supplied parameter v
Type: Character string v Character Set: N/A v Length: 16 bytes
A pause element token that identifies the pause element for which information will be returned. You can obtain the PET from the Allocate_Pause_Element service.
,authorization
Returned parameter v Type: Integer v Character Set: N/A v
Length: 4 bytes
The authorization level of the creator of the pause element specified by the input PET.
One of the following values:
IEAASM and IEAC defined constants Value (hexadecimal) Meaning
IEA_UNAUTHORIZED 0 The caller is not key 0 and supervisor state.
IEA_AUTHORIZED 1
IEA_UNAUTHORIZED +
IEA_CHECKPOINTOK
IEA_AUTHORIZED +
IEA_CHECKPOINTOK
2
3
The caller is not key 0 and supervisor state.
Unauthorized PET that can tolerate the pause elements' not being restored upon a restart after a checkpoint.
Authorized PET that can tolerate the pause elements' not being restored upon a restart after a checkpoint.
,owner
Returned parameter v Type: Character string
Chapter 47. IEA4RPI — Retrieve_Pause_Element_Information service
339
IEA4RPI callable service
v Character Set: N/A v
Length: 8 bytes
The Stoken of the address space that currently owns the pause element specified by the input PET.
,state
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
The state of the pause element specified by the input PET.
Note:
The value returned is the state at the time the service obtained it. The state might have changed after it was obtained.
Meaning State Constant
Hexadecimal
(Decimal)
IEA4_PET_PRERELEASED
1
(1)
IEA4_PET_RESET
2
(2)
The PE was released before any task or SRB was suspended on it, and no task or SRB has attempted to pause it.
IEA4_PET_RELEASED
40
(64)
IEA4_PET_PAUSED
80
(128)
The PE is not being used to make any task or SRB nondispatchable. If the PE is used in an attempt to pause the current task or SRB, the task or SRB will be made nondispatchable.
The task RB or SRB is currently dispatchable, but control has not been returned to the task or SRB following a call to the Pause or Transfer service.
A call to the Release or Transfer service has released the task or SRB. In either case, control has not been returned to the caller of the Pause or Transfer service. The system has not transited the PE into the RESET state.
A task RB or SRB is currently nondispatchable. Its dispatchability is controlled by the PE.
,release_code
Returned parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
The release code is specified by the issuer of the release service, which can release the task or SRB from the paused condition.
Note:
The returned value is random if the state parameter is not
IEA4_PET_RELEASED or IEA4_PET_PRERELEASED.
ABEND codes
None.
340
z/OS MVS Assembler Services Reference IAR-XCT
IEA4RPI callable service
Return codes
When the service returns control to your program, GPR 15 contains one of the following return codes:
Return code in: Decimal
(Hex)
00 (00)
Equate symbol
IEA_SUCCESS
04 (04)
08 (08)
24 (18)
36 (24)
Meaning and Action
IEA_PE_TOKEN_BAD
IEA_PE_TOKEN_STALE
IEA_LOCK_HELD
Meaning
: Successful completion.
Action
: None.
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET returned on Pause or Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
IEA_UNSUPPORTED_MVS_RELEASE
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
44 (2C)
60 (3C)
64 (40)
IEA_INVALID_MODE
IEA_AUTH_TOKEN
IEA_PE_NOT_HOME
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The caller specified an unauthorized auth_level type, but a pause element token allocated with an authorized auth_level type was encountered. The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning
: Program error. The caller specified an unauthorized auth_level type, but a pause element token for a pause element allocated to another address space was specified.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 47. IEA4RPI — Retrieve_Pause_Element_Information service
341
IEA4RPI callable service
Return code in: Decimal
(Hex)
4095 (FFF)
Equate symbol
IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action:
Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center.
342
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 48. IEA4RPI2 — Retrieve_Pause_Element_Information service
|
Description
Call Retrieve_Pause_Element_Information to get information about a pause element. The information returned includes: v The authorization level of the pause element v The address space that currently owns the pause element v The current state (reset, prereleased, paused, or released) of the pause element v If the state of the pause element is prereleased or released, the release code of the pause element
An authorized program can use Retrieve_Pause_Element_Information to test the validity of a pause element passed by an unauthorized program. The authorized program can do this to ensure that it does not perform any operation, such as releasing the pause element, unless the unauthorized program is also able to perform the same operation.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
RMODE:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
64-bit
Includes 64-bit
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of calling program with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
© Copyright IBM Corp. 1988, 2017
343
IEA4RPI2 callable service
Input register information
Before calling the Retrieve_Pause_Element_Information service, the caller does not need to place any information into any register, unless using it in register notation for the parameters, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
14
15
Used as work registers by the system
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4RPI2
,(return_code
,pause_element_token
,linkage
,owner
,current_stoken
,authorization
,state
,release_code)
Parameters
The parameters are explained as follows:
return_code
Returned parameter
344
z/OS MVS Assembler Services Reference IAR-XCT
IEA4RPI2 callable service
v Type: Integer v
Character Set: N/A v Length: 4 bytes
Contains the return code from the Retrieve_Pause_Element_Information service.
,pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
A pause element token that identifies the pause element for which information will be returned. You can obtain the PET from the Allocate_Pause_Element service.
linkage
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Specifies how the Retrieve_Pause_Element_Information service routine is to be invoked. The following options are supported:
Variable
IEA_LINKAGE_SVC
IEA_LINKAGE_BRANCH
Value (hexadecimal) Meaning
0 The
Retrieve_Pause_Element_Information service routine will be invoked by an
SVC linkage. This option can be used when in non-cross memory task mode, in any key, and in either problem state or supervisor state.
1 The
Retrieve_Pause_Element_Information service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state.
This option must be selected when in
SRB mode.
,owner
Returned parameter v Type: Character string v Character Set: N/A v Length: 8 bytes
The Stoken of the address space that currently owns the pause element specified by the input PET.
,current_stoken
Returned parameter v Type: Character string v Character Set: N/A v Length: 8 bytes
Chapter 48. IEA4RPI2 — Retrieve_Pause_Element_Information service
345
IEA4RPI2 callable service
|
|
|
|
If the value returned in state is IEA_PET_PAUSED, The stoken of the home address space of the task or SRB which is paused by the specified pause element. If the value in state is not IEA_PET_PAUSED, the information returned in this parameter is undefined.
,authorization
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
The authorization level of the creator of the pause element specified by the input PET.
One of the following values:
IEAASM and IEAC defined constants Value (hexadecimal) Meaning
IEA_UNAUTHORIZED 0 The caller is not supervisor state or not key 0.
IEA_AUTHORIZED 1
IEA_UNAUTHORIZED +
IEA_CHECKPOINTOK
IEA_AUTHORIZED +
IEA_CHECKPOINTOK
2
3
The caller is supervisor state and key
0.
Unauthorized PET that can tolerate the pause elements' not being restored upon a restart after a checkpoint.
Authorized PET that can tolerate the pause elements' not being restored upon a restart after a checkpoint.
,state
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
The state of the pause element specified by the input PET.
Note:
The value returned is the state at the time the service obtained it. The state might have changed after it was obtained.
Meaning State Constant
Hexadecimal
(Decimal)
IEA4_PET_PRERELEASED
1
(1)
IEA4_PET_RESET
2
(2)
The PE was released before any task or SRB was suspended on it, and no task or SRB has attempted to pause it.
IEA4_PET_RELEASED
40
(64)
The PE is not being used to make any task or SRB nondispatchable. If the PE is used in an attempt to pause the current task or SRB, the task or SRB will be made nondispatchable.
The task RB or SRB is currently dispatchable, but control has not been returned to the task or SRB following a call to the Pause or Transfer service.
A call to the Release or Transfer service has released the task or SRB. In either case, control has not been returned to the caller of the Pause or Transfer service. The system has not transited the PE into the RESET state.
346
z/OS MVS Assembler Services Reference IAR-XCT
IEA4RPI2 callable service
State Constant
Hexadecimal
(Decimal)
IEA4_PET_PAUSED
80
(128)
Meaning
A task RB or SRB is currently nondispatchable. Its dispatchability is controlled by the PE.
,release_code
Returned parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
The release code is specified by the issuer of the release service, which can release the task or SRB from the paused condition.
Note:
The returned value is random if the state parameter is not
IEA4_PET_RELEASED or IEA4_PET_PRERELEASED.
ABEND codes
None.
Return codes
When the service returns control to your program, GPR 15 contains one of the following return codes:
Meaning and Action Return code in:
Decimal (Hex)
00 (00)
Equate symbol
IEA_SUCCESS
04 (04)
08 (08)
24 (18)
36 (24)
IEA_PE_TOKEN_BAD
IEA_PE_TOKEN_STALE
IEA_LOCK_HELD
IEA_UNSUPPORTED_MVS_RELEASE
Meaning
: Successful completion.
Action
: None.
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET returned on
Pause or Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Chapter 48. IEA4RPI2 — Retrieve_Pause_Element_Information service
347
IEA4RPI2 callable service
Return code in:
Decimal (Hex)
40 (28)
Equate symbol
IEA_INVALID_AUTHCODE
44 (2C) IEA_INVALID_MODE
60 (3C) IEA_AUTH_TOKEN
64 (40) IEA_PE_NOT_HOME
4095 (FFF) IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning:
Program error. The pause_element_auth_level value specified in the call is not valid. The system rejects the service call.
Action:
Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The caller was in Problem state or key 8, but the pause element token was allocated with pause_element_auth_level=IEA_AUTHORIZED. The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning
: Program error. The pause element token was for a pause element allocated with pause_element_auth_level=IEA_UNAUTHORIZED to another address space.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action:
Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center.
348
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 49. IEA4TPE — Test_Pause_Element service
Description
Call Test_Pause_Element to test a pause element and determine its state. If the state is prereleased or released, the release code of the pause element also is returned.
To ensure minimal overhead when you use the service, Test_Pause_Element establishes no recovery. You are responsible for supplying any needed recovery to handle errors that occur because of the incorrect input pause element tokens or call state errors.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
64-bit
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
None.
Input register information
Before calling the Test_Pause_Element service, the caller does not have to place any information into any register, unless using the input register in register notation for the parameters, or using the input register as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
© Copyright IBM Corp. 1988, 2017
349
IEA4TPE callable service
0-1
2-13
14
15
Used as work registers by the system
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4TPE
,(return_code
,pause_element_token
,state
,release_code)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return code from the Test_Pause_Element service.
,pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v
Length: 16 bytes
A pause element token that identifies the pause element for which information is to be returned. You can obtain the PET from the Allocate_Pause_Element service.
350
z/OS MVS Assembler Services Reference IAR-XCT
IEA4TPE callable service
,state
Returned parameter v
Type: Integer v Character Set: N/A v Length: 4 bytes
The state of the pause element specified by the input PET.
Note:
The value returned is the state at the time the service obtained it. The state might have changed after it was obtained.
Meaning State Constant
Hexadecimal
(Decimal)
IEA4_PET_PRERELEASED
1
(1)
IEA4_PET_RESET
2
(2)
The PE was released before any task or SRB was suspended on it, and no task or SRB has attempted to pause it.
IEA4_PET_RELEASED
40
(64)
IEA4_PET_PAUSED
80
(128)
The PE is not being used to make any task or SRB nondispatchable. If the PE is used in an attempt to pause the current task or SRB, the task or SRB is made nondispatchable.
The task RB or SRB is currently dispatchable, but control has not been returned to the task or SRB following a call to the Pause or Transfer service.
A call to the release or transfer service has released the task or SRB. In either case, control has not been returned to the caller of the pause or transfer service. The system has not change the PE into the RESET state.
A task RB or SRB is currently nondispatchable. Its dispatchability is controlled by the PE.
,release_code
Returned parameter v Type: Character string v Character Set: N/A v
Length: 3 bytes
The release code is specified by the issuer of the Release service, which released the task or SRB from the paused condition.
Note:
The returned value is random if the state parameter is not
IEA4_PET_RELEASED or IEA4_PET_PRERELEASED.
ABEND codes
None.
Return codes
When the service returns control to your program, GPR 15 contains one of the following return codes:
Chapter 49. IEA4TPE — Test_Pause_Element service
351
IEA4TPE callable service
Return code in:
Decimal
(Hex)
00 (00)
Equate symbol
IEA_SUCCESS
04 (04) IEA_PE_TOKEN_BAD
08 (08) IEA_PE_TOKEN_STALE
Meaning and Action
Meaning
: Successful completion.
Action
: None.
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or
Transfer service. This service requires the updated PET returned on Pause or Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
352
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 50. IEA4XFR — Transfer service
|
Description
Call IEA4XFR service to release a paused task, and, when possible, give the task immediate control. This service can also, optionally, pause the task under which the transfer request is made. If the caller does not request that its task be paused, the caller's task remains dispatchable.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
RMODE:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
64-bit
Includes 64-bit
Primary mode.
Enabled for I/O and external interrupts
No Locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the object code of the calling program with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB), or load the calling program and then call the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
When the calling program specifies auth_level=IEA_UNAUTHORIZED, the caller must be in task mode and can only transfer to another task in its home address space. All pause element tokens (PETs) used when auth_level=IEA_UNAUTHORIZED must have been obtained using an authorization level of IEA_UNAUTHORIZED.
Input register information
Before calling the Transfer service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter address list.
Address of a 144-byte register save area.
© Copyright IBM Corp. 1988, 2017
353
IEA4XFR callable service
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-14
15
Unchanged
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4XFR
,(return_code
,auth_level
,current_du_pause_element_token
,updated_pause_element_token
,current_du_release_code
,target_du_pause_element_token
,target_du_release_code)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v
Length: 4 bytes
Contains the return code from the transfer service.
354
z/OS MVS Assembler Services Reference IAR-XCT
IEA4XFR callable service
,auth_level
Supplied parameter v
Type: Integer v Character Set: N/A v Length: 4 bytes
Indicates the maximum authorization level of the pause element being deallocated. The calling program can use constant IEA_UNAUTHORIZED that is defined by IEAASM and IEAC. The following levels are supported:
Variable
IEA_UNAUTHORIZED
Value (HEX) Meaning
0 The pause elements must have been allocated with auth_level=_UNAUTHORIZED.
,current_du_pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains a pause element token that identifies the pause element used to pause the current task. When a PET is used on a call to the pause service, it cannot be reused on a second call to pause or as a current_du_pause_element_token on transfer. A new PET is returned to updated_pause_element_token. The new PET now properly defines the pause element and should be used the next time when a pause, transfer, release, or deallocate_pause_element request is using the same pause element.
If the value specified is 16-bytes of binary zeros, the current task will not be paused. The updated_pause_element_token and current_du_release_code are unpredictable.
CAUTION:
Do not specify the same PET for both current_du_pause_element_token and target_pause_element_token.
,updated_pause_element_token
Returned parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains a new pause element token that identifies the pause element originally identified by the PET specified in current_du_pause_element_token.
The PET originally specified in current_du_pause_element_token cannot be reused after a successful call to pause or transfer service.
If you set the current_du_pause_element_token to zeros, the contents of updated_pause_element_token are unpredictable.
,current_du_release_code
Returned parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
Chapter 50. IEA4XFR — Transfer service
355
IEA4XFR callable service
Contains the release code set by the issuer of the release or transfer service that released the current task from the paused condition.
If you set the current_du_pause_element_token to zero, the contents are unpredictable.
,target_du_pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains a pause element token that identifies the pause element to release the target task. Any PET that specifies a pause element not currently being used to pause a task is valid. When a PET for a previously released pause element is used to try to pause a task, the task is not paused; however, the value specified in target_du_release_code will still be returned to the caller of pause or transfer service.
If the task was paused and is now dispatchable, the task will immediately be given control on the current processor.
CAUTION:
Do not use the same PET for both current_du_pause_element_token and target_du_pause_element_token.
,target_du_release_code
Supplied parameter v Type: Character string v
Character Set: N/A v Length: 3 bytes
Contains the release code returned to the caller of the pause or transfer service that used (or will use) the same PET to pause a task.
ABEND codes
None.
Return codes
When the service returns control to the resource manager, GPR 15 and the return_code parameter contain a hexadecimal return code.
Meaning and Action Return Code in: Decimal
(Hex)
00 (00)
Equate symbol
IEA_SUCCESS
04 (04) IEA_PE_TOKEN_BAD
Meaning
: Successful completion.
Action
: None.
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
356
z/OS MVS Assembler Services Reference IAR-XCT
IEA4XFR callable service
Return Code in: Decimal
(Hex)
08 (08)
Equate symbol
IEA_PE_TOKEN_STALE
12 (0C)
16 (10)
20 (14)
24 (18)
32 (20)
36 (24)
40 (28)
Meaning and Action
IEA_DUPLICATE_PAUSE
IEA_SLEEP_DISRUPTED
IEA_SPACE_TERMINATING
IEA_LOCK_HELD
IEA_PE_BAD_STATE
IEA_UNSUPPORTED_MVS_RELEASE
IEA_INVALID_AUTHCODE
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or Transfer service. This service requires the updated PET returned on Pause or
Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The work unit has already been paused using the specified pause element token. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: RTM has terminated the task; no release is necessary.
Action
: None
Meaning
: The address space that contains the task is terminating; no release is necessary.
Action
: None
Meaning
: Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The pause element associated with the pause element token specified in the call is not in a valid state. The system rejects the service call.
Action
: Check the calling program for a probable coding error, such as attempting to perform a Pause or
Transfer using a pause element token that has already been used to Pause or
Transfer by another unit of work.
Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The auth_level value specified in the call is not valid.
The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Chapter 50. IEA4XFR — Transfer service
357
IEA4XFR callable service
Return Code in: Decimal
(Hex)
44 (2C)
Equate symbol
IEA_INVALID_MODE
52 (34) IEA_ALREADY_SUSPENDED
60 (3C) IEA_AUTH_TOKEN
64 (40)
68 (44)
72 (48)
4095 (FFF)
IEA_PE_NOT_HOME
IEA_XFER_TO_SELF
IEA_XFER_FAILED
IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The pause element was already paused.
Action
: Check the calling program for a probable coding error and correct the program and rerun it.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was allocated with auth_level=AUTHORIZED. The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Meaning
: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was for a pause element allocated to another address.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning:
Program error. The specified current_du_pause_element_token and target_du_pause_element_token are the same.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The transfer failed, and the current_du_pause_element_token is no longer useable.
Action
: Reissue the transfer request using the updated_du_pause_element_token.
Deallocate the current_du_pause_element_token.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action:
Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support
Center.
358
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 51. IEA4XFR2 — Transfer service
|
Description
Call IEA4XFR2 service to release a paused task or SRB, and, when possible, give the task or SRB immediate control. This service can also, optionally, pause the task or SRB under which the transfer request is made. If the caller does not request that its task or SRB be paused, the caller's task or SRB remains dispatchable.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
RMODE:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
64-bit
Includes 64-bit
Primary mode.
Enabled for I/O and external interrupts.
No locks held.
Must be in the primary address space and addressable by the caller.
Programming requirements
Either link the calling program's object code with the linkable stub routine
(IEA4CSS from SYS1.CSSLIB) or load the calling program and then call the service.
The high-level language (HLL) definitions for the callable service are:
HLL Definition
IEAASM
IEAC
Description
390 Assembler declarations
C/390 and C++/390 declarations
Restrictions
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Transfer cannot be used by tasks that are higher in the task tree than the cross memory resource owning task (the top, or first, job step task in the address space).
Input register information
Before calling the Transfer service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
Address of the parameter address list.
13
Address of a 144-byte register save area.
© Copyright IBM Corp. 1988, 2017
359
IEA4XFR2 callable service
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-14
15
Unchanged
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Syntax
SYSSTATE AMODE64=YES
Description
CALL IEA4XFR2
,(return_code
,current_du_pause_element_token
,updated_pause_element_token
,current_du_release_code
,target_du_pause_element_token
,target_du_release_code
,linkage)
Parameters
The parameters are explained as follows:
return_code
Returned parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Contains the return code from the Transfer service.
,current_du_pause_element_token
Supplied parameter
360
z/OS MVS Assembler Services Reference IAR-XCT
IEA4XFR2 callable service
v Type: Character string v
Character Set: N/A v Length: 16 bytes
Contains a pause element token that identifies the pause element that is being or will be used to pause a task or SRB. When a PET is used on a call to the pause service, it cannot be reused on a second call to pause or as a current_du_pause_element_token on transfer. A new PET is returned to update_pause_element_token. The new PET now properly defines the pause element and should be used the next time when a pause, transfer, release, or deallocate_pause_element request is using the same pause element.
If the value specified is 16-bytes of binary zeros, the current task or SRB will not be paused. The updated_pause_element_token and current_du_release_code are unpredictable.
CAUTION:
Do not specify the same PET for both current_du_pause_element_token and target_pause_element_token.
,updated_pause_element_token
Returned parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains a new pause element token that identifies the pause element originally identified by the PET specified in current_du_pause_element_token.
The PET originally specified in current_du_pause_element_token cannot be reused after a successful call to Pause or Transfer.
If you set the current_du_pause_element_token to zeros, the contents of updated_pause_element_token are unpredictable.
,current_du_release_code
Returned parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
Contains the release code set by the issuer of the release or transfer service that released the current task or SRB from the paused condition.
If you set the current_du_pause_element_token to zero, the contents are unpredictable.
,target_du_pause_element_token
Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes
Contains a pause element token that identifies a pause element that is being or will be used to pause a task or SRB. If the task or SRB is paused, it will be released, and, if possible, be given control. If the task or SRB is not paused using the specified pause element, it will not be paused when an attempt to pause is made. In either case the task or SRB will be returned the value specified in target_release_code.
Chapter 51. IEA4XFR2 — Transfer service
361
IEA4XFR2 callable service
CAUTION:
Do not use the same PET for both current_du_pause_element_token and target_du_pause_element_token.
,target_du_release_code
Supplied parameter v Type: Character string v Character Set: N/A v Length: 3 bytes
Contains the release code returned to the caller of the pause or transfer service used (or will use) the PET specified in target_du_pause_element_token to pause a task or SRB.
linkage
Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes
Specifies how the Transfer service routine is to be invoked. The following options are supported:
Variable
IEA_LINKAGE_SVC
IEA_LINKAGE_BRANCH
Value (hexadecimal) Meaning
0
1
The Transfer service routine will be invoked by an SVC linkage. This option can be used when in non-cross memory task mode, in any key, and either problem state or supervisor state.
The Transfer service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in SRB mode.
ABEND codes
None.
Return Code in:
Decimal (Hex)
00 (00)
Return codes
When the service returns control to the resource manager, GPR 15 and the return_code parameter contain a hexadecimal return code.
Equate symbol Meaning and Action
IEA_SUCCESS
04 (04)
08 (08)
IEA_PE_TOKEN_BAD
IEA_PE_TOKEN_STALE
Meaning
: Successful completion.
Action
: None
Meaning
: Program error. The specified pause element token is not valid. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The specified pause element token is stale; that is, it was valid but has been used on the Pause or
Transfer service. This service requires the updated
PET returned on Pause or Transfer.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
362
z/OS MVS Assembler Services Reference IAR-XCT
Return Code in:
Decimal (Hex)
12 (0C)
Equate symbol
IEA_DUPLICATE_PAUSE
16 (10)
20 (14)
24 (18)
IEA_SLEEP_DISRUPTED
IEA_SPACE_TERMINATING
IEA_LOCK_HELD
32 (20) IEA_PE_BAD_STATE
36 (24) IEA_UNSUPPORTED_MVS_RELEASE
44 (2C) IEA_INVALID_MODE
52 (34)
60 (3C)
IEA_ALREADY_SUSPENDED
IEA_AUTH_TOKEN
IEA4XFR2 callable service
Meaning and Action
Meaning
: The work unit has already been paused using the specified pause element token. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: RTM has terminated the task or SRB; no release is necessary.
Action
: None
Meaning
: The address space that contains the task or
SRB is terminating; no release is necessary.
Action
: None
Meaning
: Program error. If a current_du_pause_element_token of 16 bytes of binary zeros is specified, one or more locks other than the local lock are held. Otherwise, one or more locks are held. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The pause element associated with the pause element token specified in the call is not in a valid state. The system rejects the service call.
Action
: Check the calling program for a probable coding error, such as attempting to perform a Pause or
Transfer using a pause element token that has already been used to Pause or Transfer by another unit of work. Correct the program and rerun it.
Meaning
: Environmental error. The system release does not support this service. The system rejects the service call.
Action
: Run the program on a system that supports the service.
Meaning
: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The pause element was already paused.
Action
: Check the calling program for a probable coding error and correct the program and rerun it.
Meaning:
Program error. The caller was in Problem state or key 8, but the pause element token was allocated with pause_element_auth_level=IEA_AUTHORIZED. The system rejects the service call.
Action
: Program error. The specified pause element token is not valid. The system rejects the service call.
Chapter 51. IEA4XFR2 — Transfer service
363
IEA4XFR2 callable service
Return Code in:
Decimal (Hex)
64 (40)
Equate symbol
IEA_PE_NOT_HOME
68 (44) IEA_XFER_TO_SELF
72 (48) IEA_XFER_FAILED
4095 (FFF) IEA_UNEXPECTED_ERROR
Meaning and Action
Meaning
: Program error. The pause element token was for a pause element allocated with pause_element_auth_level=IEA_UNAUTHORIZED to another address space.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: Program error. The specified current_du_pause_element_token and target_du_pause_element_token are the same.
Action
: Check the calling program for a probable coding error. Correct the program and rerun it.
Meaning
: The transfer failed, and the current_du_pause_element_token is no longer usable.
Action
: Reissue the transfer request using the updated_du_pause_element_token. Deallocate the current_du_pause_element_token.
Meaning
: This service routine encountered an unexpected error. The system rejects this service request.
Action:
Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM
Support Center.
364
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 52. IEFDDSRV — DD service
Description
Use the IEFDDSRV macro to obtain or modify DD-related information to its caller.
The IEFDDSRV service currently performs the following functions:
RETRIEVE DEVENTRY
Returns the unit control block (UCB) addresses of the devices allocated to the input DD request. For DDs that are allocated with the NOCAPTURE option, the addresses of the actual UCBs are returned; otherwise, the addresses of the captured UCBs are returned for above 16MB devices, and the addresses of the actual UCBs are returned for below 16MB devices.
EXTRACT TYPE=DEVIOENTRY
Returns the UCB addresses and selected I/O information of the devices allocated to the input DD request. Regardless of options specified on the allocation request, the 31-bit addresses of the actual UCBs are returned for all devices.
MODIFY TYPE=FEATURE
Sets the allocation feature according to the input specification. This function only affects future allocation requests, and does not affect existing batch and dynamic allocations that are initiated before the MODIFY FEATURE request.
MODIFY TYPE=ALLOCATION
Updates an outstanding DD allocation in all of the associated allocation and scheduler component control blocks, such as the TIOT, SIOT, and so on.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem or supervisor state, and any PSW key.
Task.
v PASN=HASN=SASN for MODIFY TYPE=ALLOCATION and MODIFY TYPE=FEATURE.
v
Any PASN, any HASN, any SASN for all other functions.
24- or 31-bit.
Primary or Access register (AR).
Enabled for I/O and external interrupts.
v For RETRIEVE DEVENTRY and EXTRACT
TYPE=DEVIOENTRY, authorized callers may hold the local lock. Non-authorized callers cannot hold any locks.
v For MODIFY, no locks may be held.
Control parameters must be in the primary address space.
Programming requirements
v For RETRIEVE DEVENTRY and EXTRACT TYPE=DEVIOENTRY:
If your program is authorized, there are certain situations when your program must provide or inherit serialization on the SYSZTIOT resource before using
UCB addresses that are returned from the IEFDDSRV macro. The situations are one of the following:
© Copyright IBM Corp. 1988, 2017
365
IEFDDSRV macro
– You code the DDNAME parameter.
– You code the DSABPTR parameter and your program does not have a DCB or ACB that has been open to the DD name since your program got the DSAB address.
If an authorized caller supplies the address of a DCB or ACB, this serialization is not necessary, and the returned UCB information remains valid until the DCB or
ACB is closed. This serialization is also not necessary if your program codes
DSABPTR and has a DCB or ACB that has been open since the program got the
DSAB address.
For unauthorized callers, this service ensures that the TIOT resource is properly serialized during its execution.
For more information, see "Serialization of Resources" under "Programming considerations for using the DYNALLOC macro" in z/OS MVS Programming:
Authorized Assembler Services Guide.
v For MODIFY ALLOCATION and MODIFY FEATURE:
An authorized caller may hold exclusive serialization on the SYSZTIOT resource.
If not provided, the IEFDDSRV service obtains and holds the resource while performing the requested function, and releases it before returning to the caller.
Authorized callers holding SYSZTIOT shared will be failed with return code 12, reason 12 (DDSRV_TIOTENQ_FAIL).
For unauthorized callers, the IEFDDSRV service obtains and releases the necessary SYSZTIOT serialization on behalf of the caller. For more information, see "Serialization of Resources" under "Programming considerations for using the DYNALLOC macro" in z/OS MVS Programming: Authorized Assembler Services
Guide.
Restrictions
In cross-memory mode: v For RETRIEVE DEVENTRY, EXTRACT TYPE=DEVIOENTRY and MODIFY
TYPE=FEATURE:
When running in cross-memory mode, the DSAB/TIOT information is obtained from the user's home address space.
v For MODIFY TYPE=ALLOCATION:
Cross-memory mode is not supported.
Using the returned UCBs: v
For RETRIEVE DEVENTRY:
The user must ensure that the UCBs are not dynamically deleted.
The returned UCB addresses may be either 31-bit accessible actual UCB addresses or 24-bit accessible actual or captured UCB addresses. A captured UCB address is only valid in the address space in which it is originally allocated. The returned UCB addresses are only valid if the devices remain allocated after the execution of the DD service.
In some cases, this service may not return a device UCB, but instead may return a zero UCB address or the address of a dummy UCB. This may occur for DDs that represent DD DUMMY requests, VIO data sets, SYSOUT data sets, in-stream data sets, and some SMS-managed data sets. A dummy UCB can be identified using the UCBDUMMY field in the UCB. A dummy UCB may not have all of the UCB segments that a device UCB may have and not all services that are used for processing device UCBs may support dummy UCBs.
v For EXTRACT TYPE=DEVIOENTRY:
366
z/OS MVS Assembler Services Reference IAR-XCT
⌂
Syntax
name
IEFDDSRV macro
The user must ensure that the UCBs are not dynamically deleted.
The returned UCB addresses are always uncaptured UCB addresses and remain valid unless the UCBs are dynamically deleted.
In some cases, this service may not return a device UCB, but instead may return a zero UCB address or the address of a dummy UCB. This may occur for DDs that represent DD DUMMY requests, VIO data sets, SYSOUT data sets, in-stream data sets, and some SMS-managed data sets. A dummy UCB can be identified using the UCBDUMMY field in the UCB. A dummy UCB may not have all of the UCB segments that a device UCB may have and not all services that are used for processing device UCBs may support dummy UCBs.
v This macro supports multiple versions. Some keywords are unique to certain versions. See the PLISTVER parameter description.
Input register information
There are no input register requirements for issuing the IEFDDSRV macro.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code
2-13
Used as a work register by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Performance implications
None.
Syntax
The standard form of the IEFDDSRV macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede IEFDDSRV.
IEFDDSRV
Chapter 52. IEFDDSRV — DD service
367
IEFDDSRV macro
Syntax Description
⌂ One or more blanks must follow IEFDDSRV.
RETRIEVE
,DEVENTRY
,DDNAME=ddname
,DSABPTR=dsabptr
,DCBPTR=dcbptr
,ACBPTR=acbptr
,SUBPOOL=subpool
,DEVAREA=devarea
,LOC=BELOW
,LOC=ANY
EXTRACT
,TYPE=DEVIOENTRY
,DDNAME=ddname
,DSABPTR=dsabptr
,DCBPTR=dcbptr
,ACBPTR=acbptr
,SUBPOOL=subpool
,DEVIOAREA=devioarea
MODIFY
,TYPE=ALLOCATION
,DDNAME=ddname
,DSABPTR=dsabptr
,NEWDDNAME=newddname
,TYPE=FEATURE
,DSENQMGMT=NO_CHANGE
,DSENQMGMT=MEMORY
,TCBPTR=tcbptr
,RETCODE=retcode
,RSNCODE=rsncode
ddname: RS-type address or register (2) - (12) ASM only.
dsabptr: RS-type address or register (2) - (12) ASM only.
dcbptr: RS-type address or register (2) - (12) ASM only.
acbptr: RS-type address or register (2) - (12) ASM only.
subpool: RS-type address, or register (2)-(12) ASM only.
Default
: SUBPOOL=0
devarea: RS-type address or register (2) - (12).
Default
: LOC=BELOW
Default
: TYPE=DEVIOENTRY
ddname: RS-type address or register (2) - (12) ASM only.
dsabptr: RS-type address or register (2) - (12) ASM only.
dcbptr: RS-type address or register (2) - (12) ASM only.
acbptr: RS-type address or register (2) - (12) ASM only.
subpool: RS-type address, or register (2)-(12) ASM only.
Default
: SUBPOOL=0
devioarea: RS-type address, or register (2)-(12).
Default
: TYPE=ALLOCATION
ddname: RS-type address or register (2) - (12) ASM only.
dsabptr: RS-type address or register (2) - (12) ASM only.
newddname: RS-type address, or register (2)-(12).
tcbptr: RS-type address, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
368
z/OS MVS Assembler Services Reference IAR-XCT
IEFDDSRV macro
Syntax
,PLISTVER=1
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
Description
Default
: MF=S
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IEFDDSRV macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
RETRIEVE
EXTRACT
MODIFY
An optional input parameter.
RETRIEVE
Retrieve DD related information.
EXTRACT
Extract DD related information.
MODIFY
Modify an existing allocation or feature.
,DEVENTRY
A required input parameter when RETRIEVE is specified.
,DEVENTRY
Obtain the UCB address for the devices allocated to the request.
To code:
Specify a value.
,DDNAME=ddname
,DSABPTR=dsabptr
,DCBPTR=dcbptr
,ACBPTR=acbptr
A required input parameter when RETRIEVE and DEVENTRY are specified.
,DDNAME=ddname
One of a set of mutually exclusive keys. It is the name of an 8 character input that is left justified and padded with blanks. A DDNAME of all blanks is invalid. The DSAB/TIOT chain selected is the one associated with the current TCB, unless overridden by the TCBPTR parameter.
To code:
Specify the RS-type address of an 8-character field.
Chapter 52. IEFDDSRV — DD service
369
IEFDDSRV macro
,DSABPTR=dsabptr
One of a set of mutually exclusive keys. It is the name of a pointer input that contains the address of the DSAB associated with a DD name.
To code:
Specify the RS-type address of a pointer field.
,DCBPTR=dcbptr
One of a set of mutually exclusive keys. It is the name of a pointer input that contains the address of the DCB associated with a DD name. When
DCBPTR defines an open DCB, specifying TCBPTR has no effect and the current TCB is used. When DCBPTR defines a closed DCB, the DSAB chain selected is determined by the desired TCB, which is either the current TCB
(if TCBPTR is zero) or the TCB pointed to by TCBPTR. Do not use the
DCBPTR option for a DCB in a DCB OPEN or ABEND exit routine call for that DCB.
To code:
Specify the RS-type address of a pointer field.
,ACBPTR=acbptr
One of a set of mutually exclusive keys. It is the name of a pointer input that contains the address of the ACB associated with a DD name. If this
ACB is OPEN, the DSAB pointer is retrieved from the DEB extension associated with it. If this ACB is not OPEN, the DD name is taken from the
DCBDDNAM field in the DCB, and the DSAB address corresponding to this DD name is retrieved. When ACBPTR defines a DCB associated with an OPEN DD, ACBPTR is mutually exclusive with TCBPTR. The specified
TCBPTR is ignored and the current TCB is used. When ACBPTR defines a
ACB associated with a CLOSED DD, the DSAB chain selected is determined by the desired TCB, which is either the current TCB (if
TCBPTR is zero) or the TCB pointed to by TCBPTR.
To code:
Specify the RS-type address of a pointer field.
,SUBPOOL=subpool
,SUBPOOL=0
When RETRIEVE and DEVENTRY are specified, an optional input parameter that indicates which subpool to obtain the device area storage in. If this parameter is not specified, subpool 0 is used. The default value is 0.
To code:
Specify the RS-type address, or address in register (2)-(12), of a one-byte field.
,DEVAREA=devarea
The name of a required pointer output that contains the address of the device output area. This area is obtained in the user's key and the subpool specified by the user (or subpool 0, if not specified). If the DD name is specified or obtained from a closed DCB, all the devices allocated to the requested DD and its concatenated groups are returned. If the DSAB pointer is specified or obtained from an opened DCB, only devices allocated to the requested DSAB are returned. The device area format is as follows: v An 8 byte header containing
– A 1-byte field indicating the subpool in which the storage resides.
– A 3-byte field containing the size of the device area (including the header).
– A 4-byte field containing the number of device entry lists returned (a device entry list is returned for each DD in the concatenated group).
– An array of the device list addresses.
v An array of the device entry lists. Each list has the following format:
370
z/OS MVS Assembler Services Reference IAR-XCT
IEFDDSRV macro
– A 4-byte field containing the number of device entries in the list.
– An array of 4-byte entries containing the UCB addresses.
The device area is mapped by mapping macro IEFDISMP.
If IEFDDSRV returns with return code 0 and reason code 0, the system has obtained a storage area of the appropriate size in the requested key and subpool, and placed its address in devarea. You are responsible for releasing this storage. If the return code and reason codes are not 0, the system has not obtained the storage area; do not attempt to release the storage.
To code:
Specify the RS-type address, or address in register (2)-(12), of a pointer field.
,LOC=BELOW
,LOC=ANY
When RETRIEVE and DEVENTRY are specified, an optional parameter that indicates whether the DD Service should search all the DSABs or only those residing below the 16-megabyte line. This parameter is ignored for requests other than RETRIEVE DEVENTRY. The default is LOC=BELOW.
,LOC=BELOW
Requests that the DD Service search only those DSABs residing below the
16-megabyte line.
,LOC=ANY
Requests that the DD Service search all the DSABs.
,TYPE=DEVIOENTRY
An optional parameter when EXTRACT is specified. The default is
TYPE=DEVIOENTRY.
,TYPE=DEVIOENTRY
Obtain the UCB address and selected I/O information for the devices allocated to the request.
Note:
EXTRACT,TYPE=DEVIOENTRY is used to return I/O information, as opposed to RETRIEVE,DEVENTRY, which is used to retrieve information about devices allocated to a request. Although the two functions both return UCB information, due to the nature of the information they are meant to return, the two functions may return different device information. For example, a DD that was dynamically allocated with DD-level accounting suppressed via the S99DASUP flag in macro IEFZB4D0 will not have any device information returned with
EXTRACT,TYPE=DEVIOENTRY, but will have device information returned with RETRIEVE,DEVENTRY.
,DDNAME=ddname
,DSABPTR=dsabptr
,DCBPTR=dcbptr
,ACBPTR=acbptr
A required input parameter when EXTRACT and TYPE=DEVIOENTRY are specified.
,DDNAME=ddname
One of a set of mutually exclusive keys. It is the name of an 8 character input that is left justified and padded with blanks. A DDNAME of all blanks is invalid. The DSAB/TIOT chain selected is the one associated with the current TCB, unless overridden by the TCBPTR parameter.
To code:
Specify the RS-type address of an 8-character field.
Chapter 52. IEFDDSRV — DD service
371
IEFDDSRV macro
,DSABPTR=dsabptr
One of a set of mutually exclusive keys. It is the name of a pointer input that contains the address of the DSAB associated with a DD name.
To code:
Specify the RS-type address of a pointer field.
,DCBPTR=dcbptr
One of a set of mutually exclusive keys. It is the name of a pointer input that contains the address of the DCB associated with a DD name. If this
DCB is OPEN, the DSAB pointer is retrieved from the DEB extension associated with it. If this DCB is not OPEN, the DD name is taken from the
DCBDDNAM field in the DCB, and the DSAB address corresponding to this DD name is retrieved. When DCBPTR defines a DCB associated with an OPEN DD, DCBPTR is mutually exclusive with TCBPTR. The specified
TCBPTR is ignored and the current TCB is used. When DCBPTR defines a
DCB associated with a CLOSED DD, the DSAB chain selected is determined by the desired TCB, which is either the current TCB (if
TCBPTR is zero) or the TCB pointed to by TCBPTR.
To code:
Specify the RS-type address of a pointer field.
,ACBPTR=acbptr
One of a set of mutually exclusive keys. It is the name of a pointer input that contains the address of the ACB associated with a DD name. If this
ACB is OPEN, the DSAB pointer is retrieved from the DEB extension associated with it. If this ACB is not OPEN, the DD name is taken from the
DCBDDNAM field in the DCB, and the DSAB address corresponding to this DD name is retrieved. When ACBPTR defines a DCB associated with an OPEN DD, ACBPTR is mutually exclusive with TCBPTR. The specified
TCBPTR is ignored and the current TCB is used. When ACBPTR defines a
ACB associated with a CLOSED DD, the DSAB chain selected is determined by the desired TCB, which is either the current TCB (if
TCBPTR is zero) or the TCB pointed to by TCBPTR.
To code:
Specify the RS-type address of a pointer field.
,SUBPOOL=subpool
,SUBPOOL=0
When EXTRACT and TYPE=DEVIOENTRY are specified, an optional input parameter that indicates which subpool to obtain the device I/O area storage in. If this parameter is not specified, subpool 0 is used. The default is 0.
To code:
Specify the RS-type address, or address in register (2)-(12), of a one-byte field.
,DEVIOAREA=devioarea
When EXTRACT and TYPE=DEVIOENTRY are specified, a required output parameter that is to contain the address of the device output area. This area is obtained in the user's key and the subpool specified by the user (or subpool 0, if not specified). If the DD name is specified or obtained from a closed DCB, all the devices allocated to the requested DD and its concatenated groups are returned. If the DSAB pointer is specified or obtained from an opened DCB, only devices allocated to the requested DSAB are returned. The device area format is as follows: v An 8 byte header containing
– A 1-byte field indicating the subpool in which the storage resides.
– A 3-byte field containing the size of the device area (including the header).
372
z/OS MVS Assembler Services Reference IAR-XCT
IEFDDSRV macro
– A 4-byte field containing the number of device entry lists returned (a device entry list is returned for each DD in the concatenated group).
– An array of the device I/O list addresses.
v An array of the device I/O entry lists. Each list has the following format:
– A 4-byte field containing the number of device I/O entries in the list.
– An array of 20-byte entries containing the UCB addresses (4 bytes), the
TCTTIOT block size (8 bytes), the number of EXCPs against this device (4 bytes), and the device connect time (4 bytes).
The device I/O area is mapped by macro IEFDISMP.
Note:
The invoker is responsible for releasing the storage for the returned device I/O area.
To code:
Specify the RS-type address, or address in register (2)-(12), of a pointer field.
,TYPE=ALLOCATION
,TYPE=FEATURE
When MODIFY is specified, an optional parameter to modify an existing allocation or feature. The default is TYPE=ALLOCATION.
,TYPE=ALLOCATION
Update a DD allocation using the information provided.
,TYPE=FEATURE
Update the allocation settings of the job as requested.
,DDNAME=ddname
,DSABPTR=dsabptr
A required input parameter when MODIFY and TYPE=ALLOCATION are specified.
,DDNAME=ddname
One of a set of mutually exclusive keys. It is the name of an 8 character input that is left justified and padded with blanks. A DDNAME of all blanks is invalid. The DSAB/TIOT chain selected is the one associated with the current TCB, unless overridden by the TCBPTR parameter.
Note:
Multiple DDs with the same name are allowed, and all references to that DDNAME use the first DD found.
To code:
Specify the RS-type address of an 8-character field.
,DSABPTR=dsabptr
One of a set of mutually exclusive keys. It is the name of a pointer input that contains the address of the DSAB associated with a DD name.
To code:
Specify the RS-type address of a pointer field.
,NEWDDNAME=newddname
When MODIFY and TYPE=ALLOCATION are specified, a required input parameter, which is left justified and padded with blanks.
The following DD names are not allowed: v JOBLIB v STEPLIB (unless the program invoking IEFDDSRV is authorized) v
A DD name of all blanks v Any DD name that is already in use
Chapter 52. IEFDDSRV — DD service
373
IEFDDSRV macro
v Any DD name that does not conform to the rules documented in the JCL reference.
In addition, the DD to be modified cannot be concatenated to a named DD and cannot be modified while the DD is OPEN.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,DSENQMGMT=NO_CHANGE
,DSENQMGMT=MEMORY
When MODIFY and TYPE=FEATURE are specified, a required parameter that indicates how Allocation should manage ENQs on the data set name.
,DSENQMGMT=NO_CHANGE
Requests that no change be made to the data set ENQs management.
,DSENQMGMT=MEMORY
Requests that data set ENQs be managed in memory. Specifying this option causes the job to be non-restartable through the check-point/restart function from this point on. The SYSTEM MEMDSENQMGMT keyword in
ALLOCxx must be set to ENABLE to allow the job or subsystem to use the memory-based data set ENQ management. Memory-based data set ENQ management is not available for ASID 1.
,TCBPTR=tcbptr
An optional input parameter that contains the address of the TCB associated with the task for which DSAB/TIOT information is requested or modified.
When DCBPTR or ACBPTR defines a DCB or ACB associated with an OPEN
DD, DCBPTR is mutually exclusive with TCBPTR. The specified TCBPTR is ignored, and the current TCB is used.
When specified for a MODIFY TYPE=ALLOCATION request by an unauthorized caller, only the following subset of tasks within the address space are accepted: v The cross-memory resource owner (CMRO) TCB v Tasks that are subtasks of the CMRO TCB v Tasks that use the same DSAB/TIOT structure as the CMRO TCB
Any task that does not meet these requirements is considered not valid, resulting in return code X’0C’ with reason code X’14’.
When specified for a MODIFY TYPE=FEATURE request, only the current TCB is accepted. Any other task is considered not valid, resulting in return code
X’0C’ with reason code X’14’.
To code:
Specify the RS-type address, or address in register (2)-(12), of a pointer field.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value is left in GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12) or
(15), (GPR15), (REG15), or (R15).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value is left in GPR 0.
374
z/OS MVS Assembler Services Reference IAR-XCT
IEFDDSRV macro
To code:
Specify the RS-type address of a fullword field, or register (0) or
(2)-(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX
, if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , which supports all parameters except those specifically referenced in higher versions.
v 1
, which supports both the following parameters and those from version 0:
– ALLOCATION
– DEVIOAREA
– DSENQMGMT
– EXTRACT
– FEATURE
– MODIFY
– NEWDDNAME
– TYPE
To code:
Specify one of the following: v
IMPLIED_VERSION v MAX v A decimal value of 0, or 1
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Chapter 52. IEFDDSRV — DD service
375
IEFDDSRV macro
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and
MF=E, the name can be an RS-type address or an address in register
(1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When the IEFDDSRV macro returns control to your program, GPR 15 (and retcode if you code RETCODE) contains the return code. If the value in GPR 15 is not 0,
GPR0 (and rsncode if you code RSNCODE) contains the reason code.
The return and reason codes are mapped in macro IEFDISRC. The hexadecimal return and reason codes from the IEFDDSRV macro are as follows:
Table 25. Return and reason codes for the IEFDDSRV macro
Return code
X'00'
X'04'
X'04'
X'08'
X'08'
X'08'
Reason code
X'00'
–
X'04'
–
X'04'
X'08'
Meaning and action
Meaning:
The requested function successfully completed.
Meaning:
The requested function completed with warnings.
Meaning:
AREALEN is insufficient to contain the output. The necessary length is in the
DVAR_LENGTH field of the output area.
Meaning:
Input parameter is not valid.
Meaning:
The specified or obtained DD name is blank.
Meaning:
The specified or obtained DSAB pointer is zero.
376
z/OS MVS Assembler Services Reference IAR-XCT
IEFDDSRV macro
Table 25. Return and reason codes for the IEFDDSRV macro (continued)
Return code
X'08'
X'08'
X'08'
X'08'
X'08'
X'08'
X'08'
X'08'
X'08'
X'0C'
X'0C'
X'0C'
X'0C'
X'0C'
X'0C'
Reason code
X'0C'
X'10'
X'14'
X'18'
X'20'
X'24'
X'28'
X'2C'
X'34'
–
X'04'
X'08'
X'0C'
X'10'
X'14'
Meaning and action
Meaning:
Meaning:
Meaning:
Meaning:
The specified DCB pointer is zero.
An invalid subpool was specified.
The specified ACB pointer is zero.
The specified DSAB pointer is a 31-bit address, but LOC=ANY was not specified.
Meaning:
The parameter list version and the parameter list length are not consistent.
Meaning:
The parameter list version does not support the IEFDDSRV function requested.
Meaning:
The parameter list version is higher than what is supported by IEFDDSRV.
Meaning:
The function in the parameter list is not supported by IEFDDSRV.
Meaning:
Invalid environment for the specified function.
Meaning:
The input parameter is not valid.
Meaning:
The specified or obtained DD name is not valid.
Meaning:
The specified or obtained DSAB pointer is not valid.
Meaning:
Failed to obtain the TIOT resource.
Meaning:
Failed to obtain the lock.
Meaning:
The specified TCB pointer is not valid for this request. This may indicate one of the following errors: v The specified pointer does not point to a valid
TCB.
v The specified pointer does point to a valid TCB, but that TCB is not a valid target for the request.
X'0C'
X'0C'
X'0C'
X'0C'
X'0C'
X'0C'
X'0C'
X'1C'
X'20'
X'100'
X'104'
X'108'
X'10C'
X'128'
For more information, see the description of the
TCBPTR parameter.
Meaning:
The DSAB pointer obtained from the
OPEN input DCB/ACB is a 31-bit address, but
LOC=ANY was not specified.
Meaning:
The TCTTIOT offset obtained from the
DSAB is zero.
Meaning:
The DD name cannot be modified while the DD is open.
Meaning:
The requested feature has not been enabled by the installation.
Meaning:
The requested new DD name does not follow the documented rules for a DDNAME.
Meaning:
The DD to be modified is concatenated to a named DD.
Meaning:
The DD to be modified is in an inconsistent state and cannot be modified.
Chapter 52. IEFDDSRV — DD service
377
IEFDDSRV macro
Table 25. Return and reason codes for the IEFDDSRV macro (continued)
Return code
X'0C'
X'0C'
X'0C'
X'0C'
X'10'
Reason code
X'12C'
X'130'
X'134'
X'138'
–
Meaning and action
Meaning:
The requested feature is already set.
Meaning:
The requested new DD name is already in use.
Meaning:
The requested function is not allowed from ASID 1.
Meaning:
The DD to be modified is an insulated
DD. You may not modify an insulated DD.
Meaning:
System error: Recovery entered.
Action:
Check the dump produced by the abend and supply it to the appropriate IBM support personnel.
378
z/OS MVS Assembler Services Reference IAR-XCT
|
|
Chapter 53. IEFOPZQ — Query the IEFOPZ configuration
|
|
|
|
|
Description
The IEFOPZQ macro provides the interface to obtain various pieces of information about the IEFOPZ configuration (via IEFOPZxx parmlib members) that is currently in effect.
Environment
The requirements for the caller are:
Environmental Factor Requirement
||
||
|
|
|
|
|
||
|
|
|
|
|
|
||
||
||
||
|||
||
||
|
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Problem state. PSW key 8-15
Task
PASN=HASN=SASN
31- or 64-bit
If in AMODE 64, specify SYSSTATE AMODE64=YES before invoking this macro.
Primary or access register (AR)
If in Access Register ASC mode, specify SYSSTATE
ASCENV=AR before invoking this macro. Do not use ALET value 1 ("secondary") for addressing parameters.
Enabled for I/O and external interrupts
No locks may be held.
Control parameters must be in the primary address space or, for AR-mode callers, must be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
Control parameters above 2GB are allowed for AMODE 64 callers only.
|
|
|
|
|
|
Programming requirements
Include the IEFOPZAA macro to get a mapping for the answer area and to get equate symbols for related constants as well as return and reason codes.
Restrictions
The caller must not have a functional recovery routine (FRR) established.
Input register information
|
|
|
Before issuing the IEFOPZQ macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
|
|
|
Before issuing the IEFOPZQ macro, the caller does not have to place any information into any access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.
© Copyright IBM Corp. 1988, 2017
379
|
| |
|||||||||||||||||||||||||||||||||||||||||||||||
| |
||||||||||||||||||||||||||||||||
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
||
||
||
||
||
|
|
|
|
||
||
||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||||||||
| |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
IEFOPZQ macro
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0
0-1
Reason code, when register 15 is not 0.
Used as work registers by the system.
2-13
14
15
Unchanged.
Used as work registers by the system.
Return code.
When control returns to the caller, the ARs contain:
Register
0-1
2-13
Contents
Used as work registers by the system.
Unchanged.
14-15
Used as work registers by the system.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax main diagram
►► ⌂ IEFOPZQ ⌂ ►
name
► ► REQUEST = BY_OLD
REQUEST = BY_NEW parameters-1 parameters-2
REQUEST = BY_DDJOBNAME , DDNAME =
ddname
, JOBNAME =
jobname
REQUEST = BY_OWNER , OWNER =
owner
REQUEST = STATUSINFO
► , ANSAREA =
ansarea
, ANSLEN =
anslen
, RETCODE =
retcode
►
, RSNCODE =
rsncode
►
, MF = S
, MF = ( L ,
list addr
, MF = ( E ,
list addr
, PLISTVER = IMPLIED_VERSION
, PLISTVER = MAX
, PLISTVER = 0
, 0D
,
attr
, COMPLETE
)
)
►
►
►◄
380
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||
|||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
IEFOPZQ macro parameters-1
►► , DSNAME =
dsname
►
, OWNER = ANY
, OWNER =
owner
, VOLUME = ANY
, VOLUME =
volume
, MEMBERS = NO
, MEMBERS = YES
, ARCH = ANY
, ARCH =
arch
, STATE = ANY
, STATE = ACTIVE
, STATE = INACTIVE
►
, STATUSINFO = NO
, STATUSINFO = YES
►
►
►◄
parameters-2
►► , DSNAME =
dsname
, VOLUME = ANY
, VOLUME =
volume
►
, STATE = ANY
, STATE = ACTIVE
, STATE = INACTIVE
, OWNER = ANY
, OWNER =
owner
►
►◄
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IEFOPZQ macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
,ANSAREA=ansarea
A required output parameter, which is to contain the returned information. The length of ANSAREA is given via ANSLEN. The answer area is mapped by macro IEFOPZAA. It should start on a doubleword boundary.
To code:
Specify the RS-type address, or address in register (2) - (12), of a character field.
,ANSLEN=anslen
A required input parameter, which contains the length of the provided answer area in bytes. The length must be at least of value IEFOPZQ_Min_Anslen. If you get return code IEFOPZQRC_Warn with reason code
IEFOPZQRsn_NotAllDataReturned, allocate a larger area based upon the value returned in field OpzaaHTLen and request the function again.
To code:
Specify the RS-type address, or address in register (2) - (12), of a fullword field, or specify a literal decimal value.
,ARCH=arch
,ARCH=ANY
When REQUEST=BY_OLD is specified, an optional input parameter, which contains the ARCH level. A value of 0 is treated as ANY. A value of X'FFFF' is treated as "same as MAXARCH". When ARCH=ANY is not in effect, the
Chapter 53. IEFOPZQ — Query the IEFOPZ configuration
381
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
IEFOPZQ macro
system locates the particular NEW data set that would be used if MAXARCH were set to the specified ARCH value, if such a data set is in the configuration.
The default is ANY.
To code:
Specify the RS-type address, or address in register (2) - (12), of a halfword field, or specify a literal decimal value.
,DDNAME=ddname
When REQUEST=BY_DDJOBNAME is specified, a required input parameter, which identifies the DDNAME for which data is to be returned. You may use wildcard characters within the DDNAME. A value of zeros indicates that all
DDNAMEs are to match. The IEFOPZQ service translates the DDNAME to uppercase before use.
To code:
Specify the RS-type address, or address in register (2) - (12), of an
8-character field.
,DSNAME=dsname
When REQUEST=BY_OLD or REQUEST=BY_NEW is specified, a required input parameter, which contains the data set name. You may use wildcard characters within the data set name. The IEFOPZQ service translates the data set name to uppercase before use.
To code:
Specify the RS-type address, or address in register (2) - (12), of a
44-character field.
,JOBNAME=jobname
When REQUEST=BY_DDJOBNAME is specified, a required input parameter, which identifies the jobname for which data is to be returned. You may use wildcard characters within the jobname. A value of zeros indicates that all
JOBNAMEs are to match. The IEFOPZQ service translates the jobname to uppercase before use.
To code:
Specify the RS-type address, or address in register (2) - (12), of an
8-character field.
,MEMBERS=NO
,MEMBERS=YES
When REQUEST=BY_OLD is specified, an optional parameter that indicates whether to return member information or not. The default is MEMBERS=NO.
,MEMBERS=NO
Indicates not to return member information.
,MEMBERS=YES
Indicates to return member information.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The
382
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
IEFOPZQ macro
list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and
MF=E, this can be an RS-type address or an address in register (1) - (12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,OWNER=owner
,OWNER=ANY
When REQUEST=BY_OLD or REQUEST=BY_NEW is specified, an optional input parameter, which identifies the owner for which information is to be retrieved. This correlates to the OWNER parameter of the IEFOPZxx parmlib member. You may use wildcard characters within the owner name. The
IEFOPZQ service translates the owner to uppercase before use. The default is
ANY.
When REQUEST=BY_OWNER is specified, a required input parameter, which identifies the OWNER for which data is to be returned. You may use wildcard characters within the OWNER. A value of zeros indicates that all OWNERs are to match. The IEFOPZQ service translates the owner to uppercase before use.
To code:
Specify the RS-type address, or address in register (2) - (12), of a
16-character field.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are
Chapter 53. IEFOPZQ — Query the IEFOPZ configuration
383
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
IEFOPZQ macro
assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0
, if you use the currently available parameters.
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0
REQUEST=BY_OLD
REQUEST=BY_NEW
REQUEST=BY_DDJOBNAME
REQUEST=BY_OWNER
REQUEST=STATUSINFO
A required parameter, which identifies the type of request.
REQUEST=BY_OLD
Returns entries matching the OLD data set. Upon return, the answer area contains: v An OPZAAH area.
v Zero or more OPZAAOLD areas. The offset of the first is in the
OPZAAH area. The offset of the "next" is in the OPZAAOLD area.
Matching items are returned in the order of the OLDNEWs' specification
(from first in the first parmlib member to last in the last parmlib member).
v For each OPZAAOLD, zero or more OPZAANEW areas. The offset of the first is in the OPZAAOLD area. The offset of the "next" is in the
OPZAANEW area. Matching NEW entries are returned in the order of their specification within the OLDNEW.
v
Optionally, for each OPZAAOLD, zero or more OPZAAMEM areas for included members and zero or more OPZAAMEM areas for excluded members. The offset of the first is in the OPZAAOLD area. The offset of the "next" is in the OPZAAMEM area. Matching include member list items are returned in the order of their specification within the
OLDNEW. Matching exclude member list items are returned in the order of their specification within the OLDNEW.
v Optionally, an OPZAAS area. The offset is in the OPZAAH area.
REQUEST=BY_NEW
Returns entries matching the NEW data set. Upon return, the answer area contains: v An OPZAAH area.
v Zero or more OPZAANEW areas. The offset of the first is in the
OPZAAH area. The offset of the "next" is in the OPZAANEW area.
Matching items are returned in the order of the OLDNEWs' specification
(from first in the first parmlib member to last in the last parmlib member) and the NEW specifications within the OLDNEW.
v For each OPZAANEW, zero or more OPZAAOLD areas. The offset of the first is in the OPZAANEW area. The offset of the "next" is in the
OPZAAOLD area. Matching items are returned in the order of the
OLDNEWs' specification.
REQUEST=BY_DDJOBNAME
Returns entries matching the DDNAME and/or JOBNAME. Upon return, the answer area contains: v
An OPZAAH area.
384
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
IEFOPZQ macro
v Zero or more OPZAADDJ areas. The offset of the first is in the
OPZAAH area. The offset of the "next" is in the OPZAADDJ area.
Matching items are returned in the order of the DDNAME/JOBNAME pairs' specification.
If the input DDNAME has wildcard character(s) or the input JOBNAME has wildcard character(s) then the input DDNAME/JOBNAME pair is treated as the pattern for purposes of wildcard matching. Otherwise the
IEFOPZ configuration DDNAME/JOBNAME is treated as the pattern. For example, v When the input DDNAME is DD* (has wildcard characters), it does not matter whatthe input JOBNAME is. The input DDNAME/JOBNAME is treated as the pattern and the IEFOPZ configuration
DDNAME/JOBNAME is treated as the string.
v
When the input DDNAME is DD (has no wildcard characters) and the input JOBNAME is zeros (or JOBNAME is not specified), the input
DDNAME/JOBNAME is treated as the string and the IEFOPZ configuration DDNAME/JOBNAME is treated as the pattern.
v When the input DDNAME is DD (has no wildcard characters) and the input JOBNAME is J (has no wildcard characters), the input
DDNAME/JOBNAME is treated as the string and the IEFOPZ configuration DDNAME/JOBNAME is treated as the pattern.
v When the input DDNAME is DD (has no wildcard characters) and the input JOBNAME is J* (has wildcard characters), the input
DDNAME/JOBNAME is treated as the pattern and the IEFOPZ configuration DDNAME/JOBNAME is treated as the string.
REQUEST=BY_OWNER
Returns information provided by the OWNER statement, such as the
MINARCH value, for matching owners. Note that this does not provide information about OLDNEW definitions associated with particular owner(s). That information can be gotten via REQUEST=BY_OLD with an appropriate OWNER= specification. Upon return, the answer area contains: v An OPZAAH area.
v Zero or more OPZAAOWN areas. The offset of the first is in the
OPZAAH area. The offset of the "next" is in the OPZAAOWN area.
Matching items are returned in the order of the OWNER statements' specification, with the proviso that all matching OWNER values without wildcard characters are presented before any matching OWNER values that have wildcard character(s).
If the input OWNER has wildcard character(s) then it is treated as the pattern for purposes of wildcard matching. Otherwise the IEFOPZ configuration OWNER is treated as the pattern.
REQUEST=STATUSINFO
Returns only status information. Upon return, the answer area contains: v An OPZAAH area.
v An OPZAAS area. The offset is in the OPZAAH area.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2) - (12) or
(15), (GPR15), (REG15), or (R15).
Chapter 53. IEFOPZQ — Query the IEFOPZ configuration
385
IEFOPZQ macro
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (0) or (2) -
(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).
,STATE=ANY
,STATE=ACTIVE
,STATE=INACTIVE
When REQUEST=BY_OLD or REQUEST=BY_NEW is specified, an optional parameter that indicates the states for which data should be returned. The default is STATE=ANY.
,STATE=ANY
Indicates to return information when the state is active or inactive.
,STATE=ACTIVE
Indicates to return information only when the state is active.
,STATE=INACTIVE
Indicates to return information only when the state is inactive.
,STATUSINFO=NO
,STATUSINFO=YES
When REQUEST=BY_OLD is specified, an optional parameter that relates to status information. The default is STATUSINFO=NO.
,STATUSINFO=NO
Indicates not to return status information.
,STATUSINFO=YES
Indicates to return status information, mapped by DSECT OPZAAS.
,VOLUME=volume
,VOLUME=ANY
When REQUEST=BY_OLD or REQUEST=BY_NEW is specified, an optional input parameter, which contains the volume (volser). You may use wildcard characters within the volume ID. The default, ANY, indicates that matching does not depend on whether the IEFOPZ specification provided a volume or not. If a volume is provided, it can match either of the following cases: v The IEFOPZ specification provided a volume.
v
When IEFOPZ processing last allocated the data set, it found the volume.
The IEFOPZQ service translates the volume to uppercase before use. The default is ANY.
To code:
Specify the RS-type address, or address in register (2) - (12), of a
6-character field.
ABEND codes
None.
Return and reason codes
|
|
|
|
When the IEFOPZQ macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code
RSNCODE) contains a reason code.
386
z/OS MVS Assembler Services Reference IAR-XCT
IEFOPZQ macro
|
|
|
|
Macro IEFOPZAA provides equate symbols for the return and reason codes. It also provides equate IEFOPZQRsnCodeMask. That equate can be used to create a word that should be ANDed with the reason code to isolate the non component-diagnostic portion of of the reason code prior to doing a comparison.
|||
|
|
|||
|
|
|
|
|
|
|||
|||
|
|
|
|||
|
|
|||
|
|
|
|
|
|
|||
|||
|
|
|||
||
|||
|
|
|
The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code. IBM support personnel may request the entire reason code, including the xxxx value.
Table 26. Return and reason codes for the IEFOPZQ macro
Return code
0
Reason code
–
Equate symbol, meaning and action
Equate symbol
: IEFOPZQRc_OK
4
4
8
8
8
8
8
8
–
xxxx0401
–
xxxx0801
xxxx0802
xxxx0803
xxxx0804
xxxx0805
Meaning
: Successfully returned requested information.
Action
: None required.
Equate symbol
: IEFOPZQRc_Warn
Meaning
: Warning.
Action
: Refer to the action under the individual reason code.
Equate symbol
: IEFOPZQRsn_NotAllDataReturned
Meaning
: Not all data was returned because the answer area is not big enough.
Answer area field OpzaaHTLen. how much space is currently required.
Action
: Allocate a larger area and request the function again. Within the returned data from this call, use only the OpzaaHTLen field.
Equate symbol
: IEFOPZQRc_InvParm
Meaning
: The IEFOPZQ invocation specified parameters that are not valid.
Action
: Refer to the action under the individual reason code.
Equate symbol
: IEFOPZQRsn_BadParmlist
Meaning
: Error accessing the parameter list.
Action
: Check for possible storage overlay.
Equate symbol
: IEFOPZQRsn_SrbMode
Meaning
: SRB mode.
Action
: Avoiding issuing IEFOPZQ in SRB mode.
Equate symbol
: IEFOPZQRsn_NotEnabled
Meaning
: Not Enabled.
Action
: Avoiding issuing IEFOPZQ while not enabled.
Equate symbol
: IEFOPZQRsn_XM
Meaning
: Cross memory mode.
Action
: Avoid issuing IEFOPZQ when the home, primary, and secondary address spaces are not all the same.
Equate symbol
: IEFOPZQRsn_Locked
Meaning
: Locked.
Action
: Avoid issuing IEFOPZQ while holding a system lock.
Chapter 53. IEFOPZQ — Query the IEFOPZ configuration
387
IEFOPZQ macro
|
|
|
|
|
|
|
|
|||
|
|
|
|
|||
|||
|
|
|||
|
|
|
|
|||
|
|
|
|
|||
|
|
|
|||
|
|||
|||
|
|
Table 26. Return and reason codes for the IEFOPZQ macro (continued)
Return code
8
Reason code
xxxx0806
Equate symbol, meaning and action
Equate symbol
: IEFOPZQRsn_FRR
8 xxxx0810
Meaning
: FRR.
Action
: Avoid issuing IEFOPZQ while an FRR is in effect.
Equate symbol
: IEFOPZQRsn_BadAnslen
Meaning
: AnsLen is less than the size of the header area.
8
8
8
xxxx0811
xxxx0812
xxxx0813
Action
: Provide a larger answer area (as indicated by the ANSLEN keyword).
Equate symbol
: IEFOPZQRsn_BadAnsarea
Meaning
: Error accessing answer area.
Action
: Make sure that the provided answer area is valid.
Equate symbol
: IEFOPZQRsn_BadParmlistALET
Meaning
: Bad parameter list ALET.
Action
: Make sure that the ALET associated with the parameter list is valid. The access register might not have been set up correctly.
Equate symbol
: IEFOPZQRsn_BadAnsAreaALET
0C
10
10
–
–
xxxx1001
Meaning
: Bad answer area ALET.
Action
: Make sure that the ALET associated with the answer area is valid.
Equate symbol
: IEFOPZQRc_Env
Meaning
: Environmental error.
Action
: None - no such reason codes currently exist.
Equate symbol
: IEFOPZQRc_CompError
Meaning
: Unexpected failure.
Action
: Report the associated reason code to the system programmer to contact
IBM Support.
Equate symbol
: IEFOPZQRsn_CompError
Meaning
: Unexpected failure. The state of the request is unpredictable.
Action
: Contact your system programmer.
Examples
Example 1:
This example finds the NEW information that is used for this IPL for data set
MY.DSN (the value for the ARCH parameter is X'FFFF' which indicates
MAXARCH). Return information only for an active specification. Do not return member information. Do not return status information.
For this specification, the amount of data to be returned is known to consist of a header area and one OLD entry and one NEW entry.
388
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
IEFOPZQ macro
The code is as follows:
* Invoke IEFOPZQ
IEFOPZQ REQUEST=BY_OLD,
DSNAME=d,
MEMBERS=NO,STATE=ACTIVE,
ARCH=ar,
STATUSINFO=NO,
ANSAREA=a,ANSLEN=al,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,
MF=(E,OPTQL)
* Here you would place code to process the return and
* reason codes.
...
d al
DC
DC
CL44’MY.DSN’
A(L’a) ar DC
DYNAREA DSECT a DS
LRETCODE DS
X’FFFF’
CL(OPZAAH_LEN+OPZAAOLD_LEN+OPZAANEW_LEN)
F
LRSNCODE DS F
IEFOPZQ MF=(L,OPTQL),PLISTVER=MAX
IEFOPZAA
*
*
*
*
*
*
*
Example 2:
This example finds the OLD information for this IPL for a given NEW data set that is to be located by the provided volume ID.
The code is as follows:
* Code to set up d, v, and al and to acquire an answer area
* and place its address into register n
...
* Invoke IEFOPZQ
IEFOPZQ REQUEST=BY_NEW,
DSNAME=d,VOLUME=v,
ANSAREA=(n),ANSLEN=al,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,
MF=(E,OPTQL)
* Here you would place code to process the return and
* reason codes. If they indicated that not all data was
* returned (reason IEFOPZQRsn_NotAllDataReturned), then
* acquiring a larger answer area, updating the al value and
* retrying IEFOPZQ.
...
DYNAREA DSECT d v al
DS
DS
DS
LRETCODE DS
LRSNCODE DS
CL44
CL6
F
F
F
IEFOPZQ MF=(L,OPTQL),PLISTVER=MAX
IEFOPZAA
*
*
*
*
Example 3:
This example finds the matching DDName/Jobname pairs.
The code is as follows:
* Code to set up dd, j, and al and to acquire an answer area
* and place its address into register n
...
* Invoke IEFOPZQ
IEFOPZQ REQUEST=BY_DDJOBNAME, *
Chapter 53. IEFOPZQ — Query the IEFOPZ configuration
389
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
IEFOPZQ macro
DDNAME=dd,JOBNAME=j,
ANSAREA=(n),ANSLEN=al,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,
MF=(E,OPTQL)
* Here you would place code to process the return and
* reason codes. If they indicated that not all data was
* returned (reason IEFOPZQRsn_NotAllDataReturned), then
* acquiring a larger answer area, updating the al value and
* retrying IEFOPZQ.
...
DYNAREA DSECT dd j al
DS
DS
DS
LRETCODE DS
LRSNCODE DS
D
D
F
F
F
IEFOPZQ MF=(L,OPTQL)
IEFOPZQ MF=(L,OPTQL),PLISTVER=MAX
IEFOPZAA
*
*
*
390
z/OS MVS Assembler Services Reference IAR-XCT
|
Chapter 54. IEFPRMLB — Logical parmlib support
Description
The Logical Parmlib Concatenation is a set of up to 10 partitioned data sets defined by PARMLIB statements in the LOADxx member of either SYSn.IPLPARM
or SYS1.PARMLIB which contains many initialization parameters in a pre-specified form in a single logical data set, thus minimizing the need for the operator to enter parameters. SYS1.PARMLIB makes the 11th or last data set in the concatenation and is the default logical parmlib if no PARMLIB statements exist in LOADxx.
The objective of this support is to allow installations to partition access to parmlib and isolate members customized by an installation from IBM maintenance and product level upgrades. The logical parmlib is established during IPL and is used by Master Scheduler Initialization and IEFPRMLB. There is a new SETLOAD command that allows you to switch from one logical parmlib to another without an IPL. The IEFPRMLB macro allows you to access the logical parmlib.
Use the IEFPRMLB macro to: v Allocate the logical parmlib data set concatenation v Unallocate the logical parmlib data set concatenation v Read a logical parmlib data set v
Retrieve information about which data sets make up the logical parmlib
The four functions for the macro are: v IEFPRMLB REQUEST=ALLOCATE allocates the logical parmlib via DDname.
v IEFPRMLB REQUEST=FREE unallocates the logical parmlib via DDname.
v IEFPRMLB REQUEST=LIST retrieves information about the logical parmlib data set concatenation.
v IEFPRMLB REQUEST=READMEMBER reads a specified member of an already allocated logical parmlib and returns its contents in an input buffer.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and PSW key 8-15
Task
PASN=HASN=SASN
24- or 31-bit
Primary or access register (AR)
Enabled for I/O and external interrupts.
No locks may be held.
Control parameters must be in the primary address space.
Programming requirements
The caller should include the IEFZPRC mapping macro to get return and reason code equates for all the functions.
© Copyright IBM Corp. 1988, 2017
391
IEFPRMLB macro
If you are going to use the read, message or list buffers, then you should include the IEFZPMAP mapping macro to get their mappings.
Restrictions
The caller may not have an EUT FRR established.
Input register information
Before issuing the IEFPRMLB macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code when GPR15 is not 0
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
REQUEST=ALLOCATE option of IEFPRMLB
Syntax
name
Syntax
The IEFPRMLB macro is written as follows:
Description
name: Symbol. Begin name in column 1.
392
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
Syntax
⌂
IEFPRMLB
⌂
REQUEST=ALLOCATE
,S99RB=NO
,S99RB=YES
,WAITDSN=NO
,WAITDSN=YES
,MOUNT=YES
,MOUNT=NO
,RETMSG=NO
,RETMSG=YES
,CONSOLID=consolid
,CONSOLID=NOCONSID
,CART=cart
,CART=NOCART
,MSGBUF=msgbuf
,MSGBUF=NOMSGBUF
,S99RBPTR=s99rbptr
,ALLOCDDNAME=allocddname
,READ=NO
,READ=YES
,MEMNAME=memname
,READBUF=readbuf
,BLANK72=YES
Description
One or more blanks must precede IEFPRMLB.
One or more blanks must follow IEFPRMLB.
Default
: S99RB=NO
Default
: WAITDSN=NO
Default
: MOUNT=YES
Default
: RETMSG=NO
consolid: RS-type address or register (2) - (12).
Default
: CONSOLID=NOCONSID
cart: RS-type address or register (2) - (12).
Default
: CART=NOCART
msgbuf: RS-type address or register (2) - (12).
Default
: MSGBUF=NOMSGBUF
s99rbptr: RS-type address or register (2) - (12).
allocddname: RS-type address or register (2) - (12).
Default
: READ=NO
memname: RS-type address or register (2) - (12).
readbuf: RS-type address or register (2) - (12).
Default
: BLANK72=YES
Chapter 54. IEFPRMLB — Logical parmlib support
393
IEFPRMLB macro
Syntax
,BLANK72=NO
,STARCOMMENT=NO
,STARCOMMENT=YES
,MEMNOTFOUND=MSGOK
,MEMNOTFOUND=NOMSG
Description
Default
Default
: STARCOMMENT=NO
: MEMNOTFOUND=MSGOK
,FREECLOSE=NO
,FREECLOSE=YES
,CALLERNAME=callername
,RETCODE=retcode
Default
: FREECLOSE=NO
callername: RS-type address or register (2) - (12).
retcode: RS-type address or register (2) - (12).
,RSNCODE=rsncode
,PLISTVER=IMPLIED_VERSION
rsncode: RS-type address or register (2) - (12).
Default
: PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Default
: MF=S
list addr: RS-type address or register (1) - (12).
Parameters
The parameters are explained as follows:
REQUEST=ALLOCATE
A required parameter. REQUEST=ALLOCATE allocates the logical parmlib data set concatenation. The allocation uses the data set name(s) and volume serial number(s) provided on the PARMLIB statements in the LOADxx member of SYSn.IPLPARM or SYS1.PARMLIB that is used during IPL processing or as specified by a SETLOAD command. If a volume serial number(s) isn't specified, IEFPRMLB searches the catalog for it. The allocation uses DISP=SHR and UNIT=SYSALLDA. If no PARMLIB statements are provided in the LOADxx member, the allocation uses only SYS1.PARMLIB.
,S99RB=NO
394
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
,S99RB=YES
An optional parameter, that specifies whether or not an SVC99 request block is input. The default is S99RB=NO.
,S99RB=NO
specifies that no S99RB is input.
,S99RB=YES
specifies that an SVC99RB (and optionally an SVC99RBX) is input. The
SVC99 request block is only required when the caller requires
S99FLAG1/S99FLAG2 options not automatically provided by the
ALLOCATE function. If the caller requires that the allocation wait for data sets to become available or allow mounting of volumes, the caller must set the appropriate bits in the S99FLAG1/S99FLAG2 fields to request those options. The address of the list of text unit pointers (S99TXTPP) must be zero. If an SVC99 request block is passed and the caller wishes messages issued or returned, the caller must also provide an SVC99 request block extension. The SVC99 request block and SVC99 request block extension are mapped by mapping macro IEFZB4D0.
,WAITDSN=NO
,WAITDSN=YES
An optional parameter when S99RB=YES is not specified, that indicates whether waiting should be allowed for one or more of the data sets in the logical parmlib data set concatenation if they are not readily available (for example, enqueued exclusive by another job). The default is WAITDSN=NO.
,WAITDSN=NO
If one or more of the data sets in the logical parmlib data set concatenation is not readily available (e.g., enqueued exclusive by another job), waiting should not be allowed. In this case upon return from the IEFPRMLB service the logical parmlib data set concatenation will not have been allocated.
,WAITDSN=YES
If one or more of the data sets in the logical parmlib data set concatenation is not readily available (for example, enqueued exclusive by another job), waiting should be allowed. In this case the service will wait for the data set(s) to become available before proceeding with the allocation. Upon return from the IEFPRMLB service the logical parmlib data set concatenation will have been allocated barring other errors.
,MOUNT=YES
,MOUNT=NO
An optional parameter when S99RB=YES is not specified, that indicates whether the service should allow mounting of volumes or consideration of offline or pending offline devices for one or more of the data sets in the logical parmlib data set concatenation. The default is MOUNT=YES.
,MOUNT=YES
If one or more of the volumes on which one or more of the data sets in the logical parmlib reside is not currently mounted, mounting of that volume(s) should be allowed. If one or more of the devices on which one or more of the data sets in the logical parmlib reside is not currently online or is pending offline, consideration of the offline or pending offline device should be allowed. Upon return from the IEFPRMLB service the logical parmlib data set concatenation will have been allocated barring other errors.
Chapter 54. IEFPRMLB — Logical parmlib support
395
IEFPRMLB macro
,MOUNT=NO
If one or more of the volumes on which one or more of the data sets in the logical parmlib reside is not currently mounted, mounting of that volume(s) should not be allowed. If one or more of the devices on which one or more of the data sets in the logical parmlib reside is not currently online, consideration of the offline device should not be allowed. Upon return from the IEFPRMLB service the logical parmlib data set concatenation will not have been allocated.
,RETMSG=NO
,RETMSG=YES
An optional parameter when S99RB=YES is not specified, that specifies whether or not messages are to be returned to the caller in an input message buffer. The default is RETMSG=NO.
,RETMSG=NO
specifies that messages generated during IEFPRMLB processing should not be returned to the caller in the input message buffer (MSGBUF). Messages generated during IEFPRMLB processing will be issued to the console specified by the input console id or will be issued with Route Code 11
(Programmer Information) and descriptor code 4 (System Status) if no console id is input.
,RETMSG=YES
specifies that messages generated during IEFPRMLB processing should be returned to the caller in the input message buffer (MSGBUF). Note that the only messages capable of being returned are those issued by MVS
Allocation and SMS. Also, only error messages (severity level 8 and higher) are returned with RETMSG=YES. If warning messages (severity level 4) or informational messages (severity level 0) are desired, then an S99RB and an
S99RBX with the desired message severity level (S99EMGSV) must be built and passed by specifying, S99RB=YES, MSGBUF=msgbuf, and
S99RBPTR=s99rbptr.
,CONSOLID=consolid
,CONSOLID=NOCONSID
An optional input parameter when RETMSG=YES and S99RB=YES are not specified. It contains the id of the console that originated this request and may be provided if messages are to be issued. The default is NOCONSID.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
4-character field.
,CART=cart
,CART=NOCART
An optional input parameter when RETMSG=YES and S99RB=YES are not specified, that contains the command and response token. The default is
NOCART.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,MSGBUF=msgbuf
,MSGBUF=NOMSGBUF
A required input parameter when RETMSG=YES is specified and S99RB=YES is not specified, that is the area into which all messages generated during
IEFPRMLB processing are to be placed. The format of each message returned in the buffer is mapped by IEFZPMAP and is compatible with WTO format requirements for the TEXT keyword. There may be more than one message in the buffer. A 4K buffer is recommended. Messages are placed contiguously into
396
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
the buffer in 256-byte message elements. If the input buffer is not large enough to contain all the generated messages, those messages that will fit are returned in the buffer in the order they are generated. If the message buffer is filled, an indicator (PRM_Msg_Buffer_Full) will be returned to indicate the buffer is full and, therefore, may not contain all messages. PRM_Message_Count will contain the number of messages in the buffer. See DSECT
PRM_Message_Buffer in IEFZPMAP for a complete mapping of the message buffer.
The caller must fill in the following fields in the message buffer (DSECT
PRM_Message_Buffer): v PRM_Msg_Buffer_Size set to the size of the buffer (including the header) v All other fields set to zero
The default is NOMSGBUF.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,S99RBPTR=s99rbptr
A required input parameter when S99RB=YES is specified that contains the address of the SVC99 request block to be used to process the allocation request.
To code:
Specify the RS-type address, or address in register (2)-(12), of a pointer field.
,ALLOCDDNAME=allocddname
A required input output parameter, that is the DDname associated with the logical parmlib. If a non-blank/non-zero DDname is input, the service will examine the active task's TIOT to determine if the DDname is currently allocated. If it is currently allocated, the service will return to its caller without further processing. The service will set return code x'04' (PRMLB_WARNING) and reason code x'01' (PRMLB_DD_ALREADY_ALLOC) to indicate the
DDname is currently allocated. If the DDname is not currently allocated, the service will allocate the logical parmlib data set concatenation using the input
DDname.
If a blank or zero DDname is input, the service will allocate the logical parmlib data set concatenation and return the system-generated DDname to the caller.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,READ=NO
,READ=YES
An optional parameter, that specifies whether or not a specified member is to be read from the logical parmlib. The default is READ=NO.
,READ=NO
indicates that no read is to be performed.
,READ=YES
indicates that the specified member of the logical parmlib data set concatenation is to be read and placed into the input buffer. If READ is requested, the member to be read (specified by MEMNAME) and the buffer in which to place the member contents (specified by READBUF) must be provided.
,MEMNAME=memname
A required input parameter when READ=YES is specified, that is the name of the member which is to be read from the logical parmlib data set
Chapter 54. IEFPRMLB — Logical parmlib support
397
IEFPRMLB macro
concatenation. The entire contents of the specified member will be read from the logical parmlib data set concatenation and returned in the input buffer specified on the READBUF keyword.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,READBUF=readbuf
A required input output parameter when READ=YES is specified, that is the area into which the contents of the member of the logical parmlib data set concatenation (specified by MEMNAME) are to be placed. The format of the buffer is mapped by IEFZPMAP. If the member is too large to fit into the buffer, records will be read into the buffer until the buffer is full. The service will terminate with return code x'0C' (PRMLB_Request_Failed) and reason code x'0A' (PRMLB_Read_Buffer_Full) and upon return, the buffer header will contain the buffer size needed to contain the entire member contents. The caller may obtain a larger buffer and invoke IEFPRMLB to read the member again from the beginning. The read buffer header will also contain the number of records that were successfully read the placed into the input buffer and the total number of records contained in the specified member.
For each record read, columns 73 - 80 will be blanked. Unless requested by the
Blank72 parameter, column 72 will also be blanked. Symbolic substitution will be performed.
The caller must fill in the following fields in the READ buffer (DSECT
PRM_Read_Buffer): v PRM_Read_Buff_Size - set to the size of the buffer v All other fields set to zero
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,BLANK72=YES
,BLANK72=NO
An optional parameter when READ=YES is specified, that indicates whether or not to blank out column 72. Most parmlib processing is defined to ignore column 72. The default is BLANK72=YES.
,BLANK72=YES
Do blank out column 72.
,BLANK72=NO
Do not blank out column 72.
,STARCOMMENT=NO
,STARCOMMENT=YES
An optional parameter when READ=YES is specified, that indicates whether a line within the parmlib member that has an asterisk in column 1 should be considered to be a comment that is not even returned to the caller. The default is STARCOMMENT=NO.
,STARCOMMENT=NO
A line with an asterisk in column 1 is not to be considered a comment. It will be included within the data returned.
,STARCOMMENT=YES
A line with an asterisk in column 1 is to be considered a comment. It will not be included within the data returned. Due to this, the nth line of output will be the nth non-star comment line rather than the nth overall
398
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
line of the member. If you use the line number, make it clear in your explanation that the line number is not the overall line number.
,MEMNOTFOUND=MSGOK
,MEMNOTFOUND=NOMSG
An optional keyword input thta indicates whether or not to write a message when the member is not found. The default is MEMNOTFOUND=MSGOK.
,MEMNOTFOUND=MSGOK
Specifies to write a message.
,MEMNOTFOUND=NOMSG
Specifies not to write a message..
,FREECLOSE=NO
,FREECLOSE=YES
An optional keyword input that indicates whether the “logical parmlib” dataset concatenation should be automatically unallocated when the DD is closed. The default is FREECLOSE=NO.
,FREECLOSE=NO
The “logical parmlib” dataset concatenation will not be automatically unallocated when the DD is closed. When the caller's use of the “logical parmlib” dataset concatenation has been complete, the caller must reinvoke the IEFPRMLB service with REQUEST=FREE to unallocated the “logical parmlib” dataset concatenation. Additionally, the caller must ensure the
“logical parmlib” has been closed prior to reinvoking the IEFPRMLB service with REQUEST=FREE.
,FREECLOSE=YES
The “logical parmlib” dataset concatenation will be automatically unallocated when the DD is closed. The caller does not need to reinvoke the IEFPRMLB service with REQUEST=FREE. However, the caller should be aware that the “logical parmlib” dataset concatentaion will be automatically unallocated as soon as it is closed and would therefore no longer be allocated for use by the caller.
Note:
If the caller requests READ(YES) and FREECLOSE(YES), the caller does not need to close the data set nor reinvoke the IEFPRMLB service to free the “logical parmlib” dataset concatenation. The close and free will be done by the Logical Parmlib Service.
,CALLERNAME=callername
A required input parameter, that is the EBCDIC caller's name which is to be used in messages, symptom records and other diagnostic areas as necessary during IEFPRMLB processing. Initial characters A-I and SYS are reserved for
IBM use.
The suggested callername definition is 'ProgramName || ServiceLevel'
Example:
IEF761I jjobname [procstep] stepname ddname callername
DD IS ALREADY ALLOCATED AND WILL BE USED BY
THIS TASK
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
Chapter 54. IEFPRMLB — Logical parmlib support
399
IEFPRMLB macro
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
400
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
,list addr
The name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this can be an RS-type address or an address in register
(1)-(12).
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When the IEFPRMLB macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded
RSNCODE) contains reason code.
Return and reason code constants are defined in macro IEFZPRC.
The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code.
Table 27. Return and Reason Codes for the IEFPRMLB Macro
Return Code
X'00'
Reason Code
—
Equate Symbol Meaning and Action
Equate Symbol
: PRMLB_Success
X'04'
X'04'
X'08'
—
X'01'
—
Meaning
: Return Code - function completed successfully
Action
: None required.
Equate Symbol
: PRMLB_Warning
Meaning
: Return Code - Warning
Equate Symbol
: PRMLB_DD_Already_ALLOC
Meaning
: The specified DDname is already allocated to this task.
Action
: None required.
Equate Symbol
: PRMLB_Locks_Held
Meaning
: Return Code - the caller of IEFPRMLB holds a lock.
Action
: Change the caller's code to release locks prior to invoking IEFPRMLB.
Chapter 54. IEFPRMLB — Logical parmlib support
401
IEFPRMLB macro
Table 27. Return and Reason Codes for the IEFPRMLB Macro (continued)
Return Code
X'0C'
Reason Code
—
Equate Symbol Meaning and Action
Equate Symbol
: PRMLB_Request_Failed
X'0C'
X'0C'
X'01'
X'02'
Meaning
: Return Code - request failed.
Equate Symbol
: PRMLB_Member_Not_Found
Meaning
: The specified member name was not found.
Action
: Ensure the specified member name exists. If so, contact the system programmer.
Equate Symbol
: PRMLB_Read_IO_Error
X'0C'
X'0C'
X'03'
X'04'
Meaning
: An I/O error was encountered while attempting to read the specified member.
Action
: Contact the system programmer.
Equate Symbol
: PRMLB_Open_Error
Meaning
: An error was encountered while attempting to open the logical parmlib.
Action
: Contact the system programmer.
Equate Symbol
: PRMLB_ALLOC_Failed
Meaning
: Allocation of one of the logical parmlib data sets failed
X'0C'
X'0C'
X'0C'
X'0C'
X'05'
X'06'
X'07'
X'08'
Action
: Contact the system programmer.
Equate Symbol
: PRMLB_CONCAT_Failed
Meaning
: Concatenation of the logical parmlib data sets failed
Action
: Contact the system programmer.
Equate Symbol
: PRMLB_Reader_Load_Failed
Meaning
: Load of the parmlib read routine failed.
Action
: Contact the system programmer.
Equate Symbol
: PRMLB_Unable_To_Access_DS
Meaning
: The parmlib read routine was unable to access the logical parmlib
Action
: Contact the system programmer.
Equate Symbol
: PRMLB_Parmlib_Still_Open
Meaning
: REQUEST=FREE was requested but the logical parmlib is still open.
Action
: Close the data set prior to issuing the
REQUEST=FREE.
402
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
Table 27. Return and Reason Codes for the IEFPRMLB Macro (continued)
Return Code
X'0C'
Reason Code
X'09'
Equate Symbol Meaning and Action
Equate Symbol
: PRMLB_UNALLOC_Failed
X'0C'
X'0C'
X'0A'
X'0B'
Meaning
: Unallocation of the logical parmlib data sets failed.
Action
: Contact the system programmer.
Equate Symbol
: PRMLB_Read_Buffer_Full
Meaning
: The input READ buffer is full and READ processing could not continue
Action
: The caller may obtain a buffer large enough to contain the entire member contents
(PRM_Buff_Size_Needed in DSECT
PRM_Read_Buffer which is mapped by IEFZPMAP contains the required size) and re-invoke IEFPRMLB to begin reading the specified member again.
Equate Symbol
: PRMLB_Putline_Error
X'10'
X'10'
—
X'01'
Meaning
: Putline processing abended. This could be due to an error in the user-provided CPPL (pointed to by S99ECPPL when the user provides an S99RB).
Action
: Verify that the CPPL is valid.
Equate Symbol
: PRMLB_Internal_Error
Meaning
: Return Code - an internal error occurred.
Equate Symbol
: PRMLB_Bad_Parameter
Meaning
: A bad parameter list was passed to the parmlib read routine.
X'10'
X'14'
X'1C'
X'1C'
X'02'
—
—
X'01'
Action
: Contact the system programmer.
Equate Symbol
: PRMLB_Unknown_Reason
Meaning
: Return Code - Reason for failure is unknown.
Action
: Contact the system programmer.
Equate Symbol
: PRMLB_Not_Task_Mode
Meaning
: Return Code - the caller is not in Task mode.
Action
: Contact the system programmer.
Equate Symbol
: PRMLB_Invalid_Parameter_List
Meaning
: Return Code - the input parameter list is invalid.
Equate Symbol
: PRMLB_Plist_Unaccessible
Meaning
: The IEFPRMLB service was unable to access the input parameter list.
Action
: Ensure the parameter list resides in storage belonging to the caller. If so, contact the system programmer.
Chapter 54. IEFPRMLB — Logical parmlib support
403
IEFPRMLB macro
Table 27. Return and Reason Codes for the IEFPRMLB Macro (continued)
Return Code
X'1C'
Reason Code
X'02'
Equate Symbol Meaning and Action
Equate Symbol
: PRMLB_ListBuff_Unaccessible
Meaning
: The IEFPRMLB service was unable to access the input LIST buffer.
X'1C'
X'1C'
X'03'
X'04'
Action
: Ensure the list buffer resides in storage belonging to the caller. If so, contact the system programmer.
Equate Symbol
: PRMLB_MsgBuff_Unaccessible
Meaning
: The IEFPRMLB service was unable to access the input message buffer.
Action
: Ensure the message buffer resides in storage belonging to the caller. If so, contact the system programmer.
Equate Symbol
: PRMLB_ReadBuff_Unaccessible
Meaning
: The IEFPRMLB service was unable to access the input read buffer.
X'1C'
X'1C'
X'1C'
X'1C'
X'1C'
X'05'
X'06'
X'07'
X'08'
X'09'
Action
: Ensure the read buffer resides in storage belonging to the caller. If so, contact the system programmer.
Equate Symbol
: PRMLB_Plist_S99TXTPP_NOT0
Meaning
: The S99RB provided to the IEFPRMLB service contains a non-zero S99TXTPP field.
Action
: Change the caller's code to zero the
S99TXTPP prior to the call to IEFPRMLB.
Equate Symbol
: PRMLB_MsgBuff_Format_Error
Meaning
: The format of the message buffer provided to the IEFPRMLB service is invalid.
Action
: Correct the message buffer format.
Equate Symbol
: PRMLB_ReadBuff_Format_Error
Meaning
: The format of the read buffer provided to the IEFPRMLB service is invalid.
Action
: Correct the read buffer format.
Equate Symbol
: PRMLB_ListBuff_Format_Error
Meaning
: The format of the list buffer provided to the IEFPRMLB service is invalid.
Action
: Correct the list buffer format.
Equate Symbol
: PRMLB_S99RB_Unaccessible
Meaning
: The IEFPRMLB service was unable to access the input read buffer.
Action
: Ensure the S99RB resides in storage belonging to the caller. If so, contact the system programmer.
404
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
Table 27. Return and Reason Codes for the IEFPRMLB Macro (continued)
Return Code
X'20'
Reason Code
—
Equate Symbol Meaning and Action
Equate Symbol
: PRMLB_Cross_Memory
X'24' —
Meaning
: Return Code - the caller is in cross memory mode.
Action
: Change the caller's code so it is not in cross memory mode when invoking IEFPRMLB.
Equate Symbol
: PRMLB_ESTAE_Setup_Failed
X'28' —
Meaning
: Return Code - a failure occurred when
IEFPRMLB processing attempted to set up an ESTAE environment.
Action
: Contact the system programmer.
Equate Symbol
: PRMLB_Notauth_To_Subpool
Meaning
: Return Code - an unauthorized caller requested messages in an authorized subpool.
Action
: Only specify subpools to which the program is authorized.
REQUEST=FREE option of IEFPRMLB
Syntax
Syntax
The IEFPRMLB macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede IEFPRMLB.
IEFPRMLB
� One or more blanks must follow IEFPRMLB.
REQUEST=FREE
,RETMSG=NO
,RETMSG=YES
,CONSOLID=consolid
,CONSOLID=NOCONSID
,CART=cart
Default
: RETMSG=NO
consolid: RS-type address or register (2) - (12).
Default
: CONSOLID=NOCONSID
cart: RS-type address or register (2) - (12).
Chapter 54. IEFPRMLB — Logical parmlib support
405
IEFPRMLB macro
Syntax
,CART=NOCART
,MSGBUF=msgbuf
,MSGBUF=NOMSGBUF
,DDNAME=ddname
,CALLERNAME=callername
Description
Default
Default
: CART=NOCART
msgbuf: RS-type address or register (2) - (12).
: MSGBUF=NOMSGBUF
ddname: RS-type address or register (2) - (12).
callername: RS-type address or register (2) - (12),
,RETCODE=retcode
,RSNCODE=rsncode
,PLISTVER=IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Default
: MF=S
list addr: RS-type address or register (1) - (12).
Parameters
The parameters are explained as follows:
REQUEST=FREE
A required parameter. REQUEST=FREE unallocates the logical parmlib data set concatenation.
,RETMSG=NO
,RETMSG=YES
An optional parameter, that indicates whether or not messages are to be returned to the caller in an input message buffer. The default is RETMSG=NO.
,RETMSG=NO
specifies that messages generated during IEFPRMLB processing should not be returned to the caller in the input message buffer (MSGBUF). Messages generated during IEFPRMLB processing will be issued to the console specified by the input console id or will be issued with Route Code 11
(Programmer Information) and descriptor code 4 (System Status) if no console id is input.
406
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
,RETMSG=YES
specifies that messages generated during IEFPRMLB processing should be returned to the caller in the input message buffer (MSGBUF). Note that the only messages capable of being returned are those issued by MVS
Allocation and SMS. Also, only error messages (severity level 8 and higher) are returned with RETMSG=YES.
,CONSOLID=consolid
,CONSOLID=NOCONSID
An optional input parameter when RETMSG=YES is not specified, that contains the id of the console which originated this request and may be provided if messages are to be issued. The default is NOCONSID.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
4-character field.
,CART=cart
,CART=NOCART
An optional input parameter when RETMSG=YES is not specified, that contains the Command And Response Token. The default is NOCART.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,MSGBUF=msgbuf
,MSGBUF=NOMSGBUF
A required input parameter when RETMSG=YES is specified, that is the area into which all messages generated during IEFPRMLB processing are to be placed. The format of each message returned in the buffer is mapped by
IEFZPMAP and is compatible with WTO format requirements for the TEXT keyword. There may be more than one message in the buffer. A 4K buffer is recommended. Messages are placed contiguously into the buffer in 256-byte message elements. If the input buffer is not large enough to contain all the generated messages, those messages that will fit are returned in the buffer in the order they are generated. If the message buffer is filled, an indicator
(PRM_Msg_Buffer_Full) will be returned to indicate the buffer is full and, therefore, may not contain all messages. PRM_Message_Count will contain the number of messages in the buffer. See DSECT PRM_Message_Buffer in
IEFZPMAP for a complete mapping of the message buffer.
The caller must fill in the following fields in the message buffer (DSECT
PRM_Message_Buffer): v PRM_Msg_Buffer_Size set to the size of the buffer (including the header) v
All other fields set to zero
The default is NOMSGBUF.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,DDNAME=ddname
A required input parameter, that is the DDname associated with the logical parmlib. The logical parmlib data set concatenation will be unallocated. The
DDname originally input to or returned by the invocation of IEFPRMLB
REQUEST=ALLOCATE should be input. If the logical parmlib is open when
IEFPRMLB is invoked with REQUEST=FREE, the unallocation will fail.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
Chapter 54. IEFPRMLB — Logical parmlib support
407
IEFPRMLB macro
,CALLERNAME=callername
A required input parameter, that is the EBCDIC caller's name which is to be used in messages, symptom records and other diagnostic areas as necessary during IEFPRMLB processing. Initial characters A-I and SYS are reserved for
IBM use.
The suggested callername definition is 'ProgramName || ServiceLevel'
Example:
IEF761I jjobname [procstep] stepname ddname callername
DD IS ALREADY ALLOCATED AND WILL BE USED BY
THIS TASK
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
408
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this can be an RS-type address or an address in register
(1)-(12).
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When the IEFPRMLB macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.
v
When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded
RSNCODE) contains reason code.
See the return codes in under REQUEST=ALLOCATE option of IEFPRMLB.
Examples
None.
REQUEST=LIST option of IEFPRMLB
Chapter 54. IEFPRMLB — Logical parmlib support
409
IEFPRMLB macro
Syntax
Syntax
The IEFPRMLB macro is written as follows:
Description
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede IEFPRMLB.
IEFPRMLB
�
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
One or more blanks must follow IEFPRMLB.
REQUEST=LIST
,BUFFER=buffer buffer: RS-type address or register (2) - (12).
callername: RS-type address or register (2) - (12).
,CALLERNAME=callername
,RETCODE=retcode
,RSNCODE=rsncode
,PLISTVER=IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default
: MF=S
list addr: RS-type address or register (1) - (12),
Parameters
The parameters are explained as follows:
REQUEST=LIST
A required parameter. REQUEST=LIST requests information about the logical parmlib data set concatenation. For each data set included in the logical parmlib, for which there is room in the provided buffer, the following information is returned:
410
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
v Data set name (either specified on a PARMLIB statement in LOADxx or
SYS1.PARMLIB (if no PARMLIB statements are provided in LOADxx)).
v
Volume serial number where the data set resides (if a volume serial number is provided on the PARMLIB statement).
The number of data sets which make up the logical parmlib data set concatenation is also returned. If this number is larger than the number of
60-byte entries for which room was provided, then the system did not return all of the available information. In that case, you should allocate a larger buffer based on the returned number and call the service again, in order to retrieve all of the information.
NOTE: The LIST function only returns information on those data sets which are currently being used by the system. If a data set was found unusable during LOADxx processing, that data set is not being used as part of the logical parmlib concatenation and its information will not be returned by the
LIST function. Exclusion of unusable data sets is only possible when no
SETLOAD command was issued after IPL since an unusable data set encountered during SETLOAD processing causes SETLOAD to fail.
,BUFFER=buffer
A required input parameter, that is the area where the information about the logical parmlib data set concatenation is to be placed. The buffer is mapped by
IEFZPMAP. The caller must fill in the following fields in the list buffer (DSECT
PRM_List_Buffer): v PRM_List_Version
– Set this using either equate symbol PRM_List_VER1 or
PRM_List_Current_Version.
v PRM_List_Buff_Size
– Set this to the size of the provided area. It must be at least the size of
PRM_List_Header. It should contain room for at least 11 60-byte entries as well.
v All other fields set to zero
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,CALLERNAME=callername
A required input parameter, that is the EBCDIC caller's name which is to be used in messages, symptom records and other diagnostic areas as necessary during IEFPRMLB processing. Initial characters A-I and SYS are reserved for
IBM use.
The suggested callername definition is 'ProgramName || ServiceLevel'
Example:
IEF761I jjobname [procstep] stepname ddname callername
DD IS ALREADY ALLOCATED AND WILL BE USED BY
THIS TASK
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
Chapter 54. IEFPRMLB — Logical parmlib support
411
IEFPRMLB macro
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
To code:
Specify one of the following: v
IMPLIED_VERSION v MAX v A decimal value of 0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
412
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
,list addr
The name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this can be an RS-type address or an address in register
(1)-(12).
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When the IEFPRMLB macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded
RSNCODE) contains reason code.
See return codes under REQUEST=ALLOCATE option of IEFPRMLB.
Examples
None.
REQUEST=READMEMBER option of IEFPRMLB
Syntax
Syntax
The IEFPRMLB macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede IEFPRMLB.
name
⌂
IEFPRMLB
⌂
REQUEST=READMEMBER
,DDNAME=ddname
One or more blanks must follow IEFPRMLB.
ddname: RS-type address or register (2) - (12).
Chapter 54. IEFPRMLB — Logical parmlib support
413
IEFPRMLB macro
Syntax
,MEMNAME=memname
,READBUF=readbuf
,BLANK72=YES
,BLANK72=NO
,STARCOMMENT=NO
,STARCOMMENT=YES
,MSG=YES
,MSG=NO
,RETMSG=NO
,RETMSG=YES
,CONSOLID=consolid
,CONSOLID=NOCONSID
,CART=cart
,CART=NOCART
Description
memname: RS-type address or register (2) - (12).
readbuf: RS-type address or register (2) - (12).
Default
Default
Default
Default
: BLANK72=YES
: STARCOMMENT=NO
: MSG=YES
: RETMSG=NO
consolid: RS-type address or register (2) - (12).
Default
: CONSOLID=NOCONSID
cart: RS-type address or register (2) - (12).
Default
: CART=NOCART
,MSGBUF=msgbuf
,MSGBUF=NOMSGBUF
,CALLERNAME=callername
,RETCODE=retcode
msgbuf: RS-type address or register (2) - (12).
Default
: MSGBUF=NOMSGBUF
callername: RS-type address or register (2) - (12).
retcode: RS-type address or register (2) - (12).
,RSNCODE=rsncode rsncode: RS-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
Default
: PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
Default
: MF=S
list addr: RS-type address or register (1) - (12).
414
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
Syntax
,MF=(E,list addr,COMPLETE)
Description
Parameters
The parameters are explained as follows:
REQUEST=READMEMBER
A required parameter. REQUEST=READMEMBER indicates to read the specified member of the logical parmlib data set concatenation and place the contents into the input buffer.
,DDNAME=ddname
A required input parameter, that is the DDname associated with the allocated logical parmlib.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,MEMNAME=memname
A required input parameter, that is the name of the member which is to be read from the logical parmlib data set concatenation. The entire contents of the specified member will be read from the logical parmlib data set concatenation and returned in the input buffer specified on the READBUF keyword.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,READBUF=readbuf
A required input output parameter, that is the area into which the contents of the member of the logical parmlib data set concatenation (specified by
MEMNAME) are to be placed. The format of the buffer is mapped by
IEFZPMAP. If the member is too large to fit into the buffer, records will be read into the buffer until the buffer is full. The service will terminate with return code x'0C' (PRMLB_Request_Failed), reason code x'0A'
(PRMLB_Read_Buffer_Full) and upon return, the buffer header will contain the buffer size needed to contain the entire member contents. The caller may obtain a larger buffer and invoke IEFPRMLB to read the member again from the beginning. The read buffer header will also contain the number of records that were successfully read the placed into the input buffer and the total number of records contained in the specified member.
For each record read, columns 73 - 80 will be blanked. Unless requested by the
Blank72 parameter, column 72 will also be blanked. Symbolic substitution will be performed.
The caller must fill in the following fields in the READ buffer (DSECT
PRM_Read_Buffer): v PRM_Read_Buff_Size - set to the size of the buffer v All other fields set to zero
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,BLANK72=YES
Chapter 54. IEFPRMLB — Logical parmlib support
415
IEFPRMLB macro
,BLANK72=NO
An optional parameter, that indicates whether or not to blank out column 72.
Most parmlib processing is defined to ignore column 72. The default is
BLANK72=YES.
,BLANK72=YES
Do blank out column 72.
,BLANK72=NO
Do not blank out column 72.
,STARCOMMENT=NO
,STARCOMMENT=YES
An optional parameter that indicates whether a line within the parmlib member that has an asterisk in column 1 should be considered to be a comment that is not even returned to the caller. The default is
STARCOMMENT=NO.
,STARCOMMENT=NO
A line with an asterisk in column 1 is not to be considered a comment. It will be included within the data returned.
,STARCOMMENT=YES
A line with an asterisk in column 1 is to be considered a comment. It will not be included within the data returned. Due to this, the nth line of output will be the nth non-star comment line rather than the nth overall line of the member. If you use the line number, make it clear in your explanation that the line number is not the overall line number.
,MSG=YES
,MSG=NO
An optional parameter, that indicates whether or not allocation/SMS message processing is to be performed. The default is MSG=YES.
,MSG=YES
Specifies that allocation/SMS message processing is to be performed.
,MSG=NO
Specifies that no message processing is to be performed. If MSG=NO is coded, no messages generated by the logical parmlib service will be issued to the console or hardcopy log and no messages will be returned to the caller.
,RETMSG=NO
,RETMSG=YES
An optional parameter when MSG=YES is specified, that indicates whether or not messages are to be returned to the caller in an input message buffer. The default is RETMSG=NO.
,RETMSG=NO
specifies that messages generated during IEFPRMLB processing should not be returned to the caller in the input message buffer (MSGBUF). Messages generated during IEFPRMLB processing will be issued to the console specified by the input console id or will be issued with Route Code 11
(Programmer Information) and descriptor code 4 (System Status) if no console id is input.
,RETMSG=YES
specifies that messages generated during IEFPRMLB processing should be returned to the caller in the input message buffer (MSGBUF). Note that the
416
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
only messages capable of being returned are those issued by MVS
Allocation and SMS. Also, only error messages (severity level 8 and higher) are returned with RETMSG=YES.
,CONSOLID=consolid
,CONSOLID=NOCONSID
An optional input parameter when RETMSG=YES is not specified and
MSG=YES is specified, that contains the id of the console which originated this request and may be provided if messages are to be issued. The default is
NOCONSID.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
4-character field.
,CART=cart
,CART=NOCART
An optional input parameter when RETMSG=YES is not specified and
MSG=YES is specified, that contains the Command And Response Token. The default is NOCART.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,MSGBUF=msgbuf
,MSGBUF=NOMSGBUF
A required input parameter when RETMSG=YES and MSG=YES are specified, that is the area into which all messages generated during IEFPRMLB processing are to be placed. The format of each message returned in the buffer is mapped by IEFZPMAP and is compatible with WTO format requirements for the TEXT keyword. There may be more than one message in the buffer. A
4K buffer is recommended. Messages are placed contiguously into the buffer in
256-byte message elements. If the input buffer is not large enough to contain all the generated messages, those messages that will fit are returned in the buffer in the order they are generated. If the message buffer is filled, an indicator (PRM_Msg_Buffer_Full) will be returned to indicate the buffer is full and, therefore, may not contain all messages. PRM_Message_Count will contain the number of messages in the buffer. See DSECT
PRM_Message_Buffer in IEFZPMAP for a complete mapping of the message buffer.
The caller must fill in the following fields in the message buffer (DSECT
PRM_Message_Buffer): v PRM_Msg_Buffer_Size set to the size of the buffer (including the header) v
All other fields set to zero
The default is NOMSGBUF.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,CALLERNAME=callername
A required input parameter, that is the EBCDIC caller's name which is to be used in messages, symptom records and other diagnostic areas as necessary during IEFPRMLB processing. Initial characters A-I and SYS are reserved for
IBM use.
The suggested callername definition is 'ProgramName || ServiceLevel'
Example:
Chapter 54. IEFPRMLB — Logical parmlib support
417
IEFPRMLB macro
IEF761I jjobname [procstep] stepname ddname callername
DD IS ALREADY ALLOCATED AND WILL BE USED BY
THIS TASK
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX
, if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , if you use the currently available parameters.
To code:
Specify one of the following: v
IMPLIED_VERSION v MAX v A decimal value of 0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The
418
z/OS MVS Assembler Services Reference IAR-XCT
IEFPRMLB macro
list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this can be an RS-type address or an address in register
(1)-(12).
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When the IEFPRMLB macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded
RSNCODE) contains reason code.
See return codes under REQUEST=ALLOCATE option of IEFPRMLB.
Examples
None.
Chapter 54. IEFPRMLB — Logical parmlib support
419
420
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 55. IEFSSI — Dynamically query a subsystem
Description
Use the IEFSSI macro to dynamically query a subsystem. The REQUEST=QUERY parameter allows an application to query the following information for all subsystems defined to the SSI: v The subsystem name v If the subsystem is dynamic or not dynamic v If the subsystem is the primary subsystem v If the subsystem is active or inactive v
If the subsystem is dynamic, whether it accepts or rejects the SETSSI command v If the subsystem is active, which function codes it supports.
v The number of vector tables associated with the subsystem, with a maximum of two vector tables.
v The following information for each associated vector table:
– If the vector table is managed by the SSI. A vector table managed by the SSI is a vector table created with the IEFSSVT REQUEST=CREATE macro.
– A locator. This locator is a token if the vector table is is managed by the SSI and is an address if the vector table is not managed by the SSI.
– If the vector table is active
– The function codes supported by the vector table
This information represents a snapshot of the subsystems defined to the SSI when you process the query request.
To obtain information about the primary subsystem without knowing its name, use the query request and specify a subsystem name of '!PRI'.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
For the QUERY request, problem state with any PSW key.
Task
PASN=HASN=SASN
24-bit or 31-bit
Primary or Access register (AR)
Enabled for I/O and external interrupts
No locks held
Control parameters must be in the primary address space.
Programming requirements
v Include the CVT and IEFJESCT mapping macros in your program.
v Include the IEFJSRC mapping macro in your program. This macro defines the dynamic SSI return and reason codes.
v Include the IEFJSQRY macro to map the REQUEST=QUERY output.
© Copyright IBM Corp. 1988, 2017
421
IEFSSI macro
Syntax
Restrictions
The caller must not have established an EUT FRR.
Input register information
Before issuing the IEFSSI macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as a work register by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
REQUEST=QUERY parameter of IEFSSI
The IEFSSI macro with the QUERY parameter requests information about subsystems defined to the system.
Syntax for REQUEST=QUERY
The syntax of the IEFSSI REQUEST=QUERY macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede IEFSSI.
422
z/OS MVS Assembler Services Reference IAR-XCT
IEFSSI macro
Syntax
IEFSSI
�
Description
SUBNAME=subname
,REQUEST=QUERY
,WORKAREA=workarea
,WORKASP=workasp
One or more blanks must follow IEFSSI.
subname: RS-type address or register (2) - (12).
workarea: RS-type address or register (2) - (12) of an output area.
workasp: RS-type address or register (2) - (12) of an input area.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default
: IMPLIED_VERSION
plistver: 1
,RETCODE=retcode
,RSNCODE=rsncode
,COM=com
,COM=NULL
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list
addr,COMPLETE)
retcode: RS-type address or register (2) - (12). of fullword output variable
rsncode: RS-type address or register (2) - (12). of fullword output variable
com: comment string
Default
: COM=NULL
Default
: MF=S
Parameters for REQUEST=QUERY
The parameters are explained as follows:
SUBNAME=subname
A required parameter that specifies the field (or an address in a register) containing the 4-character subsystem name. It must be the name of a subsystem that has been previously defined to the system using SSI services.
This field must be padded to the right with blanks or nulls if it is less than 4 characters long.
Chapter 55. IEFSSI — Dynamically query a subsystem
423
IEFSSI macro
For the REQUEST=QUERY parameter, the subsystem name may contain the wildcard characters '*' and '?' to request information about multiple subsystems. The meanings for the wildcard characters are:
*
Matches 0 or more characters.
Use a SUBNAME parameter value of '*' to indicate that information is to be returned for all subsystems.
?
Matches exactly 1 character
Use a SUBNAME parameter value of '!PRI' to indicate that information is to be returned for the primary subsystem.
,REQUEST=QUERY
A parameter that specifies the request to obtain information about a currently defined subsystem named in the SUBNAME parameter.
The output from IEFSSI REQUEST=QUERY is mapped by the IEFJSQRY macro.
Subsystems are listed in broadcast order, that is, the order in which they receive broadcast SSI requests.
,WORKAREA=workarea
A required parameter that specifies a name (or register containing the address) of a pointer output field that contains the address of the subsystem information returned by the QUERY request.
The output area is mapped by the IEFJSQRY macro. The JQRYLEN field contains the length of the output area.
,WORKASP=workasp
An optional parameter that specifies a name (or register containing the address) of a one-byte input field that specifies the subpool that the SSI uses to obtain a work area for the returned subsystem information. The caller is responsible for freeing this work area.
IBM recommends
that you use a job-related or task-related subpool. This allows the system to free the associated storage when the job or task ends, if the caller does not free the returned area.
If WORKASP is not specified, the caller's subpool zero is used. Storage for the query information is obtained above 16 megabytes. AMODE 24 callers must switch into AMODE 31 to address this storage. Unauthorized callers may request storage only in the following unauthorized subpools: v 0-127 v
131 v 132
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:
IMPLIED_VERSION
The lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
424
z/OS MVS Assembler Services Reference IAR-XCT
IEFSSI macro
MAX
The largest size parameter list currently possible. This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
1
The currently available parameters.
To code,
specify in this input parameter one of the following: v IMPLIED_VERSION v
MAX v A decimal value of 1
,RETCODE=retcode
An optional 4-byte parameter that specifies the name of an output field (or a register) where the system places the return code. The return code is copied from general purpose register 15.
,RSNCODE=rsncode
An optional 4-byte parameter that specifies the name of an output field (or a register) where the system places the reason code. The reason code is copied from general purpose register 0.
,COM=com
,COM=NULL
An optional parameter that specifies the character input that appears in the block comment before the macro invocation. Use it to make comments about the macro invocation. The comment must be enclosed in quotation marks if it contains any lower case characters. The default is NULL.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Use MF=S to specify the standard form of the IEFSSI macro, which builds an in-line parameter list and generates the macro invocation to transfer control to the service.
Use MF=L to specify the list form of the IEFSSI macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. No other parameters may be coded with the list form of the macro.
Use MF=E together with the list form of the macro for applications that require reentrant code. The execute form of the IEFSSI macro stores the parameters into the storage area defined by the list form and generates the macro invocation to transfer control to the service.
,list addr
A required parameter that specifies the name of a storage area for the parameter list.
Chapter 55. IEFSSI — Dynamically query a subsystem
425
IEFSSI macro
,attr
An optional 1- to 60-character input string that contains any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
An optional parameter that specifies that the system checks for required parameters and supply defaults for omitted optional parameters. This is the default parameter.
ABEND codes
An invocation of the IEFSSI macro may result in an abend code X'8C5'. See z/OS
MVS System Codes for an explanation of this abend code.
Return and reason codes
When the IEFSSI macro returns control to your program, GPR 15 (and retcode, if you coded RETCODE) contains a return code. When the value in GPR 15 is not 0,
GPR 0 (and rsncode if you coded RSNCODE) contains the reason code.
The IEFJSRC mapping macro provides equate symbols for the return and reason codes. The equate symbols associated with each Return Code are:
Decimal (Hex)
Equate Symbols
00 (00)
IEFSSI_SUCCESS
04 (04)
IEFSSI_WARNING
08 (08)
IEFSSI_INVALID_PARAMETERS
12 (0C)
IEFSSI_REQUEST_FAIL
20 (14)
IEFSSI_SYSTEM_ERROR
24 (18)
IEFSSI_UNAVAILABLE
The following table contains return and reason codes, the equate symbols associated with each reason code and the meaning and suggested action for each return and reason code.
Table 28. Return and Reason Codes for the IEFSSI Macro
Return Code decimal (hex)
00 (00)
Reason Code decimal (hex)
00 (00)
Meaning and Action
Equate Symbol
: IEFSSI_FUNCTIONS_COMPLETE
Meaning
: The request completed successfully. The result depends on the request: v QUERY — Information for all subsystems defined to the
SSI has been queried
Action
: None.
426
z/OS MVS Assembler Services Reference IAR-XCT
IEFSSI macro
Table 28. Return and Reason Codes for the IEFSSI Macro (continued)
Return Code decimal (hex)
04 (04)
Reason Code decimal (hex)
900 (384)
Meaning and Action
Equate Symbol
: IEFSSI_QUERY_INCOMPLETE
Meaning
: The data returned by the QUERY request may be incomplete. This is a QUERY request error.
08 (08)
08 (08)
12 (0C)
00 (000)
12 (00C)
900 (384)
Action
: Check the JQRY_INCOMPLETE flag for each subsystem that was queried.
Equate Symbol
: IEFSSI_SUBSYSTEM_UNKNOWN
Meaning
: The subsystem is not defined to the SSI.
Action
: Correct the subsystem name or define a subsystem with either the IEFSSI macro or the SETSSI command.
Equate Symbol
: IEFSSI_INVALID_NAME
Meaning
: The subsystem name or the routine name contains characters that are not valid.
Action
: Correct the subsystem name by removing the characters that are not valid.
Equate Symbol
: IEFSSI_QUERY_STORAGE
Meaning
: Unable to obtain storage for an output of the
QUERY request.
20 (14)
24 (18)
—
—
Action
: Check the current use of the system storage to determine why storage was not available. Retry the request later in case storage has become available. See
z/OS MVS Programming: Authorized Assembler Services
Reference EDT-IXG for more information on the IEFSSI macro.
Equate Symbol
: IEFSSI_SYSTEM_ERROR
Meaning
: System error
Action
: Investigate the following possible causes: v Inability to obtain a system resource v Abnormal task termination
Obtain the system dump, if any, and contact the IBM support center.
Equate Symbol
: IEFSSI_UNAVAILABLE
Meaning
: The IEFSSI macro has been invoked too early during system initialization.
Action
: Delay the invocation of the IEFSSI macro to a later point in the IPL.
Example
Obtain subsystem information for any subsystem whose name begins with 'JES' and free the storage returned by the system.
IEFSSI REQUEST=QUERY,SUBNAME=SNAME,
WORKAREA=WAREA,
RETCODE=RETURN_CODE,RSNCODE=REASON_CODE
X
X
Chapter 55. IEFSSI — Dynamically query a subsystem
427
IEFSSI macro
.
.
.
.
SNAME
WAREA
L R5,WAREA
USING JQRY_HEADER,R5
L R0,JQRYLEN
STORAGE RELEASE,LENGTH=(0),ADDR=(R5)
DC
DS
CL4’JES*’
A
IEFJSQRY
428
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 56. IOCINFO — Obtain MVS I/O configuration information
Description
Use the IOCINFO macro to obtain the following I/O configuration information: v I/O configuration token v Default channel subsystem identifier for the logical partition v The maximum device measurement block index that is currently assigned v The I/O facilities that are supported and enabled by the hardware and software.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt Status
:
Locks
:
Control parameters
:
Requirement
Problem state, with any PSW key.
Task or SRB
Any PASN, any HASN, any SASN
24- or 31- bit
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
The caller may hold locks, but is not required to hold any
Must be in the primary address space or be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
Programming requirements
If in AR mode, specify SYSSTATE ASCENV=AR before invoking the macro.
Restrictions
None.
Input register information
Before issuing the IOCINFO macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0
Reason code if GPR 15 contains a return code of 08; otherwise, used as a work register by the system
1
2-13
14
Used as a work register by the system
Unchanged
Used as a work register by the system
© Copyright IBM Corp. 1988, 2017
429
IOCINFO macro
Syntax
15
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Performance implications
None.
Syntax
The standard form of the IOCINFO macro is written as follows:
Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede IOCINFO.
IOCINFO
� One or more blanks must follow IOCINFO.
ioctoken addr: RX-type address or register (2) - (12).
IOCTOKEN=ioctoken addr
,DCMINFO=xdcminfo xdcminfo: RS-type address or register (2) - (12).
cssid addr: RX-type address or register (2) - (12).
,CSSID=cssid addr
,MAXMBI=maxmbi addr maxmbi addr: RS-type address or register (2) - (12).
iofc addr: RX-type address or register (2) - (12).
,IOFACILITIES=iofc addr
,IODFINFO=xiodfinfo xiodfinfo: RS-type address or register (2) - (12).
retcode addr: RX-type address or register (2) - (12).
,RETCODE=retcode addr
,RSNCODE=rsncode addr rsncode addr: RX-type address or register (2) - (12).
,PLISTVER=xplistver
,PLISTVER=IMPLIED_VERSION Default: IMPLIED_VERSION
430
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
IOCINFO macro
Description
Parameters
The parameters are explained as follows:
IOCTOKEN=ioctoken addr
Specifies the address of a 48-character area where the system returns the current MVS I/O configuration token.
,DCMINFO=xdcminfo
Specifies the address of an optional 32 character output area into which
IOCINFO is to return Dynamic Channel Path Management (DCM) information which can be mapped by IOSDDCMI.
,CSSID=cssid addr
Specifies the address of a one byte output area where the system returns the default channel subsystem ID for the logical partition.
v A return code of X'00', reason code of X'00' indicates that the program is running on a processor that supports multiple channel subsystems.
v A return code of X'00', reason code X'01' indicates that the program is running on a processor that does not support multiple channel subsystems, and the CSS ID assigned is a zero.
,MAXMBI=maxmbi addr
Specifies the address of a halfword field where the system returns the maximum device measurement block index that is currently assigned.
,IOFACILITIES=iofc addr
Specifies the address of a required 256-byte output area into which the
IOCINFO service returns the I/O facility information. This area is mapped by mapping macro IOSDIOFC.
,IODFINFO=xiodfinfo
Specifies the address of an optional 128 character output area into which
IOCINFO is to return IODF information which is mapped by IOSDIODI.
,RETCODE=retcode addr
Specifies the fullword location where the system is to store the return code.
The return code is also in GPR 15.
,RSNCODE=rsncode addr
Specifies the fullword location where the system is to store the reason code.
The reason code is also in GPR 0.
,PLISTVER=xplistver
,PLISTVER=IMPLIED_VERSION
An optional byte input decimal value (with a value of 1) that specifies the macro version. PLISTVER is the only key allowed on the list form of MF and determines which parameter list is generated. Note that MAX may be specified instead of a number, and the parameter list will be of the largest size currently supported. This size may grow from release to release (thus possibly affecting the amount of storage needed by your program). If your program can tolerate this, IBM recommends that you always specify MAX when creating the list form parameter list as that will ensure that the list form parameter list is always long enough to hold whatever parameters might be specified on the execute form.
Chapter 56. IOCINFO — Obtain MVS I/O configuration information
431
IOCINFO macro
The default is IMPLIED_VERSION. When PLISTVER is omitted, the default is the lowest version which allows all of the parameters specified on the invocation to be processed.
ABEND codes
None.
Return and reason codes
When the system returns control to the caller, GPR 15 (and retcode addr, if you coded RETCODE) contains the return code. For return code X'08', the reason code is in GPR 0 (and rsncode addr, if you coded RSNCODE).
Hexadecimal
Return Code
00
Hexadecimal
Reason Code
Meaning and Action
00
00
08
08
08
08
00
01
01
02
05
09
Meaning
: Successful completion.
Action
: None.
Meaning
: Successful completion from a CSSID parameter request. The program is running on a processor that supports multiple channel subsystems.
Action
: None.
Meaning
: Successful completion from a CSSID parameter request. The program is running on a processor that does not support multiple channel subsystems and the CSS ID assigned is a zero.
Action
: None.
Meaning
: Program error. An ALET in the parameter list is not valid. The caller might have inadvertently written over an area in the parameter list.
Action
: Check to see if your program inadvertently overlaid the parameter list generated by the macro.
Meaning
: Program error. The system could not access the caller's parameter list.
Action
: Check to see if your program inadvertently overlaid the parameter list generated by the macro.
Meaning
: Program error. An error occurred when the system referenced the user-supplied area specified in the IOCTOKEN parameter.
Action
: Check to see if your program correctly specified the IOCTOKEN area.
Meaning
: System error. This reason code is for IBM diagnostic purposes only.
Action
: Record the reason code and supply it to the appropriate IBM support personnel.
432
z/OS MVS Assembler Services Reference IAR-XCT
Hexadecimal
Return Code
08
20
24
IOCINFO macro
Hexadecimal
Reason Code
0F
07
Meaning and Action
Meaning
: An error occurred referencing the user-supplied area that is specified in the
IOFACILITIES parameter.
Action
: Check to see if your program correctly specified the IOFACILITIES area.
Meaning
: System error. This return code is for IBM diagnostic purposes only.
Action
: Record the return code and supply it to the appropriate IBM support personnel.
Meaning
: Program error. The system does not support the specified parameter.
Action
: Check the parameters on the IOCINFO macro to make sure they are valid on your release of the system.
IOCINFO—List form
Use the list form of the IOCINFO macro together with the execute form of the macro for applications that require reentrant code. The list form of the macro defines an area of storage, which the execute form of the macro uses to contain the parameters.
Syntax
Syntax
The list form of the IOCINFO macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede IOCINFO.
IOCINFO
�
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
One or more blanks must follow IOCINFO.
list addr: Symbol.
attr: 1- to 60- character input string
Default
: 0D
Parameters
The parameters are explained under the standard form of the IOCINFO macro with the following exception:
MF=(L,list addr)
Chapter 56. IOCINFO — Obtain MVS I/O configuration information
433
IOCINFO macro
MF=(L,list addr,attr)
MF=(L,list addr,0D)
Specifies the list form of the IOCINFO macro.
list addr is the name of a storage area to contain the parameters.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
IOCINFO - Execute form
Use the execute form of the IOCINFO macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Syntax
Syntax
The execute form of the IOCINFO macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede IOCINFO.
IOCINFO
�
IOCTOKEN=ioctoken addr
,CSSID=cssid addr
,MAXMBI=maxmbi addr
,IOFACILITIES=iofc addr
,RETCODE=retcode addr
,RSNCODE=rsncode addr
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
One or more blanks must follow IOCINFO.
ioctoken addr: RX-type address or register (2) - (12).
cssid addr: RS-type address or register (2) - (12).
maxmbi addr: RS-type address or register (2) - (12).
iofc addr: RS-type address or register (2) - (12).
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
list addr: RX-type address or register (2) - (12).
Default
: COMPLETE
434
z/OS MVS Assembler Services Reference IAR-XCT
IOCINFO macro
Parameters
The parameters are explained under the standard form of the IOCINFO macro with the following exceptions:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Specifies the execute form of the IOCINFO macro.
list addr specifies the area that the system uses to contain the parameters.
COMPLETE, which is the default, specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
Chapter 56. IOCINFO — Obtain MVS I/O configuration information
435
IOCINFO macro
436
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 57. IOSCHPD — IOS CHPID description service
Description
The IOSCHPD macro returns the acronym, description, attributes, and/or the
Worldwide Port Name (WWPN) of a channel path (CHP) or channel path type.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem or Supervisor state and any PSW key
Task or SRB
Any PASN, any HASN, any SASN
24- or 31-bit
Primary or access register (AR).
Enabled or disabled for I/O and external interrupts.
No locks may be held.
Must be in the primary address space or be in an address/data space that is addressable through a public entry on the callers dispatchable unit access list (DU-AL).
Programming requirements
None.
Restrictions
The parameter list must be in the caller's primary address space or be addressable via the dispatchable unit access list.
The LINKAGE=BRANCH option is limited to callers which meet the following criteria: v Supervisor state and key 0 v 31-bit addressing mode v Primary ASC mode v
Parameter list resides in fixed or DREF storage
Input register information
Before issuing the IOSCHPD macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
The contents of registers 14 through 1 are altered during processing.
When control returns to the caller, the GPRs contain:
Register
Contents
0
Reason code
© Copyright IBM Corp. 1988, 2017
437
IOSCHPD macro
Syntax
1
2-13
14
15
Unpredictable (Used as a work register by the system)
Unchanged
Unpredictable (Used as a work register by the system)
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Unpredictable (Used as work registers by the system)
2-13
Unchanged
14-15
Unpredictable (Used as work registers by the system)
Performance implications
None.
Syntax
The IOSCHPD macro is written as follows:
Description
⌂
name
name: Symbol. Begin name in column 1.
One or more blanks must precede IOSCHPD.
IOSCHPD
⌂
CHPID=chpid
,CHP_TYPE=chp_type
,CHP_PARM=chp_parm
,CHP_PARM=0
,ACRONYM=acronym
,DESC=desc
,ATTR=attr
,WWPN=wwpn
,ND=xnd
438
z/OS MVS Assembler Services Reference IAR-XCT
One or more blanks must follow IOSCHPD.
chpid: RS-type address or register (2) - (12).
chp_type: RS-type address or register (2) - (12).
chp_type: RS-type address or register (2) - (12).
Default
: 0
acronym: RS-type address or register (2) - (12).
desc: RS-type address or register (2) - (12).
attr: RS-type address or register (2) - (12).
wwpn: RS-type address or register (2) - (12).
xnd: Optional 32-character output.
IOSCHPD macro
Syntax
,LINKAGE=SYSTEM
,LINKAGE=BRANCH
,RETCODE=retcode
,RSNCODE=rsncode
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=1
,PLISTVER=2
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Description
Default
: LINKAGE=SYSTEM
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: PLISTVER=IMPLIED_VERSION
Default
: MF=S
list addr: RS-type address or register (1) - (12).
Note:
To use the IOSCHPD macro, you need to specify the following parameters: v Either CHPID or CHP_TYPE v One or more parameters among ACRONYM, DESC, ATTR, and WWPN
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IOSCHPD macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
CHPID=chpid
An input parameter which specifies the CHPID number for which to retrieve the attributes, acronym, description, and/or WWPN. This parameter is mutually exclusive with the CHP_TYPE parameter.
If the CHPID is defined as a managed channel path, the description and acronym returned will indicate that the channel path is managed. Otherwise, a non-managed description and acronym will be returned.
To code
: Specify the RS-type address, or address in register (2)-(12), of a halfword field that contains a binary value in the range X’0000’ to X’00FF’.
CHP_TYPE=chp_type
An input parameter which specifies the channel path type for which to retrieve the attributes, acronym, description, and/or WWPN. The channel path type can be obtained by invoking the UCBINFO PATHINFO macro and mapping
Chapter 57. IOSCHPD — IOS CHPID description service
439
IOSCHPD macro
the results with the IOSDPATH mapping macro. (The interface type is in the field called PathIntType). This parameter is mutually exclusive with the CHPID parameter.
To code
: Specify the RS-type address, or address in register (2)-(12), of a one-byte field.
CHP_PARM=chp_parm
CHP_PARM=0
An optional input parameter, used only with CHP_TYPE=chp_type parameter, that specifies the channel path parameter. A value of 1 is the managed option and 0 (the default) is the non-managed option. If 1 is specified, and if the CHP type is managed, the description and acronym returned will indicate that the
CHP type is managed.
To code
: Specify the RS-type address, or address in register (2)-(12), of a one-byte field.
ATTR=attr
An optional parameter, used only with the CHPID parameter, that designates the output area that is to receive the CHPID attributes. The attributes are mapped by mapping macro IOSDCHPD.
To code
: Specify the RS-type address, or address in register (2)-(12), of a one-byte field.
,ACRONYM=acronym
An optional parameter that designates the output area that is to receive the acronym.
To code
: Specify the RS-type address, or address in register (2)-(12), of a
5-character field.
,DESC=desc
An optional parameter that designates the output area that is to receive the description.
To code
: Specify the RS-type address, or address in register (2)-(12), of a
32-character field.
,WWPN=wwpn
An optional parameter, used only with the CHPID parameter, that designates the output area that is to receive the Worldwide Port Name (WWPN). (If the
WWPN is not available, zeros will be returned.)
To code
: Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,ND=xnd
An optional parameter that designates the output area that is to receive the node descriptor for the channel.
,LINKAGE=SYSTEM
,LINKAGE=BRANCH
An optional parameter that indicates whether a branch-entry linkage should be generated or a Program Call should be issued for the routine invocation. The default is LINKAGE=SYSTEM.
,LINKAGE=SYSTEM
requests Program Call invocation.
,LINKAGE=BRANCH
requests branch-entry invocation. The LINKAGE=BRANCH option is
440
z/OS MVS Assembler Services Reference IAR-XCT
IOSCHPD macro
intended for performance-sensitive invokers or programs that require this function during NIP before a PC can be issued. See RESTRICTIONS for the restrictions on branch-entry invocation.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code
: Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code
: Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=1
,PLISTVER=2
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 1 , which supports all parameters except those specifically referenced in higher versions.
v 2 , which supports ATTR and WWPN, in addition to those from version 1.
To code
: Specify one of the following: v
IMPLIED_VERSION v MAX v A decimal value of 1 or 2
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Chapter 57. IOSCHPD — IOS CHPID description service
441
IOSCHPD macro
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and
MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When the IOSCHPD macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code
RSNCODE) reason code.
The following table identifies the hexadecimal return and reason codes:
Table 29. Return and reason codes for the IOSCHPD macro
Hexadecimal return code
00
Reason codes, meaning, and action
The requested information has been returned.
442
z/OS MVS Assembler Services Reference IAR-XCT
IOSCHPD macro
Table 29. Return and reason codes for the IOSCHPD macro (continued)
Hexadecimal return code
04
Reason codes, meaning, and action
The requested information has not been returned. Unless indicated differently in the following list of reason codes, all of the output areas for the information to be returned have been set to zeros.
Reason code
Meaning
00
01
02
03
04
The system could not determine the CHP type from the input
CHPID.
The input CHPID is not configured.
The CHP type obtained from the input CHPID is not valid.
The input CHP type is invalid.
The input CHP_PARM is invalid.
08
05
The managed option (1) was specified for the CHP_PARM, but the CHP type is one that does not support dynamic channel path management. The default acronym and/or description is returned.
07
The input CHPID value is invalid. The value must be in the range X’0000’ to X’00FF’.
Error in caller's parameters.
0C
20
Reason code
Meaning
01
The caller specified an invalid ALET.
02
An error occurred in accessing the caller's parameter list.
03
A keyword that is not allowed to be specified with CHP_TYPE was specified; the keyword is only allowed when CHPID is specified. For instance, ATTR may only be specified when
CHPID is specified.
Recovery was entered.
Recovery was entered.
Chapter 57. IOSCHPD — IOS CHPID description service
443
IOSCHPD macro
444
z/OS MVS Assembler Services Reference IAR-XCT
name
�
IOSCUMOD
�
MANF=chpid
,DEVT=devt
,MODN=devt
,MASK1=mask1
,MASK2=mask2
,MASK3=mask3
,MASK4=mask4
Chapter 58. IOSCUMOD — IOS control unit entry build service
Description
IOSCUMOD is a prototype module, to be used by manufacturers for creating an
IOSTnnn load module and for building the control unit model table.
Programming requirements
On the first invocation of the IOSCUMOD macro, it includes the parameters listed below in the manufacturer's module.
Syntax
Restrictions
None.
Performance implications
None.
Syntax
The IOSCUMOD macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede IOSCUMOD.
One or more blanks must follow IOSCUMOD.
manf: Symbol up to 3 characters long.
devt: Symbol up to 6 characters long.
modn: Symbol up to 3 characters long.
mask1: 2-byte hex symbol.
mask2: 2-byte hex symbol.
mask3: 2-byte hex symbol.
mask4: 2-byte hex symbol.
© Copyright IBM Corp. 1988, 2017
445
IOSCUMOD macro
Syntax
,DCM_SUPPORTED=YES
,DCM_SUPPORTED=NO
Description
Default
: YES
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IOSCUMOD macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
MANF=manf
Manufacturer ID that was provided with the node descriptor.
,DEVT=devt
Device type ID that was provided with the node descriptor. If a 4-character device type is entered, the two leading fields will be set to blanks.
,MODN=modn
Model number ID that was provided with the node descriptor. If NULL, then the model field will be set to all blanks. Othwerwise, leading zeroes must be coded.
,MASK1=mask1
,MASK2=mask2
,MASK3=mask3
,MASK4=mask4
Hex equivalent of the masks defined. 4 hex digits must be provided.
The tag field of the node descriptor uniquely identifies the power/service boundaries of most control units. Although this is true in most cases, it is not architected that way, and different control units represent this information in different ways.
In order to be able to interpret a control units tag, each control unit will provide four 2-byte masks.
Each 2 byte mask will be ANDed against the tag field of the control unit's
Node Descriptor to extract a unique indicator of the different service boundary in the control unit. The first (high order) mask will indicate the most significant single point of failure to avoid (For example, Cluster), the second mask will indicate the most significant single failure to avoid (e.g. I/O bay), and so on until the fourth mask.
There is no requirement for the masks to represent specific components of the control (e.g. Cluster vs. I/O Bay vs. Port card). The only requirement is that the masks are ordered from the most significant point of failure to least. If not all four masks are significant, they should be set to binary zeros and must be the last mask(s) of the four.
,DCM_SUPPORTED=YES
,DCM_SUPPORTED=NO
Indicates that the control unit does or does not support dynamic channel path management. Control units which support ESCON interfaces and are completely non-synchronous should be capable of being supported by DCM.
Control units which transfer data synchronously from the media, or remain
446
z/OS MVS Assembler Services Reference IAR-XCT
IOSCUMOD macro
connected to the channel while waiting for data to transfer between the media and the cache (or channel), are not supported. The default is YES.
ABEND codes
None.
Return and reason codes
None.
System macros require High Level Assembler. For more information about assembler language programming, see High Level Assembler and Toolkit Feature in IBM Knowledge Center (www.ibm.com/support/knowledgecenter/SSENW6).
Using this information also requires you to be familiar with the operating system and the services that programs running under it can invoke.
Chapter 58. IOSCUMOD — IOS control unit entry build service
447
448
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 59. IOSSCM — Storage class memory information
Description
The IOSSCM macro retrieves storage class memory (SCM) related information, such as the number of SCM resources and performance statistics.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
For LINKAGE=SYSTEM, problem state and any PSW key.
Task or SRB mode
Any PASN, any HASN, any SASN
31-bit or 64-bit
If in AMODE 64, specify SYSSTATE AMODE64=YES before invoking this macro.
Primary
Enabled for I/O and external interrupts
None
Control parameters must be in the primary address space.
For LINKAGE=BRANCH, the parameter list (including any data areas pointed to by the parameter list) must reside in fixed or DREF storage.
Programming requirements
None.
Restrictions
None.
Input register information
Before issuing the IOSSCM macro, the caller does not have to place any information into any general purpose register (GPR) or access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code if GPR15 is not 0
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
© Copyright IBM Corp. 1988, 2017
449
IOSSCM macro
►►
name
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
⌂ IOSSCM ⌂ CONFIGINFO
DEVINFO
, INFOAREA =
infoareaptr
►
► ► , INFOAREALEN =
infoarealen
, OUTVERSION =
0
version
, LINKAGE = SYSTEM
, PLISTVER = IMPLIED_VERSION
, PLISTVER = MAX
, PLISTVER = 1
►
, RETCODE =
retcode
, RSNCODE =
rsncode
►
, MF = S
, MF = ( L ,
list addr
, MF = ( E ,
list addr
, 0D
,
attr
, COMPLETE
)
)
►
►◄
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IOSSCM macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
CONFIGINFO
DEVINFO
Specifies the type of SCM information to be returned.
CONFIGINFO
Requests that SCM configuration information be returned. SCM configuration information includes the number of SCM resource parts and the size of an SCM measurement block.
450
z/OS MVS Assembler Services Reference IAR-XCT
IOSSCM macro
DEVINFO
Requests that SCM device (subchannel) information be returned. SCM device information includes I/O statistics for requests that were issued to each SCM device. Note that the SCM device or subchannel is not associated with a specific Flash Express feature pair; any SCM device can be used to perform I/O to any Flash Express feature pair.
,INFOAREA=infoareaptr
On a CONFIGINFO request, infoareaptr specifies the name (RS-type), or address in register (2) - (12), of a required 8-byte input that contains the address of an area which is to receive the configuration information. The area must be addressable in the primary address space. The returned INFOAREA data is mapped by the IOSDSCCI macro.
On a DEVINFO request, infoareaptr specifies the name (RS-type), or address in register (2) - (12), of a required 8-byte input that contains the address of an area which is to receive the device information. The area must be addressable in the primary address space. The returned INFOAREA data is mapped by the
IOSDSCDI macro.
,INFOAREALEN=infoarealen
On a CONFIGINFO request, infoarealen specifies the name (RS-type), or address in register (2) - (12), of a required 4-byte input/output area that contains the length of the configuration information area. If the information area is not large enough to contain all of the data for the requested output version,
IOSSCM returns a program error and this field will be updated with the required length.
On a DEVINFO request, infoarealen specifies the name (RS-type), or address in register (2) - (12), of a required 4-byte input/output area that contains the length of the device information area. The area must be large enough to contain the returned information for each SCM device or subchannel. You can issue a IOSSCM CONFIGINFO request to obtain the number of SCM devices or subchannels. If the information area is not large enough to contain all of the data for the requested output version, IOSSCM returns a program error and this field will be updated with the required length.
,LINKAGE=SYSTEM
Optional keyword input that indicates how the service is to be invoked.
SYSTEM
Indicates that a program call (PC) is to be issued.
,OUTVERSION=0
,OUTVERSION=version
The name (RS-type), or address in register (2) - (12), of an optional 1-byte input that specifies the output version of the output information to be returned. The output version controls the size and format of the returned information. If you specify an output version that is higher than the highest supported version, the highest supported version is used. The INFOAREA output (mapped by the
IOSDSCCI or IOSDSCDI macro) contains the version of the returned information.
Note:
Currently, version 0 is the only supported value.
Default:
0
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
Chapter 59. IOSSCM — Storage class memory information
451
IOSSCM macro
To code:
Specify the RS-type address of a fullword field, or register (2) - (12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (0) or (2) -
(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=1
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using
PLISTVER
, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:
IMPLIED_VERSION
The lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
MAX
Specifies that you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.
If your program can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
1
Supports all parameters except those specifically referenced in higher versions.
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 1
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant
452
z/OS MVS Assembler Services Reference IAR-XCT
IOSSCM macro
code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and MF=E, this can be an RS-type address or an address in register (1) - (12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When the IOSSCM macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code
RSNCODE
) contains a reason code.
Table 30 identifies the hexadecimal return and reason codes.
Table 30. Return and reason codes for the IOSSCM macro
Return code Reason code Meaning and action
00 –
Meaning
: The IOSSCM macro completed successfully.
04
08
08
08
01
01
02
03
Action
: None.
Meaning
: Warning. The requested output version (OUTVERSION) is not supported. The information area was updated based on the highest supported output version.
Action
: Examine the output version field in the information area to determine the format of the data that was returned.
Meaning
: Program error. An error occurred when the system attempted to reference the area specified by the INFOAREA parameter.
Action
: Correct the address specified on the INFOAREA parameter and reissue the macro.
Meaning
: Program error. The system could not access the caller’s parameter list.
Action
: Check to see if your program inadvertently overlaid the parameter list generated by the macro.
Meaning
: Program error. The output area specified by the
INFOAREA
parameter is not large enough to hold the requested information. The INFOAREALEN field has been updated with the required storage length.
Action
: Obtain storage for the output information area based on the returned INFOAREALEN value and reissue the macro.
Chapter 59. IOSSCM — Storage class memory information
453
IOSSCM macro
Table 30. Return and reason codes for the IOSSCM macro (continued)
Return code
0C
Reason code
01
Meaning and action
Meaning
: Environmental error. Storage class memory is not supported on this CPC.
0C 02
Action
: None.
Meaning
: Environmental error. The IOSSCM service is not available.
0C
0C
20
03
04
–
Action
: None.
Meaning
: Environmental error. IOSSCM detected that the caller is not in Primary ASC mode.
Action
: None.
Meaning
: Environmental error. IOSSCM detected that the caller is not enabled for I/O interrupts.
Action
: None.
Meaning
: System error. An unexpected error occurred.
Action
: Contact IBM Support.
454
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 60. ISGENQ — Global resource serialization ENQ service
Description
Interface for Global Resource Serialization ENQ OBTAIN and RELEASE requests.
The GRS ENQ service routine is given control from the ISGENQ macro to: v Obtain a single or multiple ENQs with or without associated device reserves.
v Change a single or multiple existing ENQs.
v
Release a single or multiple ENQs.
v Test an obtain request.
This service is intended to replace ENQ, DEQ, and RESERVE.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Requirement
Problem state. Any PSW key
To use OWNINGTTOKEN, ENQMAX, or when the specified
QNAME is one of the authorized QNAMEs, authorization must be one of the following: Supervisor state, PSW key 0-7, or APF authorized.
Note:
When an authorized caller issues an OBTAIN request with an unauthorized QNAME, if COND=YES, the request is granted, but a warning return code and the reason
ISGENQRsn_UnprotectedQName are given. This is to warn that an unauthorized caller may block the ENQ, or even release the ENQ if running under the owning task. If
COND=NO, authorized callers cannot obtain an ENQ on an unprotected resource.
Dispatchable unit mode:
Cross memory mode:
The authorized QNAMES are:
ADRDFRAG
ADRDSN
ARCENQG
BWODSN
SYSCTLG
SYSDSN
SYSIEA01
SYSIEECT
SYSIEFSD
SYSIGGV1
SYSIGGV2
SYSPSWRD
SYSVSAM
SYSVTOC
SYSZ*
Task
Any PASN, any HASN, any SASN Note: The resulting ENQ is associated with the owning task in the home address space.
© Copyright IBM Corp. 1988, 2017
455
ISGENQ macro
Environmental factor
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
31- or 64-bit
If in AMODE 64, specify SYSSTATE AMODE64=YES before invoking this macro.
Primary or access register (AR)
If in access register ASC mode, specify SYSSTATE
ASCENV=AR before invoking this macro.
Enabled for I/O and external interrupts
The caller must not be locked.
Control parameters must be in the primary address space or, for AR-mode callers, must be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
The control parameters must be in the same key as the caller.
The ECB specified must be in the caller's home address space or in common.
The TCB of the owning task (the current task or specified by
OWNINGTTOKEN) must be in the caller's home address space.
If a captured UCB address is specified, the captured UCB must be in the caller's home address space.
Programming requirements
The caller must include the ISGYCON macro to get the return and reason codes.
The caller must include the ISGYENQ macro to get the mappings for the
ISGYENQAA, ISGYENQRES, ISGYENQTOKEN, and ISGYENQRETURN tables.
See "Avoiding Interlock" in z/OS MVS Programming: Assembler Services Guide to ensure that you are following the required protocols to prevent the interlock.
Restrictions
The caller must not have functional recovery routines (FRRs).
This macro supports multiple versions. Some keywords are unique to certain
versions. See the “,PLISTVER=IMPLIED_VERSION” on page 466 parameter
description.
Input register information
Before issuing the ISGENQ macro, the caller does not have to place any information into any general purpose register (GPR) or access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0
Reason code if GPR15 is not 0
456
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
1
2-13
14
15
Used as a work register by the system
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Chapter 60. ISGENQ — Global resource serialization ENQ service
457
ISGENQ macro
Syntax main diagram
►►
►
,
name
RETCODE b
=
ISGENQ b
retcode
►
, MF = S
, MF = ( L ,
list addr
REQUEST = OBTAIN
REQUEST = CHANGE
REQUEST = RELEASE parameters-1 parameters-2 parameters-3
, RSNCODE =
rsncode
, COND = NO
, COND = YES
, PLISTVER = IMPLIED_VERSION
, PLISTVER = MAX
, PLISTVER = 1
, PLISTVER = 2
, 0D
,
attr
, COMPLETE
)
, MF = ( E ,
list addr
)
parameters-1
►►
►
, TEST = NO parameters-4
, TEST = YES
, ANSAREA =
ansarea
, RESLIST = NO
, RESLIST = YES parameters-5 parameters-6
, ANSLEN = NO_ANSLEN
, ANSLEN =
anslen
, OWNINGTTOKEN = CURRENT_TASK
, OWNINGTTOKEN =
owningttoken
parameters-2
►►
, RESLIST = NO
, ENQTOKEN =
enqtoken
, RESLIST = YES , NUMRES =
numres
, ENQTOKENTBL =
enqtokentbl
, RETURNTABLE =
returntable
►
, OWNINGTTOKEN = CURRENT_TASK
, OWNINGTTOKEN =
owningttoken
,
,
CONTROL
CONTROL
=
=
EXCLUSIVE
SHARED
parameters-3
►►
, RESLIST = NO
, ENQTOKEN =
enqtoken
, RESLIST = YES , NUMRES =
numres
, ENQTOKENTBL =
enqtokentbl
, RETURNTABLE =
returntable
►
, OWNINGTTOKEN = CURRENT_TASK
, OWNINGTTOKEN =
owningttoken
►
►
►◄
►
►◄
►
►◄
►
►◄
458
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro parameters-4
►►
►
,
, CONTENTIONACT = WAIT
CONTENTIONACT = FAIL
, WAITTYPE = SUSPEND
, OWNINGTTOKEN = CURRENT_TASK
,
, WAITTYPE = ECB , ECB@ =
ecb@
OWNINGTTOKEN = CURRENT_TASK
, OWNINGTTOKEN =
owningttoken
, ENQMAX = YES
, OWNINGTTOKEN =
owningttoken
, ENQMAX = NO
, USERDATA = NO_USERDATA
, USERDATA =
userdata
parameters-5
►► , QNAME =
qname
, RNAME =
rname
, RNAMELEN =
rnamelen
► , CONTROL = EXCLUSIVE
, CONTROL = SHARED
, CONTROL = VALUE , CONTROLVAL =
controlval
►
, RESERVEVOLUME = NO
, SCOPE = STEP
, SCOPE = SYSTEM
, SCOPE = SYSTEMS
, SCOPE = SYSPLEX
, SCOPE = VALUE , SCOPEVAL =
scopeval
, SYNCHRES = SYSTEM
, RESERVEVOLUME = YES , UCB@ =
ucb@
, SYNCHRES = YES
, SYNCHRES = NO
► , ENQTOKEN =
enqtoken
, RNL = YES
, RNL = NO
►
►◄
►
►◄
►
►
Chapter 60. ISGENQ — Global resource serialization ENQ service
459
ISGENQ macro parameters-6
►► , NUMRES =
numres
, RESTABLE =
restable
, ENQTOKENTBL =
enqtokentbl
►
►
►
, RETURNTABLE =
returntable
, RNAME = DO_NOT_OVERRIDE
, RNAME =
rname
, CONTROL = DO_NOT_OVERRIDE
, CONTROL = EXCLUSIVE
, CONTROL = SHARED
,
,
, QNAME = DO_NOT_OVERRIDE
, QNAME
RNAMELEN
RNAMELEN
=
=
=
qname
DO_NOT_OVERRIDE
rnamelen
, SCOPE = DO_NOT_OVERRIDE
, SCOPE = STEP
, SCOPE = SYSTEM
, SCOPE = SYSTEMS
, SCOPE = SYSPLEX
►
, RNL = DO_NOT_OVERRIDE
, RNL = YES
, RNL = NO
, SYNCHRES = DO_NOT_OVERRIDE
, UCB@ = DO_NOT_OVERRIDE
, UCB@ =
ucb@
►
, SYNCHRES = SYSTEM
, SYNCHRES = YES
, SYNCHRES = NO
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the ISGENQ macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
,ANSAREA=ansarea
When TEST=YES and REQUEST=OBTAIN are specified, an optional output parameter, which contains the returned information. The area is a list of records mapped by ISGYENQAA in the ISGYENQ macro. For RESLIST=YES, the records are in the same order as the requests in the RESTABLE. ANSLEN is required if ANSAREA is specified.
Note: The answer area is returned only when RC=0 or RC=4.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,ENQMAX=YES
,ENQMAX=NO
When TEST=NO and REQUEST=OBTAIN are specified, an optional parameter that indicates whether ENQMAX checking should be done. This keyword tells
460
z/OS MVS Assembler Services Reference IAR-XCT
►
►
►
►
►
►◄
ISGENQ macro
global resource serialization whether a check is to be made to see if the limit for the number of concurrent resource requests has been exceeded. The default is ENQMAX=YES.
,ENQMAX=YES
Indicates ENQMAX checking should be done. IBM suggests that you use the default, ENQMAX=YES, to allow global resource serialization to perform this processing.
,ENQMAX=NO
Indicates that ENQMAX checking should not be used. Use ENQMAX=NO when you have a system-critical ENQ request that should be honored regardless of the concurrent number of resource requests made from the home address space.
Note:
ENQMAX=NO can only be specified by an authorized requester and therefore can only override the maximum for authorized requesters.
See z/OS MVS Planning: Global Resource Serialization for more information.
,ANSLEN=anslen
,ANSLEN=NO_ANSLEN
When TEST=YES and REQUEST=OBTAIN are specified, an optional input parameter that is the length of the answer area provided. The answer area should be large enough to hold a ISGYENQAA record and an RNAME for each request (specified by NUMRES, or one if RESLIST=NO). The maximum size area needed to contain one RNAME is 256 bytes. ANSAREA is required if
ANSLEN is specified. The default is NO_ANSLEN.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.
,COND=NO
,COND=YES
An optional parameter that indicates how the request is handled for unsuccessful processing. The default is COND=NO.
,COND=NO
Indicates that if the request is not successful, then ISGENQ should ABEND the caller. COND=NO is mutually exclusive with RETCODE, RSNCODE,
RETURNTABLE, WAITTYPE=ECB, and with TEST=YES.
,COND=YES
Indicates that ISGENQ should always return to the caller and indicate via return and reason codes whether the request was successful. If COND=YES is specified, RETCODE and RSNCODE (and RETURNTABLE, if
RESLIST=YES) are required keywords.
Note: When COND=YES, ISGENQ tries to provide return and reason codes for the errors occurred during the process, though in some cases abends might be issued.
,CONTENTIONACT=WAIT
,CONTENTIONACT=FAIL
When TEST=NO and REQUEST=OBTAIN are specified, an optional parameter that indicates the action that should be taken if there is contention for the requested resource.
Note that a reserve request (where UCB@ is specified) that is not converted to only a global ENQ (Systems) will consist of an ENQ resource and a hardware reserve. For more information on reserve processing, see the description of the
Chapter 60. ISGENQ — Global resource serialization ENQ service
461
ISGENQ macro
“,SYNCHRES=SYSTEM” on page 472 keyword for more information on reserve
processing. The default is CONTENTIONACT=WAIT.
,CONTENTIONACT=WAIT
Indicates that the caller waits until the ENQ resource is available and, if applicable, the synchronous reserve I/O (see SYNCHRES) is complete.
,CONTENTIONACT=FAIL
Indicates that if contention for the ENQ resource exists to cancel the ENQ obtain request and return to the caller.
Notes: v See CONTENTIONACT=WAIT with ECB@ as a means of timing the overall request.
v For a reserve request (where UCB@ is specified), the ENQ resource is always obtained first. As such, CONTENTIONACT=FAIL indicates to cancel the entire request when there is contention on the ENQ resource.
However, it does not apply to contention on the hardware reserve. See
CONTENTIONACT=WAIT with WAITTYPE=ECB for information on how to manage or time hardware reserve contention.
,CONTROL=EXCLUSIVE
,CONTROL=SHARED
,CONTROL=VALUE
When RESLIST=NO and REQUEST=OBTAIN are specified, a required parameter that is the control type of the ENQ to be obtained. If the resource is modified while under control of the task, the request must be for exclusive control. If the resource is not modified, the request should be for shared control.
,CONTROL=EXCLUSIVE
Indicates that the request is for exclusive control of the resource.
,CONTROL=SHARED
Indicates that the request is for shared control of the resource.
,CONTROL=VALUE
the user provides a value, through the CONTROLVAL keyword, indicating the requested control.
,CONTROL=DO_NOT_OVERRIDE
,CONTROL=EXCLUSIVE
,CONTROL=SHARED
When RESLIST=YES and REQUEST=OBTAIN are specified, an optional parameter that is the type of control to be used for all resources specified in the resource table. This overrides any control specified in the resource table. If the resource is modified while under control of the task, the request must be for exclusive control. If the resource is not modified, the request should be for shared control. The default is CONTROL=DO_NOT_OVERRIDE.
,CONTROL=DO_NOT_OVERRIDE
Indicates that the control specified in the resource table should be used.
,CONTROL=EXCLUSIVE
Indicates that all requests are for exclusive control of the resources.
,CONTROL=SHARED
Indicates that all requests are for shared control of the resources.
,CONTROL=EXCLUSIVE
462
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
,CONTROL=SHARED
When RESLIST=NO and REQUEST=CHANGE are specified, control is an optional keyword input that is the control type to which the ENQ is to be changed. If the resource is modified under control of the task the request must be for exclusive control. If the resource is not modified, the request should be for shared control. When RESLIST=YES is specified, all resources in the list will be changed to the specified scope. The default is CONTROL=EXCLUSIVE.
,CONTROL=EXCLUSIVE
Indicates that the request is to change to exclusive control of the resource.
,CONTROL=SHARED
Indicates that the request is to change to shared control of the resource.
,CONTROLVAL=controlval
When CONTROL=VALUE, RESLIST=NO and REQUEST=OBTAIN are specified, a required input parameter that contains a value indicating the desired control. The value provided must be equivalent to the constants provided in the ISGYENQ macro indicating the control. (See the
ISGYENQ_kControl constants in the ISGYENQ macro for more information.)
To code:
Specify the RS-type address, or address in register (2)-(12), of an one-byte field.
,ECB@=ecb@
When WAITTYPE=ECB, CONTENTIONACT=WAIT, TEST=NO and
REQUEST=OBTAIN are specified, a required input parameter that contains the address of the ECB to be posted when the requested resource(s) is/are obtained.
The ECB must be in one of the following locations: v the home address space of the caller.
v common space.
v for unauthorized requesters, in the same storage key as the requester.
When the ISGENQ service returns to the caller, the return and reason codes specify for each resource whether the task has been given control of the resource or needs to wait for the ECB to be posted.
When the ECB is posted, it contains a return/reason code pair. Bits 8-23 contain the low-order halfword of the reason code and bits 24-31 contain the low-order byte of the return code. For a RESLIST=NO request, the ECB contains the return and reason code for the request. For a RESLIST=YES request, the ECB contains an overall return code.
To code:
Specify the RS-type address, or address in register (2)-(12), of a pointer field.
,ENQTOKEN=enqtoken
When RESLIST=NO and REQUEST=OBTAIN are specified, a required output parameter that is a token that uniquely identifies the ENQ. The ENQTOKEN is used on subsequent REQUEST=RELEASE or CHANGE invocations to release or change the ENQ request.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
32-character field.
,ENQTOKEN=enqtoken
When RESLIST=NO and REQUEST=CHANGE are specified, a required input parameter that is an ENQ Token of the ENQ to be changed.
Chapter 60. ISGENQ — Global resource serialization ENQ service
463
ISGENQ macro
To code:
Specify the RS-type address, or address in register (2)-(12), of a
32-character field.
,ENQTOKEN=enqtoken
When RESLIST=NO and REQUEST=RELEASE are specified, a required input parameter that is an ENQ Token of the ENQ to be released.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
32-character field.
,ENQTOKENTBL=enqtokentbl
When RESLIST=YES and REQUEST=OBTAIN are specified, a required output parameter that is a table of ENQ tokens. Mapped by ISGYENQToken in the
ISGYENQ macro. To easily release any ENQs obtained by a
REQUEST=OBTAIN use the same ENQToken table as input to a
REQUEST=RELEASE.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,ENQTOKENTBL=enqtokentbl
When RESLIST=YES and REQUEST=CHANGE are specified, a required input parameter that is a table of ENQ Tokens. Mapped by ISGYENQToken in the
ISGYENQ macro.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,ENQTOKENTBL=enqtokentbl
When RESLIST=YES and REQUEST=RELEASE are specified, a required input parameter that is a table of ENQ Tokens. Mapped by ISGYENQToken in the
ISGYENQ macro.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
464
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
,list addr
The name of a storage area to contain the parameters. For MF=S and
MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NUMRES=numres
When RESLIST=YES and REQUEST=OBTAIN are specified, a required input parameter that is the number of resource entries in the resource table. The specified value can be in the range of 1 to 2?6-1 (65535).
To code:
Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.
,NUMRES=numres
When RESLIST=YES and REQUEST=CHANGE are specified, a required input parameter that is the number of ENQ tokens in the ENQ token table. The specified value can be in the range of 1 to 2?6-1 (65535).
To code:
Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.
,NUMRES=numres
When RESLIST=YES and REQUEST=RELEASE are specified, a required input parameter that is the number of ENQ tokens in the ENQ Token Table. The specified value can be in the range of 1 to 2?6-1 (65535).
To code:
Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.
,OWNINGTTOKEN=owningttoken
,OWNINGTTOKEN=CURRENT_TASK
When WAITTYPE=ECB, CONTENTIONACT=WAIT, TEST=NO and
REQUEST=OBTAIN are specified, an optional input parameter that is the task token (TToken) of the task on whose behalf the ENQ is to be obtained. The
TToken must specify a task in the caller's home address space.
Note: Mutually exclusive with RESERVEVOLUME=YES. The default is
CURRENT_TASK.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,OWNINGTTOKEN=owningttoken
,OWNINGTTOKEN=CURRENT_TASK
When CONTENTIONACT=FAIL, TEST=NO and REQUEST=OBTAIN are specified, an optional input parameter that is the task token (TToken) of the task on whose behalf the ENQ is to be obtained. The TToken must specify a task in the caller's home address space.
Note: Mutually exclusive with RESERVEVOLUME=YES. The default is
CURRENT_TASK.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
Chapter 60. ISGENQ — Global resource serialization ENQ service
465
ISGENQ macro
,OWNINGTTOKEN=owningttoken
,OWNINGTTOKEN=CURRENT_TASK
When TEST=YES and REQUEST=OBTAIN are specified, an optional input parameter that is the task token (TToken) of the task on whose behalf the test request is to be performed. The TToken must specify a task in the caller's home address space.
Note: Mutually exclusive with RESERVEVOLUME=YES. The default is
CURRENT_TASK.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,OWNINGTTOKEN=owningttoken
,OWNINGTTOKEN=CURRENT_TASK
When REQUEST=CHANGE is specified, an optional input parameter that is the task token (TToken) of the task that owns the ENQ that is to be changed.
The TToken must specify a task in the caller's home address space. The default is CURRENT_TASK.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,OWNINGTTOKEN=owningttoken
,OWNINGTTOKEN=CURRENT_TASK
When REQUEST=RELEASE is specified, an optional input parameter that is the task token (TToken) of the task that owns the ENQs that are to be released.
The TToken must specify a task in the caller's home address space. The default is CURRENT_TASK.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=1
,PLISTVER=2
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 1 , which supports all parameters except those specifically referenced in higher versions.
v 2 , which supports both the following parameters and those from version 1:
USERDATA
466
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
To code:
Specify one of the following: v
IMPLIED_VERSION v MAX v A decimal value of 1, or 2
,QNAME=qname
When RESLIST=NO and REQUEST=OBTAIN are specified, a required input parameter that is the QNAME of the resource. The QNAME can contain any character from X'00' to X'FF'. However, a unique readable value that identifies the functional area or a high level of what is being serialized is preferred.
Every program issuing a request for a serially reusable resource must use the same QNAME, RNAME, and Scope to represent the resource. Some names, such as those beginning with certain letter combinations (SYSZ for example), are used to protect system resources by requiring that the issuing program be in supervisor state, or system key, or APF-authorized. Authorized programs must use a restricted QNAME (as described under Minimum authorization in the Environment section for this service ) to prevent interference from unauthorized programs.
For a list of QNAME (also known as major name) and RNAME (also known as minor name) ENQ or DEQ names and the resources that issue the ENQ or
DEQ, see z/OS MVS Diagnosis: Reference.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,QNAME=qname
,QNAME=DO_NOT_OVERRIDE
When RESLIST=YES and REQUEST=OBTAIN are specified, an optional input parameter that is a common QNAME to be used for all resources in the resource table. This overrides any QNAMEs specified in the resource table. The
QNAME can contain any character from X'00' to X'FF'. However, a unique readable value that identifies the functional area or a high level of what is being serialized is preferred. Every program issuing a request for a serially reusable resource must use the same QNAME, RNAME, and Scope to represent the resource. Some names, such as those beginning with certain letter combinations (SYSZ for example), are used to protect system resources by requiring that the issuing program be in supervisor state, or system key, or
APF-authorized. Authorized programs must use a restricted QNAME (as described under Minimum authorization in the Environment section for this service ) to prevent interference from unauthorized programs.
For a list of QNAME (also known as major name) and RNAME (also known as minor name) ENQ or DEQ names and the resources that issue the ENQ or
DEQ, see z/OS MVS Diagnosis: Reference.
The default is DO_NOT_OVERRIDE.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
REQUEST=OBTAIN
REQUEST=CHANGE
REQUEST=RELEASE
A required parameter that indicates the type of ISGENQ request.
REQUEST=OBTAIN
Indicates a request to obtain an ENQ for a resource.
Chapter 60. ISGENQ — Global resource serialization ENQ service
467
ISGENQ macro
REQUEST=CHANGE
Indicates a request to change the status an ENQ from shared to exclusive control.
REQUEST=RELEASE
Indicates a request to release (dequeue) the ENQ for a resource.
,RESERVEVOLUME=NO
,RESERVEVOLUME=YES
When RESLIST=NO and REQUEST=OBTAIN are specified, an optional parameter. The default is RESERVEVOLUME=NO.
,RESERVEVOLUME=NO
Indicates to issue a normal ENQ obtain and not a reserve.
,RESERVEVOLUME=YES
Indicates that after the ENQ resource is obtained that a reserve for the given device (shared DASD) is to be issued.
Note: RESERVEVOLUME=YES is mutually exclusive with
OWNINGTTOKEN.
,RESLIST=NO
,RESLIST=YES
When REQUEST=OBTAIN is specified, an optional parameter, The default is
RESLIST=NO.
,RESLIST=NO
Indicates to obtain an ENQ for a single resource.
,RESLIST=YES
Indicates to obtain ENQs for multiple resources specified in a resource table. Specifying multiple requests in a list ensures that they are processed atomically with respect to other ISGENQ requests. However, the order in which the requests are processed is unpredictable. Each request is treated as a separate request, and if COND=YES is specified, then the return code for each request should be checked.
Note: An easy way to release a list of ENQs is to use the output
ENQTOKEN table from the OBTAIN request as input to a RELEASE request.
,RESLIST=NO
,RESLIST=YES
When REQUEST=CHANGE is specified, an optional parameter, The default is
RESLIST=NO.
,RESLIST=NO
Indicates to change the control of a single ENQ.
,RESLIST=YES
Indicates to change the control for multiple ENQs.
,RESLIST=NO
,RESLIST=YES
When REQUEST=RELEASE is specified, an optional parameter, The default is
RESLIST=NO.
,RESLIST=NO
Indicates to single ENQ RELEASE request.
,RESLIST=YES
Indicates to change the disposition for multiple ENQs.
468
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
Note: A easy way to release a list of ENQs is to use the output
ENQTOKEN table from the OBTAIN request as input to a RELEASE request.
,RESTABLE=restable
When RESLIST=YES and REQUEST=OBTAIN are specified, a required input parameter that is a table specifying multiple ENQ requests. The resource table is mapped by ISGYENQRes in the ISGYENQ macro.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12) or
(15), (GPR15), (REG15), or (R15).
,RETURNTABLE=returntable
When RESLIST=YES and REQUEST=OBTAIN are specified, an optional output parameter that is a table that contains the return and reason codes. Mapped by
ISGYENQReturn in the ISGYENQ macro. The return table is only valid when
ISGENQRsn_NonZeroReturnCodes is returned in the RSNCODE. Mutually exclusive with COND=NO.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,RETURNTABLE=returntable
When RESLIST=YES and REQUEST=CHANGE are specified, an optional output parameter that is a table that contains the return and reason codes.
Mapped by ISGYENQReturn in the ISGYENQ macro. The return table is only valid when ISGENQRsn_NonZeroReturnCodes is returned in the RSNCODE.
Mutually exclusive with COND=NO.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,RETURNTABLE=returntable
When RESLIST=YES and REQUEST=RELEASE are specified, an optional output parameter that is a table that contains the return and reason codes.
Mapped by ISGYENQReturn in the ISGYENQ macro. The return table is only valid when ISGENQRsn_NonZeroReturnCodes is returned in the RSNCODE.
Mutually exclusive with COND=NO.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,RNAME=rname
When RESLIST=NO and REQUEST=OBTAIN are specified, a required input parameter that is the RNAME for the resource. The RNAME must be from 1 to
255 bytes long, and can contain any hexadecimal character from X'00' to X'FF'.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,RNAME=rname
,RNAME=DO_NOT_OVERRIDE
When RESLIST=YES and REQUEST=OBTAIN are specified, an optional input parameter that is the common RNAME to be used for all resources in the
Chapter 60. ISGENQ — Global resource serialization ENQ service
469
ISGENQ macro
resource table. This overrides any RNAMEs specified in the resource table. The
RNAME must be from 1 to 255 bytes long, and can contain any hexadecimal character from X'00' to X'FF'. The default is DO_NOT_OVERRIDE.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,RNAMELEN=rnamelen
When RESLIST=NO and REQUEST=OBTAIN are specified, a required input parameter that is the length of the given RNAME. The specified length can be in the range of 1 to 255.
To code:
Specify the RS-type address, or address in register (2)-(12), of an one-byte field.
,RNAMELEN=rnamelen
,RNAMELEN=DO_NOT_OVERRIDE
When RESLIST=YES and REQUEST=OBTAIN are specified, an optional input parameter that is a common length to be used for all RNAMEs in the resource table, or if a common RNAME is specified, it is the length of the common
RNAME. The specified length can be in the range of 1 to 255. This overrides any RNAMEs lengths specified in the resource table. The default is
DO_NOT_OVERRIDE.
To code:
Specify the RS-type address, or address in register (2)-(12), of an one-byte field.
,RNL=YES
,RNL=NO
When RESERVEVOLUME=NO, RESLIST=NO and REQUEST=OBTAIN are specified, an optional parameter that indicates whether the scope can be changed by global resource serialization resource name list (RNL) processing or the dynamic exits. The default is RNL=YES.
,RNL=YES
Indicates that global resource serialization RNL processing should be used, which can cause the scope of a resource to change. IBM suggests that you use the default, RNL=YES, to allow global resource serialization to perform
RNL processing.
,RNL=NO
Indicates that global resource serialization RNL processing should not be used. The scope of the resource is not changed by the RNLs nor any dynamic exits. Use RNL=NO when you are sure that you want the request to be processed only by global resource serialization using only the specified scope. When RNL=NO is specified, the ENQ request can be ignored by alternative serialization products.
,RNL=DO_NOT_OVERRIDE
,RNL=YES
,RNL=NO
When RESLIST=YES and REQUEST=OBTAIN are specified, an optional parameter that indicates whether the scope can be changed by global resource serialization resource name list (RNL) processing or the dynamic exits. This overrides any RNL processing specified in the resource table. The default is
RNL=DO_NOT_OVERRIDE.
,RNL=DO_NOT_OVERRIDE
Indicates that the RNL specifications in the resource table should be used.
470
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
,RNL=YES
Indicates that global resource serialization RNL processing should be used, which can cause the scope of a resource to change. IBM suggests that you use the default, RNL=YES, to allow global resource serialization to perform
RNL processing.
,RNL=NO
Indicates that global resource serialization RNL processing should not be used. The scope of the resource cannot be changed by the RNLs or any dynamic exits. Use RNL=NO when you are sure that you want the request to be processed only by global resource serialization using only the specified scope. When RNL=NO is specified, the ENQ request is ignored by alternative serialization products.
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (0) or
(2)-(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).
,SCOPE=STEP
,SCOPE=SYSTEM
,SCOPE=SYSTEMS
,SCOPE=SYSPLEX
,SCOPE=VALUE
When RESERVEVOLUME=NO, RESLIST=NO and REQUEST=OBTAIN are specified, a required parameter that is the scope of the resource.
,SCOPE=STEP
Indicates that the resource is serialized only within an address space. If
STEP is specified, a request for the same QNAME and RNAME from a program in another address space denotes a different resource.
,SCOPE=SYSTEM
Indicates that the resource is serialized across all address spaces in a system.
,SCOPE=SYSTEMS
Indicates that the resource is serialized across all systems in a GRS Star or
GRS Ring complex.
,SCOPE=SYSPLEX
Indicates that the resource is serialized across all systems in a GRS Star sysplex or GRS ring. (Same as scope SYSTEMS.)
,SCOPE=VALUE
the user provides a value, through the SCOPEVAL keyword, indicating the requested scope.
,SCOPE=DO_NOT_OVERRIDE
,SCOPE=STEP
,SCOPE=SYSTEM
,SCOPE=SYSTEMS
,SCOPE=SYSPLEX
When RESLIST=YES and REQUEST=OBTAIN are specified, an optional parameter that is the scope to be used for all resources in the resource table.
This overrides any scopes specified in the resource table. The default is
SCOPE=DO_NOT_OVERRIDE.
Chapter 60. ISGENQ — Global resource serialization ENQ service
471
ISGENQ macro
,SCOPE=DO_NOT_OVERRIDE
Indicates that the scope specified in the resource table should be used.
,SCOPE=STEP
Indicates that the resource is serialized only within an address space. If
STEP is specified, a request for the same QNAME and RNAME from a program in another address space denotes a different resource.
,SCOPE=SYSTEM
Indicates that the resource is serialized across all address spaces in a system.
,SCOPE=SYSTEMS
Indicates that the resource is serialized across all systems in a GRS Star or
GRS Ring complex.
,SCOPE=SYSPLEX
Indicates that the resource is serialized across all systems in a GRS Star sysplex or GRS ring. (Same as scope SYSTEMS.)
,SCOPEVAL=scopeval
When SCOPE=VALUE, RESERVEVOLUME=NO, RESLIST=NO and
REQUEST=OBTAIN are specified, a required input parameter that contains a value indicating the desired scope. The value provided must be equivalent to the constants provided in the ISGYENQ macro indicating the scope. (See the
ISGYENQ_ constants in the ISGYENQ macro for more information.)
To code:
Specify the RS-type address, or address in register (2)-(12), of an one-byte field.
,SYNCHRES=SYSTEM
,SYNCHRES=YES
,SYNCHRES=NO
When RESERVEVOLUME=YES, RESLIST=NO and REQUEST=OBTAIN are specified, an optional parameter that specifies whether the request should issue a synchronous reserve. A synchronous reserve immediately reserves the volume instead of waiting for the first use.
Note that an RC=4 (ISGENQRc_Warn), RSC=0403
(ISGENQRsn_ECBWillBePosted) is presented for CONTENTIONACT=WAIT,
WAITTYPE=ECB, reserve requests (where UCB@ is specified) when there is contention on the ENQ resource or there was no contention on the resource, and the reserve I/O was done synchronously. The default is
SYNCHRES=SYSTEM.
,SYNCHRES=SYSTEM
Indicates that the installation system default SYNCHRES setting should be used.
,SYNCHRES=YES
Indicates to issue a synchronous reserve. In cases where the hardware reserve is performed (it was not converted to a Global/Systems ENQ), the caller is ensured that the reserve I/O is complete when the ISGENQ request has successfully completed.
,SYNCHRES=NO
Indicates that a synchronous reserve should be avoided when possible.
Some devices require that the reserve must be done synchronously regardless of this setting. If the reserve I/O is not done synchronously, the
472
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
reservce is done when the first I/O is done to the device after the reserve request is issued. For more information, see z/OS MVS Planning: Global
Resource Serialization.
,SYNCHRES=DO_NOT_OVERRIDE
,SYNCHRES=SYSTEM
,SYNCHRES=YES
,SYNCHRES=NO
When RESLIST=YES and REQUEST=OBTAIN are specified, an optional parameter that specifies whether all requests specified in the resource table should issue a synchronous reserve. This overrides any SYNCHRES specified in the resource table. A synchronous reserve immediately reserves the volume instead of waiting for the first use. The default is
SYNCHRES=DO_NOT_OVERRIDE.
,SYNCHRES=DO_NOT_OVERRIDE
Indicates that the SYNCHRES specified in the resource table should be used.
,SYNCHRES=SYSTEM
Indicates that the system default setting should be used.
,SYNCHRES=YES
Indicates to issue a synchronous reserve. In cases where the the hardware reserve is performed (it was not converted to a Global/Systems ENQ), the caller is ensured that the reserve I/O is complete when the request has successfully completed.
,SYNCHRES=NO
Indicates that a synchronous reserve should be avoided when possible.
Some devices require that the reserve must be done synchronously regardless of this setting. If the reserve I/O is not done synchronously, the reserve is done when the first I/O is done to the device after the reserve request is issued. See z/OS MVS Planning: Global Resource Serialization for more information.
,TEST=NO
,TEST=YES
When REQUEST=OBTAIN is specified, an optional parameter. The default is
TEST=NO.
,TEST=NO
Indicates that this is not a test request. The ENQ must be obtained.
,TEST=YES
Indicates that this is a test request. The ENQ must not be obtained. This parameter setting can be used to obtain information about how the given obtain request is processed and how a resource is currently held by the current task or a task specified by OWNINGTTOKEN.
Mutually exclusive with COND=NO.
For existing requests from the same task, which match the specified resource, the ENQToken of that request is returned.
See ISGQUERY SEARCH=BY_ENQTOKEN for information about outstanding ENQ requests.
The following return and reason codes can be used to determine if the resource is available and how it might be held by the OWNINGTTOKEN task: v ISGENQRc_ok
Chapter 60. ISGENQ — Global resource serialization ENQ service
473
ISGENQ macro
v ISGENQRsn_NotImmediatelyAvailable v
ISGENQRsn_TaskOwnsExclusive v ISGENQRsn_TaskOwnsShared v ISGENQRsn_TaskWaiting
,UCB@=ucb@
When RESERVEVOLUME=YES, RESLIST=NO and REQUEST=OBTAIN are specified, a required input parameter that contains the address of the UCB for the device to be reserved. For unauthorized callers, the UCB must be allocated to the job step before ISGENQ RESERVEVOLUME(YES) is issued.
Note: Authorized callers do not need to allocate the UCB to the job step before invoking ISGENQ, but the caller must serialize the UCB against dynamic I/O reconfiguration requests. The caller can accomplish this serialization by allocating or pinning the UCB. Such serialization ensures that a dynamic I/O reconfiguration request does not delete or reuse the UCB before the ISGENQ macro uses the address.
To code:
Specify the RS-type address, or address in register (2)-(12), of a pointer field.
,UCB@=ucb@
,UCB@=DO_NOT_OVERRIDE
When RESLIST=YES and REQUEST=OBTAIN are specified, an optional input parameter that contains the address of the UCB@ for the device to be reserved for all resources in the resource table. This overrides any UCB addresses specified in the resource table. The default is DO_NOT_OVERRIDE.
To code:
Specify the RS-type address, or address in register (2)-(12), of a pointer field.
,USERDATA=userdata
,USERDATA=NO_USERDATA
When TEST=NO and REQUEST=OBTAIN are specified, an optional input parameter that contains the userdata to be associated with this request. For information about using USERDATA as a filter, or making ISGQUERY return
Note that GRS has no interests in the contents of the USERDATA. Unlike the
QNAME, RNAME, and SCOPE parameters, USERDATA has no meaning in the definition of the logically serialized resource identity. For example, exclusive requests with different user data and the same QNAME, RNAME, and SCOPE contend with each other.
This request requires a version 2 parameter list. The default is
NO_USERDATA.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
32-character field.
,WAITTYPE=SUSPEND
,WAITTYPE=ECB
When CONTENTIONACT=WAIT, TEST=NO and REQUEST=OBTAIN are specified, an optional parameter that indicates the method by which the caller waits. The default is WAITTYPE=SUSPEND.
,WAITTYPE=SUSPEND
Indicates that the current task is suspended until the entire request is completed.
474
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
,WAITTYPE=ECB
Indicates that if contention for the ENQ resource exists or the device
reserve is done synchronously (see “,SYNCHRES=SYSTEM” on page 472),
return to the caller, and post the ECB when the request is complete.
Mutually exclusive with COND=NO.
WAITTYPE=ECB in combination with setting a timer with ECB can be used to control the amount of time that you are willing to wait for either
ENQ contention or a synchronous reserve to complete. If the request does not complete before the time expires you can do the following actions.
v You can use the the ISGECA and ISGQUERY services to interrogate the overall state of the request and associated resource.
v You can back out of the request using an ISGENQ REQUEST=RELEASE request."
ABEND codes
For REQUEST=OBTAIN and REQUEST=CHANGE requests the caller might encounter abend codes X'138', X'238', X'338', X'438', X'538', X'638', X'738', X'838',
X'938'.
For REQUEST=RELEASE requests the caller might encounter abend codes X'130',
X'230', X'330', X'430', X'530', X'630', X'730', X'830', X'930'.
For explanations and responses for these codes, see z/OS MVS System Codes.
Note that the ABEND reason codes correspond to the same reason codes listed in
Return and reason codes
When the ISGENQ macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code
RSNCODE) contains a reason code.
Macro ISGYCON provides equate symbols for the return and reason codes.
The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code. IBM support the xxxx value, where xxxx represent 4 hex digits. Note that when the xxxx value is 'E0F2' hexadecimal, it indicates a reason-code set by the ISGNQXITBATCH or
ISGNQXITBATCHCND exits.
Table 31. Return and Reason Codes for the ISGENQ Macro
Return Code
00
Reason Code
—
Equate Symbol Meaning and Action
Equate Symbol
: ISGENQRc_OK
Meaning
: ISGENQ request successful. Depending on the type of request, the ENQ is successfully obtained, changed to exclusive, or released. If RESLIST=YES is specified, all ENQ obtain, change, and release requests are successful. For REQUEST=OBTAIN,
TEST=YES, the resource is immediately available.
Action
: None required.
Chapter 60. ISGENQ — Global resource serialization ENQ service
475
ISGENQ macro
Table 31. Return and Reason Codes for the ISGENQ Macro (continued)
Return Code
04
Reason Code
—
Equate Symbol Meaning and Action
Equate Symbol
: ISGENQRc_Warn
04 xxxx0401
Meaning
: Warning
Action
: Refer to action under the individual reason code.
Equate Symbol
: ISGENQRsn_NonZeroReturnCodes
Meaning
: A non-zero return code was issued for one or more entries in a RESLIST=YES request. The return table has the return and reason codes for each of the requests in the list.
04
04
04
04 xxxx0402 xxxx0403 xxxx0404 xxxx0405
Action
: See the return and reason codes returned in the
RETURNTABLE.
Equate Symbol
: ISGENQRsn_RequestNotProcessed
Meaning
: For RESLIST=YES requests. One of the other requests in the RESTABLE failed such that this request was prevented from being processed. Note that requests in a RESTABLE are not necessarily processed in the order they appear in the RESTABLE.
Note: This reason code returned only in the RETURNTABLE, not through the RSNCODE keyword.
Action
: Check the return and reason codes for all other requests in the RETURNTABLE to identify the problem.
Equate Symbol
: ISGENQRsn_ECBWillBePosted
Meaning
: For REQUEST=OBTAIN CONTENTIONACT=WAIT
WAITTYPE=ECB, the OBTAIN request was successful, but the
ENQ resource was not immediately available or the reserve I/O needed to be done synchronously (SYNCHRES). The ECB is posted when all requested resources are owned by the specified task, or when an error has occurred. The ENQToken for the request has been returned.
Action
: Wait on the ECB and check the return code in the ECB before using the requested resources.
Equate Symbol
: ISGENQRsn_NotImmediatelyAvailable
Meaning
: The ENQ of the resource was not immediately available. For REQUEST=OBTAIN CONTENTIONACT=FAIL, the requested resource is not obtained. For REQUEST=OBTAIN
TEST=YES, the holder is a task other than OWNINGTTOKEN.
Action
: No action required.
Equate Symbol
: ISGENQRsn_TaskOwnsExclusive
Meaning
: For REQUEST=OBTAIN, including TEST=YES, the given task specified by OWNINGTTOKEN already owns the specified resource exclusively. The ENQToken for the owning request has been returned.
Action
: No action required.
476
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
Table 31. Return and Reason Codes for the ISGENQ Macro (continued)
Return Code
04
Reason Code
xxxx0406
Equate Symbol Meaning and Action
Equate Symbol
: ISGENQRsn_TaskOwnsShared
Meaning
: For a REQUEST=OBTAIN, including TEST=YES, the given task specified by OWNINGTTOKEN already owns the specified resource shared. The ENQToken for the owning request has been returned.
04
04
04 xxxx0407 xxxx0409 xxxx040A
Action
: No action required.
Equate Symbol
: ISGENQRsn_TaskWaiting
Meaning
: For a REQUEST=OBTAIN, including TEST=YES, the given task specified by OWNINGTTOKEN is already waiting for control of the specified resource. The ENQToken for the waiting request has been returned.
Action
: No action required.
Equate Symbol
: ISGENQRsn_OtherSharedOwners
Meaning
: For REQUEST=CHANGE. The control cannot be changed to exclusive. There are other shared owners of the resource.
Action
: No action required.
Equate Symbol
: ISGENQRsn_TaskDoesNotOwn
Meaning
: For REQUEST=CHANGE. The control cannot be changed to exclusive. The task does not yet own the resource.
04 xxxx040B
Action
: No action required.
Equate Symbol
: ISGENQRsn_TaskSuspendedForResource
Meaning
: For REQUEST=RELEASE. The task that requested the
ENQ obtain has not yet been assigned control of the resource The task continues waiting and the resource is not released. (This reason code might result in an exit routine, which received control because of an interruption, issued a RELEASE reqquest on behalf of the task.)
Action
: Correct the program so that the ISGENQ RELEASE request is issued only after the ISGENQ OBTAIN request has returned to the task. If possible, avoid issuing the RELEASE request in the exit routine.
Chapter 60. ISGENQ — Global resource serialization ENQ service
477
ISGENQ macro
Table 31. Return and Reason Codes for the ISGENQ Macro (continued)
Return Code
04
Reason Code
xxxx040D
Equate Symbol Meaning and Action
Equate Symbol
: ISGENQRsn_UnprotectedQName
Meaning
: For REQUEST=OBTAIN. An authorized caller requested an ENQ with an unauthorized QNAME.
For TEST=NO,COND=YES, the OBTAIN request completed successfully, an unauthorized caller under the same owning task might release the ENQ. The ENQToken has been returned.
For TEST=NO, COND=NO, the requester was abended with a
X'438' abend. The request might not have completed successfully
For TEST=YES requests, the resource is currently available.
04
04 xxxx040E xxxx040F
Action
: No action required. If the ENQ needs to be protected from unauthorized RELEASE requests or from unauthorized callers obtaining an ENQ to block this request, specifiy one of the authorized QNAMEs for the resource.
Equate Symbol
: ISGENQRsn_UnprotectedExitQNAME
Meaning
: For REQUEST=OBTAIN. An authorized caller requested an ENQ with a QNAME that a dynamic exit changed to an unauthorized QNAME. For TEST=NO, the OBTAIN request completed successfully, an unauthorized caller under the same owning task might release the ENQ. The ENQToken has been returned. For TEST=YES requests, the resource is currently available but the QNAME was changed by a dynamic exit to an unprotected QNAME.
Action
: No action required. Contact the system programmer, if the
ENQ needs to be protected from unauthorized RELEASE requests or from unauthorized callers obtaining an ENQ to block this request. The system programmer should check the ISGNQXIT installation exits to ensure that they are not coded to specify an unauthorized QNAME for authorized requests.
Equate Symbol
: ISGENQRsn_ECBAtleastOneRequestFailed
Meaning
: For REQUEST=OBTAIN RESLIST=Yes with ECB@, at least one request failed to be processed. Some requests might have been processed unsuccessfully. The system might not backout any successfully processed requests.
08 —
Note: This reason code is returned in a posted ECB, not through the RSNCODE or RETURNTABLE keywords.
Action
: The user should issue an ISGQUERY on the ENQTOKENs to see if they were obtained and take appropriate action.
Alternately, the user can release all the ENQs with a ISGENQ
REQUEST=RELEASE with ENQTOKENTBL and reissue the
ISGENQ OBTAIN request.
Equate Symbol
: ISGENQRc_ParmError
Meaning
: ISGENQ request specified parameters in error.
Action
: Refer to action under the individual reason code.
478
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
Table 31. Return and Reason Codes for the ISGENQ Macro (continued)
Return Code
08
Reason Code
xxxx0801
Equate Symbol Meaning and Action
Equate Symbol
: ISGENQRsn_BadPlistAddress
08
08 xxxx0802 xxxx0803
Meaning
: Unable to access parameter list.
Action
: Check that the entire parameter list is addressable. If in
AR-mode, check that the ALET of the parameter list is correct.
Note that if this macro is issued in AR-mode, SYSSTATE
ASCENV=AR must be issued before this macro. Ensure that the storage is in the same key as the caller.
Equate Symbol
: ISGENQRsn_BadPlistALET
Meaning
: Bad parameter list ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's
Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the parameter list is valid. Its access register may not have been set up properly.
Equate Symbol
: ISGENQRsn_BadPlistVersion
Meaning
: Bad parameter list version number. The service level of
GRS on which the caller is running does not support this version of the ISGENQ service, or the ISGENQ parameter list version is lower than the minimum required for parameters that were specified.
08
08 xxxx0804 xxxx0805
Action
: Check for possible storage overlay of the parameter list.
Retry the request with the correct version number. Verify that your program was assembled with the correct macro library for the release of MVS on which your program is running.
Equate Symbol
: ISGENQRsn_ReservedFieldNotNull
Meaning
: A reserved field in the parameter list is non-zero.
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGENQRsn_MutuallyExclusive
Meaning
: Mutually exclusive keywords were specified.
08
08
08 xxxx0806 xxxx0807 xxxx0808
Action
: Check for a possible storage overlay of the parameter list.
Equate Symbol
: ISGENQRsn_BadRequest
Meaning
: Bad REQUEST parameter.
Action
: IBM suggests that the ISGENQ macro is used when invoking the ISGENQ service.
Equate Symbol
: ISGENQRsn_BadContentionAct
Meaning
: Bad CONTENTIONACT parameter.
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGENQRsn_BadOwningTToken
Meaning
: The specified TToken does not represent a valid task.
Action
: Ensure that the task token (TToken) represents a valid task.
Chapter 60. ISGENQ — Global resource serialization ENQ service
479
ISGENQ macro
Table 31. Return and Reason Codes for the ISGENQ Macro (continued)
Return Code
08
Reason Code
xxxx0809
Equate Symbol Meaning and Action
Equate Symbol
: ISGENQRsn_BadAnsAreaAddress
08
08 xxxx080A xxxx080B
Meaning
: Unable to access the answer area.
Action
: Ensure that the entire answer area is addressable. If in
AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Check that the specified answer area length is correct. Ensure that the storage is in the same key as the caller.
Equate Symbol
: ISGENQRsn_BadAnsAreaALET
Meaning
: Bad answer area ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable
Unit Access List (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the answer area is valid. Its access register may not have been set up properly.
Equate Symbol
: ISGENQRsn_AnsLenTooSmall
Meaning
: The specified answer area length was too small to return the requested information.
08
08 xxxx080C xxxx080D
Action
: Invoke ISGENQ again with a larger answer area. The answer area length needed is dependent on the number of resource requests specified in NUMRES.
Equate Symbol
: ISGENQRsn_BadRNameAddress
Meaning
: Unable to access the RNAME.
Action
: Ensure that the entire RNAME is addressable. If in
AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Check that the specified
RNAME length is correct. Ensure that the storage is in the same key as the caller.
Equate Symbol
: ISGENQRsn_BadRnameALET
Meaning
: Bad RNAME ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable
Unit Access List (DU-AL), nor a valid entry for a common area data space.
08
08 xxxx080E xxxx080F
Action
: Ensure that the ALET of the RNAME is valid. Its access register may not have been set up properly.
Equate Symbol
: ISGENQRsn_BadRNameLen
Meaning
: The RNAME length specified is not valid.
Action
: Ensure the RNAME length field contains a number in the range of 1-255.
Equate Symbol
: ISGENQRsn_BadScope
Meaning
: Bad SCOPE keyword parameter.
Action
: Check for possible storage overlay of the parameter list.
480
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
Table 31. Return and Reason Codes for the ISGENQ Macro (continued)
Return Code
08
Reason Code
xxxx0810
Equate Symbol Meaning and Action
Equate Symbol
: ISGENQRsn_BadUCB@
08
08 xxxx0811 xxxx0812
Meaning
: The storage specified by the UCB@ keyword does not map to a valid UCB.
Action
: Ensure that the UCB@ points to a valid UCB.
Equate Symbol
: ISGENQRsn_BadCond
Meaning
: Bad COND keyword parameter.
Action
: IBM suggests that the ISGENQ macro is used when invoking the ISGENQ service.
Equate Symbol
: ISGENQRsn_BadSynchRes
08
08
08
08 xxxx0813 xxxx0814 xxxx0815 xxxx0816
Meaning
: Bad SYNCHRES keyword parameter.
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGENQRsn_BadENQTokenAddress
Meaning
: Unable to access the ENQToken.
Action
: Ensure that the entire ENQToken is addressable. If in
AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Ensure that the storage is in the same key as the caller. Note: The ISGENQ request might not have completed.
Equate Symbol
: ISGENQRsn_BadENQTokenALET
Meaning
: Bad ENQToken ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable
Unit Access List (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the ENQToken is valid. Its access register may not have been set up properly. Note: The ISGENQ request might not have completed.
Equate Symbol
: ISGENQRsn_BadENQToken
Meaning
: For REQUEST=RELEASE or REQUEST=CHANGE, the specified ENQToken does not represent an ENQ for the given task
(current task or specified by OWNINGTTOKEN).
Action
: Ensure that the specified ENQToken is from a previous request for the given task, that has not been subsequently released.
Equate Symbol
: ISGENQRsn_BadNumRes
Meaning
: The NUMRES specified is not valid.
Action
: Ensure the NUMRES field contains a number in the range of 1-65535 (2?6-1)
Chapter 60. ISGENQ — Global resource serialization ENQ service
481
ISGENQ macro
Table 31. Return and Reason Codes for the ISGENQ Macro (continued)
Return Code
08
Reason Code
xxxx0817
Equate Symbol Meaning and Action
Equate Symbol
: ISGENQRsn_BadResTableAddress
08 xxxx0818
Meaning
: Unable to access the resource table.
Action
: Ensure that the entire resource table is addressable. If in
AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Check that the resource table length is correct. Ensure that the storage is in the same key as the caller.
Equate Symbol
: ISGENQRsn_BadResTableALET
08
08 xxxx0819 xxxx081A
Meaning
: Bad resource table ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's
Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the resource table is valid. Its access register may not have been set up properly.
Equate Symbol
: ISGENQRsn_BadResTable
Meaning
: The RESTABLE specified is not valid.
Action
: Ensure that the resource table does not specify mutually exclusive parameters.
Equate Symbol
: ISGENQRsn_BadENQTokenTblAddress
Meaning
: Unable to access the ENQToken table.
08
08 xxxx081B xxxx081C
Action
: Ensure that the entire ENQToken table is addressable. If in AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Check that the ENQToken table length is correct. Ensure that the storage is in the same key as the caller. Note: The ISGENQ request might not have completed.
Equate Symbol
: ISGENQRsn_BadENQTokenTblALET
Meaning
: Bad ENQToken table ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's
Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the ENQToken table is valid. Its access register may not have been set up properly. Note: The
ISGENQ request might not have completed.
Equate Symbol
: ISGENQRsn_BadReturnTableAddress
Meaning
: Unable to access the return table.
Action
: Ensure that the entire return table is addressable. If in
AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Check that the return table length is correct. Ensure that the storage is in the same key as the caller. Note: The ISGENQ request might not have completed.
482
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
Table 31. Return and Reason Codes for the ISGENQ Macro (continued)
Return Code
08
Reason Code
xxxx081D
Equate Symbol Meaning and Action
Equate Symbol
: ISGENQRsn_BadReturnTableALET
08 xxxx081E
Meaning
: Bad return table ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable
Unit Access List (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the return table is valid. Its access register may not have been set up properly. Note: The
ISGENQ request might not have completed.
Equate Symbol
: ISGENQRsn_NotAuthorizedForQName
Meaning
: For REQUEST=OBTAIN. An unauthorized caller specified an authorized QNAME.
08
08 xxxx081F xxxx0821
Action
: Unauthorized callers must avoid specifying the authorized QNAMEs listed in the ISGENQ macro prologue.
Equate Symbol
: ISGENQRsn_NotAuthorizedForExitQname
Meaning
: For REQUEST=OBTAIN. An ISGNQXIT exit specified an authorized QNAME for an unauthorized OBTAIN request.
Action
: Contact your system programmer. The system programmer should check the ISGNQXIT installation exits to ensure they are not coded to specify an authorized QNAME for unauthorized requests.
Equate Symbol
:
ISGENQRsn_NotAuthorizedForOWNINGTTOKEN
Meaning
: An unauthorized caller specified OWNINGTTOKEN.
08
08 xxxx0822 xxxx0823
Action
: Unauthorized callers should avoid specifying
OWNINGTTOKEN.
Equate Symbol
: ISGENQRsn_BadUserDataAddress
Meaning
: Unable to access the USERDATA.
Action
: Ensure that the entire USERDATA is addressable. If in
AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Ensure that the storage is in the same key as the caller.
Equate Symbol
: ISGENQRsn_BadUserDataAlet
Meaning
: Bad UserData ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable
Unit Access List (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the userdata is valid. Its access register may not have been set up properly.
Chapter 60. ISGENQ — Global resource serialization ENQ service
483
ISGENQ macro
Table 31. Return and Reason Codes for the ISGENQ Macro (continued)
Return Code
08
Reason Code
xxxx0824
Equate Symbol Meaning and Action
Equate Symbol
: ISGENQRsn_DeviceNotAllocated
Meaning
: For REQUEST=OBTAIN with RESERVEVOLUME=YES.
An unauthorized caller specified a device that is not allocated to the requesting task.
08
08 xxxx0825 xxxx0826
Action
: Unauthorized callers should allocate the UCB to the job step before ISGENQ RESERVEVOLUME(YES) is issued.
Equate Symbol
: ISGENQRsn_ExitDeviceNotAllocated
Meaning
: For REQUEST=OBTAIN. An ISGNQXIT exit specified a
UCB for a device that is not allocated to the requesting, unauthorized task.
Action
: Contact your system programmer. The system programmer should ensure that the installation exits do not modify the UCB to specify one that is not allocated to an unauthorized requests.
Equate Symbol
: ISGENQRsn_BadControl
08
08
0C
0C xxxx0827 xxxx0828
— xxxx0C01
Meaning
: Bad CONTROL keyword parameter.
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGENQRsn_BadExitUCB@
Meaning
: The storage pointed to by the UCB address changed by a dynamic exit does not map to a valid UCB.
Action
: Contact your system programmer. The system programmer should ensure that the installation exits do not specify a bad UCB address.
Equate Symbol
: ISGENQRsn_NotAuthorizedForENQMAX
Meaning
: For REQUEST=OBTAIN, an unauthorized caller specified ENQMAX=NO.
Action
: Unauthorized callers should avoid specifying
ENQMAX=NO.
Equate Symbol
: ISGENQRc_EnvError
Meaning
: ISGENQ request has an environment error.
Action
: Refer to action under the individual reason code.
Equate Symbol
: ISGENQRsn_RequestLimitExceeded
Meaning
: For REQUEST=OBTAIN, the limit for the number of concurrent resource requests has been reached. The task does not have control of the resource unless some previous ENQ or
RESERVE request caused the task to obtain control of the resource.
Action
: Retry the request one or more times. If the problem persists, consult your system programmer. For more information on concurrent count limits and how the system can be tuned when necessary, see z/OS MVS Planning: Global Resource
Serialization.
484
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
Table 31. Return and Reason Codes for the ISGENQ Macro (continued)
Return Code
0C
Reason Code
xxxx0C05
Equate Symbol Meaning and Action
Equate Symbol
: ISGENQRsn_AbendInExit
0C xxxx0C0A
Meaning
: One of the GRS dynamic exits abended.
Action
: Retry the request one or more times. Contact your system programmer.
Equate Symbol
: ISGENQRsn_TaskEnding
Meaning
: The task represented by the specified TToken was ending. The point was reached in task termination after which no
ENQs can be obtained.
0C
0C
0C
0C
0C
0C xxxx0C0B xxxx0C0C xxxx0C0D xxxx0C0E xxxx0C0F xxxx0C10
Action
: Determine why the task identified by the TToken was ending. Correct that error and retry the request.
Equate Symbol
: ISGENQRsn_FRRHeld
Meaning
: The caller issued ISGENQ when an FRR was established.
Action
: Avoid issuing ISGENQ when using functional recovery routines.
Equate Symbol
: ISGENQRsn_LockHeld
Meaning
: A lock was held upon entry. No locks can be held when calling ISGENQ.
Action
: Avoid using ISGENQ when locks are held.
Equate Symbol
: ISGENQRsn_SrbMode
Meaning
: ISGENQ was issued while in SRB mode.
Action
: Avoid using ISGENQ in SRB mode.
Equate Symbol
: ISGENQRsn_NotEnabled
Meaning
: ISGENQ was issued while not enabled.
Action
: Avoid using ISGENQ when not enabled.
Equate Symbol
: ISGENQRsn_MasidTarget
Meaning
: The requester to be released is still the target of an ENQ with the MASID and MTCB options specified. The release does complete and the resource might be damaged.
Action
: The task that issued the ENQ macro instruction with
MASID and MTCB should issue the DEQ before this requester does so.
Equate Symbol
: ISGENQRsn_UnsupportedMode.
Meaning
: The current GRS mode does not support this specific request.
Action
: Defer the usage of this particular type of request.
Chapter 60. ISGENQ — Global resource serialization ENQ service
485
ISGENQ macro
Table 31. Return and Reason Codes for the ISGENQ Macro (continued)
Return Code
0C
Reason Code
xxxx0C11
Equate Symbol Meaning and Action
Equate Symbol
: ISGENQRsn_MasidNotSupported.
10 —
Meaning
: The resource that was the target of this
REQUEST=CHANGE,CONTROL=SHARED request currently or at one time contained MASID users.
REQUEST=CHANGE,CONTROL=SHARED is not supported for resources that involve MASID requestors.
Action
: Do not use REQUEST=CHANGE,CONTROL=SHARED on resources that involve MASID requestors.
Equate Symbol
: ISGENQRc_CompError
10 xxxx1002
Meaning
: Component Error.
Action
: Contact the IBM Support Center.
Reason code that are not defined below contain internal diagnostic information.
Equate Symbol
: ISGENQRsn_CannotObtainHomeStorage
10
10
10
10
10
10
10
10 xxxx1003 xxxx1004 xxxx1006 xxxx1007 xxxx1008 xxxx1009 xxxx100A xxxx100B
Meaning
: ISGENQ processing could not obtain storage in the home address space.
Equate Symbol
: ISGENQRsn_CannotObtainCommonStorage
Meaning
: ISGENQ processing could not obtain storage in the common area.
Equate Symbol
: ISGENQRsn_CannotObtainPrimaryAlet
Meaning
: ISGENQ processing could not obtain the ALET of the caller's primary address space.
Equate Symbol
: ISGENQRsn_SynchResFlushFailed
Meaning
: For REQUEST=OBTAIN, a synchronous reserve failed device state transition flushing.
Equate Symbol
: ISGENQRsn_ReserveStartFailed
Meaning
: For REQUEST=OBTAIN, reserve start processing failed.
Equate Symbol
: ISGENQRsn_ReserveCountOverflow
Meaning
: For REQUEST=OBTAIN, reserve processing detected an overflow when updating the reserve count.
Equate Symbol
: ISGENQRsn_CannotObtainDSQE
Meaning
: ISGENQ processing could not obtain a DSQE to suspend a request during an RNL change.
Equate Symbol
: ISGENQRsn_ReserveDoneFailed
Meaning
: For REQUEST=OBTAIN, synchronous reserve back end processing has failed; therefore, the reserve was never completed.
Equate Symbol
: ISGENQRsn_CannotObtainPrimaryStorage
Meaning
: ENQ/DEQ processing could not obtain storage in the primary address space.
486
z/OS MVS Assembler Services Reference IAR-XCT
ISGENQ macro
Examples
Use these examples as a guide.
* **********************************************************************
* Request exclusive control of a single resource
* **********************************************************************
ISGENQ REQUEST=OBTAIN,QNAME=QNAM1,RNAME=RNAM1,RNAMELEN=RLEN1, X
SCOPE=SYSTEMS,CONTROL=EXCLUSIVE,ENQTOKEN=ENQT1
* **********************************************************************
* Release control of a single resource
* **********************************************************************
ISGENQ REQUEST=RELEASE,ENQTOKEN=ENQT1,COND=YES,
RETCODE=(3),RSNCODE=(2)
X
* ***********************************************************************
* Conditionally request shared control of 3 resources
* ***********************************************************************
ISGENQ REQUEST=OBTAIN,RESLIST=YES,NUMRES=3,RESTABLE=RSTBL,
ENQTOKENTBL=ETTBL,RETURNTABLE=RTTBL,COND=YES,
RETCODE=(3),RSNCODE=(2),PLISTVER=1
X
X
ENTRY2 DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
ENTRY3 DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
QNAM1
RNAM1
RLEN1
RNAM2
RNAM3 DC
DS
RSTBL DS
ENTRY1 DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
CL8’QNAME1’
CL10’RNAME1’
AL1(L’RNAM1)
CL12’RNAME2’
CL14’RNAME3’
0D
0CL(3*ISGYENQRES_LEN)
CL8’QNAME1’ QNAME
F’0’
A(RNAM1)
F’0’
A(0)
FIRST WORD OF RNAME ADDR
RNAME ADDR31
RNAME ALET
UCB@
RNAME LENGTH AL1(L’RNAM1)
AL1(ISGYENQ_kSTEP)
AL1(ISGYENQ_kCONTROLSHARED)
XL1’00’
XL4’00’
FLAGS
RESERVED
CL8’QNAME2’
F’0’
A(RNAM2)
F’0’
QNAME
FIRST WORD OF RNAME ADDR
RNAME ADDR31
RNAME ALET
A(0)
AL1(L’RNAM2)
UCB@
RNAME LENGTH
AL1(ISGYENQ_kSYSTEM)
AL1(ISGYENQ_kCONTROLSHARED)
XL1’00’
XL4’00’
CL8’QNAME3’
F’0’
A(RNAM3)
F’0’
A(0)
AL1(L’RNAM3)
FLAGS
RESERVED
QNAME
FIRST WORD OF RNAME ADDR
RNAME ADDR31
RNAME ALET
UCB@
RNAME LENGTH
AL1(ISGYENQ_kSYSTEMS)
AL1(ISGYENQ_kCONTROLSHARED)
XL1’00’
XL4’00’
FLAGS
RESERVED
DYNAREA DSECT
ENQT1 DS
ETTBL
RTTBL
DS
DS
CL(ISGYENQTOKEN_LEN)
CL(3*ISGYENQTOKEN_LEN)
CL(3*ISGYENQRETURN_LEN)
Chapter 60. ISGENQ — Global resource serialization ENQ service
487
ISGENQ macro
* **********************************************************************
* Request exclusive control of a single resource with userdata
* **********************************************************************
ISGENQ REQUEST=OBTAIN,QNAME=QNAM1,RNAME=RNAM1,RNAMELEN=RLEN1, X
SCOPE=SYSTEMS,CONTROL=EXCLUSIVE,ENQTOKEN=ENQT1,
USERDATA=UDATA1
X
UDATA1 DC CL32’MY USERDATA’
For more information on global resource serialization, see z/OS MVS Planning:
Global Resource Serialization.
488
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 61. ISGQUERY — Global resource serialization query service
|
|
|
Description
The GRS query service routine is given control from the ISGQUERY macro to: v Search a resource name list (RNL) for a QNAME/RNAME pair.
v Obtain information on resources and requesters of outstanding ENQ requests.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Problem state. Any PSW key
Task
Any PASN, any HASN, any SASN
31- or 64-bit
If in AMODE 64, specify SYSSTATE AMODE64=YES before invoking this macro.
Primary or access register (AR)
If in Access Register ASC mode, specify SYSSTATE
ASCENV=AR before invoking this macro.
Enabled for I/O and external interrupts
For REQINFO=RNLSEARCH, the caller can be unlocked or hold both a local lock (LOCAL or CML) and the CMSEQDQ lock.
For REQINFO=QSCAN, the caller must not hold any locks.
Control parameters must be in the primary address space or for AR-mode callers, must be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
The control parameters must be in the same key as the caller.
For an AMODE 64 caller, the control parameters can reside in virtual storage above the 2G bar.
The user-provided answer area that uses the ANSAREA parameter has the same requirements and restrictions as the control parameters.
Programming requirements
The caller must include the ISGYQUAC macro to get a mapping for the answer area.
Note:
The ISGYQUAC macro is stabilized as of z/OS R12.
The caller must include the ISGYCON macro to get the values for the return and reason codes.
© Copyright IBM Corp. 1988, 2017
489
ISGQUERY macro
The caller must include the ISGRNLE macro to get a mapping for the RNLE.
Restrictions
Do not issue ISGQUERY before the GRS address space has been initialized.
There is a restriction on the number of concurrent resource requests in an address space. These include unauthorized ISGENQ, ENQ, RESERVE, and incomplete
GQSCAN and ISGQUERY requests. Reason code
ISGQUERYRsn_MaxConcurrentRequests is issued if ISGQUERY would cause this limit to be exceeded.
When multilevel security support is active on the system, unauthorized callers of
ISGQUERY who specify REQINFO=QSCAN must have at least READ authorization to the ISG.QSCANSERVICES.AUTHORIZATION resource in the
FACILITY class. When multilevel security support is active on the system, unauthorized callers of ISGQUERY who specify REQINFO=LATCHECA must have at least READ authorization to the ISG.LATCHECASERVICES.AUTHORIZATION
resource in the FACILITY class. You can activate the multilevel security support through the SETROPTS MLACTIVE option in RACF. For general information about defining profiles in the FACILITY class, see z/OS Security Server RACF Command
Language Reference and z/OS Security Server RACF Security Administrator's Guide. For information about multilevel security, see z/OS Planning for Multilevel Security and
the Common Criteria.
Callers who specify REQINFO=LATCHECA must not hold any FRRs.
This macro supports multiple versions. Some keywords are unique to certain versions. For more information, see the description of the
“,PLISTVER=IMPLIED_VERSION” on page 499 parameter and the common
criteria.
Input register information
Before issuing the ISGQUERY macro, the caller does not have to place any information into any general-purpose register (GPR) or access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code if GPR15 is not 0.
Used as a work register by the system.
2-13
14
15
Unchanged
Used as a work register by the system.
Return code.
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Used as work registers by the system.
490
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
2-13
Unchanged
14-15
Used as work registers by the system.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
In general, the narrower the search parameters (particularly QNAME and
RNAME), the less time the query takes. Using both a specific QNAME and a specific RNAME gives better performance than using patterns.
The use of GATHERFROM=SYSPLEX might greatly degrade the performance of the query request.
Polling for ENQ contention through GQSCAN or ISGQUERY is not recommended.
See the z/OS MVS Planning: Global Resource Serialization and z/OS MVS
Programming: Authorized Assembler Services Guide for more information about monitoring contention through ENF 51.
Chapter 61. ISGQUERY — Global resource serialization query service
491
ISGQUERY macro
Syntax main diagram
►► b ISGQUERY b
name
► REQINFO = RNLSEARCH parameters-1
REQINFO = ENQSTATS , ASID =
asid
, ANSAREA =
ansarea
REQINFO = QSCAN parameters-2
REQINFO = LATCHECA parameters-5
REQINFO = USAGESTATS , ANSAREA =
ansarea
, ANSLEN =
anslen
►
, RETCODE =
retcode
, RSNCODE =
rsncode
, PLISTVER = IMPLIED_VERSION
, PLISTVER = MAX
, PLISTVER = 1
, PLISTVER = 2
►
, MF = S
, MF = ( L ,
list addr
, MF = ( E ,
list addr
, 0D
,
attr
, COMPLETE
)
)
parameters-1
►► , RNL = SIRNL
, RNL = SERNL
, RNL = RCRNL
►
, RNLE =
rnle
, QNAME =
qname
, RNAME =
rname
, RNAMELEN =
rnamelen
parameters-2
►► , SCANACTION = START parameters-3
, SCANACTION = RESUME , RESUMETOKEN =
resumetoken
, ANSAREA =
ansarea
, ANSLEN =
anslen
, SCANACTION = QUIT , RESUMETOKEN =
resumetoken
►◄
►
►
►
►
►◄
►◄
492
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro parameters-3
►►
, RESUMETOKEN =
resumetoken
, ANSAREA =
ansarea
, ANSLEN =
anslen
►
, ANSDETAIL = SUMMARY
, ANSDETAIL = FULL
, ANSDETAIL = FULL2
, ANSDETAIL = FULL3
,
,
GATHERFROM
GATHERFROM
►
, REQUESTERLIMIT = 32767
, REQUESTERLIMIT =
requesterlimit
,
,
=
=
SYSTEM
SYSPLEX
SEARCH
SEARCH
=
=
BY_ENQTOKEN
BY_FILTER
, ENQTOKEN parameters-4
=
enqtoken
►
►
►◄
parameters-4
►► , QNAMEMATCH = SPECIFIC , QNAME =
qname
, QNAMEMATCH = PATTERN , QNAME =
qname
► , RNAMEMATCH = ANY
, RNAMEMATCH = SPECIFIC , RNAME =
rname
, RNAMELEN =
rnamelen
, RNAMEMATCH = PATTERN , RNAME =
rname
, RNAMELEN =
rnamelen
►
, SCOPE = ANY
, SCOPE = STEP
, SCOPE = SYSTEM
, SCOPE = SYSTEMS
, SCOPE = SYSPLEX
, SERIALIZEBY = ANY
, SERIALIZEBY = RESERVE
, SERIALIZEBY = ENQ_ONLY
,
,
SYSNAME
SYSNAME
=
=
ANY_SYSNAME
sysname
►
►
,
,
, ASID = ANY_ASID
, ASID =
asid
, JOBNAME = ANY_JOBNAME
, JOBNAME =
jobname
, TTOKEN = ANY_TTOKEN
, TTOKEN =
ttoken
MINOWNERS
MINOWNERS
=
=
NO_MINOWN
minowners
, MINREQUESTERS = NO_MINREQ
, MINREQUESTERS =
minrequesters
, MINWAITERS = NO_MINWAIT
, MINWAITERS =
minwaiters
►
, USERDATAMATCH = ANY
, USERDATAMATCH = SPECIFIC , USERDATA =
userdata
, USERDATAMATCH = PATTERN , USERDATA =
userdata
, USERDATALEN =
userdatalen
parameters-5
►► , ANALYZE = WAITER
, ANSAREA =
ansarea
, ANSLEN =
anslen
►
►
►
►
►
►◄
►◄
Chapter 61. ISGQUERY — Global resource serialization query service
493
ISGQUERY macro
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1 that is the name on the ISGQUERY macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
,ANALYZE=WAITER
When REQINFO=LATCHECA is specified, a required output parameter, which queries LATCHECA waiter data to determine if any long-term latch contention exists that might be cause for concern. ISGQUERY returns only LATCHECA data for waiters.
,ANSAREA=ansarea
When REQINFO=ENQSTATS is specified, a required output parameter, which is to contain the returned information. The area is mapped by macro
ISGYQUAC. A header area, which is mapped by DSECT ISGYQUAAHdr, is returned followed by additional data, two entries mapped by ISGYQUAASys and two entries mapped by ISGYQUAASp.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,ANSAREA=ansarea
When REQINFO=LATCHECA is specified, a required output parameter, which is to contain the returned information. The area is mapped by macro
ISGYQUAC. A header area, which is mapped by DSECT ISGYQUAAHdr, is returned followed by additional data mapped by ISGYQUAALd and
ISGYQUAALrd.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,ANSAREA=ansarea
When REQINFO=USAGESTATS is specified, a required output parameter, which is to contain the returned information. The area is mapped by macro
ISGYQUAC. A header area, which is mapped by DSECT ISGYQUAAHdrUs, is returned followed by additional data mapped by ISGYQUAAUs.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,ANSAREA=ansarea
When REQINFO=QSCAN is specified, this required output parameter contains the returned information. The area is mapped by macro ISGYQUAC. A header area, which is mapped by DSECT ISGYQUAAHdr, is returned followed by additional data mapped by ISGYQUAARs, ISGYQUAARsx, ISGYQUAARq, and ISGYQUAARqx.
Note:
The ANSDETAIL specified determines which data is returned.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,ANSDETAIL=SUMMARY
,ANSDETAIL=FULL
,ANSDETAIL=FULL2
494
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
,ANSDETAIL=FULL3
When SCANACTION=START and REQINFO=QSCAN are specified, an optional parameter that indicates the detail level of the information that should be returned in the answer area. The default is ANSDETAIL=SUMMARY.
,ANSDETAIL=SUMMARY
Indicates to return only ISGYQUAAHdr, ISGYQUAARs, and
ISGYQUAARq answer area data records. See ISGYQUAC mapping macro to know what data is returned in each type of record.
,ANSDETAIL=FULL
Indicates to return ISGYQUAAHdr, ISGYQUAARs, ISGYQUAARq, and
ISGYQUAARqx answer area data records. See ISGYQUAC mapping macro to know what data is returned in each type of record.
,ANSDETAIL=FULL2
Indicates that in addition to the records returned by ANSDETAIL=FULL, the ISGYQUAARsx, and the larger FULL2 version of the ISGYQUAARqx is returned. See ISGYQUAC mapping macro to know what data is returned in each type of record.
,ANSDETAIL=FULL3
Indicates that in addition to the records returned by ANSDETAIL=FULL2,
USERDATA is returned for any records that specified USERDATA on
ISGENQ.
Note:
When GATHERFROM=SYSPLEX is specified and GRS is operating in STAR mode, USERDATA is not returned for any global requests. See
ISGYQUAC mapping macro to know what data is returned in each type of record.
,ANSLEN=anslen
When SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the length of the answer area provided. The minimum size is the amount needed to describe a single resource with a single requester.
Use an answer area length of at least 4 KB.
v For ANSDETAIL=SUMMARY, the minimum is defined by constant
ISGYQUAA_kQSCANMinSummaryAnslen.
v For ANSDETAIL=FULL, the minimum is defined by constant
ISGYQUAA_kQSCANMinFullAnslen.
v For ANSDETAIL=FULL2, the minimum is defined by constant
ISGYQUAA_kQSCANMinFull2Anslen.
v
For ANSDETAIL=FULL3, the minimum is defined by constant
ISGYQUAA_kQSCANMinFull3Anslen.
The length of the answer area is at least 4k.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.
,ANSLEN=anslen
When SCANACTION=RESUME and REQINFO=QSCAN are specified, a required input parameter that is the length of the answer area provided. The minimum size is the amount needed to describe a single resource with a single requester. Use an answer area length of at least 4 KB. For
ANSDETAIL=SUMMARY, the minimum is defined by constant
ISGYQUAA_kQSCANMinSummaryAnslen. For ANSDETAIL=FULL, the minimum is defined by constant ISGYQUAA_kQSCANMinFullAnslen. For
ANSDETAIL=FULL2, the minimum is defined by constant
Chapter 61. ISGQUERY — Global resource serialization query service
495
ISGQUERY macro
ISGYQUAA_kQSCANMinFull2Anslen. For ANSDETAIL=FULL3, the minimum is defined by constant ISGYQUAA_kQSCANMinFull3Anslen. use an answer area length of at least 4 KB.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.
,ANSLEN=anslen
When REQINFO=LATCHECA is specified, a required input parameter that is the length of the answer area provided. The minimum size is the amount needed to describe a single resource with a single requester. Use an answer area length of at least 4 K.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.
,ANSLEN=anslen
When REQINFO=USAGESTATS is specified, a required input parameter that is the length of the answer area provided. The minimum size is the amount needed to describe the ENQ, QScan, and latch usage of a single address space and the usage information for terminated address spaces. The minimum is defined by constant ISGYQUAA_kUSAGESTATSMinAnslen. Use an answer area length of at least 4 KB.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.
,ASID=asid
When REQINFO=ENQSTATS is specified, a required input parameter that is the ASID of the address space-specific information to be returned.
Note:
ASIDs are reusable. Once an address space has terminated another can be created with the same ASID.
To code:
Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.
,ASID=asid
,ASID=ANY_ASID
When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the ASID of the requesting tasks for which resource information is to be returned. Only information on requester with that ASID is returned.
Note:
ASID is reusable. Once an address space has terminated another can be created with the same ASID.
The default is ANY_ASID.
To code:
Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.
,ENQTOKEN=enqtoken
When SEARCH=BY_ENQTOKEN, SCANACTION=START and
REQINFO=QSCAN are specified, a required input parameter that is the
ENQToken of the request that is to be queried. Note: ENQTokens are only valid on the system where the ENQ request was made.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
32-character field.
,GATHERFROM=SYSTEM
496
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
,GATHERFROM=SYSPLEX
When SCANACTION=START and REQINFO=QSCAN are specified, an optional parameter that designates the extent to which the search is taken.
Information about other systems is always available locally in a global resource serialization ring complex, so this keyword is ignored and forced to
GATHERFROM=SYSTEM.
Use the SYSNAME keyword to obtain only information about one particular system.
Note: Only SYSTEMS scope information is obtained from other systems in the global resource serialization complex.
The default is GATHERFROM=SYSTEM.
,GATHERFROM=SYSTEM
Indicates to search only the caller's system. The answer area data contains information about requester on other systems in the complex only if that information is already available on the caller's system. The returned information might be incomplete regarding requester on other systems, including counts of the number of requester for a resource. If performance is an issue, use GATHERFROM=SYSTEM. This request is always handled without placing the caller's dispatchable unit into a wait.
,GATHERFROM=SYSPLEX
Indicates to search the caller's sysplex. The answer area data contains information about requesters in the entire sysplex. If complete information regarding requesters in the sysplex is required use
GATHERFROM=SYSPLEX. There are significant performance implications for this search and the caller might be suspended while the information is being gathered. Do not specify GATHERFROM=SYSPLEX if this condition cannot be tolerated.
GATHERFROM=SYSPLEX is mutually exclusive with the
USERDATAMATCH=SPECIFIC and USERDATAMATCH=PATTERN filter options.
When global resource serialization is in STAR mode,
GATHERFROM=SYSPLEX with ANSDETAIL=FULL3 results in no user data being returned for global requests.
,JOBNAME=jobname
,JOBNAME=ANY_JOBNAME
When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the job name of the requesting tasks for which resource information is to be returned. Only information on requesters with that job name is returned. The default is
ANY_JOBNAME.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.
Chapter 61. ISGQUERY — Global resource serialization query service
497
ISGQUERY macro
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and
MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,MINOWNERS=minowners
,MINOWNERS=NO_MINOWN
When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the minimum number of owners of a resource required for that resource to be returned. If any of the conditions specified by MINREQUESTERS, MINOWNERS, or MINWAITERS is met, even if the other two are not met, information for that resource and its requester is returned. The default is NO_MINOWN.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.
,MINREQUESTERS=minrequesters
,MINREQUESTERS=NO_MINREQ
When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the minimum number of owners plus waiters for a resource required for that resource to be returned. If any of the conditions specified by MINREQUESTERS, MINOWNERS, or
MINWAITERS is met, even if the other two are not met, information for that resource and its requesters is returned. The default is NO_MINREQ.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.
,MINWAITERS=minwaiters
,MINWAITERS=NO_MINWAIT
When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the minimum number of waiters for a resource required for that resource to be returned. If any of the conditions specified by MINREQUESTERS, MINOWNERS, or MINWAITERS is
498
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
met, even if the other two are not met, information for that resource and its requester is returned. The default is NO_MINWAIT.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=1
,PLISTVER=2
An optional input parameter in the 1-2 range that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 1 , if you use the currently available parameters:
– ANSAREA
– ANSDETAIL
– ANSLEN
– ASID
– ENQTOKEN
– GATHERFROM
– JOBNAME
– MINOWNERS
– MINREQUESTERS
– MINWAITERS
– QNAME
– QNAMEMATCH
– REQINFO
– REQUESTERLIMIT
– RESUMETOKEN
– RNAME
– RNAMELEN
– RNAMEMATCH
– RNL
– RNLE
– SCANACTION
– SCOPE
Chapter 61. ISGQUERY — Global resource serialization query service
499
ISGQUERY macro
– SEARCH
– SERIALIZEBY
– SYSNAME
– TTOKEN v 2 , which supports both the following parameters and those from version 1:
– USERDATA
– USERDATALEN
– USERDATAMATCH
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v
A decimal value of 1, or 2
,QNAME=qname
When REQINFO=RNLSEARCH is specified, a required input parameter that is the Qname of the resource for which the RNLs are to be searched.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,QNAME=qname
When QNAMEMATCH=SPECIFIC, SEARCH=BY_FILTER,
SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the specific Qname of the resources to be returned.
To code:To code:
Specify the RS-type address, or address in register (2)-(12), of an 8-character field.
,QNAME=qname
When QNAMEMATCH=PATTERN, SEARCH=BY_FILTER,
SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is a pattern Qname to match the resources to be returned.
The Qname pattern is 8 characters where “?” matches any single character, and
“*” matches any string of zero or more characters.
Note:
All trailing blanks are ignored when matching Qnames to Qname patterns.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,QNAMEMATCH=SPECIFIC
,QNAMEMATCH=PATTERN
When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required parameter.
,QNAMEMATCH=SPECIFIC
Indicates to only return information on resources that exactly match the specified specific Qname.
,QNAMEMATCH=PATTERN
Indicates to only return information on resources that match the specified
Qname pattern.
REQINFO=RNLSEARCH
REQINFO=ENQSTATS
REQINFO=QSCAN
500
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
REQINFO=LATCHECA
REQINFO=USAGESTATS
A required parameter that designates the data to be returned.
REQINFO=RNLSEARCH
Indicates to search a specific RNL for a resource name.
Therefore, the CMSEQDQ lock serializes the use of the RNLs, so holding this lock ensures that the RNL does not change and the returned RNLE is valid on the current RNLs.
During an RNL change, the currently active RNLs are searched.
For more information about how a resource can be changed by the system,
REQINFO=ENQSTATS
Indicates to return information related to ENQ counts.
REQINFO=QSCAN
Indicates to search the global resource serialization queues for resource and requester information.
REQINFO=LATCHECA
Indicates to search the global resource serialization queues for query latch enhanced contention analysis (ECA) data for waiters that might indicate contention issues.
Note: The LATCHECA search does not return data for blockers or dependency data.
REQINFO=USAGESTATS
Indicates to search the global resource serialization queues for address space level contention information related to ENQs (all scopes) and latches
(all latch sets). Global resource serialization gathers latch statistics in requester and latch set owner address space categories. The statistics are provided for all address spaces as follows: v ENQ by scope: this includes contention counts, total delay times, and the sum of the squared delay (SUMSQ) times. The SUMSQ times can be used to compute the standard deviation.
v Latch: For both requester and latch set owners, this includes contention counts, total delay times, and the sum of the squared delay (SUMSQ) times v ENQ usage counts.
Note:
Latch counts are kept in “fast counts” in latch sets and not on an address space basis.
,REQUESTERLIMIT=requesterlimit
,REQUESTERLIMIT=32767
When SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the maximum number of requesters (owners and waiters) to be returned for each individual resource. Only resource-related information is returned if 0 is specified. The value range of REQUESTERLIMIT is 0 to 2¬15-1 (32767). The default is 32767.
To code:
Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.
Chapter 61. ISGQUERY — Global resource serialization query service
501
ISGQUERY macro
,RESUMETOKEN=resumetoken
When SCANACTION=START and REQINFO=QSCAN are specified, an optional output parameter that is the resume token for this search. When
RESUMETOKEN is specified, a reason code of ISGQUERYRsn_AnswerAreaFull indicates that the token can be used to resume the scan on a subsequent call.
Subsequently, if the return code indicates that the search can be resumed, a
SCANACTION=RESUME or SCANACTION=QUIT with the returned resume token must be issued.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,RESUMETOKEN=resumetoken
When SCANACTION=RESUME and REQINFO=QSCAN are specified, a required input/output parameter that is the resume token from a previously started search. If the search does not complete the resume token can be used to resume the search on a subsequent call. Check the return code to determine if the resume token can be used to resume the scan. Subsequently, if the return code indicates that the search can be resumed, a SCANACTION=RESUME or
SCANACTION=QUIT with the returned resume token must be issued.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,RESUMETOKEN=resumetoken
When SCANACTION=QUIT and REQINFO=QSCAN are specified, a required input/output parameter that is the resume token from a previously started search. Any global resource serialization storage associated with the search is freed, and the resume token is cleared to binary zeros.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12) or
(15), (GPR15), (REG15), or (R15).
,RNAME=rname
When REQINFO=RNLSEARCH is specified, a required input parameter that is the RName of the resource for which the RNLs are to be searched.
The RName pattern is a string of characters where “?” matches any single character, and “*”matches any string of zero or more characters.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,RNAME=rname
When RNAMEMATCH=SPECIFIC, SEARCH=BY_FILTER,
SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the specific RName of the resources to be returned.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,RNAME=rname
When RNAMEMATCH=PATTERN, SEARCH=BY_FILTER,
SCANACTION=START and REQINFO=QSCAN are specified, a required input
502
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
parameter that is a pattern RName to match the resources to be returned. The
RName pattern is a string of characters where '?' matches any single character, and '*' matches any string of zero or more characters.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,RNAMELEN=rnamelen
When REQINFO=RNLSEARCH is specified, a required input parameter that is the length of the RName. The specified length can be 1 - 255.
To code:
Specify the RS-type address, or address in register (2)-(12), of a one-byte field.
,RNAMELEN=rnamelen
When RNAMEMATCH=SPECIFIC, SEARCH=BY_FILTER,
SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the length of the RName. The specified length can be 1 - 255.
To code:
Specify the RS-type address, or address in register (2)-(12), of a 1-byte field.
,RNAMELEN=rnamelen
When RNAMEMATCH=PATTERN, SEARCH=BY_FILTER,
SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the length of the RName pattern. The specified length can be
1 - 255.
To code:
Specify the RS-type address, or address in register (2)-(12), of a 1-byte field.
,RNAMEMATCH=ANY
,RNAMEMATCH=SPECIFIC
,RNAMEMATCH=PATTERN
When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, a required parameter.
,RNAMEMATCH=ANY
Indicates to return information on resources with any RName.
,RNAMEMATCH=SPECIFIC
Indicates to return information on resources that exactly match the specified specific RName.
,RNAMEMATCH=PATTERN
Indicates to return information on resources that match the specified
RName pattern.
,RNL=SIRNL
,RNL=SERNL
,RNL=RCRNL
When REQINFO=RNLSEARCH is specified, a required parameter that indicates which resource name list (RNL) is to be searched.
,RNL=SIRNL
Indicates to search the system inclusion RNL.
,RNL=SERNL
Indicates to search the systems exclusion RNL.
,RNL=RCRNL
Indicates to search the reserve conversion RNL.
Chapter 61. ISGQUERY — Global resource serialization query service
503
ISGQUERY macro
,RNLE=rnle
When REQINFO=RNLSEARCH is specified, an optional output parameter that is a copy of the matching RNLE. The caller must include the ISGRNLE macro to get a mapping for the RNLE.
Note: The RNLE returned depends on the version of the parameter list. If a new version of the RNLE should be introduced, it might require a larger character field. Explicitly state the PLISTVER to ensure that the size of the
RNLE returned does not change.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value is left in GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (0) or
(2)-(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).
,SCANACTION=START
,SCANACTION=RESUME
,SCANACTION=QUIT
When REQINFO=QSCAN is specified, a required parameter that designates whether to start, resume, or quit a QScan.
,SCANACTION=START
Indicates to start a search of the global resource serialization queues.
,SCANACTION=RESUME
Indicates to resume a previously started search.
,SCANACTION=QUIT
Indicates to quit a previously started search. If a started search has not completed, it must be either resumed until it completes or ended with
SCANACTION=QUIT.
,SCOPE=ANY
,SCOPE=STEP
,SCOPE=SYSTEM
,SCOPE=SYSTEMS
,SCOPE=SYSPLEX
When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional parameter that is the scope of the resources to be returned.
Note:
Only information on resources with scope of SYSTEMS is returned from systems other than the caller's system.
The default is SCOPE=ANY.
,SCOPE=ANY
Indicates to return information on resources with any scope.
,SCOPE=STEP
Indicates to return information on resources with a scope of STEP.
,SCOPE=SYSTEM
Indicates to return information on resources with a scope of SYSTEM.
504
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
,SCOPE=SYSTEMS
Indicates to return information on resources with a scope of SYSTEMS or
SYSPLEX.
,SCOPE=SYSPLEX
Indicates to return information on resources with a scope of SYSTEMS or
SYSPLEX. (SYSPLEX is an alias for SYSTEMS.)
,SEARCH=BY_ENQTOKEN
,SEARCH=BY_FILTER
When SCANACTION=START and REQINFO=QSCAN are specified, a required parameter that designates the method to search for resources.
,SEARCH=BY_ENQTOKEN
Indicates to search using a specific ENQToken. Information is returned about the requester of the ENQ and the resource for which the ENQ was requested.
,SEARCH=BY_FILTER
Indicates to search on resource and requester characteristics using filters.
Information is returned about the resources and requesters that match the search criteria.
,SERIALIZEBY=ANY
,SERIALIZEBY=RESERVE
,SERIALIZEBY=ENQ_ONLY
When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional parameter that indicates if information should be returned depending on whether the requests are serialized by device reserves.
The default is SERIALIZEBY=ANY.
,SERIALIZEBY=ANY
Indicates to return information on requests of any type.
,SERIALIZEBY=RESERVE
Indicates to return information on reserve requests that were not converted.
,SERIALIZEBY=ENQ_ONLY
Indicates to return information on requests that do not result in a device reserve. This includes reserve requests that were converted to global ENQs.
Answer area bit ISGYQUAARqReserveConverted is set for reserve requests that were converted.
,SYSNAME=sysname
,SYSNAME=ANY_SYSNAME
When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the system name of the requesting tasks for which resource information is to be returned. Only information on requester in that system is returned. If
GATHERFROM=SYSTEM is specified (or is the default), SYSNAME might only be the name of the caller's system or the default of ANY_SYSNAME.
Note: Only information on resources with scope of SYSTEMS is returned from systems other than the caller's system.
The default is ANY_SYSNAME.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,TTOKEN=ttoken
Chapter 61. ISGQUERY — Global resource serialization query service
505
ISGQUERY macro
,TTOKEN=ANY_TTOKEN
When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional input parameter that is the task token of the requesting task for which resource information is to be returned. Only information on that requester is returned. The TToken specified is valid only on the current system.
Note: The TToken of requesters is unavailable for ENQs obtained before the global resource serialization address space was created. The TToken filter will not match those ENQ requesters.
The default is ANY_TTOKEN.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,USERDATA=userdata
When USERDATAMATCH=SPECIFIC, SEARCH=BY_FILTER,
SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the specific UserData of the requests to be returned.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
32-character field.
,USERDATA=userdata
When USERDATAMATCH=PATTERN, SEARCH=BY_FILTER,
SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is a pattern UserData to match the requests to be returned. The
UserData pattern is a string of characters where '?' matches any single character, and '*' matches any string of zero or more characters.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
32-character field.
,USERDATALEN=userdatalen
When USERDATAMATCH=PATTERN, SEARCH=BY_FILTER,
SCANACTION=START and REQINFO=QSCAN are specified, a required input parameter that is the length of the given UserData pattern. The specified length can be 1 - 32.
To code:
Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.
,USERDATAMATCH=ANY
,USERDATAMATCH=SPECIFIC
,USERDATAMATCH=PATTERN
When SEARCH=BY_FILTER, SCANACTION=START and REQINFO=QSCAN are specified, an optional parameter that indicates which requests to return.
The default is USERDATAMATCH=ANY.
,USERDATAMATCH=ANY
Indicates to return information on request with any USERDATA, including those with no USERDATA.
,USERDATAMATCH=SPECIFIC
Indicates to only return requests that have USERDATA that exactly matches the specified USERDATA. For information about specifying
can only be attached to a request through the ISGENQ interface.
This request requires a version 2 parameter list.
506
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
GATHERFROM=SYSPLEX is mutually exclusive with the
USERDATAMATCH=SPECIFIC option.
,USERDATAMATCH=PATTERN
Indicates to only return information on requests that match the specified
UserData pattern. For information about specifying USERDATA on an
ISGENQ request, see Chapter 60, “ISGENQ — Global resource serialization
All trailing blanks are not ignored when matching USERDATA to
USERDATA patterns. For example, if the USERDATA is ABC123, and the pattern used to search is A*3, it does not match. A pattern such as A*3* does match.
Note: Userdata can only be attached to a request through the ISGENQ interface.
This request requires a version 2 parameter list.
GATHERFROM=SYSPLEX is mutually exclusive with the
USERDATAMATCH=PATTERN option.
ABEND codes
None.
Return and reason codes
When the ISGQUERY macro returns control to your program: v
GPR 15 (and retcode, when you code RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code
RSNCODE) contains a reason code.
Macro ISGYCON provides equate symbols for the return and reason codes.
The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code. IBM support personnel can request the entire reason code, including the xxxx value.
Table 32. Return and Reason Codes for the ISGQUERY Macro
Return Code
00
Reason Code
—
Equate Symbol Meaning and Action
Equate Symbol
: ISGQUERYRc_OK
04 —
Meaning
: ISGQUERY request successful.
For REQINFO=RNLSEARCH, a matching RNLE was found for the given resource name. For REQINFO=QSCAN, processing complete and data has been copied into the answer area. There are no more data to return.
Action
: None required.
Equate Symbol
: ISGQUERYRc_Warn
Meaning
: Warning. ISGQUERY completed successfully, however a warning has been issued.
Action
: Refer to action under the individual reason code.
Chapter 61. ISGQUERY — Global resource serialization query service
507
ISGQUERY macro
Table 32. Return and Reason Codes for the ISGQUERY Macro (continued)
Return Code
04
Reason Code
xxxx0401
Equate Symbol Meaning and Action
Equate Symbol
: ISGQUERYRsn_NoMatchingRNLE
04 xxxx0402
Meaning
: For a REQINFO=RNLSEARCH request. No matching
RNLE was found for the given resource name.
Action
: No action required.
Equate Symbol
: ISGQUERYRsn_RNLChangeInProgress
Meaning
: For a REQINFO=RNLSEARCH request. A matching
RNLE was found for the given resource name, but an RNL change is in progress in the system.
04
04 xxxx0403 xxxx0404
Action
: No action required.
Equate Symbol
: ISGQUERYRsn_GRSRNLExclude
Meaning
: For a REQINFO=RNLSEARCH request.
GRSRNL=EXCLUDE is in effect. When GRSRNL=EXCLUDE the
RNLs are not used and all SYSTEMS scope requests are forced to
SYSTEM. An alternative serialization product can be in use. No
RNLE is returned.
Action
: No action required.
Equate Symbol
: ISGQUERYRsn_NoMatchingResources
Meaning
: For REQINFO=QSCAN and REQINFO=LatchECA requests. While scanning the queues, no resources were found that match the caller's request.
04
04
08 xxxx0405 xxxx0406
—
Action
: No action required.
Equate Symbol
: ISGQUERYRsn_AnswerAreaFull
Meaning
: For a REQINFO=QSCAN request. ISGQUERY has provided some data, however the answer area is too small to contain all the requested data.
Action
: The user should process the data in the answer area.
If RESUMETOKEN was not specified on the request and more information is needed, re-issue the request with a larger answer area or specify a resume token.
If RESUMETOKEN was specified, either issue a
REQINFO=QSCAN SCANACTION=RESUME request with the returned resume token to continue continue the scan, or issue
REQINFO=QSCAN SCANACTION=QUIT to end the search.
Equate Symbol
: ISGQUERYRsn_GRSNone
Meaning
: For a REQINFO=RNLSEARCH request. GRS=NONE is in effect. When GRS=NONE the RNLs are not used and all requests are serialized only within the current system. Note that though both scope SYSTEM and SYSTEMS requests are local to the current system, they still represent separate resouces and are
NOT serialized with each other.
Equate Symbol
: ISGQUERYRc_ParmError
Meaning
: ISGQUERY request specified parameters in error.
Action
: Refer to action under the individual reason code.
508
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
Table 32. Return and Reason Codes for the ISGQUERY Macro (continued)
Return Code
08
Reason Code
xxxx0801
Equate Symbol Meaning and Action
Equate Symbol
: ISGQUERYRsn_BadPlistAddress
08 xxxx0802
Meaning
: Unable to access parameter list.
Action
: Check that the entire parameter list is addressable. If in
AR-mode, check that the ALET of the parameter list is correct.
Note that if this macro is issued in AR-mode, SYSSTATE
ASCENV=AR must be issued before this macro. Ensure that the storage is in the same key as the caller.
Equate Symbol
: ISGQUERYRsn_BadPlistALET
08
08 xxxx0803 xxxx0804
Meaning
: Bad parameter list ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's dispatchable unit access list (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the parameter list is valid. Its access register might have been set up properly.
Equate Symbol
: ISGQUERYRsn_BadPlistVersion
Meaning
: Bad parameter list version number. The service level of
GRS on which the caller is running does not support this version of the ISGQUERY service, or the ISGQUERY parameter list version is lower than the minimum required for parameters that were specified.
Action
: Check that the request has the correct version number.
Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_ReservedFieldNotNull
Meaning
: A reserved field in the parameter list is non-zero.
08
08
08 xxxx0805 xxxx0806 xxxx0807
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_BadReqInfo
Meaning
: Bad REQINFO parameter.
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_BadRNL
Meaning
: Bad RNL parameter.
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_BadRNameAddress
Meaning
: Unable to access the RName.
Action
: Ensure that the entire RName field is addressable. If in
AR-mode, this field is accessed through its address and ALET, check that both these values are correct. Check that specified
RName length is correct. Ensure that the storage is in the same key as the caller.
Chapter 61. ISGQUERY — Global resource serialization query service
509
ISGQUERY macro
Table 32. Return and Reason Codes for the ISGQUERY Macro (continued)
Return Code
08
Reason Code
xxxx0808
Equate Symbol Meaning and Action
Equate Symbol
: ISGQUERYRsn_BadRNameALET
08 xxxx0809
Meaning
: Bad RName ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's dispatchable unit access list (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the RName is valid. Its access register might have been set up properly.
Equate Symbol
: ISGQUERYRsn_BadRNameLen
Meaning
: The RName length specified is not valid.
08
08
08 xxxx080A xxxx080B xxxx080C
Action
: Ensure the RName length field contains a number from
1-255.
Equate Symbol
: ISGQUERYRsn_BadRNLEAddress
Meaning
: Unable to access RNLE output field.
Action
: Ensure that the entire RNLE field is addressable. If in
AR-mode, this field is accessed through its address and ALET, check that both these values are correct. Check that RNLE length is correct. Ensure that the storage is in the same key as the caller.
Equate Symbol
: ISGQUERYRsn_BadRNLEALET
Meaning
: Bad RNLE ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's dispatchable unit access list (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the RNLE is valid. Its access register might have been set up properly.
Equate Symbol
: ISGQUERYRsn_MutuallyExclusive
08
08 xxxx080D xxxx080E
Meaning
: Mutually exclusive keywords were specified.
Action
: Check for a possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_BadAnsAreaAddress
Meaning
: Unable to access the answer area.
Action
: Ensure that the entire answer area is addressable. If in
AR-mode, this field is accessed through its address and ALET, check that both these values are correct. Check that the specified answer area length is correct. Ensure that the storage is in the same key as the caller.
Equate Symbol
: ISGQUERYRsn_BadAnsAreaALET
Meaning
: Bad answer area ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable
Unit Access List (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the answer area is valid. Its access register might have been set up properly.
510
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
Table 32. Return and Reason Codes for the ISGQUERY Macro (continued)
Return Code
08
Reason Code
xxxx080F
Equate Symbol Meaning and Action
Equate Symbol
: ISGQUERYRsn_BadScanAction
08
08 xxxx0810 xxxx0811
Meaning
: Bad SCANACTION parameter.
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_BadResumeTokenAddress
Meaning
: Unable to access the ResumeToken.
Action
: Ensure that the entire ResumeToken is addressable. If in
AR-mode, this field is accessed through its address and ALET, check that both these values are correct. Ensure that the storage is in the same key as the caller.
Equate Symbol
: ISGQUERYRsn_BadResumeTokenALET
08
08 xxxx0812 xxxx0813
Meaning
: Bad ResumeToken ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's dispatchable unit access list (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the ResumeToken is valid. Its access register might not have been set up properly.
Equate Symbol
: ISGQUERYRsn_BadGatherFrom
Meaning
: Bad GATHERFROM parameter.
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_BadSearch
Meaning
: Bad SEARCH keyword parameter.
08
08
08 xxxx0814 xxxx0815 xxxx0816
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_BadENQTokenAddress
Meaning
: Unable to access the ENQToken.
Action
: Ensure that the entire ENQToken is addressable. If in
AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Ensure that the storage is in the same key as the caller.
Equate Symbol
: ISGQUERYRsn_BadENQTokenALET
Meaning
: Bad ENQToken ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's dispatchable unit access list (DU-AL), nor a valid entry for a common area data space.
Action
: Ensure that the ALET of the ENQToken is valid. Its access register might have been set up properly.
Equate Symbol
: ISGQUERYRsn_BadQNameMatch
Meaning
: Bad QNAMEMATCH keyword parameter.
Action
: Check for possible storage overlay of the parameter list.
Chapter 61. ISGQUERY — Global resource serialization query service
511
ISGQUERY macro
Table 32. Return and Reason Codes for the ISGQUERY Macro (continued)
Return Code
08
Reason Code
xxxx0817
Equate Symbol Meaning and Action
Equate Symbol
: ISGQUERYRsn_BadRNameMatch
08 xxxx0818
Meaning
: Bad RNAMEMATCH keyword parameter.
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_BadScope
Meaning
: Bad SCOPE keyword parameter.
08
08
08 xxxx0819 xxxx081A xxxx081B
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_BadSerializeBy
Meaning
: Bad SERIALIZEBY keyword parameter.
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_AnsLenTooSmall
Meaning
: The size of the answer area is not large enough to contain the minimal amount of information.
Action
: Increase the answer area size to at least the minimum required for the specified request. See the provided constants.
However, the answer area length should be at least 4k.
Equate Symbol
: ISGQUERYRsn_ResumeTokenNotValid
08
08
08
08 xxxx081C xxxx081D xxxx081E xxxx081F
Meaning
: The specified resume token is not a valid resume token.
Action
: Ensure the resume token is from a previously started search on the current system.
Equate Symbol
: ISGQUERYRsn_ResumeTokenTooOld
Meaning
: The specified resume token is from an old search request that has expired.
Action
: Restart the search if more information is needed.
Equate Symbol
: ISGQUERYRsn_ENQTokenNotValid
Meaning
: The ENQToken specified is not a valid ENQToken.
Action
: Ensure the ENQToken is from a previous ISGENQ request on the current system.
Equate Symbol
: ISGQUERYRsn_BadRequesterLimit
Meaning
: The REQUESTERLIMIT value specified is not valid.
RequesterLimit must be 0 - 2?5-1 (32767).
Action
: Ensure that the requester limit is in the correct range.
Equate Symbol
: ISGQUERYRsn_NoPossibleMatch
Meaning
: For a REQINFO=QSCAN request. Conflicting parameters were specified such that no resources could possibly match the request. A SYSNAME other than the current system was specified along with SCOPE=STEP, SCOPE=SYSTEM,
TTOKEN, or GATHERFROM=SYSTEM. Or
SERIALIZEBY=RESERVE was specified with SCOPE=STEP.
Action
: Avoid specifying conflicting parameters.
512
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
Table 32. Return and Reason Codes for the ISGQUERY Macro (continued)
Return Code
08
Reason Code
xxxx0820
Equate Symbol Meaning and Action
Equate Symbol
: ISGQUERYRsn_BadAnsDetail
08
08 xxxx0821 xxxx0822
Meaning
: Bad ANSDETAIL keyword parameter.
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_NotAuthToQscan
Meaning
: SETROPTS MLACTIVE is in effect, and the program is not authorized to issue ISGQUERY REQINFO=QSCAN.
Action
: Ensure that the program is running authorized, or is associated with a user id with at least READ access to the best fit
FACILITY class resource profile of the form
ISG.QSCANSERVICES.AUTHORIZATION and that the FACILITY class is SETROPTS RACLISTed.
Equate Symbol
: ISGQUERYRsn_BadASID
08
08 xxxx0823 xxxx0824
Meaning
: Bad ASID keyword parameter.
Action
: Ensure that the ASID is valid.
Equate Symbol
: ISGQUERYRsn_BadUserDataAddress
Meaning
: Unable to access the user data.
Action
: Ensure that the entire USERDATA is addressable. If in
AR-mode, this field is accessed by its address and ALET, check that both these values are correct. If this is a USERDATA pattern request, check that specified USERDATA length is correct. Ensure that the storage is in the same key as the caller.
Equate Symbol
: ISGQUERYRsn_BadUserDataAlet
08
08
08 xxxx0825 xxxx0826 xxxx0827
Meaning
: Bad USERDATA ALET. The ALET is not zero or is it associated with a valid public entry on the caller's Dispatchable
Unit Access List (DU-AL), or a valid entry for a common area data space.
Action
: Ensure that the ALET of the USERDATA is valid. Its access register might have been set up properly.
Equate Symbol
: ISGQUERYRsn_BadUserDataLen
Meaning
: The USERDATA length specified is not valid.
Action
: Ensure the USERDATA length field contains a number in the range 1-32.
Equate Symbol
: ISGQUERYRsn_BadUserDataMatch
Meaning
: Bad USERDATAMATCH keyword parameter.
Action
: Check for possible storage overlay of the parameter list.
Equate Symbol
: ISGQUERYRsn_BadAnalyze
Meaning
: The ANALYZE keyword parameter is not valid.
Action
: Check for possible storage overlay of the parameter list.
Chapter 61. ISGQUERY — Global resource serialization query service
513
ISGQUERY macro
Table 32. Return and Reason Codes for the ISGQUERY Macro (continued)
Return Code
08
Reason Code
xxxx0828
Equate Symbol Meaning and Action
Equate Symbol
: ISGQUERYRsn_NotAuthToLatchECA
0C —
Meaning
: SETROPTS MLACTIVE is in effect and the program is not authorized to issue ISGQUERY REQINFO=LATCHECA.
Action
: Ensure the program is running authorized or is associated with a userid with at least READ access to the best fit FACILITY class resource profile of the form
ISG.LATCHECASERVICES.AUTHORIZATION and that the
FACILITY class is SETROPTS RACLISTed.
Equate Symbol
: ISGQUERYRc_EnvError
Meaning
: ISGQUERY request has an environment error.
0C
0C xxxx0C01 xxxx0C02
Action
: Refer to action under the individual reason code.
Equate Symbol
: ISGQUERYRsn_SrbMode
Meaning
: ISGQUERY can not be used in SRB mode.
Action
: Avoid using ISGQUERY in SRB mode.
Equate Symbol
: ISGQUERYRsn_NotEnabled
Meaning
: ISGQUERY can not be used disabled.
0C
0C
0C xxxx0C03 xxxx0C04 xxxx0C05
Action
: Avoid using ISGQUERY when not enabled.
Equate Symbol
: ISGQUERYRsn_ComplexMigrating
Meaning
: For a REQINFO=QSCAN request. The ISGQUERY service failed because the GRS complex was migrating from a ring to a star configuration.
Action
: Retry the request on or more times.
Equate Symbol
: ISGQUERYRsn_CannotObtainLocks
Meaning
: For REQINFO=RNLSEARCH, the local and CMSEQDQ locks could not be obtained.
Action
: Only use ISGQUERY REQINFO=RNLSEARCH when either no locks are held, or both a local lock and the CMSEQDQ lock are held with no other locks.
Equate Symbol
: ISGQUERYRsn_LockHeld
Meaning
: An incorrect lock was held upon entry. For
REQINFO=QSCAN, no locks can be held. For
REQINFO=RNLSEARCH, either no locks or both a local lock
(LOCAL or CML) and the CMDEQDQ lock must be held.
Action
: Avoid using ISGQUERY REQINFO=QSCAN when locks are held. Avoid using ISGQUERY REQINFO=RNLSEARCH when locks other than both a local lock and the CMSEQDQ lock are held.
514
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
Table 32. Return and Reason Codes for the ISGQUERY Macro (continued)
Return Code
0C
Reason Code
xxxx0C06
Equate Symbol Meaning and Action
Equate Symbol
: ISGQUERYRsn_MaxConcurrentRequests
0C
0C xxxx0C07 xxxx0C08
Meaning
: For a REQINFO=QSCAN request. The answer area was filled before queue scan processing completed, and reason code
ISGQUERYRsn_AnswerAreaFull would have been issued.
However, RESUMETOKEN was specified, but the limit for the number of concurrent resource requests (ISGENQ, ENQ,
RESERVE, GQSCAN, and ISGQUERY) has been reached. The data in the answer area is valid, but incomplete. The scan cannot be resumed.
Action
: Retry the request one or more times. If the problem persists, consult your system programmer. For more information on concurrent count limits and how the system can be tuned when necessary, see z/OS MVS Planning: Global Resource
Serialization.
Equate Symbol
: ISGQUERYRsn_RingResumeInStar
Meaning
: For a REQINFO=QSCAN request. The caller attempted to resume a scan that was started when the global resource serialization complex, which is now in star mode, was in ring mode.
Action
: Reissue the original request.
Equate Symbol
: ISGQUERYRsn_InsufficientStorage
0C xxxx0C09
Meaning
: For a REQINFO=QSCAN request. The ISGQUERY service could not obtain storage to satisfy the request.
Action
: Retry the request one or more times.
Equate Symbol
: ISGQUERYRsn_FRRHeld,
Meaning
: For a REQINFO=LATCHECA request. The caller issued
ISGQUERY with a functional recover routine (FRR) established.
10 —
Action
: Avoid issuing ISGQUERY REQINFO=LATCHECA when using functional recovery routines.
Equate Symbol
: ISGQUERYRc_CompError
Meaning
: Component Error
Action
: Contact the IBM Support Center.
The reason code contains internal diagnostic information.
Examples
Use these examples as a guide.
* ***********************************************************************
* Search the Systems Inclusion RNL for a resource name
* ***********************************************************************
ISGQUERY REQINFO=RNLSEARCH,RNL=SIRNL,
QNAME=MYQNAME,RNAME=MYRNAME,RNAMELEN=MYRNAMELEN,
RETCODE=MYRC,RSNCODE=MYRSN
X
X
* ***********************************************************************
* Query information on a request specified by ENQToken
Chapter 61. ISGQUERY — Global resource serialization query service
515
ISGQUERY macro
* ***********************************************************************
ISGQUERY REQINFO=QSCAN,SCANACTION=START,
ANSAREA=MYAREA,ANSLEN=MYAREALEN,
SEARCH=BY_ENQTOKEN,ENQTOKEN=MYENQTOKEN,
RETCODE=MYRC,RSNCODE=MYRSN
X
X
X
* ***********************************************************************
* Start a resumable query for resources of a specific job that
* matches a specific QNAME and pattern RNAME
* ***********************************************************************
ISGQUERY REQINFO=QSCAN,SCANACTION=START,
ANSAREA=MYAREA,ANSLEN=MYAREALEN,
SEARCH=BY_FILTER,QNAMEMATCH=SPECIFIC,QNAME=MYQNAME,
RNAMEMATCH=PATTERN,RNAME==CL7’ABC?23*’,RNAMELEN=7,
USERDATAMATCH=SPECIFIC,USERDATA=MYUDATA, X
JOBNAME=MYJOBNAME,RESUMETOKEN=MYRESTOKEN,RETCODE=MYRC, X
RSNCODE=MYRSN
X
X
X
X
* ***********************************************************************
* Start a resumable query for resources of a specific job that
* matches a specific QNAME and pattern RNAME
* ***********************************************************************
ISGQUERY REQINFO=QSCAN,SCANACTION=START,
ANSAREA=MYAREA,ANSLEN=MYAREALEN,
SEARCH=BY_FILTER,QNAMEMATCH=SPECIFIC,QNAME=MYQNAME,
RNAMEMATCH=PATTERN,RNAME==CL7’ABC?23*’,RNAMELEN=7,
USERDATAMATCH=PATTERN,USERDATA=MYUDATAP,USERDATALEN=7,
JOBNAME=MYJOBNAME,RESUMETOKEN=MYRESTOKEN,RETCODE=MYRC,
RSNCODE=MYRSN
MYUDATA DC
MYUDATAP DC
CL32’MY USERDATA’
CL7’M??USE*’
* ***********************************************************************
* Resume a query that was started but not completed
* ***********************************************************************
X
X
X
X
X
X
ISGQUERY REQINFO=QSCAN,SCANACTION=RESUME,
RESUMETOKEN=MYRESTOKEN,
ANSAREA=MYAREA,ANSLEN=MYAREALEN,
RETCODE=MYRC,RSNCODE=MYRSN
X
X
X
* ***********************************************************************
* Quit a query that was started but not completed
* ***********************************************************************
ISGQUERY REQINFO=QSCAN,SCANACTION=QUIT,
RESUMETOKEN=MYRESTOKEN,
RETCODE=MYRC,RSNCODE=MYRSN
X
X
* ***********************************************************************
* Gather ENQ statistics for a particular address space
* ***********************************************************************
ISGQUERY REQINFO=ENQSTATS,
ANSAREA=MYAREA,ASID=MYASID,
RETCODE=MYRC,RSNCODE=MYRSN
X
X
* ***********************************************************************
* Gather query latch enhanced contention analysis (LATCHECA) data from the *
* global resource serialization queues for waiters delayed because of *
* contention *
*************************************************************************
516
z/OS MVS Assembler Services Reference IAR-XCT
ISGQUERY macro
ISGQUERY REQINFO=LATCHECA,ANALYZE=WAITER,ANSAREA=MYAREA,
ANSLEN=MYAREALEN,RETCODE=MYRC,RSNCODE=MYRSN
X
X
* ***********************************************************************
* Gather address space level contention information related to ENQs *
* (all scopes) and latches (all latch sets) from the
* global resource serialization queues
*************************************************************************
*
*
ISGQUERY REQINFO=USAGESTATS,ANSAREA=MYAREA,ANSLEN=MYAREALEN, X
RETCODE=MYRC,RSNCODE=MYRSN X
For more information on global resource serialization, see z/OS MVS Planning:
Global Resource Serialization.
Chapter 61. ISGQUERY — Global resource serialization query service
517
518
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 62. ITTUINIT — Activate external CTRACE recording
Description
Note:
ITTUINIT is a linkable system service.
ITTUINIT is one of a set of services that an unauthorized program can use to write
CTRACE output. The other services in the set are ITTUWRIT and ITTUTERM. The services must be invoked under the same task in problem state.
Use the ITTUINIT service to activate external CTRACE recording. Once ITTUINIT has been invoked, multiple calls to the ITTUWRIT service can be made to write the
CTRACE entries. The ITTUTERM service is invoked to end external CTRACE recording.
The caller of ITTUINIT provides a data structure containing parameters for the service. At the conclusion of its processing, ITTUINIT returns information for the user in the same data structure.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state with PSW key 8-15
Task
PASN=HASN=SASN
24- or 31-bit
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space.
Programming requirements
1.
To build the parameter area required by ITTUINIT, you must include the
ITTUIPRM mapping macro (see z/OS MVS Data Areas in the z/OS Internet library (www.ibm.com/systems/z/os/zos/library/bkserv)).
2.
Before calling ITTUINIT, the caller must provide the following in the fully-initialized ITTUIPRM mapping macro: v The component name v The name of the format table for the component v The ddname to which CTRACE output is to be written v The maximum length of an ITTCTE that will be accepted by ITTUWRIT.
v The number of bytes of virtual storage that the unauthorized CTRACE writer is authorized to use for trace buffers.
v
An option bit that requests NOWRAP processing. WRAP processing is requested when this bit is zero.
DSECT=NO may be specified for initial values.
3.
The caller determines whether ITTUINIT processing was successful by examining the return code.
© Copyright IBM Corp. 1988, 2017
519
ITTUINIT service
4.
Successful ITTUINIT processing results in the following updated field in
ITTUIPRM: v
A token whose value must be passed to the ITTUWRIT and ITTUTERM services.
Restrictions
The caller cannot have any enabled, unlocked task (EUT) FRRs established.
Input register information
Before linking to ITTUINIT, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of the parameter list
Address of a standard 72-byte save area in the primary address space
Before linking to ITTUINIT, the caller does not have to place any information into any access register (AR).
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
520
z/OS MVS Assembler Services Reference IAR-XCT
ITTUINIT service
Syntax
Use the following form of the LINK macro to invoke the ITTUINIT service:
►►
label
► LINK EP = ITTUINIT , MF = ( E ,
parmarea
)
LINKX EP = ITTUINIT , MF = ( E ,
parmarea
)
, SF = ( E ,
parmlist
)
►
►◄
Note:
As an alternative to using LINK or LINKX, callers in 31-bit AMODE can also:
1.
Issue the MVS LOAD macro to load the ITTUINIT service and obtain its entry point address.
2.
Issue the CALL macro to call the service. Specify MF=(E,your_parmlist) on the call.
Parameters
The parameters are explained as follows:
label
The name on the macro invocation.
LINK
LINKX
Names the system service that is to be used for linkage.
EP=ITTUINIT
Specifies the entry point name for the ITTUINIT service.
,MF=(E,parmarea)
Specifies the address of the parameter list to be passed to ITTUINIT. The parameter list consists of the following address: v The address of the fully-initialized ITTUIPRM.
,SF=(E,parmlist)
For use with LINKX when your program is reentrant. Before you call LINKX with this parameter, define parmlist using the LIST form of LINKX.
Return and reason codes
When the ITTUINIT service returns control to your program, Register 15 contains a return code.
Meaning and Action Decimal Return
Code
00
16
Meaning
: The ITTUINIT request completed successfully.
Action
: None required.
Meaning
: Warning. The ITTUINIT request did not complete successfully.
Action
: Reissue ITTUINIT.
Chapter 62. ITTUINIT — Activate external CTRACE recording
521
ITTUINIT service
522
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 63. ITTUTERM — End external CTRACE recording
Description
Note:
ITTUTERM is a linkable system service.
Use the ITTUTERM service to close the trace data set and unallocate resources that were allocated by the ITTUINIT service. uffer.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state with PSW key 8-15
Task
PASN=HASN=SASN
24- or 31-bit
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space.
Programming requirements
The caller determines whether ITTUTERM processing was successful by examining the return code.
Restrictions
The caller cannot have any enabled, unlocked task (EUT) FRRs established.
Input register information
Before linking to ITTUTERM, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
1
13
Address of parameter list
Address of a standard 72-byte save area in the primary address space
Before linking to ITTUTERM, the caller does not have to place any information into any access register (AR).
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
© Copyright IBM Corp. 1988, 2017
523
ITTUTERM service
14
15
Used as work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Use the following form of the LINK macro to invoke the ITTUTERM service:
►►
label
► LINK EP = ITTUTERM , MF = ( E ,
parmarea
)
LINKX EP = ITTUTERM , MF = ( E ,
parmarea
)
, SF = ( E ,
parmlist
)
►
►◄
Note:
As an alternative to using LINK or LINKX, callers in 31-bit AMODE can also:
1.
Issue the MVS LOAD macro to load the ITTUTERM service and obtain its entry point address.
2.
Issue the CALL macro to call the service. Specify MF=(E,your_parmlist) on the call.
Parameters
The parameters are explained as follows:
label
The name on the macro invocation.
LINK
LINKX
Names the system service that is to be used for linkage.
EP=ITTUTERM
Specifies the entry point name for the ITTUTERM service.
,MF=(E,parmarea)
Specifies the address of the parameter list to be passed to ITTUTERM. The parameter list consists of the following address: v The address of the token passed from ITTUINIT.
524
z/OS MVS Assembler Services Reference IAR-XCT
ITTUTERM service
,SF=(E,parmlist)
For use with LINKX when your program is reentrant. Before you call LINKX with this parameter, define parmlist using the LIST form of LINKX.
Return and reason codes
When the ITTUTERM service returns control to your program, Register 15 contains a return code.
Meaning and Action Decimal Return
Code
00 non-zero
Meaning
: The ITTUTERM request completed successfully.
Action
: None required.
Meaning
: Warning. The ITTUTERM request did not complete successfully.
Action
: Reissue ITTUTERM.
Chapter 63. ITTUTERM — End external CTRACE recording
525
ITTUTERM service
526
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 64. ITTUWRIT — Queue a group of CTRACE entries
Description
Note:
ITTUWRIT is a linkable system service.
ITTUWRIT is one of a set of services that an unauthorized program can use to write CTRACE output. The other services in the set are ITTUINIT and ITTUTERM.
The services must be invoked under the same task in problem state.
Use the ITTUWRIT service to queue a group of CTRACE entries. Whenever new
CTRACE entries overflow a buffer, recording of the entries occurs.
The caller of ITTUWRIT provides the token returned by the ITTUINIT service and the address of the storage area containing the ITTCTE entries.
Multiple calls to the ITTUWRIT service can be made to write the CTRACE entries.
When ITTUWRIT is in control, the system writes the ITTCTE entries from the storage area passed to ITTUWRIT into the CTRACE output buffers immediately. If necessary, the system may need to discard trace entries because of timing considerations or error conditions such as I/O errors or storage overlays.
ITTUWRIT adds control information to the trace data set whenever data losses occur, if possible.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state with PSW key 8-15
Task
PASN=HASN=SASN
24- or 31-bit
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space.
Programming requirements
1.
To reference the parameter area required by ITTUWRIT, you must include the
ITTUIPRM mapping macro (see z/OS MVS Data Areas in the z/OS Internet library (www.ibm.com/systems/z/os/zos/library/bkserv)).
2.
The caller determines whether ITTUWRIT processing was successful by examining the return code.
Restrictions
The caller cannot have any enabled, unlocked task (EUT) FRRs established.
Input register information
Before linking to ITTUWRIT, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
© Copyright IBM Corp. 1988, 2017
527
ITTUWRIT service
Register
Contents
1
13
Address of parameter list
Address of a standard 72-byte save area in the primary address space
Before linking to ITTUWRIT, the caller does not have to place any information into any access register (AR).
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
Use the following form of the LINK macro to invoke the ITTUWRIT service:
►►
label
► LINK EP = ITTUWRIT , MF = ( E ,
parmarea
)
LINKX EP = ITTUWRIT , MF = ( E ,
parmarea
)
, SF = ( E ,
parmlist
)
►
►◄
Note:
As an alternative to using LINK or LINKX, callers in 31-bit AMODE can also:
1.
Issue the MVS LOAD macro to load the ITTUWRIT service and obtain its entry point address.
2.
Issue the CALL macro to call the service. Specify MF=(E,your_parmlist) on the call.
528
z/OS MVS Assembler Services Reference IAR-XCT
ITTUWRIT service
Parameters
The parameters are explained as follows:
label
The name on the macro invocation.
LINK
LINKX
Names the system service that is to be used for linkage.
EP=ITTUWRIT
Specifies the entry point name for the ITTUWRIT service.
,MF=(E,parmarea)
Specifies the address of the parameter list to be passed to ITTUWRIT. The parameter list consists of the following three addresses: v The address of the token passed from ITTUINIT.
v The address of a fullword containing the size of the block of CTE entries.
v The address of the area containing the CTE entries.
,SF=(E,parmlist)
For use with LINKX when your program is reentrant. Before you call LINKX with this parameter, define parmlist using the LIST form of LINKX.
Return and reason codes
When the ITTUWRIT service returns control to your program, Register 15 contains a return code.
Meaning and Action Decimal Return
Code
00
16
Meaning
: The ITTUWRIT request completed successfully.
Action
: None required.
Meaning
: Warning. The ITTUWRIT request did not complete successfully.
Action
: Reissue ITTUWRIT.
Chapter 64. ITTUWRIT — Queue a group of CTRACE entries
529
ITTUWRIT service
530
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 65. ITZEVENT — Transaction trace EVENT record
Description
The ITZEVENT macro is used to build and record a transaction trace record. It optionally performs the query function to determine if the work unit should be traced.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state. PSW key 8 - 15
Task or SRB
Any PASN, any HASN, any SASN
31-bit
Primary
Enabled forI/O and external interrupts
No locks may be held
Control parameters must be in the primary address space.
The data pointed to by DATAADDR must reside in the caller's primary address space.
Programming requirements
Any module that invokes this macro must include the macos CVT and IHAECVT.
To get the equate symbols for the return and reason codes, the caller should include the ITZYRETC macro.
Restrictions
None.
Input register information
Before issuing the ITZEVENT macro, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
13
The address of a 72-byte standard save area in the primary address space
Before issuing the ITZEVENT macro, the caller does not have to place any information into any access register (AR).
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0
Contains the reason code when GPR15 is not 0
© Copyright IBM Corp. 1988, 2017
531
ITZEVENT macro
Syntax
1
2-13
14
15
Unpredictable (Used as a work register by the system)
Unchanged
Unpredictable (Used as a work register by the system)
Contains the return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Unpredictable (Used as a work register by the system)
2-13
Unchanged
14-15
Unpredictable (Used as a work register by the system)
Some callers depend on register contents remaining the same before and after issuing a macro. If the macro changes the contents of registers on which the caller depends, the caller must save them before issuing the macro and restore them after the macro returns control.
Performance implications
None.
Syntax
The ITZEVENT macro is written as follows:
Description
name
⌂
name: symbol. Begin name in column 1.
One or more blanks must precede ITZEVENT.
ITZEVENT
⌂
COMPONENT=component
,EVENTDESC=eventdesc
,DATAFORMAT=TT
,DATAFORMAT=GTF
,DATAADDR=dataaddr
,DATALEN=datalen
One or more blanks must follow ITZEVENT.
component: RS-type address or address in register (2) - (12)
eventdesc: RS-type address or address in register (2) - (12)
Default:
DATAFORMAT=TT
dataaddr: RS-type address or address in register (2) - (12)
datalen: RS-type address or address in register (2) - (12)
532
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,DATAADDR=dataaddr
,DATALEN=datalen
,GTFID=gtfid
,GTFFID=gtffid
,FMTTYPE=HEX
,FMTTYPE=MODEL
,FMTTYPE=ROUTINE
,FORMATRTN=formatrtn
,FORMATRTN=formatrtn
,FUNCTIONNAME=
,QUERY=YES
,QUERY=NO
,MONTKN=montkn
,MONTKN64=montkn
,TRACETKN=tracetkn
,PLISTVER=
IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(M,list addr,NOCHECK)
Description
dataaddr: RS-type address or address in register (2) - (12)
datalen: RS-type address or address in register (2) - (12)
gtfid: RS-type address or address in register (2) - (12)
gtffid: RS-type address or address in register (2) - (12)
Default:
FMTTYPE=HEX
ITZEVENT macro
formatrtn: RS-type address or address in register (2) - (12)
formatrtn: RS-type address or address in register (2) - (12)
functionname
functionname: RS-type adderss or address in register (2) - (12)
Default:
QUERY=YES
montkn: RS-type address or address in register (2) - (12)
tracetkn: RS-type address or address in register (2) - (12)
Default:
PLISTVER=IMPLIED_VERSION
Default
: MF=S
list addr: RS-type address or register (1) - (12)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
Chapter 65. ITZEVENT — Transaction trace EVENT record
533
ITZEVENT macro
Syntax Description
Parameters
The parameters are explained as follows:
name
This is an optional symbol, starting in column 1, that is the name on the
ITZEVENT macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
COMPONENT=component
This is a required input parameter that specifies the user component name used in formatting the standard transaction trace header.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,EVENTDESC=eventdesc
This is a required input parameter that specifies the event-related field used in formatting the standard transaction trace header.
Some examples might be START xxxxxxxx, END xxxxxxxx, ENTRYPTxxx,
COMMIT, and ROLLBACK.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
16-character field.
,DATAFORMAT=TT
,DATAFORMAT=GTF
This is an optional parameter that specifies the kind of data that follows the transaction trace header in the trace record. The default is DATAFORMAT=TT.
,DATAFORMAT=TT
The data recorded will contain transaction trace-related data.
,DATAFORMAT=GTF
This indicates that a GTF data record follows the standard transaction trace header. A pointer to the GTF record is passed along with the length.
,DATAADDR=dataaddr
When DATAFORMAT=TT is specified, this is an optional input parameter that can be used to specify the address and length of the data to be appended at the end of the transaction trace header. This is event-specific data set up by the user of this macro.
To code:
Specify the RS-type address, or address in register (2)-(12), of a pointer field.
,DATALEN=datalen
When DATAADDR=dataaddr and DATAFORMAT=TT are specified, this is a required input parameter that specifies the length of the data to be appended at the end of the transaction trace header. This is event-specific data, set up by the user of this macro.
The maximum length of data may not exceed 1K. If a length greater than 1K is specified, data will be truncated to record 1K of data.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
534
z/OS MVS Assembler Services Reference IAR-XCT
ITZEVENT macro
,DATAADDR=dataaddr
When DATAFORMAT=GTF is specified, this is a required input parameter that specifies the address and length of the GTF record to be appended at the end of the transaction trace header.
To code:
Specify the RS-type address, or address in register (2)-(12), of a pointer field.
,DATALEN=datalen
When DATAFORMAT=GTF is specified, this is a required input parameter that specifies the length of the data to be appended at the end of the transaction trace header.
The maximum length of data may not exceed 1K. If a length greater than 1K is specified, data will be truncated to record 1K of data.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
,GTFID=gtfid
When DATAFORMAT=GTF is specified, this is a required input parameter that specifies the event ID that is to be recorded with the data bytes. Decimal event
IDs 0 through 1023 (X'3FF') are available for user events.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
2-character field.
,GTFFID=gtffid
When DATAFORMAT=GTF is specified, this is an optional input parameter that specifies the format appendage (fidname) that controls the formatting of the record. Formatting occurs when the trace output is processed by GTF trace.
The format appendage name is formed by appending the 2-digit GTFFID value to the names AMDUSER, HMDUSR, and IMDUSR. Assign GTFFID values as follows: v X'00' - The record is to be dumped in hex.
v X'01' to X'50' - The record contains user format identifiers.
Note:
If you omit the GTFFID parameter, the system supplies a default fidname of zero.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
1-character field.
,FMTTYPE=HEX
,FMTTYPE=MODEL
,FMTTYPE=ROUTINE
This is an optional parameter that specifies the IPCS format routine type for the user data. Refer to z/OS MVS IPCS Customization for details about the IPCS format.
The formatting can be in Hex, Model format, or from a Format routine. If a
FORMATRTN is specified, FMTTYPE must be set to Routine or Model. The default is FMTTYPE=HEX.
,FMTTYPE=HEX
The data is displayed in Hex format.
,FMTTYPE=MODEL
The data is displayed in a format provided in a model format routine.
,FMTTYPE=ROUTINE
The data is displayed in a format provided in a user format routine.
Chapter 65. ITZEVENT — Transaction trace EVENT record
535
ITZEVENT macro
,FORMATRTN=formatrtn
When FMTTYPE=MODEL is specified, this is a required parameter that specifies the name of the routine to be used for formatting the user data.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,FORMATRTN=formatrn
When FMTTYPE=ROUTINE is specified, this is a required parameter that specifies the name of the routine to be used for formatting the user data..
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,FUNCTIONNAME=functionname
this is an optional input parameter that specifies the function
(module|routine|label) that is making the trace entry. This value is displayed on the trace record formatted by IPCS.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
32-character field.
,QUERY=YES
,QUERY=NO
This is an optional parameter that specifies whether query should be performed to determine if this work unit is to be traced.
Specifying QUERY=YES causes the same function to be performed as the
ITZQUERY macro. If transaction trace is active for this work unit, a trace record is built and recorded. The default is QUERY=YES.
,QUERY=YES
Specifies that Query needs to be performed.
,QUERY=NO
Specifies that Query does not need to be performed.
The transaction trace token (TRACETKN) is a required input parameter.
The TRACETKN is obtained by issuing a ITZQUERY macro just prior to issuing the ITZEVENT.
,MONTKN=montkn
,MONTKN64=montkn
When QUERY=YES is specified, MONTKN and MONTKN64 are available as a mutually exclusive set of keys. MONTKN is an optional 32 bit and
MONTKN64 is an optional 64 bit input used as a token to locate the current monitoring environment.
IBM recommends that MONTKN or MONTKN64 be specified for a monitoring environment to keep the query pathlength short and fast.
To code:
Specify the RS-type address, or address in register (2)-(12), of a 31-bit or 64-bit field.
,TRACETKN=tracetkn
When QUERY=NO is specified, this is a required input parameter that specifies the transaction trace token returned from the previously performed query.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
32-character field.
Note:
Some existing components and products may have difficulty finding space in their data areas to hold a 32-byte transaction trace token. Apply APAR
536
z/OS MVS Assembler Services Reference IAR-XCT
ITZEVENT macro
OW50696 to shorten the significant portion of the token to 8 bytes. With service for OW50696 applied, only the first 8 bytes of the 32-byte token will contain values other than binary zeros. Components that might not be able to exploit component trace due to the size of the 32-byte token may save just the first 8 bytes between uses, expanding it for use with transaction trace APIs by padding with binary zeros.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
This is an optional input parameter that specifies the version of the macro.
PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:
IMPLIED_VERSION
This is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter,
IMPLIED_VERSION is the default.
MAX
Specify MAX if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list form parameter list is always long enough to hold all the parameters you might specify on the execute form of the macro when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
0
Specify 0 if you use the currently available parameters.
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
This is an optional input parameter that specifies the macro form.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The
Chapter 65. ITZEVENT — Transaction trace EVENT record
537
ITZEVENT macro
list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area, use the modify form to set the appropriate options, and use the execute form to call the service.
IBM recommends that you use and execute forms of ITZEVENT in the following order: v Use ITZEVENT ...MF=(M,list-addr,COMPLETE) specifying appropriate parameters, including all required ones.
v Use ITZEVENT ...MF=(M,list-addr,NOCHECK) specifying the parameters that you want to change.
v Use ITZEVENT ...MF=(E,list-addr,NOCHECK) to execute the macro.
,list addr
This is the name of a storage area to contain the parameters. For MF=S,
MF=E, and MF=M, this can be an RS-type address or an address in register
(1)-(12).
,attr
This is an optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
This specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
This specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When the ITZEVENT macro returns control to your program: v GPR 15 contains a return code.
v When the value in GPR 15 is not zero, GPR 0 contains a reason code.
The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code. IBM support personnel may request the entire reason code, including the xxxx value.
538
z/OS MVS Assembler Services Reference IAR-XCT
ITZEVENT macro
Table 33. Return and Reason Codes for the ITZEVENT Macro
Return Code
0
Reason Code
—
Equate Symbol Meaning and Action
Equate Symbol:
ITZGOOD
4
4
4
4
— xxxx0401 xxxx0402 xxxx0403
Meaning:
Success - this work unit was traced.
Action:
None.
Equate Symbol:
ITZNOTR
Meaning:
Work unit was not traced.
Action:
None.
Reason code set to indicate the reason for not tracing.
Equate Symbol:
ITZNOTKN
Meaning:
Trace token was zero.
Action:
None.
Equate Symbol:
ITZNOACT
Meaning:
Transaction trace is not active.
Action:
None.
Equate Symbol:
ITZLATNT
Meaning:
Transaction trace is LATENT with LATENT=N set.
Action:
None.
Examples
ITZEVENT COMPONENT=COMP,
EVENTDESC=DESC,
DATAADDR=TTDATA,
DATALEN=TTLEN
COMP DC CL8’COMP1 ’
DESC DC CL16’START TRAN ’
TTDATA DC CL64
TTLEN DC F’64’
Chapter 65. ITZEVENT — Transaction trace EVENT record
539
ITZEVENT macro
540
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 66. ITZQUERY — Transaction trace query
Description
The ITZQUERY macro is used to query whether a transaction or work unit should be traced.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state. PSW key 8 - 15
Task or SRB
Any PASN, any HASN, any SASN
31-bit
Primary
Enabled for I/O and external interrupts
No locks may be held
Control parameters must be in the primary address space.
Programming requirements
Any module that invokes this macro must include the CVT and IHAECVT macros.
Restrictions
None.
Input register information
Before issuing the ITZQUERY macro, the caller must insure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
13
The address of a 72-byte standard save area in the primary address space
Before issuing the ITZQUERY macro, the caller does not have to place any information into any access register (AR).
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code
Unpredictable (Used as a work register by the system)
2-13
14
15
Unchanged
Unpredictable (Used as a work register by the system)
Return code
© Copyright IBM Corp. 1988, 2017
541
ITZQUERY macro
Syntax
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Unpredictable (Used as a work register by the system)
Unchanged
14–15
Unpredictable (Used as a work register by the system)
Some callers depend on register contents remaining the same before and after issuing a macro. If the macro changes the contents of registers on which the caller depends, the caller must save them before issuing the macro and restore them after the macro returns control.
Performance implications
Specifying the MONTKN in a monitoring environment results in a faster query.
Syntax
The ITZQUERY macro is written as follows:
Description
name
⌂
ITZQUERY
⌂
name: symbol. Begin name in column 1.
One or more blanks must precede ITZQUERY.
,MONTKN=montkn
,MONTKN64=montkn
,MONTKN=0
,TRACETKN=tracetkn
,TRACELVL=tracelvl
,PLISTVER=
IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
One or more blanks must follow ITZQUERY.
montkn: RS-type address or address in register (2) - (12)
Default: MONTKN=0
tracetkn: RS-type address
tracelvl: RS-type address
Default:
PLISTVER=IMPLIED_VERSION
Default
: MF=S
list addr: RS-type address or register (1) - (12)
542
z/OS MVS Assembler Services Reference IAR-XCT
ITZQUERY macro
Syntax
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Description
Parameters
The parameters are explained as follows:
name
This is an optional symbol, starting in column 1, that is the name on the
ITZQUERY macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
,MONTKN=montkn
,MONTKN64=montkn
MONTKN=0
MONTKN is an optional 32 bit and MONTKN64 is an optional 64 bit input used as a token to locate the current monitoring environment. MONTKN and
MONTKN64 are mutually exclusive.
IBM recommends that MONTKN or MONTKN64 be specified for a monitoring environment to keep the query pathlength short and fast.
An optional input parameter that is the token used to locate the current monitoring environment.
It is recommended that MONTKN be specified for a monitoring environment to keep the query pathlength short and fast. The default is 0.
To code:
Specify the RS-type address or address in register (2) - (12) of a 31-bit or 54-bit field.
,MONTKN=montkn
,MONTKN64=montkn
When QUERY=YES is specified, MONTKN and MONTKN64 are available as a mutually exclusive set of keys. MONTKN is an optional 32 bit and
MONTKN64 is an optional 64 bit input used as a token to locate the current monitoring environment.
IBM recommends that MONTKN or MONTKN64 be specified for a monitoring environment to keep the query pathlength short and fast.
To code:
Specify the RS-type address, or address in register (2)-(12), of a 31-bit or 64-bit field.
,TRACETKN=tracetkn
This is a required output parameter that specifies the transaction trace token returned from query.
To code:
Specify the RS-type address of a 32-character field.
Note:
Some existing components and products may have difficulty finding space in their data areas to hold a 32-byte transaction trace token. Apply APAR
Chapter 66. ITZQUERY — Transaction trace query
543
ITZQUERY macro
OW50696 to shorten the significant portion of the token to 8 bytes. With service for OW50696 applied, only the first 8 bytes of the 32-byte token will contain values other than binary zeros. Components that might not be able to exploit component trace due to the size of the 32-byte token may save just the first 8 bytes between uses, expanding it for use with transaction trace APIs by padding with binary zeros.
,TRACELVL=tracelvl
This is an optional output parameter that specifies the transaction trace indicator returned from query. A non-zero value implies that this work unit is eligible for tracing. A value of zero implies that this work unit is not eligible for tracing. In that case, the trace token is also set to zero.
To code:
Specify the RS-type address of a one-byte field.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
This is an optional input parameter that specifies the version of the macro.
PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form.
When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:
IMPLIED_VERSION
This is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter,
IMPLIED_VERSION is the default.
MAX
Specify MAX if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list form parameter list is always long enough to hold all the parameters you might specify on the execute form of the macro when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
0
Specify 0 if you use the currently available parameters.
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
This is an optional input parameter that specifies the macro form.
544
z/OS MVS Assembler Services Reference IAR-XCT
ITZQUERY macro
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
v Use ITZQUERY ...MF=(M,list-addr,COMPLETE) specifying appropriate parameters, including all required ones.
v Use ITZQUERY ...MF=(M,list-addr,NOCHECK), specifying the parameters that you want to change.
v Use ITZQUERY ...MF=(E,list-addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this can be an RS-type address or an address in register
(1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When the ITZQUERY macro returns control to your program, GPR 15 contains a return code.
The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code.
Chapter 66. ITZQUERY — Transaction trace query
545
ITZQUERY macro
Table 34. Return and Reason Codes for the ITZQUERY Macro
Equate Symbol
0
Meaning and
Action
—
Equate Symbol:
ITZGOOD
4 —
Meaning:
Success.
Action:
Trace this work unit. Trace token is non-zero.
Equate Symbol:
ITZNOTR
Meaning:
Work unit not to be traced.
Action:
Do not trace this work unit.
546
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 67. IXGBRWSE — Browse/read a log stream
Description
Use the IXGBRWSE macro to read and browse a log stream for log block information. Using IXGBRWSE, a program can read consecutive log blocks in a log stream or search for and read a specific log block in a log stream. IXGBRWSE returns the specified log block in the calling program's output buffer.
The requests for IXGBRWSE are: v
REQUEST=START, which starts a browse session. A browse session is identified by a browse token which is created by the browse start request. The browse session remains active until it is ended as a result of a REQUEST=END request
or the log stream has been disconnected. See “REQUEST=START option of
IXGBRWSE” on page 550 for the syntax of this request.
v REQUEST=READCURSOR, which reads the next consecutive log block (or blocks) in the log stream. Use this request multiple times or use the
MULTIBLOCK keyword to read consecutive blocks in a log stream. See
“REQUEST=READCURSOR option of IXGBRWSE” on page 556 for the syntax of
this request.
v REQUEST=READBLOCK, which reads a selected log block in a log stream. See
“REQUEST=READBLOCK option of IXGBRWSE” on page 562 for the syntax of
this request.
v
REQUEST=RESET, which resets the browse cursor to either the beginning or the
end of the log stream. See “REQUEST=RESET option of IXGBRWSE” on page
568 for the syntax of this request.
v
REQUEST=END, which ends a browse session. See “REQUEST=END option of
IXGBRWSE” on page 573 for the syntax of this request.
For information about using the system logger services and the IXGBRWSE request, see z/OS MVS Programming: Assembler Services Guide, which also includes information about related macros IXGCONN, IXGINVNT, IXGWRITE, IXGDELET, and IXGQUERY.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Requirement
Problem or Supervisor state with any PSW key. The caller must be in supervisor state with any system (0-7) PSW key to either invoke this service in SRB mode or to use the
MODE=SYNCEXIT keyword.
Task or SRB
Any PASN, HASN or SASN
31-bit or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts.
No locks held.
© Copyright IBM Corp. 1988, 2017
547
IXGBRWSE macro
Environmental factor
Control parameters
:
Requirement
All control parameters must be in the primary address space with the following exceptions: v The ECB should be addressable from the home address space.
v Any parameter area that is explicitly ALET-qualified as allowed by the input parameter (for example, the area referenced by the BUFFER parameter when the
BUFFALET parameter is specified) must be in an address or data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
All storage areas specified must be in the same storage key as the caller with the following exception: v Any parameter area is explicitly storage key qualified as allowed by the input parameters (example: the area referenced by the BUFFER parameter when the BUFFKEY parameter is also specified).
Programming requirements
v The current primary address space must be the same primary address space used at the time your program issued the IXGCONN request.
v The calling program must be connected to the log stream through the
IXGCONN service with either read or write authority.
v The parameter list for this service must be addressable in the caller's primary address space.
v Include the IXGCON mapping macro in your program. This macro provides a list of equate symbols for the system logger services.
v Include macro IXGANSAA in your program. This macro maps the format of the answer area output returned for each system logger service in the ANSAREA parameter.
v For a READCURSOR browse request with the MULTIBLOCK=YES option, include the IXGBRMLT mapping macro in your program. This macro provides a mapping of the area returned by the system logger for each block that is returned in the caller's buffer. Additionally, the area pointed to by the BUFFER or BUFFER64 parameter must be on a word boundary for multiple log block
READCURSOR requests.
v Although the data pointed to by the BUFFER64 keyword may be above the bar
(2-gigabyte), the length of the name or address of the input field specified in the
BUFFLEN keyword is still limited to 4 bytes.
v When coding the MODE=SYNCECB and ECB parameters, you must ensure that:
– The virtual storage area specified for the ECB resides on a fullword boundary.
– You initialize the ECB field to zero.
– The ECB resides in either common or home address space storage at the time the IXGBRWSE request is issued.
– The storage used for output parameters, such as ANSAREA,
BROWSETOKEN, BUFFER, BUFFER64, ANSAREA, BLKSIZE, TIMESTAMP, and RETBLOCKID, are accessible by both the IXGBRWSE invoker and the
ECB waiter.
548
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
Restrictions
There is more than one version of this macro available. The parameters you can use depend on the version you specify on the PLISTVER parameter. See the description of the PLISTVER parameter for more information.
You can call any of the system logger services in either AMODE 31 or 64, but the parameter list and all other data addresses, with the excption of BUFFER64 must reside in 31-bit storage.
Input register information
Before issuing the IXGBRWSE macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code, if register 15 contains a non-zero return code
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as a work register by the system
Unchanged
14-15
Used as a work register by the system
When control returns to a caller running in AMODE 64, the 64–bit registers contain:
Register
Contents
0-1
Used as a work register by the system, if the caller specified BUFFER64.
Otherwise, unchanged.
2-13
14
15
Unchanged
Unchanged
Used as a work register by the system.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Chapter 67. IXGBRWSE — Browse/read a log stream
549
IXGBRWSE macro
Syntax
Performance implications
None.
REQUEST=START option of IXGBRWSE
The IXGBRWSE macro with the REQUEST=START parameter starts a browse session and sets the starting position of the browse cursor.
Syntax for REQUEST=START
The IXGBRWSE REQUEST=START macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede
IXGBRWSE.
IXGBRWSE
� One or more blanks must follow IXGBRWSE.
REQUEST=START
,STREAMTOKEN=streamtoken
,BROWSETOKEN=browsetoken
,ANSAREA=ansarea
,ANSLEN=anslen
,OLDEST
,YOUNGEST
,STARTBLOCKID=startblockid
,SEARCH=search
GMT=YES
GMT=NO
VIEW=ACTIVE
VIEW=ALL
VIEW=NO_VIEW
550
z/OS MVS Assembler Services Reference IAR-XCT
streamtoken: RS-type address or register (2) -
(12).
browsetoken: RS-type address or register (2) -
(12).
ansarea: RS-type address or register (2) - (12).
anslen: RS-type address or register (2) - (12).
Default
: OLDEST
startblockid: RS-type address or register (2) -
(12).
search: RS-type address or register (2) - (12).
Default
: VIEW=ACTIVE
Syntax
MODE=SYNC
MODE=SYNCECB
,ECB=ecb
,DIAG=NO_DIAG
,DIAG=NO
,DIAG=YES
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
,RETCODE=retcode
,RSNCODE=rsncode
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
IXGBRWSE macro
Description
Default
: MODE=SYNC
ecb: RS-type address or register (2) - (12).
Default
: DIAG=NO_DIAG
Default
: IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: MF=S
Parameters for REQUEST=START
The parameters are explained as follows:
REQUEST=START
Requests that a browse session be started.
,STREAMTOKEN=streamtoken
Specifies the name or address (using a register) of a required 16-byte input field containing the token for the log stream that you want to browse and read.
The stream token is returned by the IXGCONN service at connection to the log stream.
,BROWSETOKEN=browsetoken
Specifies the name or address (using a register) of a required 4-byte output area where a token uniquely identifying the browse session is returned by the
Chapter 67. IXGBRWSE — Browse/read a log stream
551
IXGBRWSE macro
IXGBRWSE REQUEST=START request. This browse token is then used as an input to subsequent IXGBRWSE requests to identify the browse session.
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,OLDEST
,YOUNGEST
,STARTBLOCKID=startblockid
,SEARCH=search
Specifies where the cursor should be set for the start of the browse session.
v OLDEST: Specifies that the block cursor be positioned at the oldest log block in the log stream.
When VIEW=ACTIVE is specified for this browse session, the cursor is positioned at the oldest active log block in the log stream. If there is no active data in the log stream, the request will fail.
When VIEW=ALL is specified, the cursor is positioned at the oldest log block in the log stream of the active and inactive data. If there is neither active nor inactive data in the log stream, the request will fail.
v YOUNGEST: Specifies that the block cursor be positioned at the youngest log block in the log stream.
When VIEW=ACTIVE is specified for this browse session, the cursor is positioned at the youngest active log block in the log stream.
When VIEW=ALL is specified, the cursor is positioned at the youngest log block in the log stream, even if the youngest block is eligible for deletion.
v STARTBLOCKID=startblockid: Specifies the name (or register) of a 8-byte input field containing the block identifier for the log block you want to use as the starting cursor position.
When VIEW=ALL is specified, you must specify a starting block that is active.
v SEARCH=search: Specifies the name (or register) of a 64-bit input field containing the time stamp you want to use in searching for a particular log block as the starting cursor position for this browse session. For information on how the SEARCH keyword works, see z/OS MVS Programming: Assembler
Services Guide.
The time stamp must be Coordinated universal time (UTC) or local time, in time of day (TOD) clock format. The GMT parameter is required with the
SEARCH parameter.
,GMT=YES
,GMT=NO
Specifies whether the time stamp specified on the SEARCH parameter is UTC or local time.
v GMT=YES: The time stamp specified on the SEARCH parameter is in UTC format.
552
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
v GMT=NO: The time stamp specified on the SEARCH parameter is local time.
VIEW=ACTIVE
VIEW=ALL
VIEW=NO_VIEW
Specifies whether requests issued during this browse session return active data only, or both active and inactive data. Active data is data that has not been marked for deletion via the IXGDELET service. Inactive data is data that has been deleted via IXGDELET but has not been physically deleted from the log stream because of the retention period specified in the log stream definition in the LOGR couple data set.
v VIEW=ACTIVE, which is the default, specifies that in this browse session, system logger will only return active data from the log stream.
v
VIEW=ALL specifies that in this browse session, system logger will return both active and inactive data.
When VIEW=ALL is specified and a log block is returned, system logger sets a flag in the answer area, AnsaaBlkFromInactive, indicating whether the block was active or eligible for deletion.
v VIEW=NO_VIEW specifies that the default VIEW value will be used for the browse session.
The system where IXGBRWSE is issued must be IPLed for the VIEW parameter to be recognized.
,MODE=SYNC
,MODE=SYNCECB
Specifies that the request should be processed in one of the following ways: v
MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
v MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB parameter is posted when the request completes. The ECB parameter is required with MODE=SYNCECB.
,ECB=ecb
Specifies the name or address (using a register) of a 4-byte input field containing an event control block (ECB) to be posted when the request completes.
Before coding ECB, you must ensure that: v You initialize the ECB to zero.
v The ECB must reside in either common storage or the home address space at the time the IXGBRWSE request is issued.
v The virtual storage area specified for the ECB must reside on a fullword boundary.
,DIAG=NO_DIAG
,DIAG=NO
,DIAG=YES
Specifies whether or not the DIAG option on the IXGCONN for this logstream will be in effect for this browse session. Refer to the DIAG keyword on the
IXGINVNT, IXGCONN, and IXGDELET macro services.
Chapter 67. IXGBRWSE — Browse/read a log stream
553
IXGBRWSE macro
If you specify DIAG=NO_DIAG, which is the default, then the DIAG option on the IXGCONN for this logstream will be in effect for this browse session.
If you specify DIAG=NO, thenLogger will not take additional diagnostic action as defined in the logstream definition DIAG parameter.
If you specify DIAG=YES, then Logger will take additional diagnostic action as defined on the logstream definition DIAG parameter providing the IXGCONN connect DIAG specification allows it.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , supports all parameters except those specifically referenced in higher versions.
v 1 , supports both the following parameters and parameters from version 0:
– DIAG
– REQDATA v 2 , supports both the following parameters and parameters from version 0 and 1:
– MAXNUMLOGBLOCKS
– MULTIBLOCK
– RETBLOCKINFO
To code
: Specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0, 1 or 2
,RETCODE=retcode
Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name or address (using a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
554
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
You should use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
Chapter 67. IXGBRWSE — Browse/read a log stream
555
IXGBRWSE macro
Syntax
REQUEST=READCURSOR option of IXGBRWSE
The IXGBRWSE macro with the REQUEST=READCURSOR option allows a program to read the next consecutive log block in a log stream. Subsequent
READCURSOR requests will start reading at the next consecutive block. Use this request multiple times or use the MULTIBLOCK keyword to read a series of consecutive log blocks. The direction of the browse is controlled by the program and can be changed dynamically.
READCURSOR requests are limited to reading log blocks within the range of data defined by the browse session's view. The view is controlled by the VIEW keyword on either the browse START request or the browse RESET request.
Note:
REQUEST=READCURSOR reads the next consecutive log block in the log stream, but the blocks may not be in exact local time sequence. This can happen, for example, because of daylight savings time, one or more records with the same local time stamp, or multiple applications writing to the same log stream.
Syntax for REQUEST=READCURSOR
The IXGBRWSE REQUEST=READCURSOR macro is written as follows:
Description
name
�
IXGBRWSE
�
name: symbol. Begin name in column 1.
One or more blanks must precede IXGBRWSE.
One or more blanks must follow IXGBRWSE.
REQUEST=READCURSOR
,STREAMTOKEN=streamtoken
,BROWSETOKEN=browsetoken
,BUFFER=buffer
,BUFFER64=buffer64
,BUFFLEN=bufflen
,DIRECTION=OLDTOYOUNG
,DIRECTION=YOUNGTOOLD
,ANSAREA=ansarea
streamtoken: RS-type address or register (2) - (12).
browsetoken: RS-type address or register (2) - (12).
buffer: RS-type address or register (2) - (12).
buffer64: RS-type address or register (2) - (12).
bufflen: RS-type address or register (2) - (12).
ansarea: RS-type address or register (2) - (12).
556
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,ANSLEN=anslen
,BUFFALET=buffalet
,BLKSIZE=blksize
,MULTIBLOCK=YES
,MULTIBLOCK=NO
,RETBLOCKID=retblockid
,TIMESTAMP=timestamp
,RETBLOCKINFO=YES
,RETBLOCKINFO=NO
,MAXNUMLOGBLOCKS=maxnumlogblocks
MODE=SYNC
MODE=SYNCECB
,ECB=ecb
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
,RETCODE=retcode
,RSNCODE=rsncode
,MF=S
IXGBRWSE macro
Description
anslen: RS-type address or register (2) - (12).
buffalet: RS-type address or register (2) - (12).
Default
: BUFFALET=0
blksize: RS-type address or register (2) - (12). Default:
BLKSIZE=0
Default
: MULTIBLOCK=NO
retblockid: RS-type address or register (2) - (12). Default:
NO_BLKID Note: RETBLOCKID is valid with
MULTIBLOCK=NO only.
timestamp: RS-type address or register (2) - (12). Default:
NO_TIMESTAMP Note: TIMESTAMP is valid with
MULTIBLOCK=NO only.
Default
: NO Note: RETBLOCKINFO is valid with
MULTIBLOCK=YES only.
maxnumlogblocks: RS-type address or register (2) - (12).
Default
: MAXNUMLOGBLOCKS=0 Note:
MAXNUMLOGBLOCKS is valid with MULTIBLOCK=YES only.
Default
: MODE=SYNC
ecb: RS-type address or register (2) - (12).
Default
: IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: MF=S
Chapter 67. IXGBRWSE — Browse/read a log stream
557
IXGBRWSE macro
Syntax
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Description
Parameters for REQUEST=READCURSOR
The parameters are explained as follows:
REQUEST=READCURSOR
Requests that a program read the next consecutive log block in the log stream, in the direction specified on the DIRECTION parameter.
,STREAMTOKEN=streamtoken
Specifies the name or address (using a register) of a required 16-byte input field containing the token for the log stream that you want to browse and read.
The stream token is returned by the IXGCONN service at connection to the log stream.
,BROWSETOKEN=browsetoken
Specifies the name or address (using a register) of a required 4-byte input field containing the identifier for the browse session which was returned on the
IXGBRWSE REQUEST=START request.
,BUFFER=buffer
,BUFFER64=buffer64
Specifies the name or address (using a register) of a required output field that contains the buffer into which the log block is read.
v BUFFER=buffer specifies that the location of the buffer is in 31-bit storage.
v
BUFFER64=buffer64 specifies that the location of the buffer is in 64-bit storage.
the BUFFER and BUFFER64 parameters are mutually exclusive.
,BUFFLEN=bufflen
Specifies the name or address (using a register) of a required 4-byte input field that contains the length of the buffer specified on the BUFFER or BUFFER64 parameter.
IXGBRWSE will return the length of the block in the BLKSIZE parameter, if specified. If you specify MULTIBLOCK=NO, you can issue IXGBRWSE with
BLKSIZE specified to obtain the length of the block and then re-issue
IXGBRWSE using the returned BLKSIZE value in the BUFFLEN parameter.
,DIRECTION=OLDTOYOUNG
,DIRECTION=YOUNGTOOLD
Specifies the direction that you want the cursor to move to read the next
558
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
consecutive log block. Specify OLDTOYOUNG to get the next youngest block or YOUNGTOOLD to get the next oldest block.
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,BUFFALET=buffalet
Specifies the name (or address in a register) of a 4-byte input field specifying the access list entry table (ALET) to be used to access the buffer specified on the BUFFER or BUFFER64 keyword. If the buffer is ALET-qualified, the ALET must index a valid entry on the task's dispatchable unit access list (DUAL) or specify a SCOPE=COMMON data space. An ALET that indexes the system logger PASN-AL list will not work.
The default is 0, which means that the buffer is in the calling program's primary address space.
,BLKSIZE=blksize
Specifies the name or address (using a register) of a 4-byte output field where the space used or needed in the BUFFER or BUFFER64 area is returned. When
MULTIBLOCK=NO is specified and there is enough space in the buffer to return the requested log block data, the actual size of the log block is returned.
When MULTIBLOCK=YES is specified and there is enough space in the buffer to return the requested log blocks, the amount of space used in the BUFFER or
BUFFER64 area is returned. If the BUFFLEN value is not large enough to allow any log block data to be returned, then the BLKSIZE value will indicate the minimum amount of space necessary to return the next log block.
,MULTIBLOCK=YES
,MULTIBLOCK=NO
Specifies whether one or more than one log stream log block will be returned by the read cursor request.
v MULTIBLOCK=NO indicates that only one log stream log block is to be returned.
v MULTIBLOCK=YES indicates that the system logger will retrieve as many log blocks as meet the browse parameter criteria and fit into the caller's buffer.
,RETBLOCKID=retblockid
Specifies the name or address (using a register) of an 8-byte output field where the identifier or the requested log block is returned
,TIMESTAMP=timestamp
Specifies the name or address (using a register) of a 16-byte output field where the Coordinated universal time stamp and the local time stamp associated with the requested log block are returned. The UTC time stamp is first, then the local time stamp. Both time stamps are in TOD-clock format.
,RETBLOCKINFO=YES
Chapter 67. IXGBRWSE — Browse/read a log stream
559
IXGBRWSE macro
,RETBLOCKINFO=NO
Specifies whether or not system logger should return the log blocksize, blockid, timestamps and other identification information in the caller's buffer as part of the output. Specify RETBLOCKINFO=YES to receive each log block's identification information. Specify RETBLOCKINFO=NO to only receive the information necessary to navigate the caller's buffer.
If you omit the RETBLOCKINFO parameter, RETBLOCKINFO=NO is the default.
,MAXNUMLOGBLOCKS=xmaxnumlogblocks
Specifies the name (or address in a register) of an optional fullword input that indicates the maximum number of log blocks to be returned in the buffer.
When a non-zero value is specified, system logger will not return more than this requested number of log blocks, even if there are more log blocks that meet the other browse parameter criteria.
v If enough room is provided in the BUFFLEN value and there are sufficient log blocks that meet the browse criteria, system logger will return the requested maximum number of log blocks.
v If enough room is not provided in the BUFFLEN value, system logger will return as many log blocks as fit into the caller's buffer.
v If there are fewer log blocks remaining than the requested maximum number, system logger will return as many of the remaining log blocks as fit into the caller's buffer.
If you omit the MAXNUMLOGBLOCKS, the default is 0.
,MODE=SYNC
,MODE=SYNCECB
Specifies that the request should be processed in one of the following ways: v MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
v MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB parameter is posted when the request completes. The ECB parameter is required with MODE=SYNCECB.
ECB=ecb
Specifies the name or address (using a register) of a 4-byte input field that contains an event control block (ECB) to be posted when the request completes.
Before coding ECB, you must ensure that: v You initialize the ECB to zero.
v The ECB must reside in either common storage or the home address space at the time the IXGBRWSE request is issued.
v The virtual storage area specified for the ECB must reside on a fullword boundary.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are:
560
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , supports all parameters except those specifically referenced in higher versions.
v 1 , supports both the following parameters and parameters from version 0:
– DIAG
– REQDATA v 2 , supports both the following parameters and parameters from version 0 and 1:
– MAXNUMLOGBLOCKS
– MULTIBLOCK
– RETBLOCKINFO
To code
: Specify in this input parameter one of the following: v
IMPLIED_VERSION v MAX v A decimal value of 0, 1 or 2
,RETCODE=retcode
Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name or address (using a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The
Chapter 67. IXGBRWSE — Browse/read a log stream
561
IXGBRWSE macro
Syntax
list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends
that you use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
REQUEST=READBLOCK option of IXGBRWSE
The IXGBRWSE macro with the REQUEST=READBLOCK parameter allows a program to search for and read a specific log block from the log stream. The target can be defined either by the log block identifier or by a time stamp.
Syntax for REQUEST=READBLOCK
The IXGBRWSE REQUEST=READBLOCK macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede IXGBRWSE.
562
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
IXGBRWSE
�
REQUEST=READBLOCK
,STREAMTOKEN=streamtoken
,BROWSETOKEN=browsetoken
,BLOCKID=blockid
,SEARCH=search
,BUFFER=buffer
,BUFFER64=buffer64
,BUFFLEN=bufflen
,ANSAREA=ansarea
,ANSLEN=anslen
GMT=YES
GMT=NO
,BUFFALET=buffalet
,BLKSIZE=blksize
,RETBLOCKID=retblockid
,TIMESTAMP=timestamp
MODE=SYNC
MODE=SYNCECB
,ECB=ecb
IXGBRWSE macro
Description
One or more blanks must follow IXGBRWSE.
streamtoken: RS-type address or register (2) - (12).
browsetoken: RS-type address or register (2) - (12).
blockid: RS-type address or register (2) - (12).
search: RS-type address or register (2) - (12).
buffer: RS-type address or register (2) - (12).
buffer64: RS-type address or register (2) - (12).
bufflen: RS-type address or register (2) - (12).
ansarea: RS-type address or register (2) - (12).
anslen: RS-type address or register (2) - (12).
buffalet: RS-type address or register (2) - (12).
Default
: BUFFALET=0
blksize: RS-type address or register (2) - (12).
Default
: BLKSIZE=0
retblockid: RS-type address or register (2) - (12).
Default
: NO_BLKID
timestamp: RS-type address or register (2) - (12).
Default
: NO_TIMESTAMP
Default
: MODE=SYNC
ecb: RS-type address or register (2) - (12).
Chapter 67. IXGBRWSE — Browse/read a log stream
563
IXGBRWSE macro
Syntax
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
,RETCODE=retcode
,RSNCODE=rsncode
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Description
Default
: IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: MF=S
Parameters for REQUEST=READBLOCK
The parameters are explained as follows:
REQUEST=READBLOCK
Requests that a program read a specific block from the log stream. The target can be defined either by the log block identifier or by a time stamp.
,STREAMTOKEN=streamtoken
Specifies the name or address (using a register) of a required 16-byte input field containing the token for the log stream that you want to search. The stream token is returned by the IXGCONN service at connection to the log stream.
,BROWSETOKEN=browsetoken
Specifies the name or address (using a register) of a required 4-byte input field containing the identifier for the browse session which was returned from the
IXGBRWSE REQUEST=START request.
,BLOCKID=blockid
Specifies the name or address (using a register) of an 8-byte input field that contains the block identifier of the log block you wish to read. The block identifier was returned from the IXGWRITE request.
,SEARCH=search
Specifies the name or address (using a register) of a 64-bit input field containing the time stamp for the log block you wish to search for and read.
The time stamp must be Greenwich mean time or local time,
564
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
When you use a time stamp as a search criteria, IXGBRWSE searches in the oldest-to-youngest direction, searching for a log block with an exactly matching time stamp. If no exact match is found, IXGBRWSE reads the next latest
(youngest) time stamp. For information on how the SEARCH keyword works, see z/OS MVS Programming: Assembler Services Guide.
The GMT parameter is required with the SEARCH parameter.
,BUFFER=buffer
,BUFFER64=buffer64
Specifies the name or address (using a register) of a required output field that contains the buffer into which the log block is read.
v BUFFER=buffer specifies that the location of the buffer is in 31-bit storage.
v BUFFER64=buffer64 specifies that the location of the buffer is in 64-bit storage.
the BUFFER and BUFFER64 parameters are mutually exclusive.
,BUFFLEN=bufflen
Specifies the name or address (using a register) of a required 4-byte input field that contains the length of the buffer specified on the BUFFER or BUFFER64 parameter.
IXGBRWSE will return the length of the block in the BLKSIZE parameter, if specified. You can issue IXGBRWSE with BLKSIZE specified to obtain the length of the block and then re-issue IXGBRWSE using the returned BLKSIZE value in the BUFFLEN parameter.
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 32 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area size, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,GMT=YES
,GMT=NO
Specifies whether the time stamp specified on the SEARCH parameter is in
Coordinated universal time (UTC) or local time.
v GMT=YES: The time stamp specified on the SEARCH parameter is in
Greenwich mean time.
v GMT=NO: The time stamp specified on the SEARCH parameter is local time.
,BUFFALET=buffalet
Specifies the name (or address in a register) of a 4-byte input field specifying the access list entry table (ALET) to be used to access the buffer specified on
Chapter 67. IXGBRWSE — Browse/read a log stream
565
IXGBRWSE macro
the BUFFER or BUFFER64 keyword. If the buffer is ALET-qualified, the ALET must index a valid entry on the task's dispatchable unit access list (DUAL) or specify a SCOPE=COMMON data space. An ALET that indexes the system logger PASN-AL list will not work.
The default is 0, which means that the buffer is in the calling program's primary address space.
,BLKSIZE=blksize
Specifies the name or address (using a register) of a 4-byte output field where the actual size of the requested log block is returned.
,RETBLOCKID=retblockid
Specifies the name or address (using a register) of a 8-byte output field where the identifier of the requested log block is returned.
,TIMESTAMP=timestamp
Specifies the name or address (using a register) of a 16-byte output field where the Coordinated universal time and local time stamps associated with the requested log block is returned. The UTC time stamp is first, then the local time stamp. Both time stamps will be in TOD-clock format.
,MODE=SYNC
,MODE=SYNCECB
Specifies that the request should be processed in one of the following ways: v MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
v MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB parameter is posted when the request completes. The ECB parameter is required with MODE=SYNCECB.
ECB=ecb
Specifies the name or address (using a register) of a 4-byte input field that contains an event control block (ECB) to be posted when the request completes.
Before coding ECB, you must ensure that: v You initialize the ECB to zero.
v
The ECB must reside in either common storage or the home address space at the time the IXGBRWSE request is issued.
v The virtual storage area specified for the ECB must reside on a fullword boundary.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
566
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , supports all parameters except those specifically referenced in higher versions.
v 1 , supports both the following parameters and parameters from version 0:
– DIAG
– REQDATA v 2 , supports both the following parameters and parameters from version 0 and 1:
– MAXNUMLOGBLOCKS
– MULTIBLOCK
– RETBLOCKINFO
To code
: Specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0, 1 or 2
,RETCODE=retcode
Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name or address (using a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Chapter 67. IXGBRWSE — Browse/read a log stream
567
IXGBRWSE macro
Syntax
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends
that you use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v
Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
REQUEST=RESET option of IXGBRWSE
The IXGBRWSE macro with the REQUEST=RESET parameter allows a program to re-position the browse cursor to either the youngest or oldest block in the log stream.
Syntax for REQUEST=RESET
The IXGBRWSE REQUEST=RESET macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede IXGBRWSE.
IXGBRWSE
� One or more blanks must follow IXGBRWSE.
568
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
REQUEST=RESET
,STREAMTOKEN=streamtoken
,BROWSETOKEN=browsetoken
,POSITION=YOUNGEST
,POSITION=OLDEST
,ANSAREA=ansarea
,ANSLEN=anslen
VIEW=ACTIVE
VIEW=ALL
MODE=SYNC
MODE=SYNCECB
,ECB=ecb
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
,RETCODE=retcode
,RSNCODE=rsncode
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
IXGBRWSE macro
Description
streamtoken: RS-type address or register (2) - (12).
browsetoken: RS-type address or register (2) - (12).
ansarea: RS-type address or register (2) - (12).
anslen: RS-type address or register (2) - (12).
Default
: MODE=SYNC
ecb: RS-type address or register (2) - (12).
Default
: IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: MF=S
Chapter 67. IXGBRWSE — Browse/read a log stream
569
IXGBRWSE macro
Parameters for REQUEST=RESET
The parameters are explained as follows:
REQUEST=RESET
Requests that the browse cursor be repositioned at either the oldest or youngest block in the log stream.
,STREAMTOKEN=streamtoken
Specifies the name or address (using a register) of a required 16-byte input field containing the token for the log stream that you want to search. The stream token is returned by the IXGCONN service at connection to the log stream.
,BROWSETOKEN=browsetoken
Specifies the name or address (using a register) of a required 4-byte input field containing the identifier for the browse session which was returned from the
IXGBRWSE REQUEST=START request.
,POSITION=YOUNGEST
,POSITION=OLDEST
Specifies the cursor position desired, at either the youngest or the oldest log block in the log stream.
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 32 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area size, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
VIEW=ACTIVE
VIEW=ALL
Specifies whether requests issued during this browse session return active data only, or both active and inactive data. Active data is data that has not been marked for deletion via the IXGDELET service. Inactive data is data that has been deleted via IXGDELET but has not been physically deleted from the log stream because of the retention period specified in the log stream definition in the LOGR couple data set.
v VIEW=ACTIVE, which is the default, specifies that in this browse session, system logger will only return active data from the log stream.
v
VIEW=ALL specifies that in this browse session, system logger will return both active and inactive data.
570
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
When VIEW=ALL is specified and a log block is returned, system logger sets a flag in the answer area, AnsaaBlkFromInactive, indicating whether the block was active or eligible for deletion.
The system where IXGBRWSE is issued must be IPLed.
,MODE=SYNC
,MODE=SYNCECB
Specifies that the request should be processed in one of the following ways: v MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
v MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB parameter is posted when the request completes. The ECB parameter is required with MODE=SYNCECB.
ECB=ecb
Specifies the name or address (using a register) of a 4-byte input field that contains an event control block (ECB) to be posted when the request completes.
Before coding ECB, you must ensure that: v You initialize the ECB to zero.
v The ECB must reside in either common storage or the home address space at the time the IXGBRWSE request is issued.
v
The virtual storage area specified for the ECB must reside on a fullword boundary.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , supports all parameters except those specifically referenced in higher versions.
v 1 , supports both the following parameters and parameters from version 0:
– DIAG
– REQDATA
Chapter 67. IXGBRWSE — Browse/read a log stream
571
IXGBRWSE macro
v 2 , supports both the following parameters and parameters from version 0 and 1:
– MAXNUMLOGBLOCKS
– MULTIBLOCK
– RETBLOCKINFO
To code
: Specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0, 1 or 2
,RETCODE=retcode
Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name or address (using a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends
that you use the modify and execute forms in the following order: v
Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
572
z/OS MVS Assembler Services Reference IAR-XCT
�
�
Syntax
name
IXGBRWSE macro
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v
Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
REQUEST=END option of IXGBRWSE
The IXGBRWSE macro with the REQUEST=END parameter ends the browse session begun with the REQUEST=START parameter.
Syntax for REQUEST=END
The IXGBRWSE REQUEST=END macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede IXGBRWSE.
IXGBRWSE
One or more blanks must follow IXGBRWSE.
REQUEST=END
,STREAMTOKEN=streamtoken
,BROWSETOKEN=browsetoken
,ANSAREA=ansarea
,ANSLEN=anslen
MODE=SYNC
streamtoken: RS-type address or register (2) - (12).
browsetoken: RS-type address or register (2) - (12).
ansarea: RS-type address or register (2) - (12).
anslen: RS-type address or register (2) - (12).
Default
: MODE=SYNC
Chapter 67. IXGBRWSE — Browse/read a log stream
573
IXGBRWSE macro
Syntax
MODE=SYNCECB
,ECB=ecb
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
,RETCODE=retcode
,RSNCODE=rsncode
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Description
ecb: RS-type address or register (2) - (12).
Default
: IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: MF=S
Parameters for REQUEST=END
The parameters are explained as follows:
REQUEST=END
Requests that the browse session be ended.
,STREAMTOKEN=streamtoken
Specifies the name or address (using a register) of a required 16-byte input field containing the token for the log stream that you want to search. The stream token is returned by the IXGCONN service at connection to the log stream.
,BROWSETOKEN=browsetoken
Specifies the name or address (using a register) of a required 4-byte input field containing the identifier for the browse session which was returned from the
IXGBRWSE REQUEST=START request.
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the
574
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,MODE=SYNC
,MODE=SYNCECB
Specifies that the request should be processed in one of the following ways: v MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
v MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB parameter is posted when the request completes. The ECB parameter is required with MODE=SYNCECB.
ECB=ecb
Specifies the name or address (using a register) of a 4-byte input field that contains an event control block (ECB) to be posted when the request completes.
Before coding ECB, you must ensure that: v You initialize the ECB to zero.
v The ECB must reside in either common storage or the home address space at the time the IXGBRWSE request is issued.
v
The virtual storage area specified for the ECB must reside on a fullword boundary.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , supports all parameters except those specifically referenced in higher versions.
v 1 , supports both the following parameters and parameters from version 0:
– DIAG
– REQDATA
Chapter 67. IXGBRWSE — Browse/read a log stream
575
IXGBRWSE macro
v 2 , supports both the following parameters and parameters from version 0 and 1:
– MAXNUMLOGBLOCKS
– MULTIBLOCK
– RETBLOCKINFO
To code
: Specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0, 1 or 2
,RETCODE=retcode
Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name or address (using a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends
that you use the modify and execute forms in the following order: v
Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
576
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v
Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
The IXGBRWSE service may issue abend X'1C5' with reason codes X'804', X'85F' or
X'30006'. See z/OS MVS System Codes for more information on this abend.
Return and reason codes
When IXGBRWSE macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.
Note:
A program invoking the IXGBRWSE service may indicate via the MODE parameter that requests which can not be completed synchronously should have control returned to the caller prior to completion of the request. When the request does complete, the invoker will be notified and the return and reason codes are in the answer area mapped by IXGANSAA.
The IXGCON mapping macro provides equate symbols for the return and reason codes. The equate symbols associated with each hexadecimal return code are as follows:
00
04
IXGRSNCODEOK - Service completes successfully.
IXGRSNCODEWARNING - Service completes with a warning.
08
0C
IXGRETCODEERROR - Service does not complete.
IXGRETCODECOMPERROR - Service does not complete.
The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code.
Table 35. Return and Reason Codes for the IXGBRWSE Macro
Return Code
00
Reason Code
xxxx0000
Meaning and Action
Equate Symbol
: IxgRsnCodeOk
Explanation
: Request processed successfully.
Chapter 67. IXGBRWSE — Browse/read a log stream
577
IXGBRWSE macro
Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)
Return Code
04
Reason Code
xxxx0401
Meaning and Action
Equate Symbol
: IxgRsnCodeProcessedAsynch
04 xxxx0402
Explanation
: Program error. The program specified
MODE=SYNCECB and the request must be processed asynchronously.
Action
: Wait for the ECB specified on the ECB parameter to be posted, indicating that the request is complete. Check the ANSAA_ASYNCH_RETCODE and ANSAA_ASYNCH_RSNCODE fields, mapped by IXGANSAA, to determine whether the request completed successfully.
Equate Symbol
: IxgRsnCodeWarningDel
04 xxxx0403
Explanation
: Environment error. The request completed successfully, but the data requested was deleted from the log stream. The next available data in the log stream in the direction specified is returned.
Action
: Determine whether this is an acceptable condition for your application. If so, ignore this condition. If not, provide serialization or some other installation protocol to prevent deletes from being performed by other applications on the log stream during a browse session.
Equate Symbol
: IxgRsnCodeWarningGap
Explanation
: Environment error. The request completed successfully, but the data requested was unreadable. The next readable data in the log stream in the specified direction is returned. This condition could be caused by either an I/O error while attempting to read a log data set or a log data set deleted without using the logger interfaces.
Action
: The action necessary is completely up to the application, depending on how critical your data is.
You can do one of the following: v Accept this condition and continue reading.
v Stop processing the log all together.
v Attempt to get the problem rectified, if possible, and then attempt to re-read the log data.
578
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)
Return Code
04
Reason Code
xxxx0405
Meaning and Action
Equate Symbol
: IxgRsnCodeWarningLossOfData
04 xxxx0416
Explanation
: Environment error. Returned for
READCURSOR, START OLDEST and RESET
OLDEST requests. This condition occurs when a system and coupling facility fail and not all of the log data in the log stream could be recovered.
v For READCURSOR: A log block has been returned, but there may be log blocks permanently missing between this log block and the one previously returned.
v
For START OLDEST and RESET OLDEST: The oldest log blocks in the log stream may be permanently missing, the browse cursor is set at the oldest available log block.
Action
: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
Equate Symbol
: IxgRsnCodeWarningMultiblock
Explanation
: Environment error. Returned for
READCURSOR requests with MULTIBLOCK=YES specified only. The request completed successfully, which means that some log block data was returned, but at least one of the log blocks returned in the buffer area encountered a warning return code condition. To determine which log block or blocks encountered the warning condition, check the fields,
Ixgbrmlt_RetCode and Ixgbrmlt_RsnCode, as the log blocks are processed by your program.
Action
: The action necessary is completely up to the application, depending on how critical your data is.
You can do one of the following: v Accept this condition and continue reading.
v Stop processing the log all together.
v Attempt to get the problem rectified, if possible, and then attempt to re-read the log data.
Chapter 67. IXGBRWSE — Browse/read a log stream
579
IXGBRWSE macro
Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)
Return Code
04
Reason Code
xxxx0417
Meaning and Action
Equate Symbol
: IxgRsnCodeMultiblockErrorWarning
08 xxxx0801
Explanation
: Environment error. Returned for
READCURSOR requests with MULTIBLOCK=YES specified only. A log block has been returned, but an error condition was encountered while attempting to read more data. This may be issued when some log block data is returned and an end of the log stream
(eof) is reached.
Action
: The action necessary is completely up to the application, depending on how critical your data is.
You can do one of the following: v Accept this condition and continue reading.
v Stop processing the log all together.
v Attempt to get the problem rectified, if possible, and then attempt to re-read the log data.
Equate Symbol
: IxgRsnCodeBadParmlist
08
08 xxxx0802 xxxx0803
Explanation
: Program error. The parameter list could not be accessed.
Action
: Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.
Equate Symbol
: IxgRsnCodeXESError
Explanation
: System error. A severe cross-system extended services (XES) error has occurred.
Action
: See ANSAA_DIAG1 for the XES return code and ANSAA_DIAG2 for the XES reason code.
Equate Symbol
: IxgRsnCodeBadBuffer
Explanation
: Program error. The virtual storage area specified on the BUFFER or BUFFER64 parameter is not addressable. On IXGBRWSE READCURSOR
MULTIBLOCK requests, the buffer address must be on a word boundary.
Action
: Ensure that the storage area specified on the
BUFFER or BUFFER64 parameter is accessible to system logger for the duration of the request. If the
BUFFKEY parameter is specified, make sure it contains a valid key associated with the storage area.
If BUFFKEY is not used, ensure that the storage is in the same key as the program at the time the logger service was requested. The storage must be addressable in the caller's primary address space.
For IXGBRWSE READCURSOR MULTIBLOCK requests, put the buffer address on a word boundary.
580
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)
Return Code
08
Reason Code
xxxx0804
Meaning and Action
Equate Symbol
: IxgRsnCodeNoBlock
08 xxxx0806
Explanation
: Program error. The block identifier or time stamp does not exist in the requested view of the log stream. If the SEARCH parameter was specified on a START request, the time stamp is greater than any block in the log stream. Either the value provided was never a valid location within the log stream, or a prior IXGDELET request deleted the portion of the log stream it referred to.
Action
: Ensure that the value provided references an existing portion of the log stream.
Equate Symbol
: IxgRsnCodeBadStmToken
08
08
08 xxxx0807 xxxx080A xxxx080F
Explanation
: Program error. One of the following occurred: v The stream token was not valid.
v The specified request was issued from an address space other than the connector's address space.
Action
: Do one of the following: v
Make sure that the stream token specified is valid.
v
Ensure that the request was issued from the connector's address space.
Equate Symbol
: IxgRsnCodeBadBrwToken
Explanation
: Program error. The browse token specified is not valid.
Action
: Ensure that the browse token being passed to the IXGBRWSE service is the same one returned from the IXGBRWSE REQUEST=START function.
Equate Symbol
: IxgRsnCodeRequestLocked
Explanation
: Program error. The program issuing the request is holding a lock.
Action
: Ensure that the program issuing the request is not holding a lock.
Equate Symbol
: IxgRsnCodeBadBufsize
Explanation
: Program error. The buffer specified on the BUFFER or BUFFER64 parameter is not large enough to contain the next log block. No data is returned.
Action
: Obtain a buffer of at least the length returned in the BLKSIZE parameter and then re-issue the request.
Chapter 67. IXGBRWSE — Browse/read a log stream
581
IXGBRWSE macro
Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)
Return Code
08
Reason Code
xxxx0814
Meaning and Action
Equate Symbol
: IxgRsnCodeNotAvailForIPL
08 xxxx0815
Explanation
: Environment error. The system logger address space is not available for the remainder of this IPL. The system issues messages about this error during system logger initialization.
Action
: See the explanation for system messages issued during system logger initialization.
Equate Symbol
: IxgRsnCodeNotEnabled
Explanation
: Program error. The program issuing the request is not enabled for I/O and external interrupts, so the request fails.
08
08
08 xxxx0816 xxxx0817 xxxx0818
Action
: Make sure the program issuing the request is enabled for I/O and external interrupts.
Equate Symbol
: IxgRsnCodeBadAnslen
Explanation
: Program error. The answer area length
(ANSLEN parameter) is not large enough. The system logger returned the required size in the
Ansaa_Preferred_Size field of the answer area, mapped by IXGANSAA macro.
Action
: Re-issue the request, specifying an answer area of the required size.
Equate Symbol
: IxgRsnCodeBadAnsarea
Explanation
: Program error. The storage area specified on the ANSAREA parameter cannot be accessed. This may occur after the system logger address space has terminated.
Action
: Specify storage that is in the caller's primary address space and in the same key as the calling program at the time the system logger service was issued. This storage must be accessible until the request completes.
Equate Symbol
: IxgRsnCodeBadBlockidStor
08 xxxx082D
Explanation
: Program error. The storage area specified by BLOCKID cannot be accessed.
Action
: Ensure that the storage area is accessible to system logger for the duration of the request. The storage must be addressable in the caller's primary address space and in the same key as the caller.
Equate Symbol
: IxgRsnCodeExpiredStmToken
Explanation
: Environment error. The stream token is no longer valid because the connector has been disconnected.
Action
: Connect to the log stream again before issuing any functional requests.
582
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)
Return Code
08
Reason Code
xxxx0836
Meaning and Action
Equate Symbol
: IxgRsnCodeBadGap
08
08 xxxx0837 xxxx083B
Explanation
: Environment error. The request failed because the requested log data was unreadable. This condition could be caused by either an I/O error while attempting to read a log data set or a log data set deleted without using logger interfaces.
Action
: For an IXGBRWSE request, choose on of the following: v
Continue processing.
v
Stop processing the log stream all together.
v Attempt to get the problem rectified if possible, then attempt to re-read the log data.
For an IXGDELET request, the block identifier of the first accessible block toward the youngest data in the log stream is returned in the
ANSAA_GAPS_NEXT_BLKID field in the answer area mapped by the IXGANSAA macro. If appropriate, re-issue the IXGDELET request using this block identifier.
Equate Symbol
: IxgRsnCodeBadTimestamp
Explanation
: Program error. The storage area specified by TIMESTAMP cannot be accessed.
Action
: Ensure that the storage area is accessible to the system logger service for the duration of the request. The storage must be addressable in the caller's primary address space and in the same key as the caller.
Equate Symbol
: IxgRsncodeBadBTokenStor
08 xxxx083D
Explanation
: Program error. The storage area specified by BROWSETOKEN cannot be accessed.
Action
: Ensure that the storage area is accessible to the system logger for the duration of the request.
The storage must be addressable in the caller's primary address space and in the same key as the caller.
Equate Symbol
: IxgRsnCodeBadECBStor
Explanation
: Program error. The ECB storage area was not accessible to the system logger.
Action
: Ensure that the storage area is accessible to the system logger for the duration of the request.
The storage must be addressable in the caller's home address space and in the same key as the caller.
Chapter 67. IXGBRWSE — Browse/read a log stream
583
IXGBRWSE macro
Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)
Return Code
08
Reason Code
xxxx083F
Meaning and Action
Equate Symbol
: IxgRsnCodeTestartError
08
08 xxxx0841 xxxx0845
Explanation
: System error. An unexpected error was encountered while attempting to validate the buffer
ALET.
Action
: See ANSAA_DIAG1 in the answer area mapped by the IXGANSAA macro for the return code from the TESTART system service.
Equate Symbol
: IxgRsnCodeBadBufferAlet
Explanation
: Program error. The buffer ALET specified is not zero and does not represent a valid entry on the caller's dispatchable unit access list
(DUAL). See the ANSAA_DIAG1 field of the answer area, mapped by the IXGANSAA macro, for the return code from the TESTART system service.
Action
: Ensure that the correct ALET was specified.
If not, provide the correct ALET. Otherwise, add the correct ALET to dispatchable unit access list
(DUAL).
Equate Symbol
: IxgRsnCodeInvalidFunc
Explanation
: System error. One of 2 problems was detected.
1.
The parameter list for this service contains an unrecognizable function code. The parameter list storage may have been overlayed.
2.
The IXGBRWSE START is rejected because either: v A: An unauthorized caller attempted to start a session when 100 or more browse sessions already exist for this connection. Or, v B: An unauthorized caller attempted to start a session when 20 or more browse sessions already exist that show no recent activity. (An unauthorized caller is a caller whose PSW Key is >= 8 and that is not in supervisor state).
08 xxxx0846
For Case 2: DIAG1 in the Answer Area will contain
1 if 'A' is the case, and 2 if 'B' is the case.
DIAG2 will contain the number of browse sessions that was exceeded.
Action
: Fix the problem and then re-issue the request. It may be necessary to terminate some
Browse sessions that are not being used.
Equate Symbol
: IxgRsnCodeEmptyStream
Explanation
: Environment error. The log stream is empty.
Action
: Wait for data to be written to the log stream before browsing for data.
584
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)
Return Code
08
Reason Code
xxxx0847
Meaning and Action
Equate Symbol
: IxgRsnCodeEOFDelete
08 xxxx0848
Explanation
: Environment error. The request prematurely reached the beginning or the end of the log stream. The portion of the log stream from the requested log data to either the beginning or the end of the log stream (depending on the direction of the read) was deleted from the log stream.
Action
: Determine whether this is an acceptable condition for your application. If so, ignore this condition. If not, provide serialization on the log stream or some other installation protocol to prevent deletes from being performed by other applications during a browse session.
Equate Symbol
: IxgRsnCodeEndReached
Explanation
: Environment error. The request failed and no log data is returned. For a READCURSOR request, the end of the log stream has been reached in the direction of the read. If the SEARCH parameter was specified on a READBLOCK request, the time stamp is greater than any block in the log stream.
08 xxxx0849
Action
: For the READCURSOR case, no more data exists in the log stream in the direction of the read.
You can choose to stop reading, wait for more data to be written, or change the direction of the read. In the case where the SEARCH parameter was provided, ensure that the time stamp is less than or equal to the highest time stamp of a log block in the log stream.
Equate Symbol
: IxgRsnCodeBadBuffkey
Explanation
: Program error. The buffer key specified on the BUFFKEY parameter specifies an invalid key.
Either the key is greater than 15 or the program is running in problem state and the specified key is not the same key as the PSW key at the time the system logger service was issued.
Action
: For problem state programs, either do not specify the BUFFKEY parameter or else specify the same key as the PSW key at the time the system logger service was issued. For supervisor state programs, specify a valid storage key (0 <= key <=
15).
Chapter 67. IXGBRWSE — Browse/read a log stream
585
IXGBRWSE macro
Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)
Return Code
08
Reason Code
xxxx084A
Meaning and Action
Equate Symbol
: IxgRsnCodeEOFGap
08 xxxx084B
Explanation
: Environment error. The request prematurely reached the beginning or the end of the log stream. The portion of the log stream from the requested log data to either the beginning or the end of the log stream (depending on the direction of the read) was unreadable. This condition may be caused by either an I/O error while trying to read a log data set, or a log data set deleted without using logger interfaces.
Action
: The action necessary is completely up to the application depending on how critical your data is.
You can do one of the following: v Accept this condition and continue reading.
v Stop processing the log all together.
v Attempt to get the problem rectified, if possible, and then attempt to re-issue the request.
Equate Symbol
: IxgRsncodeLossOfDataGap
08 xxxx084D
Explanation
: Environment error. The requested log data referenced a section of the log stream where log data is permanently missing. This condition occurs when a system or coupling facility is in recovery due to a failure, but not all of the log data in the log stream could be recovered.
Action
: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
Equate Symbol
: IxgRsnCodeLossOfDataEOF
Explanation
: Environment error. The request prematurely reached the beginning or the end of the log stream. The portion of the log stream from the requested log data to either the beginning or the end of the log stream (depending on direction of the read) was permanently lost. This condition occurs when a system or coupling facility is in recovery due to a failure, but not all of the log data in the log stream could be recovered.
Action
: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
586
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)
Return Code
08
Reason Code
xxxx0852
Meaning and Action
Equate Symbol
: IxgRsnCodeBadBlkSizeStor
Explanation
: Program error. The storage area specified on the BLKSIZE parameter cannot be accessed.
08
08 xxxx085F xxxx0861
Action
: Ensure that the storage area is accessible to system logger for the duration of the request.
Equate Symbol
: IxgRsnPercToRequestor
Explanation
: Environment error. Percolation to the service requestor's task occurred because of an abend during system logger processing. Retry was not allowed.
Action
: Issue the request again. If the problem persists, contact the IBM Support Center.
Equate Symbol
: IxgRsnCodeRebuildInProgress
08
08 xxxx0862 xxxx0863
Explanation
: Environment error. No requests can be processed for this log stream because a coupling facility structure re-build is in progress for the structure associated with this log stream.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v The re-build failed and the log stream is not available.
Equate Symbol
: IxgRsnCodeXESPurge
Explanation
: Environment error. An cross-system extended services (XES) request has been purged due to re-build processing.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v The re-build failed and the log stream is not available.
Equate Symbol
: IxgRsnCodeStructureFailed
Explanation
: Environment error. Either the coupling facility structure associated with the log stream has failed or the coupling facility itself has failed.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v The re-build failed and the log stream is not available.
Chapter 67. IXGBRWSE — Browse/read a log stream
587
IXGBRWSE macro
Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)
Return Code
08
Reason Code
xxxx0864
Meaning and Action
Equate Symbol
: IxgRsnCodeNoConnectivity
08 xxxx0890
Explanation
: Environment error. No connectivity exists to the coupling facility associated with the log stream. The system logger will either attempt to re-build the log stream in another coupling facility or the log stream will be disconnected.
Action
: Listen for ENF signal 48 that will indicate one of the following: v
The log stream is available because the re-build completed successfully. Re-issue the request.
v The re-build failed and the log stream is not available.
v The log stream has been disconnected from this system.
If a re-build initiated because of a loss of connectivity previously failed, an ENF corresponding to this reason code might not be issued. Further action by the installation might be necessary to cause the change of the log stream status again. Check the log for messages IXG101I,
IXG107I and related rebuild messages for information on resolving any outstanding issues.
Equate Symbol
: IxgRsnCodeAddrSpaceNotAvail
08
08 xxxx0891 xxxx08D0
Explanation
: System error. The system logger address space failed and is not available.
Action
: Do not issue system logger requests.
Equate Symbol
: IxgRsnCodeAddrSpaceInitializing
Explanation
: System error. The system logger address space is not available because it is IPLing.
Action
: Listen for ENF signal 48, which will indicate when the system logger address space is available.
Re-connect to the log stream, then re-issue this request. You can also listen for ENF signal 48, which will indicate if the system logger address space will not be available for the life of the IPL. In that case, do not issue system logger services.
Equate Symbol
: IxgRsnCodeProblemState
Explanation
: Environment error. The request was rejected because of one of the following: v The request was issued in SRB mode while the requestor was in problem program state.
v The SYNCEXIT parameter was specified while the requestor's PSW key was in problem program key.
Action
: Change the invoking environment to supervisor state.
588
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)
Return Code
08
Reason Code
xxxx08D1
Meaning and Action
Equate Symbol
: IxgRsnCodeProgramKey
08 xxxx08D2
Explanation
: Environment error. The request was rejected because of one of the following: v The request was issued in SRB mode while the requestor was in problem program key (key 8-F).
v The SYNCEXIT parameter was specified while the requestor's PSW key was in problem program key.
Action
: Change the invoking environment to a system key (key 0-7).
Equate Symbol
: IxgRsnCodeNoCompleteExit
Explanation
: Program error. MODE=SYNCEXIT was specified, but the connection request did not identify a complete exit.
08
0C xxxx08D3 xxxx0000
Action
: Either change this request to a different
MODE option, or reconnect to the log stream with a complete exit on the COMPLETEXIT parameter.
Equate Symbol
: IxgRsnCodeFuncNotSupported
Explanation
: Environment error. The options specified on the IXGBRWSE request are not supported on this system/maintenance level of system logger.
Action
: Either install the level of system logger that provides the support for the requested function, or do not specify options that are not supported at this level.
Equate Symbol
: IxgRetCodeCompError
Explanation
: User or System error. One of the following occurred: v
You issued the FORCE IXGLOGR,ARM command to terminate the system logger address space.
v System logger component error occurred.
Action
: If this reason code is not the result of forcing the system logger address space, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center. Provide the diagnostic data in the answer area (IXGANSAA) and any dumps or LOGREC entries from system logger.
Examples
Example 1
Issue IXGBRWSE REQUEST=START to start a browse session, starting the browse cursor at the log block with the specified local time.
IXGBRWSE REQUEST=START,
STREAMTOKEN=TOKEN,
SEARCH=SRCHTIME,
X
X
X
Chapter 67. IXGBRWSE — Browse/read a log stream
589
IXGBRWSE macro
GMT=NO,
BROWSETOKEN=BRSTOKEN,
MODE=SYNC,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
ANSLEN DC
TOKEN DS
SRCHTIME DS
BRSTOKEN DS
A(L’ANSAREA)
CL16
2F
CL4
ANSAREA DS
RETCODE DS
RSNCODE DS
DATAREA DSECT
CL(ANSAA_LEN)
F
F
IXGANSAA LIST=YES length of logger’s answer area stream token from connect local search time in stck format returned browse token answer area for log requests return code reason code answer area
X
X
X
X
X
X
X
Example 2
Issue IXGBRWSE REQUEST=READCURSOR to read the next consecutive log block in the specified direction. In this example, the default of MULTIBLOCK=NO has been taken.
IXGBRWSE REQUEST=READCURSOR,
STREAMTOKEN=TOKEN,
BUFFER=BUFF,
BUFFLEN=BUFFLEN,
BUFFALET=ALET,
BLKSIZE=BLKSIZE,
DIRECTION=OLDTOYOUNG,
RETBLOCKID=RETBLK,
TIMESTAMP=TIMESTMP,
BROWSETOKEN=BRSTOKEN,
MODE=SYNC,
ANSAREA=ANSAREA,
ANSLEN DC
BUFFLEN DC
TOKEN
BUFF
ALET
BLKSIZE
RETBLK
TIMESTMP DS
ANSAREA DS
RETCODE
RSNCODE
DS
BRSTOKEN DS
DS
DC
DS
DS
DS
DS
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
A(L’ANSAREA)
F’200’
CL16
CL4
CL200
F’1’
F
CL8
CL16
CL(ANSAA_LEN)
F
F
DATAREA DSECT
IXGANSAA LIST=YES length of logger’s answer area buffer length stream token from connect returned browse token buffer where data will be put buffer alet in secondary block size of buffer return block id returned time stamp stck format answer area for log requests return code reason code answer area
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
Example 3
Issue IXGBRWSE REQUEST=READBLOCK to read a log block selected by block identifier.
IXGBRWSE REQUEST=READBLOCK,
STREAMTOKEN=TOKEN,
BLOCKID=BLKID,
BUFFER=BUFF,
BUFFLEN=BUFFLEN,
BUFFALET=ALET,
X
X
X
X
X
X
590
z/OS MVS Assembler Services Reference IAR-XCT
IXGBRWSE macro
BLKSIZE=BLKSIZE,
RETBLOCKID=RETBLK,
TIMESTAMP=TIMESTMP,
BROWSETOKEN=BRSTOKEN,
MODE=SYNC,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
ANSLEN DC
BUFFLEN DC
TOKEN
BUFF
ALET
BLKSIZE
RETBLK
BLKID DS
TIMESTMP DS
ANSAREA
RETCODE
DS
BRSTOKEN DS
DS
DS
DS
DS
DS
DS
MF=S,
RETCODE=RETCODE
A(L’ANSAREA)
F’200’
CL16
CL4
CL200
F’1’
F
CL8
CL8
CL16
CL(ANSAA_LEN)
F
F RSNCODE DS
DATAREA DSECT
IXGANSAA LIST=YES length of logger’s answer area buffer length stream token from connect returned browse token buffer where data will be put buffer alet in secondary block size of buffer return block id specific block id to browse returned time stamp stck format answer area for log requests return code reason code answer area
X
X
X
X
X
X
X
X
X
Example 4
Issue IXGBRWSE REQUEST=RESET to reset the cursor at the youngest block in the log stream.
IXGBRWSE REQUEST=RESET,
STREAMTOKEN=TOKEN,
POSITION=YOUNGEST,
BROWSETOKEN=BRSTOKEN,
MODE=SYNC,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
ANSLEN DC
TOKEN DS
BRSTOKEN DS
ANSAREA DS
RETCODE DS
RSNCODE DS
MF=S,
RETCODE=RETCODE
A(L’ANSAREA)
CL16
CL4
CL(ANSAA_LEN)
F
F
DATAREA DSECT
IXGANSAA LIST=YES length of logger’s answer area stream token from connect returned browse token answer area for log requests return code reason code answer area
X
X
X
X
X
X
X
X
X
Example 5
Issue IXGBRWSE REQUEST=END to end a browse session.
ANSLEN DC
TOKEN DS
BRSTOKEN DS
ANSAREA DS
IXGBRWSE REQUEST=END,
STREAMTOKEN=TOKEN,
BROWSETOKEN=BRSTOKEN,
MODE=SYNC,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
A(L’ANSAREA)
CL16
CL4
CL(ANSAA_LEN) length of logger’s answer area stream token from connect browse token from browse start answer area for log requests
X
X
X
X
X
X
X
X
Chapter 67. IXGBRWSE — Browse/read a log stream
591
IXGBRWSE macro
RETCODE DS
RSNCODE DS
F
F
DATAREA DSECT
IXGANSAA LIST=YES
Example 6
return code reason code answer area
Issue IXGBRWSE REQUEST=END to end a browse session asynchronously, if synchronous processing is not possible.
IXGBRWSE REQUEST=END,
STREAMTOKEN=TOKEN,
BROWSETOKEN=BRSTOKEN,
MODE=SYNCECB,
ECB=ANECB,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
*++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* if rsncode = ’00000401’X then wait on
* the ecb ANECB.
*++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ANSLEN DC
TOKEN DS
BRSTOKEN DS
A(L’ANSAREA)
CL16
CL4 length of logger’s answer area stream token from connect browse token from browse start
ANSAREA DS
ANECB DS
RETCODE DS
RSNCODE DS
CL(ANSAA_LEN)
F
F
F
DATAREA DSECT
IXGANSAA LIST=YES answer area for log requests ecb on which to wait return code reason code answer area
X
X
X
X
X
X
X
X
X
Example 7
Issue IXGBRWSE REQUEST=END using registers.
LA R6,TOKEN
IXGBRWSE REQUEST=END,
STREAMTOKEN=(6),
BROWSETOKEN=BRSTOKEN,
MODE=SYNC,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
ANSLEN DC
TOKEN DS
BRSTOKEN DS
ANSAREA DS
RETCODE DS
RSNCODE DS
MF=S,
RETCODE=RETCODE
A(L’ANSAREA)
CL16
CL4
CL(ANSAA_LEN)
F
F
DATAREA DSECT
R6
IXGANSAA LIST=YES
EQU 6 place stream token in reg 6 length of logger’s answer area stream token from connect browse token from browse start answer area for log requests return code reason code answer area
X
X
X
X
X
X
X
X
592
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 68. IXGCONN — Connect/disconnect to log stream
Description
Use the IXGCONN macro to connect a program to a specific log stream or disconnect a program from a specific log stream.
IXGCONN returns a unique connection identifier called a stream token on completion of the IXGCONN REQUEST=CONNECT request. Subsequent logger services use the stream token to identify the connection. If multiple applications connect to the same log stream, the log blocks written from the different applications are merged.
The IXGCONN connect service can be used in the following ways: v Once a program has connected to a log stream, any application running in the same address space shares the connect status and may share the same stream token to issue other logger services. Any program in the address space can disconnect the entire address space from the log stream by issuing the
IXGCONN REQUEST=DISCONNECT service.
v Multiple programs in a single address space can issue IXGCONN
REQUEST=CONNECT individually to connect to the same log stream and receive separate stream tokens. Each program must disconnect from the log stream individually.
v Multiple address spaces on one or more MVS systems may connect to a single log stream, but each one must issue IXGCONN individually to connect and then disconnect from the log stream. Each one receives a unique stream token; address spaces cannot share a stream token.
Note that a DASD-only log stream is single-system in scope. This means that only one system may connect to a DASD-only log stream, although there can be multiple connections from that one system.
For information about using the system logger services and the IXGCONN request, see z/OS MVS Programming: Assembler Services Guide which includes information about related macros IXGBRWSE, IXGDELET, IXGWRITE, IXGINVNT, and
IXGQUERY.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state with any PSW key.
Task
PASN=HASN, any SASN
31-bit or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts.
No locks may be held.
None.
© Copyright IBM Corp. 1988, 2017
593
IXGCONN macro
Programming requirements
v
The parameter list for this service must be addressable in the caller's primary address space.
v Include the IXGCON mapping macro in your program. This macro provides a list of equate symbols for the system logger services.
v Include mapping macro IXGANSAA in your program. This macro shows the format of the answer area output returned for each system logger service in the
ANSAREA parameter.
v If you use IXGCONN REQUEST=CONNECT,...,MF=(E,parmlist,NOCHECK) with either the STREAMTOKEN=xxxx or the USERDATA=yyyy keyword, the following procedure must be followed. When the processing is complete, move the STREAMTOKEN or USERDATA values from the parameter list specified on
MF= to your own storage.
v Each task that issues IXGCONN REQUEST=CONNECT to connect to a log stream must later issue IXGCONN REQUEST=DISCONNECT to disconnect from the log stream. When a task disconnects from the log stream, the stream token that identified the connection expires. Any requests that use the stream token after the disconnect are rejected with reason code X'82D'.
v If a task that issued the IXGCONN REQUEST=CONNECT request ends before issuing a disconnect request, system logger automatically disconnects the task from the log stream. This means that the unique log stream connection identifier, or the STREAMTOKEN, is no longer valid. The application receives an expired log stream token error response with reason code X'82D', if this application continues to use the same STREAMTOKEN after the task has been disconnected on subsequent logger service requests.
v
Any job step task (JST) terminates within the address space that has a connection to the log stream. System logger treats any job step task termination in a manner similar to an address space termination. That is, all log stream connections are disconnected and logger associations are terminated with the address space.
If this condition occurs and there remains an expected use of a log stream, then a new log stream connection will be required.
Restrictions
v All storage areas specified in this service must be in the same storage key as the caller's storage key and must exist in the caller's primary address space.
v
The caller cannot have an EUT FRR established.
v If the System Authorization Facility (SAF) is available, the system performs SAF authorization checks on all IXGCONN REQUEST=CONNECT requests in order to protect the integrity of data in a log stream.
To connect successfully to a log stream, the caller must have SAF authorization that matches the authorization required for the log stream:
– To connect to a log stream with an authorization level of READ, the caller must have read access to RESOURCE(log_stream_name) in SAF class
CLASS(LOGSTRM).
– To connect to a log stream with an authorization level of WRITE, the caller must have alter access to RESOURCE(log_stream_name) in SAF class
CLASS(LOGSTRM).
If SAF is not available or if CLASS(LOGSTRM) is not defined to SAF, no security checking is performed. In that case, the caller is connected to the log stream with the requested or default AUTH parameter value.
594
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
name
IXGCONN macro
v There is more than one version of this macro available. The parameters you can use depend on the version you specify on the PLISTVER parameter. See the description of the PLISTVER parameter for more information.
Input register information
Before issuing the IXGCONN macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0
2-13
Reason code, if register 15 contains a non-zero return code
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as a work register by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
Some messages and WTORs can be issued to delay or fail the IXGCONN Request.
These messages and WTORs are issued when Logger is waiting for other system services. The following messages may need to be replied to, or other action taken: v IXG054A - LOGR CDS not yet made available for Logger's use v IXG254I - SMS is not yet active v IXG115A - Log stream recovery not making progress trying to move recovered log data to secondary (offload) data sets.
See the topic on IXG Messages in z/OS MVS System Messages, Vol 10 (IXC-IZP) for more information about IXG messages.
Syntax
The standard form of the IXGCONN macro is written as follows:
Description
name: symbol. Begin name in column 1.
Chapter 68. IXGCONN — Connect/disconnect to log stream
595
IXGCONN macro
Syntax
⌂
IXGCONN
⌂
REQUEST=CONNECT
REQUEST=DISCONNECT
,STREAMNAME=streamname
,STREAMTOKEN=streamtoken
,ANSAREA=ansarea
,ANSLEN=anslen
,AUTH=READ
,AUTH=WRITE
,STRUCTNAME=structname
,AVGBUFSIZE=avgbufsize
,MAXBUFSIZE=maxbufsize
,ELEMENTSIZE=elementsize
,LSVERSION=lsversion
,USERDATA=userdata
,IMPORTCONNECT=NO
,IMPORTCONNECT=YES
,DIAG=NO_DIAG
,DIAG=NO
596
z/OS MVS Assembler Services Reference IAR-XCT
Description
One or more blanks must precede IXGCONN.
One or more blanks must follow IXGCONN.
Valid parameters (Required parameters are underlined.)
All parameters are valid.
STREAMTOKEN, ANSAREA, ANSLEN,
USERDATA, RETCODE, RSNCODE, MF
streamname: RS-type address or register (2) - (12).
streamtoken: RS-type address or register (2) - (12).
ansarea: RS-type address or register (2) - (12).
anslen: RS-type address or register (2) - (12).
Default
: AUTH=READ
structname: RS-type address or register (2) - (12).
avgbufsize: RS-type address or register (2) - (12).
maxbufsize: RS-type address or register (2) - (12).
elementsize: RS-type address or register (2) - (12).
lsversion: RS-type address or register (2) - (12).
userdata: RS-type address or register (2) - (12).
Default
: IMPORTCONNECT=NO
Default
: DIAG=NO_DIAG
IXGCONN macro
Syntax
,DIAG=YES
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=1
,PLISTVER=2
,RETCODE=retcode
,RSNCODE=rsncode
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Description
Default
: IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: MF=S
Parameters
The parameters are explained as follows:
REQUEST=CONNECT
REQUEST=DISCONNECT
Input parameter specifying whether the program is connecting to or disconnecting from the specified log stream.
When you specify CONNECT, all parameters are valid. Keywords required with connect are: STREAMNAME, STREAMTOKEN, ANSAREA, and
ANSLEN.
When you specify DISCONNECT, the following parameters are valid (required parameters are underlined): STREAMTOKEN, ANSAREA, ANSLEN,
USERDATA, RETCODE, RSNCODE, and MF.
,STREAMNAME=streamname
Specifies the 26-byte field (or register) containing the name of the log stream to which a program is connecting. You must use the name you defined for the log stream in the LOGR policy, see the IXGINVNT macro for information on the syntax of log stream names in the LOGR policy.
,STREAMTOKEN=streamtoken
Specifies the 16-byte token uniquely identifying the program's connection to the log stream.
Chapter 68. IXGCONN — Connect/disconnect to log stream
597
IXGCONN macro
When specified with REQUEST=CONNECT, STREAMTOKEN is an output parameter where IXGCONN places the log stream token when the macro completes successfully.
When specified with REQUEST=DISCONNECT or other logger services,
STREAMTOKEN is an input parameter where you specify the log stream token returned at connection.
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,AUTH=READ
,AUTH=WRITE
Specifies whether the caller has write or read access to the specified log stream.
If you specify AUTH=READ when connecting to a log stream, the program must also have read access authority to SAF resource(logstream_name) in
CLASS(LOGSTRM) for the specified log stream. You can then issue only the
IXGBRWSE and IXGQUERY requests against the log stream.
If you specify AUTH=WRITE when connecting to a log stream, the program must also have write access authority to SAF resource(logstream_name) in
CLASS(LOGSTRM) for the specified log stream. You can then issue any system logger request against the log stream.
,STRUCTNAME=structname
Specifies the name or address (using a register) of a 16-byte output field where
IXGCONN REQUEST=CONNECT will return the name of the coupling facility structure that the log stream is connected to. The name comes from the LOGR policy.
If you are connecting to a DASD-only log stream, this field will contain binary zeros. In addition, flag Ansaa_DasdOnlyLogStream in macro IXGANSAA will be set on for a DASD-only log stream.
,MAXBUFSIZE=maxbufsize
Specifies the name or address (using a register) of a 4-byte output field where
IXGCONN returns the size, in bytes, of the largest log block that can be written to this log stream.
MAXBUFSIZE is defined in the LOGR policy.
,AVGBUFSIZE=avgbufsize
Specifies the name or address (using a register) of a 4-byte output field where
IXGCONN returns the average size, in bytes, of individual log blocks that can be written to the coupling facility structure associated with this log stream.
AVGBUFSIZE is defined in the LOGR policy.
v
If you are using a LOGR couple data set for a coupling facility log stream, this value shows the initial setting used to determine the element-to-entry ratio. system logger monitors structure usage and adjusts the average buffer
598
z/OS MVS Assembler Services Reference IAR-XCT
IXGCONN macro
size dynamically, but the AVGBUFSIZE value returned by IXGCONN will always reflect the original setting rather than the actual value in use by system logger at any given time.
v If you are connecting to a DASD-only log stream, this field will contain binary zeros. In addition, flag Ansaa_DasdOnlyLogStream in macro
IXGANSAA will be set on for a DASD-only log stream.
,ELEMENTSIZE=elementsize
Specifies the name or address (using a register) of a 4-byte output field where
IXGCONN returns the size of the elements that system logger will break the log blocks into to write them to the coupling facility associated with this log stream.
If you are connecting to a DASD-only log stream, this field will contain binary zeros. In addition, flag Ansaa_DasdOnlyLogStream in macro IXGANSAA will be set on for a DASD-only log stream.
,LSVERSION=lsversion
Specifies the name or address (using a register) of a 64-bit output field where
IXGCONN returns the version of the log stream the program is connecting to.
The log stream version is a UTC timestamp that uniquely identifies the instance of the log stream definition. A program can use the log stream version to see if a log stream definition has been deleted and redefined since the last connect to a log stream.
For example, assume you connect to log stream LS1 and IXGCONN returns a log steam version of X'AA00000000000000', which the program saves. On a subsequent connection to log stream LS1, IXGCONN returns a different log stream version, which indicates that the definition for log stream LS1 in the
LOGR policy has been deleted and redefined since the last connection.
,USERDATA=userdata
Specifies a 64-byte input/output field containing a user data area.
When specified with REQUEST=CONNECT, USERDATA is an output parameter where IXGCONN returns the user data specified for this log stream.
When specified with REQUEST=DISCONNECT, USERDATA is an input parameter where you can specify or update the user data the user data for the specified log stream. You can only specify or change the user data for a log stream on a disconnect request.
,IMPORTCONNECT=NO
,IMPORTCONNECT=YES
Specifies whether the connection is for writing or importing log data to a log stream. You must specify AUTH=WRITE to use the IMPORTCONNECT parameter.
If you specify IMPORTCONNECT=YES, this connection will be used for importing data to a log stream. Importing log data means using the IXGIMPRT service to copy data from one log stream to another, maintaining the same log block identifier and UTC time stamp. IXGWRITE requests are not valid with
IMPORTCONNECT=YES. You can have only one IMPORTCONNECT=YES connection active for a log stream in the sysplex.
If you specify IMPORTCONNECT=NO, which is the default, the connect request is a write connection. In a write connection, only IXGWRITE requests can be issued against the log stream, IXGIMPRT requests will be rejected.
You can have multiple write connects to a log stream, provided there are no import connections. If you have a write connect established against a log
Chapter 68. IXGCONN — Connect/disconnect to log stream
599
IXGCONN macro
stream, a subsequent import connection will be rejected. You cannot, in other words, issue both IXGIMPRT and IXGWRITE requests against a single log stream.
,DIAG=NO_DIAG
,DIAG=NO
,DIAG=YES
Specifies whether Logger should provide additional diagnostics as specified on the logstream definition DIAG parameter. This indication is used over the span of this connectoin. Refer to the DIAG keyword on the IXGINVNT, IXGBRWSE, and IXGDELET macro services.
If you specify DIAG=NO_DIAG, which is the default, then Logger will not provide the additional diagnostics as specified on the logstream definition
DIAG parameter, unless another Logger service, for example, IXGBRWSE, specifically requests the additional diagnostics.
If you specify DIAG=NO, the Logger will not provide the additional diagnostics as specified on the logstream definition DIAG parameter, regardless of other Logger service specifications.
If you specify DIAG=YES, then Logger will provide additional diagnostics as specified on the logstream definition DIAG parameter, unless another Logger service, for example, IXGDELET, specifically requests not to provide the additional diagnostics.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=1
,PLISTVER=2
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 1 , which supports all parameters except those specifically referenced in higher versions.
v 2 , which supports both the following parameters and parameters from version 1:
– IMPORTCONNECT
– LSVERSION
To code
: specify in this input parameter one of the following: v IMPLIED_VERSION v MAX
600
z/OS MVS Assembler Services Reference IAR-XCT
IXGCONN macro
v A decimal value of 1 or 2
,RETCODE=retcode
Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to
Chapter 68. IXGCONN — Connect/disconnect to log stream
601
IXGCONN macro
force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When IXGCONN macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.
The IXGCON mapping macro provides equate symbols for the return and reason codes. The equate symbols associated with each hexadecimal return code are as follows:
00
04
IXGRETCODEOK - Service completes successfully.
IXGRETCODEWARNING - Service completes with a warning.
08
0C
IXGRETCODEERROR - Service does not complete.
IXGRETCODECOMPERROR - Service does not complete.
The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code.
Table 36. Return and reason codes for the IXGCONN macro
Return code
00
Reason code
xxxx0000
Meaning and zction
Equate symbol
: IxgRsnCodeOk
04 xxxx0404
Explanation
: Request processed successfully.
Equate symbol
: IxgRsnCodeDisconnectInProgress
Explanation
: Environment error. The disconnect request is being completed asynchronously. The application has been disconnected from the log stream and the stream token is no longer valid.
Action
: The log stream cannot be deleted until the asynchronous portion of the disconnect processing completes.
602
z/OS MVS Assembler Services Reference IAR-XCT
IXGCONN macro
Table 36. Return and reason codes for the IXGCONN macro (continued)
Return code
04
Reason code
xxxx0406
Meaning and zction
Equate symbol
: IxgRsnCodeConnectRebuild
04 xxxx0407
Explanation
: Environment error. The connect request was successful, but the log stream is temporarily unavailable because a coupling facility structure re-build is in progress.
Action
: Listen to the ENF signal 48, which will indicate either that the log stream is available because the re-build completed successfully or that the log stream is not available because the re-build failed. In the meantime, do not attempt to issue system logger services against the log stream.
Equate symbol
:
IxgRsnCodeConnPossibleLossOfData
04 xxxx0408
Explanation
: Environment error. The request was successful, but there may be log blocks permanently missing between this log block and the one previously returned. This condition occurs when a system or coupling facility fails and not all of the data in the log stream could be recovered.
Action
: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
Equate symbol
: IxgRsnCodeDsDirectoryFullWarning
Explanation
: Environment error. The request was successful, but the DASD data set directory for the log stream is now full. system logger cannot offload any further data to DASD. system logger will continue to process IXGWRITE requests only until the coupling facility structure space for this log stream is full.
Action
: Either delete data from the log stream to free up space in the data set directory or disconnect from the log stream.
Chapter 68. IXGCONN — Connect/disconnect to log stream
603
IXGCONN macro
Table 36. Return and reason codes for the IXGCONN macro (continued)
Return code
04
Reason code
xxxx0409
Meaning and zction
Equate symbol
: IxgRsnCodeWowWarning
08 xxxx0801
Explanation
: Environment error. The request was successful, but an error condition was detected during a previous offload of data. system logger might not be able to offload further data. system logger will continue to process IXGWRITE requests only until the interim storage for the log stream is filled. (Interim storage is the coupling facility for a coupling facility log stream and local storage buffers for a DASD-only log stream.)
Action
: Do not issue any further requests for this log stream and disconnect. Connect to another log stream. Check the system log for message IXG301I to determine the cause of the error. If you cannot fix the error, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM
Support Center.
Equate symbol
: IxgRsnCodeBadParmlist
08
08 xxxx0802 xxxx0806
Explanation
: Program error. The parameter list could not be accessed.
Action
: Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.
Equate symbol
: IxgRsnCodeXESError
Explanation
: System error. A severe cross-system extended services (XES) error has occurred.
Action
: See ANSAA_DIAG1 for the XES return code and ANSAA_DIAG2 for the XES reason code.
Equate symbol
: IxgRsnCodeBadStmToken
Explanation
: Program error. The stream token was not valid.
08
08 xxxx0808 xxxx080A
Action
: Make sure that the stream token specified is valid.
Equate symbol
: IxgRsnCodeEIOError
Explanation
: System error. A severe log data set I/O error has occurred.
Action
: Contact the IBM Support Center. Provide the return and reason code.
Equate symbol
: IxgRsnCodeRequestLocked
Explanation
: Program error. The program issuing the request is holding a lock.
Action
: Ensure that the program issuing the request is not holding a lock.
604
z/OS MVS Assembler Services Reference IAR-XCT
IXGCONN macro
Table 36. Return and reason codes for the IXGCONN macro (continued)
Return code
08
Reason code
xxxx080B
Meaning and zction
Equate symbol
: IxgRsnCodeNoStream
08 xxxx080C
Explanation
: Program error. The log stream name specified has not been defined in the LOGR policy.
Action
: Ensure that the required log stream name has been defined in the LOGR policy. If the definition appears to be correct, ensure that the application is passing the correct log stream name to the service.
Equate symbol
: IxgRsnCodeStagingAllocError
Explanation
: Environment error. The system encountered a severe dynamic allocation error with the staging data set. ANSAA_DIAG2 of the answer area contains either the dynamic allocation error code, SMS reason code, or media manager reason code. For more information about the error, check for either message IXG251I, which is issued for data set allocation errors, or check for messages issued by the access method.
08 xxxx080D
Action
: If the problem persists, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center.
Equate symbol
: IxgRsnCodeNoSAFAuth
Explanation
: Environment error. The user does not have correct SAF authorization for the request. The caller is not authorized to connect to the log stream or the caller specified AUTH=WRITE when connecting to a log stream with only READ authority.
Action
: IXGCONN returns information about the error in the answer area that is mapped by
IXGANSAA. Investigate the meaning of
ANSAA_Diag1, ANSAA_Diag2 and ANSAA_Diag4.
v ANSAA_Diag1 contains the RACF or installation exit return code from the RACROUTE
REQUEST=AUTH macro.
v ANSAA_Diag2 contains the RACF or installation exit reason code from the RACROUTE
REQUEST=AUTH macro.
v ANSAA_Diag4 contains the SAF return code from the RACROUTE REQUEST=AUTH macro.
See z/OS Security Server RACROUTE Macro Reference for information about the RACROUTE macro.
Define the required SAF authorization to allow the requestor to connect to the log stream. If authorization has already been defined, either change the authorization to allow UPDATE access to the log stream or change the application to
AUTH=READ.
Chapter 68. IXGCONN — Connect/disconnect to log stream
605
IXGCONN macro
Table 36. Return and reason codes for the IXGCONN macro (continued)
Return code
08
Reason code
xxxx0811
Meaning and zction
Equate symbol
: IxgRsnCodeBadStrname
08
08 xxxx0812 xxxx0813
Explanation
: Environment error. The structure name specified on the STRUCTNAME parameter is not defined in the CFRM policy.
Action
: Make sure that the structure you want to specify is defined in the CFRM policy.
Equate symbol
:
IxgRsnCodeLogStreamRecoveryFailed
Explanation
: Environment error. The log stream could not be recovered so the connection attempt failed. The system issues message IXG210E and/or
IXG211E along with message IXG231I providing further information about the error.
Action
: If the problem persists, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center.
Equate symbol
: IxgRsnCodeLogStreamDeleted
08
08
08 xxxx0814 xxxx0815 xxxx0816
Explanation
: Environment error. The request to connect to the specified log stream failed because the log stream is being deleted.
Action
: Re-define the log stream in the LOGR policy and then re-issue the connect request.
Equate symbol
: IxgRsnCodeNotAvailForIPL
Explanation
: Environment error. The system logger address space is not available for the remainder of this IPL. The system issues messages about this error during system logger initialization.
Action
: See the explanation for system messages issued during system logger initialization.
Equate symbol
: IxgRsnCodeNotEnabled
Explanation
: Program error. The program issuing the request is not enabled for I/O and external interrupts, so the request fails.
Action
: Make sure the program issuing the request is enabled for I/O and external interrupts.
Equate symbol
: IxgRsnCodeBadAnslen
Explanation
: Program error. The answer area length
(ANSLEN parameter) is not large enough. The system logger returned the required size in the
Ansaa_Preferred_Size field of the answer area, mapped by IXGANSAA macro.
Action
: Re-issue the request, specifying an answer area of the required size.
606
z/OS MVS Assembler Services Reference IAR-XCT
IXGCONN macro
Table 36. Return and reason codes for the IXGCONN macro (continued)
Return code
08
Reason code
xxxx0819
Meaning and zction
Equate symbol
: IxgRsnCodeSRBMode
08 xxxx081A
Explanation
: Program error. The calling program is in SRB mode, but task mode is the required dispatchable unit mode for this system logger service.
Action
: Make sure the calling program is in task mode.
Equate symbol
: IxgRsnCodeMaxStreamConn &
IXGINVNT requests
Explanation
: Environment error. This system has reached the limit for the maximum number of log streams that can be concurrently active. One of the following is true: v The limit of 16,384 concurrently active
DASDONLY log streams per system has been reached. For this case, the Answer Area field
DIAG1 will contain 16,384.
v Either the PRODUCTION or TEST GROUP cannot connect to any more log streams. Message
IXG075E or IXG076I is issued. In this case, the
Answer Area field DIAG1 will contain the number of structures that are in use for this GROUP.
v The TEST GROUP has previously failed and a request has been made to define a logstream with
GROUP(TEST). Message IXG074I has been previously issued. In this case, the Answer Area field DIAG1 will contain 0.
v A Log stream delete cannot be processed because logger needs to perform an internal connect to the
Log stream to complete the delete but no more connections are allowed.
08
08 xxxx081B xxxx081D
Action
: Your workload need to be planned to either consolidate log streams or balance system activity such that fewer log streams are needed during this time frame.
Equate symbol
: IxgRsnCodePrimaryNotHome
Explanation
: Program error. The primary address space does not equal the home address space.
Action
: Make sure that the primary address space equals the home address space when issuing this system logger service.
Equate symbol
: IxgRsnCodeRMNameBadState
Explanation
: Program error. The calling program cannot issue IXGCONN with the RMNAME parameter unless it is in supervisor state and system key.
Action
: Make sure the calling program is in supervisor state.
Chapter 68. IXGCONN — Connect/disconnect to log stream
607
IXGCONN macro
Table 36. Return and reason codes for the IXGCONN macro (continued)
Return code
08
Reason code
xxxx081E
Meaning and zction
Equate symbol
: IxgRsnCodeXESStrNotAuth
08 xxxx081F
Explanation
: Environment Error. The system logger address space does not have access authority to the coupling facility structure associated with the log stream specified.
Action
: Make sure the system logger address space has SAF access to the structure.
Equate symbol
: IxgRsnCodeXcdsError
Explanation
: System error. system logger encountered an internal problem while processing the LOGR couple data set.
08 xxxx0820
Action
: Contact the IBM Support Center. Provide the return and reason code and the contents of the answer area (ANSAREA field).
Equate symbol
: IxgRsnCodeBadModelConn
Explanation
: Program error. The program issued an
IXGCONN request to connect to a log stream that was defined as a model in the LOGR policy. You cannot connect to a model log stream.
08
08
08 xxxx082D xxxx082E xxxx0831
Action
: Either change the definition of the specified structure so that it is not a model, or else request connection to a different log stream that is not a model.
Equate symbol
: IxgRsnCodeExpiredStmToken
Explanation
: Environment error. The stream token is no longer valid because the connector has been disconnected.
Action
: Connect to the log stream again before issuing any functional requests.
Equate symbol
: IxgRsnCodeNoLogrCDSAvail
Explanation
: Environment error. The request failed because no LOGR couple data set is available. The operator was prompted to either make a couple data set available or to indicate that the current request should be rejected. The operator specified that the current request should be rejected.
Action
: system logger services are unavailable for the remainder of this IPL.
Equate symbol
: IxgRsnCodeBadStreamName
Explanation
: Program error. The log stream name specified on the STREAMNAME parameter is not valid.
Action
: Issue the request again with a valid log stream name on the STREAMNAME parameter.
608
z/OS MVS Assembler Services Reference IAR-XCT
IXGCONN macro
Table 36. Return and reason codes for the IXGCONN macro (continued)
Return code
08
Reason code
xxxx083A
Meaning and zction
Equate symbol
: IxgRsnCodeRMNameNotAllowed
08 xxxx0843
Explanation
: Program error. The request specified the RMNAME parameter, but the log stream is not defined as having an associated resource manager.
Action
: Either define a resource manager for the log stream definition in the LOGR couple data set, or remove the RMNAME parameter from the request.
Equate symbol
: IxgRsnCodeXcdsReformat
08
08
08 xxxx084C xxxx084E xxxx084F
Explanation
: Program error. A couple data set record is not valid.
Action
: Format the system logger couple data set again.
Equate symbol
: IxgRsnCodeRMAlreadyConnected
Explanation
: Program error. The resource manager is trying to connect to a log stream that it is already connected to. Only one connection specifying
RMNAME can be active for a log stream.
Action
: Correct the program so that it does not try to reconnect to the log stream.
Equate symbol
:
IXGRSNCODESTRSACETOOSMALL
Explanation
: Environment error. Structure resources are not available to satisfy the request. All structure resources are allocated as system logger control resources. This condition occurs when the structure resources are consumed by the logstreams connections.
Action
: Increase the size of the structure in the
CFRM policy or use the SETXCF ALTER command to dynamically increase the size of the structure.
Equate symbol
:
IxgRsnCodeInvalidRMNameSpecified
Explanation
: Program error. The value for the
RMNAME parameter on the connect request does not match the name of the resource manager defined in the LOGR couple data set for the log stream.
Action
: Either correct the RMNAME value on the connect request or correct the resource manager name in the log stream definition in the LOGR couple data set.
Chapter 68. IXGCONN — Connect/disconnect to log stream
609
IXGCONN macro
Table 36. Return and reason codes for the IXGCONN macro (continued)
Return code
08
Reason code
xxxx0850
Meaning and zction
Equate symbol
: IXGRSNCODEBADVECTORLEN
08 xxxx0851
Explanation
: Environment error. The connect request was rejected. system logger was unable to locate a vector table in the hardware system area (HSA) that is large enough for the number of log streams associated with it.
Action
: Add storage to the vector storage table and/or retry the connect request later, when storage might be available.
Equate symbol
: IXGRSNCODEBADCFLEVEL
Explanation
: Environment error. The connect request was rejected. The operational level of the coupling facility is not sufficient to support logger functions.
08
08
08 xxxx0853 xxxx0861 xxxx0862
Action
: Ensure that the coupling facility operational level for logger structures is at the required level.
See z/OS MVS Setting Up a Sysplex.
Equate symbol
: IxgRsnCodeNoCF
Explanation
: Environment error. The connect request was rejected. system logger could not allocate coupling facility structure space because no suitable coupling facility was available.
Action
: Check accompanying message IXG206I for a list of the coupling facilities where space allocation was attempted and the reason why each attempt failed.
Equate symbol
: IxgRsnCodeRebuildInProgress
Explanation
: Environment error. No requests can be processed for this log stream because a coupling facility structure re-build is in progress for the structure associated with this log stream.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v The re-build failed and the log stream is not available.
Equate symbol
: IxgRsnCodeXESPurge
Explanation
: Environment error. An cross-system extended services (XES) request has been purged due to re-build processing.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v The re-build failed and the log stream is not available.
610
z/OS MVS Assembler Services Reference IAR-XCT
IXGCONN macro
Table 36. Return and reason codes for the IXGCONN macro (continued)
Return code
08
Reason code
xxxx0863
Meaning and zction
Equate symbol
: IXGRSNCODESTRUCTUREFAILED
08 xxxx0864
Explanation
: Environment error. Either the coupling facility structure associated with the log stream has failed or the coupling facility itself has failed.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v The re-build failed and the log stream is not available.
Equate symbol
: IXGRSNCODENOCONNECTIVITY
08
08 xxxx0866 xxxx0890
Explanation
: Environment error. No connectivity exists to the coupling facility associated with the log stream. The system logger will either attempt to re-build the log stream in another coupling facility or the log stream will be disconnected.
Action
: Listen for ENF signal 48 that will indicate one of the following: v
The log stream is available because the re-build completed successfully. Re-issue the request.
v The re-build failed and the log stream is not available.
v The log stream has been disconnected from this system.
If a re-build initiated because of a loss of connectivity previously failed, an ENF corresponding to this reason code might not be issued. Further action by the installation might be necessary to cause the change of the log stream status again. Check the log for messages IXG101I,
IXG107I and related rebuild messages for information on resolving any outstanding issues.
Equate symbol
: IXGRSNCODESTRUCTUREFULL
Explanation
: Environment error. The coupling facility structure space is full.
Action
: Listen to the ENF signal 48 which will indicate that space is available for the structure after data has been offloaded to DASD.
Equate symbol
:
IXGRSNCODEADDRSPACENOTAVAIL
Explanation
: System error. The system logger address space failed and is not available.
Action
: Do not issue system logger requests.
Chapter 68. IXGCONN — Connect/disconnect to log stream
611
IXGCONN macro
Table 36. Return and reason codes for the IXGCONN macro (continued)
Return code
08
Reason code
xxxx0891
Meaning and zction
Equate symbol
:
IXGRSNCODEADDRSPACEINITIALIZING
08 xxxx08B0
Explanation
: System error. The system logger address space is not available because it is IPLing.
Action
: Listen for ENF signal 48, which will indicate when the system logger address space is available.
Re-issue this request. You can also listen for ENF signal 48, which will indicate if the system logger address space will not be available for the life of the
IPL. In that case, do not issue system logger services.
Equate symbol
:
IXGRSNCODESTRUCTURENOTAVAIL
08 xxxx08D3
Explanation
: Environment error. The connect request failed. The structure associated with the log stream is temporarily unavailable because either a re-build is in progress, a structure dump is in progress, or connections to the structure are being prevented.
Action
: Listen for ENF signal 48, which indicates that a coupling facility is available, and then retry the connect.
Equate symbol
: IXGRsnCodeFuncNotSupported
Explanation
: Environment error. The connect request specified the RMNAME or IMPORTCONNECT parameter. The request failed because the active primary LOGR couple data set must be at the z/OS level to support these parameters.
Action
: Either retry the request without the
RMNAME or IMPORTCONNECT parameters or reformat the LOGR couple data set to the z/OS level.
612
z/OS MVS Assembler Services Reference IAR-XCT
IXGCONN macro
Table 36. Return and reason codes for the IXGCONN macro (continued)
Return code
08
Reason code
xxxx08D6
Meaning and zction
Equate symbol
: IXGRsnCodeConnTypeNotAllowed
Explanation
: Environment error. One of the following occurred: v The connect request specified
IMPORTCONNECT=YES, but there is already an active write connection (AUTH=WRITE
IMPORTCONNECT=NO) in the sysplex. You cannot have an import connection and a write connection to the same log stream.
v The connect request specified AUTH=WRITE
IMPORTCONNECT=NO, but there is already an active import connection
(IMPORTCONNECT=YES) for the log stream. You cannot have an import connection and a write connection to the same log stream.
You can only have one import connection to a log stream. You may have multiple write connections, as long as there is no import connection against a log stream.
08 xxxx08E2
Action
: Correct your program and retry the request.
Equate symbol
: IxgRsncodeDasdOnlyConnected
Explanation
: Environment error system logger rejected an attempt to connect to a DASD-only log stream because the log stream is already connected to by another log stream in the sysplex. Only one system at a time can connect to a DASD-only log stream.
Action
: Determine which system you want to have a connection to the log stream. If you need this connection, disconnect the first system connection to the log stream and retry this connect request.
Chapter 68. IXGCONN — Connect/disconnect to log stream
613
IXGCONN macro
Table 36. Return and reason codes for the IXGCONN macro (continued)
Return code
08
Reason code
000008E3
Meaning and zction
Equate symbol
: IxgRsnCodeLogstreamNotSupported
Explanation
: Environment error. An attempt to connect for the log stream is rejected on this system because the system release level does not support this type of log stream. For example, this system does not support DASD-only log streams, or a log stream attribute such as EHLQ or
DUPLEXMODE(DRXRC) cannot be processed on this system release level.
Action
: If you must connect to a DASD-only log stream, make sure you do one of the following: v Update the log stream definition in the LOGR policy to a coupling facility one by specifying a structure name on the definition.
v To issue a request for a log stream that has the
EHLQ attribute, you must be on a system that is at z/OS Version 1 Release 3 or higher.
0C xxxx0000
If you must connect to a log stream with the EHLQ attribute specified, make sure you connect from a system that is at z/OS Version 1 Release3 or higher.
If you must connect to a log stream with the
DUPLEXMODE(DRXRC) attribute specified, make sure you connect from a system that is at z/OS
Version 1 Release 7 or higher.
Equate symbol
: IxgRetCodeCompError
Explanation
: User or System error. One of the following occurred: v You issued the FORCE IXGLOGR,ARM command to terminate the system logger address space.
v system logger component error occurred.
Action
: If this reason code is not the result of forcing the system logger address space, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center. Provide the diagnostic data in the answer area (IXGANSAA) and any dumps or LOGREC entries from system logger.
Example 1
Issue IXGCONN REQUEST=CONNECT to connect to a log stream with write authority.
IXGCONN REQUEST=CONNECT,
STREAMNAME=STRMNAME,
STREAMTOKEN=TOKEN,
AUTH=WRITE,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
X
X
X
X
X
X
X
X
614
z/OS MVS Assembler Services Reference IAR-XCT
IXGCONN macro
STRMNAME
ANSLEN
TOKEN
ANSAREA
DC
DC
DS
DS
RETCODE DS
RSNCODE DS
F
F
CL26’LOG.STREAM.NAME’ stream name
A(L’ANSAREA) length of logger’s answer area
CL16
CL(ANSAA_LEN) returned stream token answer area for log requests return code from logger reason code from logger
DATAREA DSECT
IXGANSAA LIST=YES answer area
Example 2
Issue IXGCONN REQUEST=CONNECT using registers.
LA R6,STRMNAME
IXGCONN REQUEST=CONNECT,
STREAMNAME=(6),
STREAMTOKEN=TOKEN,
AUTH=WRITE,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE, load stream name into reg 6
STRMNAME
ANSLEN
TOKEN
ANSAREA
DC
DC
DS
DS
RETCODE DS
RSNCODE DS
R6
F
F
MF=S,
RETCODE=RETCODE
CL26’LOG.STREAM.NAME’ stream name
A(L’ANSAREA) length of logger’s answer area
CL16
CL(ANSAA_LEN) returned stream token answer area for log requests return code from logger reason code from logger
DATAREA DSECT
IXGANSAA LIST=YES
EQU 6 answer area set up register 6
X
X
X
X
X
X
X
X
Example 3
Issue IXGCONN REQUEST=CONNECT as an import connect. This means the connection may issue IXGIMPRT to import data to a log stream.
IXGCONN REQUEST=CONNECT,
STREAMNAME=ONAME,
STREAMTOKEN=OTOKEN,
AUTH=WRITE,
IMPORTCONNECT=YES,
ANSAREA=XANSAREA,
ANSLEN=XANSLEN,
RSNCODE=RSCODE
X
X
X
X
X
X
X
*
ONAME DS
STOKEN DS
XANSAREA DS
XANSLEN DC
CL26
CL16
CL(ANSAA_LEN)
A(ANSAA_LEN)
RSCODE DS F
DSECT ,
IXGANSAA ,
Output Stream name
Input Stream token
Logger answer area
Answer area length
Reason code
The answer area macro
Example 4
Issue IXGCONN REQUEST=DISCONNECT to disconnect from a log stream and associate some user data with the log stream.
IXGCONN REQUEST=DISCONNECT,
STREAMTOKEN=TOKEN,
USERDATA=USERDATA,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
X
X
X
X
X
X
X
Chapter 68. IXGCONN — Connect/disconnect to log stream
615
IXGCONN macro
USERDATA DC
ANSLEN DC
TOKEN DS
ANSAREA DS
RETCODE=RETCODE
CL64’SOME USER DATA’
A(L’ANSAREA)
CL16
RETCODE DS
RSNCODE DS
CL(ANSAA_LEN)
F
F
DATAREA DSECT
IXGANSAA LIST=YES user data to log with DISCONNECT length of logger’s answer area token returned from CONNECT answer area for log requests return code from logger reason code from logger answer area
616
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 69. IXGDELET — Deleting log data from a log stream
Description
Use the IXGDELET macro to delete log blocks from a log stream.
For information about using the system logger services and the system logger inventory, see z/OS MVS Programming: Assembler Services Guide, which includes information about related macros IXGCONN, IXGBRWSE, IXGWRITE, IXGINVNT, and IXGQUERY.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameter
:
Requirement
Problem state with any PSW key. The caller must be supervisor state with any system (0-7) PSW key to either invoke the service in SRB mode or use the
MODE=SYNCEXIT keyword.
Task
PASN=HASN, any SASN
31-bit or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts.
No locks held.
All control parameters must be in the primary address space with the following exceptions: v The ECB should be addressable from the home address space.
v All storage areas specified must be in the same storage key as the caller.
Programming requirements
v The current primary address space must be the same primary address space used at the time your program issued the IXGCONN request.
v
The parameter list for this service must be addressable in the caller's primary address space.
v The calling program must be connected to the log stream with write authority through the IXGCONN service.
v Include the IXGCON mapping macro in your program. This macro provides a list of equate symbols for the system logger services.
v Include mapping macro IXGANSAA in your program. This macro shows the format of the answer area output returned for each system logger service in the
ANSAREA parameter.
v If there are multiple connections to a log stream, each connected application must serialize delete requests so that a delete of log blocks does not occur, for example, in the middle of another application's browse session.
v When coding the MODE=SYNCECB and ECB parameters, you must ensure that:
– The virtual storage area specified for the ECB resides on a full word boundary.
© Copyright IBM Corp. 1988, 2017
617
IXGDELET macro
– You initialize the ECB field to zero.
– The ECB resides in either the common or home address space storage at the time the IXGDELET request is issued.
– The storage used for output parameters, such as ANSAREA and OBLOCKID, are accessible by both the IXGDELET invoker and the ECB waiter.
Restrictions
v All storage areas specified in this service must be in the same storage key as the caller's storage key and must exist in the caller's primary address space.
v There is more than one version of this macro available. The parameters you can use depend on the version you specify on the PLISTVER parameter. See the description of the PLISTVER parameter for more information.
Input register information
Before issuing the IXGDELET macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code, if register 15 contains a non-zero return code
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as a work register by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
618
z/OS MVS Assembler Services Reference IAR-XCT
⌂
⌂
Syntax
name
IXGDELET macro
Syntax
The standard form of the IXGDELET macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede
IXGDELET.
IXGDELET
,STREAMTOKEN=streamtoken
One or more blanks must follow
IXGDELET.
streamtoken: RS-type address or register
(2) - (12).
,BLOCKS=ALL
,BLOCKS=RANGE
,BLOCKID=blockid
,ANSAREA=ansarea
,ANSLEN=anslen
blockid: RS-type address or register (2) -
(12).
ansarea: RS-type address or register (2) -
(12).
anslen: RS-type address or register (2) -
(12).
Default
: FORCE=NO ,FORCE=NO
,FORCE=YES
,FORCEINFO=NO
,OBLOCKID=oblockid
Default
: FORCEINFO=NO
oblockid: RS-type address or register (2) -
(12).
Default
: MODE=SYNC MODE=SYNC
MODE=ASYNCNORESPONSE
MODE=SYNCECB
,ECB=ecb
,DIAG=NO_DIAG
ecb: RS-type address or register (2) - (12).
Default
: DIAG=NO_DIAG
Chapter 69. IXGDELET — Deleting log data from a log stream
619
IXGDELET macro
Syntax
,DIAG=NO
,DIAG=YES
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
,RETCODE=retcode
,RSNCODE=rsncode
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Description
Default
: IMPLIED_VERSION
retcode: RS-type address or register (2) -
(12).
rsncode: RS-type address or register (2) -
(12).
Default:
MF=S
Parameters
The parameters are explained as follows:
,STREAMTOKEN=streamtoken
Specifies the name or address (using a register) of a required 16-byte input field containing the token for the log stream that you want to search. The stream token is returned by the IXGCONN service at connection to the log stream.
,BLOCKS=ALL
,BLOCKS=RANGE
Specifies whether all or just a subset of log blocks in a log stream be deleted.
v BLOCKS=ALL: Specifies that all the log blocks in the specified log stream be deleted.
v BLOCKS=RANGE: Specifies that the range of log blocks, older than the block specified on the BLOCKID parameter, be deleted. The BLOCKID parameter is required with BLOCKS=RANGE, See z/OS MVS Programming:
Assembler Services Guide for more information on deleting a range of log blocks.
620
z/OS MVS Assembler Services Reference IAR-XCT
IXGDELET macro
,BLOCKID=blockid
Specifies the name or address (using a register) of a 8-byte input field which contains a log block identifier. BLOCKID is required with the
BLOCKS=RANGE parameter. All blocks in the log stream older than the block specified on BLOCKID will be deleted. Note that the block specified in
BLOCKID is not deleted.
Block identifiers are returned in the RETBLOCKID field of the IXGWRITE service.
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,FORCE=NO
,FORCE=YES
Specifies whether this delete request can be overridden by a resource manager exit.
If you specify FORCE=NO, which is the default, the delete request can be overridden by the resource manager exit.
If you specify FORCE=YES, the delete request cannot be overridden by a delete exit.
,OBLOCKID=oblockid
Specifies the name or address (using a register) of an 8 character output field where the resource manager places the override block identifier.
,MODE=SYNC
,MODE=ASYNCNORESPONSE
,MODE=SYNCECB
Specifies that the request should be processed in one of the following ways: v MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
v MODE=ASYNCNORESPONSE: Specifies that the request process asynchronously. The caller is not notified when the request completes and the answer area (ANSAREA) fields will not contain valid information.
To use this parameter, the system where the application is running must be
IPLed.
v MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB parameter is posted when the request completes. The ECB parameter is required with MODE=SYNCECB.
ECB=ecb
Specifies the name or address (using a register) of a 4-byte input field that contains an event control block (ECB) to be posted when the request completes.
Chapter 69. IXGDELET — Deleting log data from a log stream
621
IXGDELET macro
Before coding ECB, you must ensure that: v
You initialize the ECB.
v The ECB must reside in either common storage or the home address space where the IXGDELET request was issued.
v The virtual storage area specified for the ECB must reside on a fullword boundary.
,DIAG=NO_DIAG
,DIAG=NO
,DIAG=YES
Specifies whether or not the DIAG option on the IXGCONN for this logstream will be in effect for this delete log data request. Refer to the DIAG keyword on the IXGINVNT, IXGCONN and IXGBRWSE macro services.
If you specify DIAG=NO_DIAG, which is the default, then the DIAG option on the IXGCONN for this logstream will be in effect for this delete log data request.
If you specify DIAG=NO, then Logger will not take additional diagnostic action as defined on the logstream definition DIAG parameter.
If you specify DIAG=YES, then Logger will take additional diagnostic action as defined on the logstream definition DIAG parameter providing the IXGCONN connect DIAG specification allows it.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , supports all parameters except those specifically referenced in higher versions.
v 2 , supports both the following parameters and parameters from version 0:
– FORCE
– OBLOCKID
To code
: specify in this input parameter one of the following: v
IMPLIED_VERSION v MAX v A decimal value of 0 or 1
622
z/OS MVS Assembler Services Reference IAR-XCT
IXGDELET macro
,RETCODE=retcode
Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
Chapter 69. IXGDELET — Deleting log data from a log stream
623
IXGDELET macro
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When IXGDELET macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.
Note:
A program invoking the IXGDELET service may indicate through the
MODE parameter that requests which can not be completed synchronously should have control returned to the caller prior to the completion of the request. When the request does complete, the invoker will be notified and the return and reason codes are in the answer area mapped by IXGANSAA.
The IXGCON macro provides equate symbols for the return and reason codes. The equate symbols associated with each hexadecimal return code are as follows:
00
04
IXGRETCODEOK - Service completes successfully.
IXGRETCODEWARNING - Service completes with a warning.
08
0C
IXGRETCODEERROR - Service does not complete.
IXGRETCODECOMPERROR - Service does not complete.
The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code.
Table 37. Return and Reason Codes for the IXGDELET Macro
Return Code
00
Reason Code
xxxx0000
Meaning and Action
Equate Symbol
: IxgRsnCodeOk
04 xxxx0401
Explanation
: Request processed successfully.
Equate Symbol
: IxgRsnCodeProcessedAsynch
Explanation
: Program error. The program specified
MODE=SYNCECB and the request must be processed asynchronously.
Action
: Wait for the ECB specified on the ECB parameter to be posted, indicating that the request is complete. Check the ANSAA_ASYNCH_RETCODE and
ANSAA_ASYNCH_RSNCODE fields, mapped by
IXGANSAA, to determine whether the request completed successfully.
624
z/OS MVS Assembler Services Reference IAR-XCT
IXGDELET macro
Table 37. Return and Reason Codes for the IXGDELET Macro (continued)
Return Code
04
Reason Code
xxxx040B
Meaning and Action
Equate Symbol
: IxgRsnCodeRMNotConnected
04
04
04 xxxx040C xxxx040D xxxx040E
Explanation
: Program or environment error. The log stream is identified as being a source log stream managed by a resource manager (RMNAME is specified in the LOGR couple data set). However, at the time of the delete request, the resource manager was not connected to the log stream and FORCE=NO was specified on the request. Delete requests can only be honored on a resource manager managed system if the resource manager is connected to the log stream.
Action
: Either: v Start the resource manager so that it can connect to the log stream.
v Issue the IXGDELET request specifying FORCE=YES to delete the log block even though the resource manager is not connected to the source log stream.
Equate Symbol
: IxgRsnCodeRMOverrideOK
Explanation
: The caller's delete request was overridden by the associated resource manager. The override information was successfully processed.
Equate Symbol
: IxgRsnCodeRMNoBlock
Explanation
: Program error. The log block identifier on the
IXGDELET request does not exist in the log stream. Either the block id never existed or was deleted in a previous
IXGDELET request. This warning is issued only if a resource manager overrides the caller-specified block id.
Action
: Make sure that the block id specified on the
IXGDELET request is correct.
Equate Symbol
: IxgRsnCodeRMBadGap
Explanation
: Environment error. The IXGDELET request failed because the requested log data was unreadable. This problem is caused by either an I/O error while attempting to read a DASD log data set or a log data set was deleted using an interface other than IXGDELET. This reason code is issued only when a resource manager exit overrides the block identifier specified on the IXGDELET request.
Action
: System logger returns the block identifier of the first readable log block (in the direction of youngest data) in the ANSAA_GAPS_NEXT_BLKID field of the answer area mapped by IXGANSAA. If appropriate, reissue the
IXGDELET request using this block identifier.
Chapter 69. IXGDELET — Deleting log data from a log stream
625
IXGDELET macro
Table 37. Return and Reason Codes for the IXGDELET Macro (continued)
Return Code
04
Reason Code
xxxx040F
Meaning and Action
Equate Symbol
: IxgRsnCodeRMEOFGap
04
04
04 xxxx0410 xxxx0411 xxxx0412
Explanation
: Environment error. While processing the
IXGDELET request, system logger prematurely reached the end or beginning of the log stream. The portion of the log stream from the requested log data to either the beginning or end of the log stream was unreadable. This problem is caused by either an I/O error while attempting to read a
DASD log data set or a log data set was deleted using an interface other than IXGDELET. This reason code is issued only when a resource manager exit overrides the block identifier specified on the IXGDELET request.
Action
: The action you take depends on whether your application can tolerate any loss of data. You can either: v Accept the loss of data and continue processing this log stream.
v Stop using this log stream.
v Correct the problem and re-issue the request.
Equate Symbol
: IxgRsnCodeRMLossOfDataGap
Explanation
: Environment error. The log data you tried to delete is in a section of the log stream where data is permanently missing. This condition occurs when a system or coupling facility is in recovery from a failure and not all the log data could be recovered. This reason code is issued only when a resource manager exit overrides the block identifier specified on the IXGDELET request.
Action
: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. If your application can tolerate data loss, you can continue using the log stream.
Equate Symbol
: IxgRsnCodeRMAbended
Explanation
: Program error. The resource manager abended and percolated to the system logger recovery environment. The IXGDELET request was not processed.
Action
: Look for and correct the problem in your resource manager program or reissue the delete request, specifying
FORCE=YES.
Equate Symbol
: IxgRsnCodeRMDisabled
Explanation
: Environment error. The log stream is identified as being managed by a resource manager
(RMNAME is specified in the LOGR couple data set). The resource manager is connected to the log stream, but is disabled due to an abend from which it did not recover successfully (by percolating to system logger recovery environment).
Action
: Either: v Cancel the resource manager exit and then restart the resource manager address space.
v
Reissue the request, specifying FORCE=YES.
626
z/OS MVS Assembler Services Reference IAR-XCT
IXGDELET macro
Table 37. Return and Reason Codes for the IXGDELET Macro (continued)
Return Code
04
Reason Code
xxxx0414
Meaning and Action
Equate Symbol
: IxgRsnCodeRMStoppedDelete
08
08
08
08 xxxx0801 xxxx0802 xxxx0804 xxxx0806
Explanation
: The resource manager does not allow this
IXGDELET request to delete any log blocks.
Action
: Determine why the resource manager is prohibiting deletes. Specify FORCE=YES to stop the resource manager exit from stopping the delete request.
Equate Symbol
: IxgRsnCodeBadParmlist
Explanation
: Program error. The parameter list could not be accessed.
Action
: Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.
Equate Symbol
: IxgRsnCodeXESError
Explanation
: System error. A severe cross-system extended services (XES) error has occurred.
Action
: See ANSAA_DIAG1 for the XES return code and
ANSAA_DIAG2 for the XES reason code.
Equate Symbol
: IxgRsnCodeNoBlock
Explanation
: Program error. The block identifier or time stamp does not exist in the log stream. Either the value provided was never a valid location within the log stream or a prior IXGDELET request deleted the portion of the log stream it referenced.
Action
: Ensure that the value provided references an existing portion of the log stream and issue the request again. Use the LIST LOGSTREAM DETAIL(YES) request on the IXCMIPU utility to display the range of valid block identifiers for the log stream.
Equate Symbol
: IxgRsnCodeBadStmToken
Explanation
: Program error. One of the following occurred: v The stream token was not valid.
v The specified request was issued from an address space other than the connector's address space.
08 xxxx080A
Action
: Do one of the following: v Make sure that the stream token specified is valid.
v Ensure the request was issued from the connector's address space.
Equate Symbol
: IxgRsnCodeRequestLocked
Explanation
: Program error. The program issuing the request is holding a lock.
Action
: Ensure that the program issuing the request is not holding a lock.
Chapter 69. IXGDELET — Deleting log data from a log stream
627
IXGDELET macro
Table 37. Return and Reason Codes for the IXGDELET Macro (continued)
Return Code
08
Reason Code
xxxx0814
Meaning and Action
Equate Symbol
: IxgRsnCodeNotAvailForIPL
08
08
08
08
08 xxxx0815 xxxx0816 xxxx0817 xxxx081C xxxx081F
Explanation
: Environment error. The system logger address space is not available for the remainder of this IPL. The system issues messages about this error during system logger initialization.
Action
: See the explanation for system messages issued during system logger initialization.
Equate Symbol
: IxgRsnCodeNotEnabled
Explanation
: Program error. The program issuing the request is not enabled for I/O and external interrupts, so the request fails.
Action
: Make sure the program issuing the request is enabled for I/O and external interrupts.
Equate Symbol
: IxgRsnCodeBadAnslen
Explanation
: Program error. The answer area length
(ANSLEN parameter) is not large enough. The system logger returned the required size in the
Ansaa_Preferred_Size field of the answer area, mapped by
IXGANSAA macro.
Action
: Re-issue the request, specifying an answer area of the required size.
Equate Symbol
: IxgRsnCodeBadAnsarea
Explanation
: Program error. The storage area specified on the ANSAREA parameter cannot be accessed. This may occur after the system logger address space has terminated.
Action
: Specify storage that is in the caller's primary address space and in the same key as the calling program at the time the system logger service was issued. This storage must be accessible until the request completes.
Equate Symbol
: IxgRsnCodeNotAuthFunc
Explanation
: Program error. The program connected to the log stream with the AUTH=READ parameter and then tried to delete or write data. You cannot write or delete data when connected with read authority.
Action
: Issue the IXGCONN service with AUTH=WRITE authority and then re-issue this request.
Equate Symbol
: IxgRsnCodeXcdsError
Explanation
: System error. System logger encountered an internal problem while processing the LOGR couple data set.
08 xxxx082D
Action
: Contact the IBM Support Center. Provide the return and reason code and the contents of the answer area
(ANSAREA field).
Equate Symbol
: IxgRsnCodeExpiredStmToken
Explanation
: Environment error. The stream token is no longer valid because the connector has been disconnected.
Action
: Connect to the log stream again before issuing any functional requests.
628
z/OS MVS Assembler Services Reference IAR-XCT
IXGDELET macro
Table 37. Return and Reason Codes for the IXGDELET Macro (continued)
Return Code
08
Reason Code
xxxx0836
Meaning and Action
Equate Symbol
: IxgRsnCodeBadGap
08
08
08 xxxx083D xxxx084A xxxx084B
Explanation
: Environment error. The request failed because the requested log data was unreadable. This condition could be caused by either an I/O error while attempting to read a log data set or a log data set deleted without using the IXGDELET interface.
Action
: The block identifier of the first accessible block toward the youngest data in the log stream is returned in the ANSAA_GAPS_NEXT_BLKID field in the answer area mapped by the IXGANSAA macro. If appropriate, re-issue the IXGDELET request using this block identifier.
Equate Symbol
: IxgRsnCodeBadECBStor
Explanation
: Program error. The ECB storage area was not accessible to the system logger.
Action
: Ensure that the storage area is accessible to the system logger for the duration of the request. The storage must be addressable in the caller's home address space and in the same key as the caller.
Equate Symbol
: IxgRsnCodeEOFGap
Explanation
: Environment error. The request prematurely reached the beginning or the end of the log stream. The portion of the log stream from the requested log data to either the beginning or the end of the log stream
(depending on the direction of the read) was unreadable.
This condition may be caused by either an I/O error while trying to read a log data set, or a log data set deleted without using the IXGDELET interface.
Action
: The action necessary is completely up to the application depending on how critical your data is. You can do one of the following: v Accept this condition and continue reading.
v Stop processing the log all together.
v Attempt to get the problem rectified, if possible, and then try to re-issue the request.
Equate Symbol
: IxgRsnCodeLossOfDataGap
Explanation
: Environment error. The requested log data referenced a section of the log stream where log data is permanently missing. This condition occurs when a system or coupling facility is in recovery due to a failure, but not all of the log data in the log stream could be recovered.
Action
: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
Chapter 69. IXGDELET — Deleting log data from a log stream
629
IXGDELET macro
Table 37. Return and Reason Codes for the IXGDELET Macro (continued)
Return Code
08
Reason Code
xxxx0861
Meaning and Action
Equate Symbol
: IxgRsnCodeRebuildInProgress
08
08
08 xxxx0862 xxxx0863 xxxx0864
Explanation
: Environment error. No requests can be processed for this log stream because a coupling facility structure re-build is in progress for the structure associated with this log stream.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v
The re-build failed and the log stream is not available.
Equate Symbol
: IxgRsnCodeXESPurge
Explanation
: Environment error. An cross-system extended services (XES) request has been purged due to re-build processing.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v
The re-build failed and the log stream is not available.
Equate Symbol
: IxgRsnCodeStructureFailed
Explanation
: Environment error. Either the coupling facility structure associated with the log stream has failed or the coupling facility itself has failed.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v
The re-build failed and the log stream is not available.
Equate Symbol
: IxgRsnCodeNoConnectivity
Explanation
: Environment error. No connectivity exists to the coupling facility associated with the log stream. The system logger will either attempt to re-build the log stream in another coupling facility or the log stream will be disconnected.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v The re-build failed and the log stream is not available.
v The log stream has been disconnected from this system.
If a re-build initiated because of a loss of connectivity previously failed, an ENF corresponding to this reason code might not be issued. Further action by the installation might be necessary to cause the change of the log stream status again. Check the log for messages IXG101I, IXG107I and related rebuild messages for information on resolving any outstanding issues.
630
z/OS MVS Assembler Services Reference IAR-XCT
IXGDELET macro
Table 37. Return and Reason Codes for the IXGDELET Macro (continued)
Return Code
08
Reason Code
xxxx0890
Meaning and Action
Equate Symbol
: IxgRsnCodeAddrSpaceNotAvail
08
08
08
08
08 xxxx0891 xxxx08D0 xxxx08D1 xxxx08D2 xxxx085F
Explanation
: System error. The system logger address space failed and is not available.
Action
: Do not issue system logger requests.
Equate Symbol
: IxgRsnCodeAddrSpaceInitializing
Explanation
: System error. The system logger address space is not available because it is IPLing.
Action
: Listen for ENF signal 48, which will indicate when the system logger address space is available. Re-connect to the log stream, then re-issue this request. You can also listen for ENF signal 48, which will indicate if the system logger address space will not be available for the life of the
IPL. In that case, do not issue system logger services.
Equate Symbol
: IxgRsnCodeProblemState
Explanation
: Environment error. The request was rejected because of one of the following: v The request was issued in SRB mode while the requestor was in problem program state.
v The SYNCEXIT parameter was specified while the requestor's PSW key was in problem program key.
Action
: Change the invoking environment to supervisor state.
Equate Symbol
: IxgRsnCodeProgramKey
Explanation
: Environment error. The request was rejected because of one of the following: v The request was issued in SRB mode while the requestor was in problem program key (key 8-F).
v The SYNCEXIT parameter was specified while the requestor's PSW key was in problem program key.
Action
: Change the invoking environment to a system key
(key 0-7).
Equate Symbol
: IxgRsnCodeNoCompleteExit
Explanation
: Program error. MODE=SYNCEXIT was specified, but the connection request did not identify a complete exit.
Action
: Either change this request to a different MODE option, or reconnect to the log stream with a complete exit specified on the COMPLETEXIT parameter.
Equate Symbol
: IxgRsnPercToRequestor
Explanation
: Environment error. Percolation to the service requestor's task occurred because of an abend during system logger processing. Retry was not allowed.
Action
: Issue the request again. If the problem persists, contact the IBM Support Center.
Chapter 69. IXGDELET — Deleting log data from a log stream
631
IXGDELET macro
Table 37. Return and Reason Codes for the IXGDELET Macro (continued)
Return Code
0C
Reason Code
xxxx0000
Meaning and Action
Equate Symbol
: IxgRetCodeCompError
Explanation
: User or System error. One of the following occurred: v You issued the FORCE IXGLOGR,ARM command to terminate the system logger address space.
v
System logger component error occurred.
Action
: If this reason code is not the result of forcing the system logger address space, search problem reporting data bases for a fix for the problem. If no fix exists, contact the
IBM Support Center. Provide the diagnostic data in the answer area (IXGANSAA) and any dumps or LOGREC entries from system logger.
Examples
Example 1
Delete all data from the log stream.
IXGDELET STREAMTOKEN=TOKEN,
BLOCKS=ALL,
MODE=SYNC,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
ANSLEN
TOKEN
DC
DS
ANSAREA DS
RETCODE DS
A(L’ANSAREA)
CL16
CL(ANSAA_LEN)
F
F RSNCODE DS
DATAREA DSECT
IXGANSAA LIST=YES length of logger’s answer area stream token from connect answer area for log requests return code reason code answer area
Example 2
Delete a range of data from the log stream asynchronously, if synchronous processing is not possible.
IXGDELET STREAMTOKEN=TOKEN,
BLOCKS=RANGE,
BLOCKID=BLOCKID,
MODE=SYNCECB,
ECB=ANECB,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
*++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* If rsncode = ’00000401’X then wait on
* the ecb ANECB.
*++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ANSLEN DC
BLOCKID DS
TOKEN DS
ANSAREA DS
ANECB DS
RETCODE DS
A(L’ANSAREA)
CL8
CL16
CL(ANSAA_LEN)
F
F length of logger’s answer area block id from which to delete stream token from connect answer area for log requests ecb on which to wait return code
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
632
z/OS MVS Assembler Services Reference IAR-XCT
IXGDELET macro
RSNCODE DS
DATAREA DSECT
F
IXGANSAA LIST=YES
Example 3
reason code answer area
Delete all data from the log stream using registers with the macro.
LA R6,TOKEN
IXGDELET STREAMTOKEN=(6),
BLOCKS=ALL,
MODE=SYNC,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
ANSLEN DC
TOKEN DS
ANSAREA DS
RETCODE DS
RETCODE=RETCODE
A(L’ANSAREA)
CL16
CL(ANSAA_LEN)
RSNCODE DS
DATAREA DSECT
R6
F
F
IXGANSAA LIST=YES
EQU 6 load stream token into register 6 length of logger’s answer area stream token from connect answer area for log requests return code reason code answer area
X
X
X
X
X
X
X
Chapter 69. IXGDELET — Deleting log data from a log stream
633
IXGDELET macro
634
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 70. IXGIMPRT — Import log blocks
Description
The IXGIMPRT macro allows a program to import a copy of a log block from one log stream to another, specifying a log block identifier and time stamp to be assigned to the log block.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state. Any PSW key
Task
PASN=HASN, any SASN
31-bit 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks may be held.
None.
Programming requirements
v
Before issuing this request, the caller must have a valid connection to the log stream. The connection must be issued with AUTH=WRITE and
IMPORTCONNECT=YES parameters specified.
v The parameter list for this service must be addressable in the caller's primary address space.
v Include the IXGCON mapping macro in your program. This macro provides a list of equate symbols for the system logger services.
v Include mapping macro IXGANSAA in your program. This macro shows the format of the answer area output returned for each system logger service in the
ANSAREA parameter.
v Although the data pointed to by the BUFFER64 keyword may be above the bar
(2-gigabyte), the length of the name or address of the input field specified in the
BUFFLEN keyword is still limited to 4 bytes.
Restrictions
All storage areas specified must be in the same storage key as the caller. Storage areas that are not ALET qualified must exist in the caller's primary address space.
You can call any of the system logger services in AMODE 64, but the parameter list and all other data addresses, with the excption of BUFFER64 must reside in
31-bit storage.
Input register information
Before issuing the IXGIMPRT macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
© Copyright IBM Corp. 1988, 2017
635
IXGIMPRT macro
Syntax
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Reason code, if register 15 contains a non-zero return code
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as a work register by the system
Unchanged
14-15
Used as a work register by the system
When control returns to a caller running in AMODE 64, the 64–bit registers contain:
Register
Contents
0-1
Used as a work register by the system, if the caller specified BUFFER64.
Otherwise, unchanged.
2-13
14
15
Unchanged
Unchanged
Used as a work register by the system.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The IXGIMPRT macro is written as follows:
Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede IXGIMPRT.
IXGIMPRT
636
z/OS MVS Assembler Services Reference IAR-XCT
IXGIMPRT macro
Syntax Description
�
STREAMTOKEN=streamtoken
,BUFFER=buffer
BUFFER64=buffer64
,BLOCKLEN=blocklen
One or more blanks must follow IXGIMPRT.
streamtoken: RS-type address or address in register (2) - (12).
buffer: RS-type address or address in register (2) - (12).
buffer64: RS-type address or register (2) - (12).
blocklen: RS-type address or address in register (2) - (12).
,BLOCKID=blockid blockid: RS-type address or address in register (2) - (12).
,GMT_TIMESTAMP=gmt_timestamp
gmt_timestamp: RS-type address or address in register (2) - (12).
,LOCALTIME=localtime localtime: RS-type address or address in register (2) - (12).
,ANSAREA=ansarea
,ANSLEN=anslen
,BUFFALET=buffalet
,BUFFALET=0,
ansarea: RS-type address or address in register (2) - (12).
anslen: RS-type address or address in register (2) - (12).
buffalet: RS-type address or address in register (2) - (12).
Default
: BUFFALET=0,
,RETCODE=retcode
,RSNCODE=rsncode
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
Default
: PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
Default
: MF=S
list addr: RS-type address or register (1) - (12).
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Chapter 70. IXGIMPRT — Import log blocks
637
IXGIMPRT macro
Syntax Description
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IXGIMPRT macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
STREAMTOKEN=streamtoken
A required input parameter that specifies the log stream token that was returned by the IXGCONN service.
To code
: Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,BUFFER=buffer
,BUFFER64=buffer64
Required input parameter that specifies the buffer from which the log stream block is to be written.
v BUFFER=buffer specifies that the location of the buffer is in 31-bit storage.
v BUFFER64=buffer64 specifies that the location of the buffer is in 64-bit storage.
The BUFFER and BUFFER64 parameters are mutually exclusive.
The buffer can be ALET qualified. If a buffer is ALET qualified, the ALET must index a valid entry on the task's dispatchable unit access list (DUAL).
To code
: Specify the RS-type address, or address in register (2)-(12), of a character field.
,BLOCKLEN=blocklen
A required input parameter that specifies the length of the log block to be written. The maximum block length is 65,536.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
,BLOCKID=blockid
A required input parameter that specifies the block id to be assigned to the log block being written. The block identifier specified must be greater than any previous block identifier in the log stream.
To code
: Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,GMT_TIMESTAMP=gmt_timestamp
A required input parameter that specifies the 8-byte UTC time stamp to be associated with the log block being written. The timestamp specified must be greater than any previous timestamp in the log stream. The timestamp must be in STCK format.
To code
: Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
638
z/OS MVS Assembler Services Reference IAR-XCT
IXGIMPRT macro
,LOCALTIME=localtime
A required input parameter that specifies the 8-byte local time stamp to be associated with the log block being imported. The timestamp must be in STCK format.
To code
: Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,ANSAREA=ansarea
A required output parameter of a virtual storage area, called the answer area, in which service response information will be placed. The format of the answer area is described by the IXGANSAA mapping macro.
To code
: Specify the RS-type address, or address in register (2)-(12), of a field.
,ANSLEN=anslen
A required input parameter that specifies the answer area length. The length of the answer area must be at least as large as the length of IXGANSAA.
To code
: Specify the RS-type address, or address in register (2)-(12), of a fullword field.
,BUFFALET=buffalet
,BUFFALET=0,
An optional input parameter that specifies the ALET to be used to access the storage specified by the BUFFER or BUFFER64 keyword. The default is 0, which means that the buffer resides in the caller's primary address space.
To code
: Specify the RS-type address, or address in register (2)-(12), of a fullword field.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code
: Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code
: Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are
Chapter 70. IXGIMPRT — Import log blocks
639
IXGIMPRT macro
assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0
, supports all parameters except those specifically referenced in higher versions.
To code
: Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to
640
z/OS MVS Assembler Services Reference IAR-XCT
IXGIMPRT macro
force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
Abend 1C5 Ixg_Abend_Code - See z/OS MVS System Codes for more information on this abend.
Return and reason codes
When the IXGIMPRT macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded
RSNCODE) contains reason code.
The IXGCON mapping macro provides equate symbols for the return and reason codes. The equate symbols associated with each hexadecimal return code are as follows:
00
04
IXGRETCODEOK - Service completes successfully.
IXGRETCODEWARNING - Service completes with a warning.
08
0C
IXGRETCODEERROR - Service does not complete.
IXGRETCODECOMPERROR - Service does not complete. A system logger component error has been encountered.
The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code.
Table 38. Return and Reason Codes for the IXGIMPRT Macro
Return Code
00
Reason Code
xxxx0000
Meaning and Action
IxgRsnCodeOk -
Explanation
: Request processed successfully.
Chapter 70. IXGIMPRT — Import log blocks
641
IXGIMPRT macro
Table 38. Return and Reason Codes for the IXGIMPRT Macro (continued)
Return Code
04
Reason Code
xxxx0405
Meaning and Action
IxgRsnCodeWarningLossOfData -
Explanation
: Environment error. Returned for
READCURSOR, START OLDEST and RESET OLDEST requests. This condition occurs when a system and coupling facility fail and not all of the log data in the log stream could be recovered.
v For READCURSOR: A log block has been returned, but there may be log blocks permanently missing between this log block and the one previously returned.
v For START OLDEST and RESET OLDEST: The oldest log blocks in the log stream may be permanently missing, the browse cursor is set at the oldest available log block.
04
04
04 xxxx0407 xxxx0408 xxxx0409
Action
: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
IxgRsnCodeConnPossibleLossOfData -
Explanation
: Environment error. The request was successful, but there may be log blocks permanently in the log stream. This condition occurs when a system or coupling facility fails and not all of the data in the log stream could be recovered.
Action
: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
IxgRsnCodeDsDirectoryFullWarning -
Explanation
: Environment error. The request was successful, but the log stream's DASD data set directory is full. System logger cannot offload any further data from the coupling facility structure to DASD. The system logger will continue to process IXGIMPRT requests until this log streams portion of the coupling facility structure becomes full.
Action
: Either delete enough data from the log stream to free up space in the log streams data set directory so that offloading can occur or disconnect from the log stream.
Equate Symbol
: IxgRsnCodeWowWarning
Explanation
: Environment error. The request was successful, but an error condition was detected during a previous offload of data. System logger might not be able to offload further data. System logger will continue to process IXGWRITE requests only until the interim storage for the log stream is filled. (Interim storage is the coupling facility for a coupling facility log stream and local storage buffers for a DASD-only log stream.)
Action
: Do not issue any further requests for this log stream and disconnect. Connect to another log stream.
Check the system log for message IXG301I to determine the cause of the error. If you cannot fix the error, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center.
642
z/OS MVS Assembler Services Reference IAR-XCT
IXGIMPRT macro
Table 38. Return and Reason Codes for the IXGIMPRT Macro (continued)
Return Code
04
Reason Code
0000040A
Meaning and Action
IxgRsnCodeDuplexFailureWarning -
08
08
08 xxxx0801 xxxx0802 xxxx0803
Explanation
: Environment error. The request was successful, but the system logger was unable to duplex log data to staging data sets, even though the log stream definition requested unconditional duplexing to staging data sets by specifying the log stream attributes:
STG_DUPLEX=YES, DUPLEXMODE=UNCOND, or
STG_DUPLEX=YES,DUPLEXMODE=DRXRC. When
DUPLEXMODE=UNCOND is specified, but Logger was unable to obtain a staging data set to duplex the log data.
Therefore, the Logger duplexing is being done in local buffers (data space).
When DUPLEXMODE=DRXRC is specified for a logstream and being used for (non-local) disaster recovery duplexing, if the internal buffers used for asynchronous buffering of the log blocks become full. Meaning the internal buffers became full before at least one of the full buffers could be written to the staging data set.
Action
: For DUPLEXMODE=UNCOND, if duplexing to staging data sets is required, disconnect from this log stream and connect to a log stream that can be duplexed to staging data sets.
For DUPLEXMODE=DRXRC, if duplexing to a
DRXRC-type staging data sets is required, then cause the log data to be offload to the log stream secondary storage
(offload data sets) and then continue writing to the log stream.
IxgRsnCodeBadParmlist -
Explanation
: Program error. The parameter list is invalid.
Either the parameter list storage is inaccessible, or an invalid version of the macro was used.
Action
: Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request, and that the macro version is correct. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.
IxgRsnCodeXESError -
Explanation
: System error. A severe cross-system extended services (XES) error has occurred.
Action
: See ANSAA_DIAG1 for the XES return code and
ANSAA_DIAG2 for the XES reason code.
IxgRsnCodeBadBuffer -
Explanation
: Program error. The virtual storage area specified on the BUFFER parameter is not addressable.
Action
: Ensure that the storage area specified on the
BUFFER parameter is accessible to system logger for the duration of the request. If the BUFFKEY parameter is specified, make sure it contains a valid key associated with the storage area. If BUFFKEY is not used, ensure that the storage is in the same key as the program at the time the logger service was requested. The storage must be addressable in the caller's primary address space.
Chapter 70. IXGIMPRT — Import log blocks
643
IXGIMPRT macro
Table 38. Return and Reason Codes for the IXGIMPRT Macro (continued)
Return Code
08
Reason Code
xxxx0806
Meaning and Action
IxgRsnCodeBadStmToken -
08
08
08
08
08 xxxx0809 xxxx080A xxxx0814 xxxx0815 xxxx0816
Explanation
: Program error. One of the following occurred: v
The stream token was not valid.
v The specified request was issued from an address space other than the connectors address space.
Action
: Do one of the following: v Make sure that the stream token specified is valid.
v Ensure that IXGIMPRT requests were issued from the connectors address space.
IxgRsnCodeBadWriteSize -
Explanation
: Program error. The size of the log block specified in the BLOCKLEN parameter is not valid. The value for BLOCKLEN must be greater than zero and less than or equal to the maximum buffer size (MAXBUFSIZE) defined in the LOGR policy for the structure associated with this log stream.
Action
: Ensure that the value specified on the BLOCKLEN parameter is greater than 0 and less than or equal to the
MAXBUFSIZE which is returned on the log stream connect request.
IxgRsnCodeRequestLocked -
Explanation
: Program error. The program issuing the request is holding a lock.
Action
: Ensure that the program issuing the request is not holding a lock.
IxgRsnCodeNotAvailForIPL -
Explanation
: Environment error. The system logger address space is not available for the remainder of this IPL. The system issues messages about this error during system logger initialization.
Action
: See the explanation for system messages issued during system logger initialization.
IxgRsnCodeNotEnabled -
Explanation
: Program error. The program issuing the request is not enabled for I/O and external interrupts, so the request fails.
Action
: Make sure the program issuing the request is enabled for I/O and external interrupts.
IxgRsnCodeBadAnslen -
Explanation
: Program error. The answer area length
(ANSLEN parameter) is not large enough. The system logger returned the required size in the
Ansaa_Preferred_Size field of the answer area, mapped by
IXGANSAA macro.
Action
: Reissue the request, specifying an answer area of the required size.
644
z/OS MVS Assembler Services Reference IAR-XCT
IXGIMPRT macro
Table 38. Return and Reason Codes for the IXGIMPRT Macro (continued)
Return Code
08
Reason Code
xxxx0817
Meaning and Action
IxgRsnCodeBadAnsarea -
08
08 xxxx0819 xxxx082D
Explanation
: Program error. The storage area specified on the ANSAREA parameter cannot be accessed. This may occur after the system logger address space has terminated.
Action
: Specify storage that is in the caller's primary address space and in the same key as the calling program at the time the system logger service was issued. This storage must be accessible until the request completes.
IxgRsnCodeSRBMode -
Explanation
: Program error. The calling program is in SRB mode, but task mode is required for this system logger service.
Action
: Make sure your program is in task mode.
IxgRsnCodeExpiredStmToken -
Explanation
: Environment error. The stream token is no longer valid because the connector has been disconnected.
08
08
08 xxxx083F xxxx0840 xxxx0841
Action
: Re-connect to the logstream before issuing any functional requests.
IxgRsnCodeTestartError -
Explanation
: System error. An unexpected error was encountered while attempting to validate the buffer ALET.
Action
: See ANSAA_DIAG1 in the answer area mapped by the IXGANSAA macro for the return code from the
IxgRsnCodeBadVersion -
Explanation
: Environment error. The parameter list passed to the service routine has an incorrect version indicator.
Action
: Make sure that the level of MVS executing the request and the macro library used to compile the invoking routine are compatible.
IxgRsnCodeBadBufferAlet -
Explanation
: Program error. The buffer ALET specified is not zero and does not represent a valid entry on the callers dispatchable unit access list (DUAL). See the
ANSAA_DIAG1 field of the answer area, mapped by the
IXGANSAA macro, for the return code from the TESTART system service.
Action
: Ensure that the correct ALET was specified. If not, provide the correct ALET. Otherwise, add the correct ALET to dispatchable unit access list (DUAL).
Chapter 70. IXGIMPRT — Import log blocks
645
IXGIMPRT macro
Table 38. Return and Reason Codes for the IXGIMPRT Macro (continued)
Return Code
08
Reason Code
xxxx0849
Meaning and Action
IxgRsnCodeBadBuffkey -
08 xxxx085C
Explanation
: Program error. The buffer key specified on the
BUFFKEY parameter specifies an invalid key. Either the key is greater than 15 or the program is running in problem state and the specified key is not the same key as the PSW key at the time the system logger service was issued.
Action
: For problem state programs, either do not specify the BUFFKEY parameter or else specify the same key as the
PSW key at the time the system logger service was issued.
For supervisor state programs, specify a valid storage key
(0 <= key <= 15).
Equate Symbol
: IxgRsnCodeDsDirectoryFull
Explanation
: Environment error. The interim storage (for example: the coupling facility structure space allocated or the staging data set space) for the log stream is full. System logger's attempts to offload the interim storage log data to
DASD has failed because the log stream's data set directory is full. If this reason code is issued by the IXGIMPRT request, no further import write requests can be processed until additional directory space is available for the log stream.
System logger will periodically re-drive its offload attempts for this condition, which is applicable to both coupling facility structure and DASD-only type log streams. If system logger is able to offload log data, then an ENF event will be issued informing the connectors that the log stream should be available for writing more log data.
However, the time that passes before you can write to the log stream is unpredictable.
The system issues related messages IXG257I, IXG261E,
IXG262A and IXG301I.
Action
: The system programmer must make more log stream data set directory space available.
For information about how an authorized application program might respond to this reason code, see Setting up the system logger configuration in the z/OS MVS
Programming: Authorized Assembler Services Guide.
For information about how an unauthorized application program might respond to this reason code, see IXGIMPRT:
Import log blocks in the z/OS MVS Programming: Assembler
Services Guide.
646
z/OS MVS Assembler Services Reference IAR-XCT
IXGIMPRT macro
Table 38. Return and Reason Codes for the IXGIMPRT Macro (continued)
Return Code
08
Reason Code
xxxx085D
Meaning and Action
Equate Symbol
: IxgRsnCodeWowError
08
08 xxxx0860 xxxx0861
Explanation
: Environment error. The interim storage (for example: the coupling facility structure space allocated or the staging data set space) for the log stream is full. System logger's attempts to offload the interim storage log data to
DASD have failed because of severe errors. No further write requests can be processed until the offload error condition is cleared.
System logger will periodically re-drive its offload attempts for this condition, which is applicable to both coupling facility structure and DASD-only type log streams. If system logger is able to offload log data, then an ENF event will be issued informing the connectors that the log stream should be available for writing more log data.
However, the time that passes before you can write to the log stream is unpredictable.
The system issues related message IXG301I.
Action
: The system programmer must correct the severe error condition inhibiting the log stream offload. If you are unable to correct the error, search problem reporting data bases for a fix for the problem. If no fixt exists, contact the
IBM Support Center.
You can retry your write request periodically or wait for the ENF signal that the log stream is available, or disconnect from this log stream and connect to another log stream.
For information on how an authorized application program might respond to this reason code, see Setting up the system logger configuration in the z/OS MVS Programming:
Authorized Assembler Services Guide.
For information on how an authorized application program might respond to this reason code, see IXGIMPRT: Import log blocks in the z/OS MVS Programming: Assembler Services
Guide.
IxgRsnCodeCFLogStreamStorFull -
Explanation
: Environment error. The coupling facility structure space allocated for this log stream is full. No furtherm requests can be processed until the log data in the coupling facility structure is offloaded to DASD log data sets.
Action
: Listen to the ENF signal 48 which will indicate that the log stream is available after the data has been offloaded to DASD and then reissue the request.
IxgRsnCodeRebuildInProgress -
Explanation
: Environment error. No requests can be processed for this log stream because a coupling facility structure re-build is in progress for the structure associated with this log stream.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Reissue the request.
v The re-build failed and the log stream is not available.
Chapter 70. IXGIMPRT — Import log blocks
647
IXGIMPRT macro
Table 38. Return and Reason Codes for the IXGIMPRT Macro (continued)
Return Code
08
Reason Code
xxxx0862
Meaning and Action
IxgRsnCodeXESPurge -
08
08
08 xxxx0863 xxxx0864 xxxx0865
Explanation
: Environment error. An cross-system extended services (XES) request has been purged due to re-build processing.
Action
: Listen for ENF signal 48 that will indicate one of the following: v
The log stream is available because the re-build completed successfully. Reissue the request.
v The re-build failed and the log stream is not available.
IxgRsnCodeStructureFailed -
Explanation
: Environment error. Either the coupling facility structure associated with the log stream has failed or the coupling facility itself has failed.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Reissue the request.
v The re-build failed and the log stream is not available.
IxgRsnCodeNoConnectivity -
Explanation
: Environment error. No connectivity exists to the coupling facility associated with the log stream. The system logger will either attempt to re-build the log stream in another coupling facility or the log stream will be disconnected.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Reissue the request.
v The re-build failed and the log stream is not available. #
The log stream has been disconnected from this system.
If a re-build initiated because of a loss of connectivity previously failed, an ENF corresponding to this reason code might not be issued. Further action by the installation might be necessary to cause the change of the log stream status again. Check the log for messages IXG101I, IXG107I and related rebuild messages for information on resolving any outstanding issues.
Equate Symbol
: IxgRsnCodeStagingDSFull
Explanation
: Environment error. The staging data set allocated for this log stream on this system is full. No further requests can be processed until enough log data in the coupling facility structure is offloaded to DASD log data sets to relieve the staging data set's full condition.
Action
: Listen to the ENF signal 48 which will indicate that the log stream is available after room becomes available in the staging data set. Then, reissue the request.
648
z/OS MVS Assembler Services Reference IAR-XCT
IXGIMPRT macro
Table 38. Return and Reason Codes for the IXGIMPRT Macro (continued)
Return Code
08
Reason Code
xxxx0867
Meaning and Action
Equate Symbol
: IxgRsnCodeLocalBufferFull
Explanation
: Environment error. The available local buffer space for the system logger address space is full. No further requests can be processed until the log data in the local storage buffer is offloaded to DASD log data sets.
Note that this reason code applies only to a IXGWRITE or
IXGIMPRT request issued against a DASD-only log stream.
08
08
08
08
08 xxxx0868 xxxx0890 xxxx0891 xxxx08D7 xxxx08D9
Action
: Listen for the ENF signal 48 indicating that the
DASD-only log stream is available again after the data has been offloaded to DASD log data sets. Then reissue the request.
Equate Symbol
: IxgRsnCodeStagingDSFormat
Explanation
: Environment error. The staging data set allocated for this log stream on this system has not finished being formatted for use by System Logger. No further
IXGWRITE requests can be processed until the formatting completes.
Action
: Listen to the ENG signal 48 which will indicate that the log stream is available after formatting process is finished. Then, reissue the request.
IxgRsnCodeAddrSpaceNotAvail -
Explanation
: System error. The system logger address space failed and is not available.
Action
: Do not issue system logger requests.
IxgRsnCodeAddrSpaceInitializing -
Explanation
: System error. The system logger address space is not available because it is IPLing.
Action
: Listen for ENF signal 48, which will indicate when the system logger address space is available. Once it's available, re-connect to the log stream, then reissue this request. You can also listen for ENF signal 48, which will indicate if the system logger address space will not be available for the life of the IPL. In that case, do not issue system logger services.
IxgRsnCodeRequestNotAllowed -
Explanation
: Program error. The caller attempted to issue an import request while a write connection (IXGCONN
AUTH=WRITE,IMPORTCONNECT=NO) was active.
Action
: Issue the correct type of request based on the import status of your connection.
IxgRsnCodeBadImportBlockId -
Explanation
: Program error. The blockid specified on the import request was either less than the blockid expected or less than the size the control information system logger adds to each log block. You can use IXGQUERY service to ascertain the size of control information for a log block.
IXGQUERY returns the control information size for a log stream in the QBUF_Control_Info_Size field in the query buffer. IXGQUERY also returns the block identifier of the last successfully written log block.
Action
: Specify a valid value for the block id and reissue the import request.
Chapter 70. IXGIMPRT — Import log blocks
649
IXGIMPRT macro
Table 38. Return and Reason Codes for the IXGIMPRT Macro (continued)
Return Code
08
Reason Code
xxxx08DA
Meaning and Action
IxgRsnCodeBadImportTimeStamp -
08
08
0C xxxx08DB xxxx08DC xxxx0000
Explanation
: Program error. The UTC timestamp specified on the import request was not greater than or equal to the
UTC time stamp assigned to the last log block successfully imported.
Action
: Specify a valid value for GMT_TimeStamp and reissue the request. You can obtain the UTC timestamp of the last successfully written log block using the IXGQUERY service.
IxgRsnCodeImportNoSrbMode -
Explanation
: Program error. IXGIMPRT requests can only be issued in task mode.
Action
: Issue the IXGIMPRT request while executing in task mode.
IxgRsnCodeImportInProgress -
Explanation
: Program error. Only one import operation for a given log stream can be in progress at any instance in time. The problem may be due to a task initiating an import request before a previously initiated import to the log stream has completed.
Action
: Wait for the currently executing import operation to complete before initiating a subsequent import operation.
IxgRetCodeCompError -
Explanation
: User or System error. One of the following occurred: v
You issued the FORCE IXGLOGR,ARM command to terminate the system logger address space.
v System logger component error occurred.
Action
: If this reason code is not the result of forcing the system logger address space, search problem reporting data bases for a fix for the problem. If no fix exists, contact the
IBM Support Center. Provide the diagnostic data in the answer area (IXGANSAA) and any dumps or LOGREC entries from system logger.
Example
Issue IXGIMPRT to import a log block to a back up log stream.
* R6 Read buffer address
IXGIMPRT
STREAMTOKEN=OTOKEN,
BUFFER=(R6),
BLOCKLEN=DATALEN,
BLOCKID=RBLKID,
GMT_TIMESTAMP=GMTTIME,
LOCALTIME=LOCTIME,
ANSAREA=XANSAREA,
ANSLEN=XANSLEN,
R6 EQU
OTOKEN DS
RSNCODE=RSCODE
6
CL16
DATALEN DS
RBLKID DS
F
CL8
Output Stream token
Returned data length
Returned block identifier
650
z/OS MVS Assembler Services Reference IAR-XCT
X
X
X
X
X
X
X
X
X
GMTTIME DS
LOCTIME DS
XANSAREA DS
XANSLEN DC
CL8
CL8
CL(ANSAA_LEN)
A(ANSAA_LEN)
RSCODE DS F
DSECT ,
IXGANSAA ,
GMT
Local Time
Logger answer area
Answer area length
Reason code
The answer area macro
IXGIMPRT macro
Chapter 70. IXGIMPRT — Import log blocks
651
IXGIMPRT macro
652
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
IXGINVNT description
The LOGR policy tracks all data associated with log streams, such as log stream characteristics, coupling facility structures associated with log streams, and the systems connected to each log stream.
Use the IXGINVNT macro to manage the LOGR policy by: v
Defining, updating or deleting entries for log streams in the LOGR policy.
v Defining or deleting entries for coupling facility structures in the LOGR policy.
v Checking on whether a particular log stream or structure is already defined in the LOGR policy.
The four requests for the macro are: v IXGINVNT REQUEST=DEFINE, which defines an entry in the LOGR policy.
There are two types of DEFINE requests:
– TYPE=LOGSTREAM defines an entry for a log stream. See
“REQUEST=DEFINE TYPE=LOGSTREAM option of IXGINVNT” on page 656
for the syntax of this request.
– TYPE=STRUCTURE defines an entry for a system logger coupling facility
structure. See “REQUEST=DEFINE TYPE=STRUCTURE option of
IXGINVNT” on page 677 for the syntax of this request.
v IXGINVNT REQUEST=UPDATE, which updates a log stream entry in the LOGR
policy. See “REQUEST=UPDATE option of IXGINVNT” on page 681 for the
syntax of this request.
v IXGINVNT REQUEST=CHECKDEF, which indicates whether a particular log stream or structure entry is currently defined in the LOGR policy. See
“REQUEST=CHECKDEF option of IXGINVNT” on page 702 for the syntax of
this request.
v IXGINVNT REQUEST=DELETE, which deletes a log stream or structure entry
from the LOGR policy. See “REQUEST=DELETE option of IXGINVNT” on page
728 for the syntax of this request.
For information about using the system logger services and the LOGR policy, see
z/OS MVS Programming: Assembler Services Guide.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state with any PSW key.
Task
PASN=HASN, any SASN
31-bit or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts.
No locks held.
Control parameters must be in the primary address space.
© Copyright IBM Corp. 1988, 2017
653
IXGINVNT macro
Programming requirements
v The parameter list for this service must be addressable in the caller's primary address space.
v Include the IXGCON mapping macro in your program. This macro provides a list of equate symbols for the system logger services.
v Include mapping macro IXGANSAA in your program. This macro shows the format of the answer area output returned for each system logger service in the
ANSAREA parameter.
v A minimum LOGR couple data set (CDS) format level is required to specify some parameters. Refer to each parameter description for details. Also see
“Updating a log stream's attributes” in z/OS MVS Programming: Assembler
Services Guide and “LOGR parameters for format utility” in z/OS MVS Setting Up
a Sysplex for more information.
Restrictions
v All storage areas specified in this service must be in the same storage key as the caller's storage key and must exist in the caller's primary address space.
v The caller cannot have an EUT FRR established.
v You can only use the IXGINVNT REQUEST=DELETE TYPE=LOGSTREAM request to delete a log stream entry from the LOGR policy if there are no connections (active or failed) to the log stream.
v
For a few parameters on the IXGINVNT REQUEST=UPDATE request, there must be no connections (active or failed) to the log stream being updated. Refer to each parameter description to determine whether an update is allowed and when it takes effect when there are log stream connections.
v Restrictions for DASD-only log stream definitions:
– A DASD-only log stream is single-system in scope. This means that only one system at a time can connect to a DASD-only log stream. You can have multiple connections from one system or multiple systems connecting in sequence.
– A DASD-only log stream is not associated with a coupling facility structure.
– If the requested function is to update the attributes of a DASD-only log stream, the following parameters are not allowed:
- STG_DUPLEX
- DUPLEXMODE
- LOGGERDUPLEX
Use of staging data sets is automatic rather than optional for a DASD-only log stream.
– A DASD-only log stream can be upgraded to a coupling facility log stream by specifying STRUCTNAME on the IXGINVNT REQUEST=UPDATE
TYPE=LOGSTREAM request. Conversely, a coupling facility log stream cannot be changed to DASD-only.
v If the System Authorization Facility (SAF) is available, the system performs SAF authorization checks on all IXGINVNT requests.
For log stream entries, you must have the following authorization:
– To define, delete, or update a log stream entry, the caller must have alter access to RESOURCE(log_stream_name) in SAF class CLASS(LOGSTREAM)
654
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
– If you specify the STRUCTNAME parameter on a DEFINE request for a log stream entry, the caller must also have update access authority to the coupling facility structure, RESOURCE(IXLSTR.structure_name) in SAF class
CLASS(FACILITY)
– If you use the LIKE parameter to model your definition after another log stream on a DEFINE request for a log stream entry that will be mapped to a structure named in the like_log_stream_name structure name, i.e.
like_structure_name, then you must also have update access to the
RESOURCE(IXLSTR.like_structure_name) in class CLASS(FACILITY).
– To check if a log stream is defined in the LOGR policy, the caller must have read access to RESOURCE(MVSADMIN.LOGR) in SAF class
CLASS(FACILITY).
For logger structure entries, you must have the following authorization:
– To define or delete a structure entry in the LOGR policy, the caller must have alter access to RESOURCE(MVSADMIN.LOGR) in SAF class
CLASS(FACILITY).
– To check a logger structure entry definition in the LOGR policy, the caller must have read access to RESOURCE(MVSADMIN.LOGR) in SAF class
CLASS(FACILITY).
If SAF is not available or if there is no CLASS(LOGSTRM) or CLASS(FACILITY) class defined for the log stream or structure, no security checking is performed.
v There is more than one version of this macro available. The parameters you can use depend on the version you specify on the PLISTVER parameter. See the description of the PLISTVER parameter for more information.
Input register information
Before issuing the IXGINVNT macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0
2-13
Reason code, if register 15 contains a non-zero return code
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Used as a work register by the system
2-13
Unchanged
14-15
Used as a work register by the system
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
655
IXGINVNT macro
Syntax
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
REQUEST=DEFINE TYPE=LOGSTREAM option of IXGINVNT
The IXGINVNT macro with the DEFINE TYPE=LOGSTREAM parameters defines a log stream or coupling facility structure entry in the LOGR policy.
Syntax for REQUEST=DEFINE TYPE=LOGSTREAM
The standard form of the IXGINVNT REQUEST=DEFINE TYPE=LOGSTREAM macro is written as follows:
Description
name
⌂
name: symbol. Begin name in column 1.
One or more blanks must precede IXGINVNT.
IXGINVNT
⌂ One or more blanks must follow IXGINVNT.
REQUEST=DEFINE
,TYPE=LOGSTREAM
,ANSAREA=ansarea
,ANSLEN=anslen
,STREAMNAME=streamname
,GROUP=PRODUCTION
,GROUP=TEST
,STRUCTNAME=structname
,DASDONLY=NO
,DASDONLY=YES
ansarea: RS-type address or register (2) - (12).
anslen: RS-type address or register (2) - (12).
streamname: RS-type address or register (2) - (12).
Default
: GROUP=PRODUCTION
structname: RS-type address or register (2) - (12).
Default
: NO_STRUCTNAME
Default
: DASDONLY=NO
656
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,MAXBUFSIZE=maxbufsize
,RMNAME=rmname
,DESCRIPTION=description
IXGINVNT macro
Description
maxbufsize: RS-type address or register (2) - (12).
rmname: RS-type address or register (2) - (12).
description: RS-type address or register (2) - (12).
Default
: NO_DESCRIPTION
Default
: LOGGERDUPLEX=UNCOND ,LOGGERDUPLEX=UNCOND
,LOGGERDUPLEX= COND
,STG_DUPLEX=NO
,STG_DUPLEX=YES
,DUPLEXMODE=COND
,DUPLEXMODE=UNCOND
,DUPLEXMODE=DRXRC
,STG_MGMTCLAS=stg_mgmtclas
Default
: STG_DUPLEX=NO for DASDONLY=NO
Default
: STG_DUPLEX=YES for DASDONLY=YES
Default
: DUPLEXMODE=COND for DASDONLY=NO
Default
: DUPLEXMODE=UNCOND for
DASDONLY=YES
,STG_DATACLAS=stg_dataclas
,STG_STORCLAS=stg_storclas
,STG_SIZE=stg_size
,LS_ALLOCAHEAD={xls_allocahead | *}
,LS_MGMTCLAS=ls_mgmtclas
,LS_DATACLAS=ls_dataclas
,LS_STORCLAS=ls_storclas
stg_mgmtclas: RS-type address or register (2) - (12).
Default
: NO_STG_MGMTCLAS
stg_dataclas: RS-type address or register (2) - (12).
Default
: NO_STG_DATACLAS
stg_storclas: RS-type address or register (2) - (12).
Default
: NO_STG_STORCLAS
stg_size: RS-type address or register (2) - (12).
Default
: Size defined in SMS data class or by dynamic allocation
xls_allocahead: RS-type address or register (2) - (12).
Default
: * 0
ls_mgmtclas: RS-type address or register (2) - (12).
Default
: NO_LS_MGMTCLAS
ls_dataclas: RS-type address or register (2) - (12).
Default
: NO_LS_DATACLAS
ls_storclas: RS-type address or register (2) - (12).
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
657
IXGINVNT macro
Syntax
,LS_SIZE=ls_size
,RETPD=retpd
Description
Default
: NO_LS_STORCLAS
ls_size: RS-type address or register (2) - (12).
Default
: Size defined in SMS data class or by dynamic allocation
retpd: RS-type address or register (2) - (12).
Default
: NO_RETPD
Default
: AUTODELETE=NO ,AUTODELETE=NO
,AUTODELETE=YES
,AUTODELETE=NO_AUTODELETE
,HLQ=hlq
,EHLQ=ehlq
,LOWOFFLOAD=lowoffload
,HIGHOFFLOAD=highoffload
WARNPRIMARY
,WARNPRIMARY=NO_WARNPRIMARY
,WARNPRIMARY=NO
,WARNPRIMARY=YES
,OFFLOADRECALL=YES
,OFFLOADRECALL=NO
,OFFLOADRECALL=NO_OFFLOADRECALL
,LIKE=like_streamname
hlq: RS-type address or register (2) - (12).
Default
: NO_HLQ
ehlq: RS-type address or register (2) - (12).
Default
: NO_EHLQ
lowoffload: RS-type address or register (2) - (12).
Default
: LOWOFFLOAD=0
highoffload: RS-type address or register (2) - (12).
Default
: HIGHOFFLOAD=80
RS-type address or register (2) - (12)
Default
: NO_WARNPRIMARY
Default
: OFFLOADRECALL=YES
,MODEL=NO
,MODEL=YES
,DIAG=NO
658
z/OS MVS Assembler Services Reference IAR-XCT
like_streamname: RS-type address or register (2) - (12).
Default
: NO_LIKE
Default
: MODEL=NO
Default
: DIAG=NO
IXGINVNT macro
Syntax
,DIAG=YES
,DIAG=NO_DIAG
,ZAI=NO
,ZAI=YES
,ZAI=NO_ZAI
,ZAIDATA=NO_ZAIDATA
,ZAIDATA=Xzaidata
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
,PLISTVER=2
,PLISTVER=3
,RETCODE=retcode
,RSNCODE=rsncode
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Description
Default
: ZAI=NO
Default
: ZAIDATA=NO_ZAIDATA
Default
: IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: MF=S
Parameters for REQUEST=DEFINE,TYPE=LOGSTREAM
The parameters are explained as follows:
REQUEST=DEFINE
Requests that an entry for a log stream or coupling facility structure be defined in the LOGR policy.
,TYPE=LOGSTREAM
Indicates that the entry to be defined in the LOGR policy is a log stream entry.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
659
IXGINVNT macro
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,STREAMNAME=streamname
Specifies the name (or address in a register) of the 26-byte input field containing the name of the log stream that you want to define in the LOGR policy.
The stream name must be 26 characters, padded on the right with blanks if necessary. The name can be made up of one or more segments separated by periods, up to the maximum length of 26 characters. The following rules apply: v Each segment may contain up to eight numeric, alphabetic, or national ($, #, or @) characters.
v The first character of each segment must be an alphabetic or national character.
v Each segment must be separated by periods, which you must count as characters.
STREAMNAME is required with the TYPE=LOGSTREAM parameter.
[GROUP=(PRODUCTION|TEST)]
An optional keyword input that specifies whether the log stream is in the test group or the production group. This keyword allows you to keep processing and resources for log streams in the two groups separate on a single system, including requests such as data set allocation and data set recalls. If the TEST group fails, the failure does not normally affect the PRODUCTION group. You can only specify the GROUP parameter in the LOGR couple data set because the sysplex is formatted at the HBB7705 level or higher.
If you specify GROUP(PRODUCTION), which is the default, system logger places this log stream in the PRODUCTION group. A PRODUCTION log stream can use at least 75% of the system logger couple data set DSEXTENT records and connection slots.
If you specify GROUP(TEST), system logger places this log stream in the TEST group. TEST log streams are limited to at most 25% of the system logger couple data set DSEXTENT records and connection slots.
Because system logger does not allow you to define a mixture of TEST and
PRODUCTION log streams to a single structure, The GROUP value must match the group of the structure the log stream is being defined to. When you define the first log stream to a structure, the structure becomes either a TEST or PRODUCTION structure. After that, the GROUP value for subsequent log streams defined to a structure must match the GROUP value of the initial log stream. For example, if you specify or default to GROUP(PRODUCTION) for the first log stream defined to a structure, you will only be able to define
PRODUCTION log streams to that structure subsequently. See “Example 10” on page 757.
660
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
,STRUCTNAME=structname
With TYPE=LOGSTREAM, specifies the name (or address in a register) of a
16-byte input field that contains the name of the coupling facility structure associated with the coupling facility log stream being defined. The structure specified is a list structure defined in the CFRM policy. All of this log stream's log blocks will be written to this structure before being written to DASD.
For a coupling facility log stream, you must define STRUCTNAME in the log stream definition in the LOGR policy via this parameter or the STRUCTNAME defined for the log stream referenced by the LIKE parameter before you can connect to the log stream.
The following rules apply for the structname: v It can contain numeric, alphabetic, or national ($, #, or @) characters, or an underscore(_), padded on the right with blanks if necessary.
v
The first character must be an alphabetic character.
For a DASD-only log stream, omit the STRUCTNAME parameter, since there is no coupling facility associated with the log stream.
If NO_STRUCTNAME is specified for STRUCTNAME, the macro will be invoked as if STRUCTNAME was not specified.
,DASDONLY=NO
,DASDONLY=YES
Specifies whether the log stream being defined is a coupling facility or a
DASD-only log stream.
If you specify DASDONLY=NO, which is the default, the log stream is defined as a coupling facility log stream.With DASDONLY=NO, you can also specify
STG_DUPLEX, DUPLEXMODE, and LOGGERDUPLEX keywords to select a method of duplexing for a coupling facility log stream.
If you specify DASDONLY=YES the log stream is defined as a DASD-only log stream and does not use the coupling facility for log data.
Since a staging data set is required when using a DASD-only log stream, check the usage of the STG_SIZE parameter, the STG_DATACLAS parameter, or the defaults used for sizing the staging data set.
DASD only log streams are unconditionally duplexed to staging data sets. This means that DASD only log streams are created as if STG_DUPLEX=YES,
DUPLEXMODE=UNCOND, and LOGGERDUPLEX=UNCOND were specified when the log stream was defined. You cannot change these duplexing parameters. However, you can optionally specify STG_DUPLEX=YES,
DUPLEXMODE=UNCOND, and LOGGERDUPLEX=UNCOND. If you specify any other parameters for these keywords when you define a DASD only log steam, the define request will fail.
,MAXBUFSIZE=maxbufsize
Specifies the name (or address in a register) of a 4-byte input field that contains the size, in bytes, of the largest log block that can be written to the
DASD-only log stream being defined in this request.
The value for MAXBUFSIZE must be between 1 and 65,532 bytes. The default is 65,532 bytes.
This parameter is valid only with DASDONLY=YES.
,RMNAME=rmname
Specifies the name (or address in a register) of the 8-byte input field containing the name of the recovery resource manager program associated with the log
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
661
IXGINVNT macro
stream. RNAME must be 8 alphanumeric or national ($,#,or @) characters, padded on the right with blanks if necessary.
You must define RMNAME in the LOGR policy before the resource manager can connect to the log stream.
If you specify RMNAME to associate a resource manager with a log stream in the LOGR policy, the resource manager specified must subsequently connect to the log stream. If the resource manager does not connect to that log stream, system logger will not process any IXGDELET requests to delete log data. This is so that the resource manager will not miss any delete requests issued against the log stream.
,DESCRIPTION=NO_DESCRIPTION
DESCRIPTION=description
Specifies the name (or address in a register) of the 16 character input field containing user defined data describing the log stream.
DESCRIPTION must be 16 alphanumeric or national ($,#,@) characters, underscore (_) or period (.), padded on the right with blanks if necessary.
If you specify DESCRIPTION=NO_DESCRIPTION, which is the default, or a field of zeros, the macro is invoked as if the DESCRIPTION parameter was not specified.
,LOGGERDUPLEX=UNCOND
,LOGGERDUPLEX=COND
An optional input parameter that specifies whether logger continues to provide its own log data duplexing, or, conditionally, not provide its own duplexing based on an alternative duplexing configuration that provides an equivalent or better recoverability of the log data.
For both coupling facility and DASD only log streams, the default parameter is
LOGGERDUPLEX=UNCOND.
The active primary TYPE=LOGR couple data set in the sysplex must be formatted at HBB7705 or higher to specify this keyword. Otherwise, the request fails with a return code 8, reason code 0839.
For coupling facility log streams:
LOGGERDUPLEX=UNCOND, indicates that system logger should provide its own duplexing of the log data regardless of any other duplexing (such as structure system-managed duplexing rebuild) that occur.
LOGGERDUPLEX=COND indicates that system logger should provide its own duplexing of the log data unless the log stream is in an alternative duplexing configuration that provides an equivalent or better recoverability of the log data. For example, system logger does not provide its own duplexing of the log data in the following configuration: v when the log stream is in a non-volatile CF list structure that is handled by system-managed duplexing rebuild (duplex-mode) v there is a failure-independent relationship between the two structure instances v there is a failure-independent connection between connecting system and composite structure view.
Refer to Logger and coupling facility duplexing combinations and System logger recovery in z/OS MVS Setting Up a Sysplex for additional considerations on using the LOGGERDUPLEX keyword.
662
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Refer to Case 5 in Logger and coupling facility duplexing combinations in the
z/OS MVS Setting Up a Sysplex for additional details about the
LOGGERDUPLEX keyword and a coupling facility log stream.
For DASD only log streams:
Log data will be unconditionally duplexed to staging data sets. You can omit this keyword or specify LOGGERDUPLEX=UNCOND. In either case, log data will be unconditionally duplexed to staging data sets. Specifying any other parameter for the LOGGERDUPLEX keyword will result in error for DASD only log streams.
,STG_DUPLEX=NO
,STG_DUPLEX=YES
Specifies whether the log stream data for a coupling facility log stream should be duplexed in DASD staging data sets.
For coupling facility log streams:
The default is STG_DUPLEX=NO. If you specify or default STG_DUPLEX=NO, the log data for a coupling facility log stream will be duplexed in local buffers, which might be vulnerable to system failure if your configuration contains a single point of failure.
If you specify STG_DUPLEX=YES, the log data for a coupling facility log stream will be duplexed in staging data sets if the conditions defined by the
DUPLEXMODE keyword are met. This method will safeguard data on DASD staging data sets.
You can use the DUPLEXMODE keyword with STG_DUPLEX and with
LOGGERDUPLEX to specify the type of duplexing desired and whether you want conditional or unconditional duplexing by logger.
For DASD only log streams:
You can either omit this keyword or specify STG_DUPLEX=YES. In either case, log data will be unconditionally duplexed to staging data sets. Specifying any other parameter for the STG_DUPLEX keyword will result in an error for
DASD only log streams.
Refer to the LOGGERDUPLEX keyword for additional duplexing options.
,DUPLEXMODE=COND
DUPLEXMODE=UNCOND
Specifies the conditions under which the log data for a log stream should be duplexed in DASD staging data sets.
For coupling facility log streams:
The default is DUPLEXMODE=COND. If you specify or default to
DUPLEXMODE=COND, the coupling facility log data will be duplexed in staging data sets only if a system's connection to the coupling facility log stream contains a single point of failure and is therefore vulnerable to permanent log data loss: v A connection to a log stream contains a single point of failure if the coupling facility is volatile and/or resides on the same CPC as the MVS system connecting to it. The coupling facility log data for the system connection containing the single point of failure is duplexed to staging data sets.
v A connection to a log stream is failure-independent when the coupling facility for the log stream is non-volatile and resides on a different central
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
663
|
|
|
|
|
IXGINVNT macro
processor complex (CPC) than the MVS system connecting to it. The coupling facility log data for that system connection will not be duplexed to staging data sets.
If you specify DUPLEXMODE=UNCOND, the log data for the coupling facility log stream will be duplexed in staging data sets, unconditionally, even if the connection is failure independent.
Note:
If DUPLEXMODE(DRXRC) is specified, the log data is duplexed same as if the COND option is specified. This means that in staging data sets, if a system's connection to the coupling facility log stream contains a single point of failure, it is therefore vulnerable to permanent log data loss. For more information, see the CONF DUPLEXMODE option.
You can use the DUPLEXMODE keyword with STG_DUPLEX and with
LOGGERDUPLEX to specify the type of duplexing desired and whether you want conditional or unconditional duplexing by logger. See "Selecting a
Method of Duplexing Coupling Facility Log Data and System logger Recovery" in z/OS MVS Setting Up a Sysplex for complete information about using staging data sets to duplex log data.coupling facility
Note:
The staging data set related keywords, STG_SIZE, STG_DATACLAS,
STG_MGMTCLAS, and STG_STORCLAS will remain set for the log stream and be used for any dynamic staging data set allocation during local recovery even after the conversion to STG_DUPLEX=NO.
For DASD only log streams:
You can either omit this keyword or specify DUPLEXMODE=UNCOND. In either case, log data will be unconditionally duplexed to staging data sets.
Specifying any other parameter for the DUPLEXMODE keyword will result in an error for DASD only log streams.
,STG_DATACLAS=NO_STG_DATACLAS
,STG_DATACLAS=stg_dataclas
Specifies the name (or address in a register) of an 8-byte input field containing the name of the SMS data class that will be used for allocation of the DASD staging data set for this log stream.
The data class must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
If you specify NO_STG_DATACLAS, which is the default, or a field of zeros, the class is assigned by standard SMS processing. See z/OS DFSMS Using Data
Sets for more information about SMS.
An SMS value specified on the STG_DATACLAS parameter, including
NO_STG_DATACLAS, always overrides one specified on a model log stream used on the LIKE parameter.
STG_DATACLAS is only valid with STG_DUPLEX=YES or DASDONLY=YES.
,STG_MGMTCLAS=NO_STG_MGMTCLAS
,STG_MGMTCLAS=stg_mgmtclas
Specifies the name (or address in a register) of an 8-byte input field containing the name of the SMS management class that will be used for allocation of the
DASD staging data set for this log stream.
664
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
The management class must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
If you specify NO_STG_MGMTCLAS, which is the default, or a field of zeros, the class is assigned by standard SMS processing. See z/OS DFSMS Using Data
Sets for more information about SMS.
An SMS value specified on the STG_MGMTCLAS parameter, including
NO_STG_MGMTCLAS, always overrides one specified on a model log stream used on the LIKE parameter.
STG_MGMTCLAS is only valid with STG_DUPLEX=YES or DASDONLY=YES.
,STG_STORCLAS=NO_STG_STORCLAS
,STG_STORCLAS=stg_storclas
Specifies the name (or address in a register) of an 8-byte input field containing the name of the SMS storage class that will be used for allocation of the DASD staging data set for this log stream.
The storage class must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
If you specify NO_STG_STORCLAS, which is the default, or a field of zeros, the class is assigned by standard SMS processing. See z/OS DFSMS Using Data
Sets for more information about SMS.
An SMS value specified on the STG_STORCLAS parameter, including
NO_STG_STORCLAS, always overrides one specified on a model log stream used on the LIKE parameter.
STG_STORCLAS is only valid with STG_DUPLEX=YES or DASDONLY=YES.
,STG_SIZE=stg_size
Specifies the size, in 4K blocks, of the DASD staging data set for the log stream being defined.
The actual size of your data set depends on many factors including track size,
CI SIZE, and volume type, and may be smaller or larger than your parameter inputs expect. Because of this reason, see "Testing log data set parameter modifications" in z/OS MVS Setting Up a Sysplex for important notes on choosing a data set size.
Specifying STG_SIZE overrides the space allocation attribute on the
STG_DATACLAS parameter if specified.
If you omit STG_SIZE, for a coupling facility log stream, system logger does one of the following, in the order listed, to allocate space for staging data sets: v Uses the STG_SIZE of the log stream specified on the LIKE parameter, if specified.
v Uses the maximum coupling facility structure size for the structure to which the log stream is defined. This value is obtained from the value defined on the SIZE parameter for the structure in the CFRM policy.
If you omit STG_SIZE for a DASD-only log stream, system logger does one of the following, in the order listed, to allocate space for staging data sets: v
Uses the STG_SIZE of the log stream specified on the LIKE parameter, if specified.
v Uses the size defined in the SMS data class for the staging data sets.
v Uses dynamic allocation rules for allocating data sets, if SMS is not available.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
665
IXGINVNT macro
|
|
|
|
|
|
|
|
|
|
|
|
As of z/OS Version 2 Release 3, system logger supports staging data set sizes greater than 4GB. Use the STG_DATACLAS log stream specification and define the corresponding DFSMS data class with space allocation attributes and include in the data class definition the following attributes: v Data Set Name Type "EXT" (extended format) v Extended Addressability "Y"
Extended format is a means of storing data on a logical DASD volume.
Extended addressability is a means to allow VSAM Data Sets greater addressability beyond the 4GB address constraint.
For more information about planning and sizing for staging data sets, see Plan space for staging data sets and Set up the SMS environment for DASD data sets in z/OS MVS Setting Up a Sysplex .
LS_ALLOCAHEAD(xls_allocahead | *)
Specifies whether offload data sets should be proactively allocated and opened in advance on systems connected to the log stream. It is the name (or address in a register) of an optional full-word input. The xls_allocahead value can be from 0 to 3.
The active primary TYPE=LOGR couple data set must be formatted at an
HBB7705 or higher format level to specify this keyword. Otherwise, the request fails with return code 8 and reason code X'0839'. See “LOGR parameters for format utility” in z/OS MVS Setting Up a Sysplex for more information.
When the value is 0 (default), logger does not proactively allocate and open advanced-current log stream offload data sets on any systems that are connected to the log stream.
When the value is between 1 and 3 (inclusively), all systems that are connected to and performing offloads for the log stream should be proactive in newly allocating up to the intended number (xls_allocahead) of advanced-current offload data sets. It also indicates these systems are proactive in opening the current offload data set as well as the first advanced-current offload data set.
The logger processing is potentially affected on a system with the
ALLOCAHEAD(NO) IXGCNFxx parmlib policy specification. See the
IXGCNFxx parmlib member in z/OS MVS Initialization and Tuning Reference for more information about the MANAGE OFFLOAD ALLOCAHEAD specification. Also see “Offloading log data from interim storage by freeing and/or moving it to DASD” in z/OS MVS Setting Up a Sysplex for more information about the logger behavior based on the ALLOCAHEAD and
LS_ALLOCAHEAD parameters.
The default is * 0. Omitting the parameter LS_ALLOCAHEAD results in the log stream being defined with an advanced-current allocate ahead value of zero (0) unless the LIKE parameter is also specified. If the LIKE parameter is specified, the LS_ALLOCAHEAD value is copied from the referenced LIKE log stream entry.
,LS_DATACLAS=NO_LS_DATACLAS
,LS_DATACLAS=ls_dataclas
Specifies the name (or address in a register) of an 8-byte input field containing the name of the SMS data class that will be used for allocation of the DASD log data set for this log stream.
The data class must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
666
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
If you specify NO_LS_DATACLAS, which is the default, or a field of zeros, the class is assigned by standard SMS processing. See z/OS DFSMS Using Data Sets for more information about SMS.
An SMS value specified on the LS_DATACLAS parameter, including
NO_LS_DATACLAS, always overrides one specified on a model log stream used on the LIKE parameter.
,LS_MGMTCLAS=NO_LS_MGMTCLAS
,LS_MGMTCLAS=ls_mgmtclas
Specifies the name (or address in a register) of an 8-byte input field containing the name of the SMS management class that will be used for allocation of the
DASD log data set for this log stream.
The management class must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
If you specify NO_LS_MGMTCLAS, which is the default, or a field of zeros, the class is assigned by standard SMS processing. See z/OS DFSMS Using Data
Sets for more information about SMS.
An SMS value specified on the LS_MGMTCLAS parameter, including
NO_LS_MGMTCLAS, always overrides one specified on a model log stream used on the LIKE parameter.
,LS_STORCLAS=NO_LS_STORCLAS
,LS_STORCLAS=ls_storclas
Specifies the name (or address in a register) of an 8-byte input field containing the name of the SMS storage class that will be used for allocation of the DASD log data set for this log stream.
The storage class must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
If you specify NO_LS_MGMTCLAS, which is the default, or a field of zeros, the class is assigned by standard SMS processing. See z/OS DFSMS Using Data
Sets for more information about SMS.
An SMS value specified on the LS_MGMTCLAS parameter, including
NO_LS_MGMTCLAS, always overrides one specified on a model log stream used on the LIKE parameter.
,LS_SIZE=ls_size
Specifies the size, in 4K blocks, of the log stream offload DASD data sets for the log stream being defined.
The actual size of your data set depends on many factors including track size,
CI SIZE, and volume type, and may be smaller or larger than your parameter inputs expect. Because of this reason, see "Testing log data set parameter modifications" in z/OS MVS Setting Up a Sysplex for important notes on choosing a data set size.
Specifying LS_SIZE overrides the space allocation attribute on the
LS_DATACLAS parameter if specified.
If you omit LS_SIZE, system logger does one of the following to allocate offload data sets: v
Uses the LS_SIZE of the log stream specified on the LIKE parameter, if specified.
v Uses the size defined in the SMS data class for the offload data sets.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
667
IXGINVNT macro
v Uses dynamic allocation rules for allocating data sets, if SMS is not available.
,AUTODELETE=NO
,AUTODELETE=YES
,AUTODELETE=NO_AUTODELETE
Specifies when system logger physically deletes log data.
If you specify AUTODELETE=NO, which is the default, system logger physically deletes an entire log data set only when both of the following are true: v Data is marked for deletion by a system logger application using the
IXGDELET service.
v The retention period for all the data in the log data set expires.
You must specify the RETPD parameter with AUTODELETE=NO.
If you specify AUTODELETE=YES, system logger automatically physically deletes log data whenever data is either marked for deletion (using the
IXGDELET service or an archiving procedure) or the retention period for all the log data in a data set has expired.
Be careful when using AUTODELETE=YES if the system logger application manages log data deletion using the IXGDELET service. With
AUTODELETE=YES, system logger can delete data that the application expects to be accessible.
If you specify AUTODELETE=NO_AUTODELETE, system logger uses the default AUTODELETE value, unless the LIKE parameter is specified. If the
LIKE parameter is specified, the AUTODELETE value is copied from the referenced like log stream entry.
RETPD=0
RETPD=retpd
Specifies the name (or address in a register) of a 4-byte input field containing the number of days of the retention period for log data in the log stream. The retention period begins when data is written to the log stream. Once the retention period for an entire log data set has expired, the data set is eligible for physical deletion. The point at which system logger physically deletes the data depends on what you have specified on the AUTODELETE parameter.
System logger will not process a retention period or delete data on behalf of log streams that are not connected to or being written to by an application.
The value specified for RETPD must be between 0 and 65,536.
,HLQ=NO_HLQ
,HLQ=hlq
Specifies the name (or address in a register) of an 8-byte input field containing the high-level qualifier for both the log stream data set name and the staging data set name.
The high-level qualifier must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
If you specify an explicit value for HLQ, this value overrides a high-level qualifier for the log stream specified on the LIKE parameter.
If you do not specify a high-level qualifier, or if you specify HLQ=NO_HLQ, the log stream being defined will have a high-level qualifier of IXGLOGR. If you also specified the LIKE parameter, it will have the high-level qualifier of the log stream specified on the LIKE parameter.
668
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
HLQ and EHLQ are mutually exclusive and cannot be specified for the same log stream definition.
If the name specified for the HLQ parameter refers to a field that contains
X'00', the macro will be invoked as if NO_HLQ had been specified. However, specifying HLQ=NO_HLQ and EHLQ=ehlq on the same request results in an error. When HLQ=NO_HLQ is specified, the resulting high-level qualifier will be determined by the EHLQ value from the LIKE log stream or using a default value.
,EHLQ=NO_EHLQ
,EHLQ=ehlq
Specifies the name (or address in a register) of a 33-byte input field containing the extended high-level qualifier for both the log stream data set name and the staging data set name.
Syntax requirements for the extended high-level qualifier are as follows: v The extended high-level qualifier must be 33 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary.
v The value can be made up of one or more qualifiers (each 1 to 8 characters) separated by periods, up to the maximum length of 33 characters.
v Each qualifier must contain up to eight alphabetic, national, or numeric characters. Lowercase alphabetic characters will be folded to uppercase.
v The first character of each qualifier must be an alphabetic or national character.
v Each qualifier must be separated by a period, which you must count as a character.
v The resulting length of concatenating the significant characters from the
EHLQ value with the STREAMNAME value (including the period delimiter) cannot exceed 35 characters.
EHLQ and HLQ are mutually exclusive and cannot be specified for the same log stream definition.
When the EHLQ parameter is not explicitly specified on the request, the resulting high-level qualifier to be used for the log stream data sets will be based on whether the HLQ or LIKE parameters are specified. If the HLQ parameter is specified, that value will be used for the log stream data sets.
When no high-level qualifier is explicitly specified on the DEFINE
LOGSTREAM request, but the LIKE parameter is specified, the the high-level qualifier value being used in the referenced log stream will be used for the newly defined log stream. If the EHLQ, HLQ, and LIKE parameters are not specified, the default value “IXGLOGR” will be used.
If the name specified for the EHLQ parameter refers to a field that contains
X'00', the macro will be invoked as if NO_EHLQ had been specified. However, specifying EHLQ=NO_EHLQ and HLQ=hlq on the same request results in an error. When EHLQ=NO_EHLQ is specified, the resulting high-level qualifier will be determined by the HLQ value from the LIKE log stream or using a default value.
The active primary TYPE=LOGR couple data set must be formatted at a
HBB7705 or higher level in order to specify the EHLQ keyword. Otherwise, the request will fail with return code 8, reason code X'0839'.
,LOWOFFLOAD=0
,LOWOFFLOAD=lowoffload
Specifies the name (or address in a register) of an 4-byte input field containing
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
669
IXGINVNT macro
the percent value you want to use as the low offload threshold for the coupling facility structure associated with this log stream. The low offload threshold is the target percent where you want offloading to stop, leaving approximately the specified LOWOFFLOAD percentage of log data in the coupling facility structure.
If you specify LOWOFFLOAD=0, which is the default, or omit the
LOWOFFLOAD parameter, system logger uses the 0% usage mark as the low offload threshold where offloading stops, leaving 0% of the data in the coupling facility.
The value specified for LOWOFFLOAD must be less than the HIGHOFFLOAD value.
,HIGHOFFLOAD=80
,HIGHOFFLOAD=highoffload
Specifies the name (or address in a register) of an 4-byte input field containing the percent value you want to use as the high offload threshold for the coupling facility structure associated with this log stream. When the coupling facility is filled to the high offload threshold percentage or beyond, system logger begins offloading data from the coupling facility to the DASD log stream data sets.
If you specify HIGHOFFLOAD=80, which is the default, HIGHOFFLOAD=0, or omit the HIGHOFFLOAD parameter, system logger uses the 80% usage mark as the high offload threshold where offloading starts.
IBM recommends that you do not define your HIGHOFFLOAD value to greater than the default of 80%. Defining a higher high offload threshold can leave you vulnerable to filling your coupling facility space for the log stream, which means that system logger will reject all write requests until the coupling facility log data can be offloaded to DASD log data sets.
The value specified for HIGHOFFLOAD must be higher than the
LOWOFFLOAD value.
,WARNPRIMARY=NO_WARNPRIMARY
,WARNPRIMARY=NO
,WARNPRIMARY=YES
is an optional keyword input that specifies whether monitoring warning messages should be issued based on the log stream primary (interim) storage consumption above the HIGHOFFLOAD value.
The active primary TYPE=LOGR couple data set must be formatted at an
HBB7705 (or higher) format level in order to specify WARNPRIMARY=YES.
Otherwise, the request will fail with return code 8, reason code X’0839’. See
'LOGR parameters for format utility' in z/OS MVS Setting Up a Sysplex for more details.
If you omit the WARNPRIMARY parameter, the result will be the same as if you coded the NO_WARNPRIMARY option.
DEFAULT: NO_WARNPRIMARY
NO_WARNPRIMARY
Indicates that the WARNPRIMARY(NO) attribute should be used for the log stream unless the LIKE parameter is specified. If the LIKE parameter is specified, the WARNPRIMARY value will be copied from the referenced
LIKE log stream entry.
NO
Indicates that the primary storage consumption monitoring warning messages will not be issued for the log stream.
670
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
YES
Indicates that log stream monitoring warning messages should be issued for the following conditions: v When the log stream primary (interim) storage consumption is 2/3 between the HIGHOFFLOAD value and 100% full (rounded down to the nearest whole number). This is called the log stream imminent alert threshold.
For example, assume the default value is used for the HIGHOFFLOAD percentage. That would mean a HIGHOFFLOAD value of 80 would be used, so the warning messages would be triggered for this case at (2(100
- 80)/3 +80) = 93%.
v For a CF based log stream, when a 90% entry full condition is encountered.
v
When an interim (primary) storage full condition is encountered.
For more details on the messages and monitoring primary storage consumption, see z/OS MVS Setting Up a Sysplex.
Note:
The value can be overridden on the system level by logger parameter options for IXGCNF keyword
CONSUMPTIONALERT(SUPPRESS).
,OFFLOADRECALL=YES
,OFFLOADRECALL=NO
,OFFLOADRECALL=NO_OFFLOADRECALL
Specifies whether or not offload processing is to skip recalling the current offload data set.
This keyword can be updated even when the log stream is actively connected.
The change will immediately be reflected in the log stream definition. It will take effect on the subsequent first connection to the log stream in the sysplex.
For a structure-based log stream, the change will also take effect during the next structure rebuild.
Specifying OFFLOADRECALL=YES indicates that offload processing should recall a migrated current offload data set.
Specifying OFFLOADRECALL=NO indicates that offload processing should not recall the current offload data set and allocate a new one. Also with this setting, Logger will not wait on any ENQ serialization contention to be resolved and will receive a class 2 type error (unavailable system resource) as described in z/OS MVS Programming: Authorized Assembler Services Guide in topic Interpreting error reason codes from DYNALLOC.
Note that this option can cause any or all of the current offload data set to be wasted space on DASD once it is recalled. Care should be taken when using this option to size the data sets appropriately.
If you specify OFFLOADRECALL=NO_OFFLOADRECALL, system logger uses the default OFFLOADRECALL value, unless the LIKE parameter is specified. If the LIKE parameter is specified, the OFFLOADRECALL value is copied from the referenced like log stream entry.
,LIKE=NO_LIKE
,LIKE=like_streamname
Specifies the name (or address in a register) of a 26-byte input field containing the name of a log stream that has already been defined in the LOGR policy.
The characteristics of the already-defined log stream, such as storage class, management class, high level qualifier, and data class will be copied for the log
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
671
IXGINVNT macro
stream you are currently defining. However, the parameters explicitly coded on this request override the characteristics of the log stream specified on the LIKE parameter.
The stream name must be 26 characters, padded on the right with blanks if necessary. The name can be made up of one or more segments separated by periods, up to the maximum length of 26 characters. The following rules apply: v Each segment contains up to eight numeric, alphabetic, or national ($, #, or
@) characters.
v The first character of each segment must be an alphabetic or national character.
v Each segment must be separated by periods, which you must count as characters.
,MODEL=NO
,MODEL=YES
Specifies whether the log stream being defined in the LOGR policy is a model, exclusively for use with the LIKE parameter to set up general characteristics for other log stream definitions.
If you specify MODEL=NO, which is the default, the log stream being defined is not a model log stream. Systems can connect to and use this log stream. It can also be specified on the LIKE parameter, but is not exclusively for use as a model.
If you specify MODEL=YES, the log stream being defined is only a model log stream. It can only be specified as a model for other log stream definitions on the LIKE parameter in other IXGINVNT requests.
v Programs cannot connect to a log stream name that is defined as a model
(MODEL=YES) using an IXGCONN request.
v No log stream data sets are allocated on behalf of a model log stream.
v The attributes of a model log stream are syntax checked at the time of the request, but not verified until a another log stream references the model log stream on the LIKE parameter.
,DIAG=NO
,DIAG=YES
,DIAG=NO_DIAG
Specifies whether or not dumping or additional diagnostics should be provided by Logger for certain conditions. See the DIAG keyword on the
IXGCONN, IXGBRWSE and IXGDELET macro services.
If you specify DIAG=NO, which is the default, no special Logger diagnostic activity is requested for this logstream regardless of the DIAG specifications on the IXGCONN, IXGDELET and IXGBRWSE requests.
Specifying DIAG=YES indicates that special logger diagnostic activity is allowed for this log stream: v Informational LOGREC software symptom records (denoted by RETCODE
VALU/H00000004) as well as other external alerts highlighting suboptimal conditions. For additional details, see z/OS MVS Diagnosis: Reference,
"Enabling additional log stream diagnostics".
v When the appropriate specifications are provided on IXGCONN, IXGDELET or IXGBRWSE requests by the exploiting application, further additional diagnostics may be captured. See z/OS MVS Programming: Assembler Services
Guide, "Dumping on data loss (804-type) conditions" for more details.
672
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
If you specify DIAG=NO_DIAG, system logger uses the default DIAG value, unless the LIKE parameter is specified. If the LIKE parameter is specified, the
DIAG value is copied from the referenced like log stream entry.
,ZAI=NO
,ZAI=YES
,ZAI=NO_ZAI
Optional keyword that specifies whether the log stream data should be included in the z/OS IBM zAware log stream client data sent to the IBM zAware server.
The active primary TYPE=LOGR couple data set must be formatted at the
HBB7705 format level or higher in order to specify ZAI=YES. Otherwise, the request will fail with return code 8, reason code X'0839'. See 'LOGR parameters for format utility' in z/OS MVS Setting Up a Sysplex.
If you omit this parameter, the result will be the same as if you coded te
NO_ZAI option.
If you specify NO, it indicates that the log stream data will not be included in data sent from the z/OS IBM zAware log stream client to the IBM zAware server. No is the default.
If you specify YES, it indicates that the log stream data will be included in the data sent to the IBM zAware server provided that the z/OS IBM zAware log stream client is established. Refer to Preparing for z/OS IBM zAware log stream client usage in z/OS MVS Setting Up a Sysplex.
If you specify NO_ZAI, it indicates that the default ZAI=NO attribute should be used for the log stream unless the LIKE parameter is specified. If the LIKE parameter is specified, the ZAI value will be copied from the referenced LIKE log stream entry. Care needs to be taken to ensure any newly defined log streams do not have the ZAI=YES designation unless that is the absolute intention.
,ZAIDATA=NO_ZAIDATA
,ZAIDATA=Xzaidata
Is the name (RS-type), or address in register (2)-(12), of an optional 48 character input that specifies a value, if any, to be passed to the IBM zAware server when the z/OS IBM zAware log stream client is established (refer to
ZAI=YES) keyword specification).
The value you specify is defined by and must match the intended log data type and capabilities of the IBM zAware server. See Preparing for z/OS IBM zAware log stream client usage in z/OS MVS Setting Up a Sysplex for more details on establishing and using z/OS IBM zAware log stream clients.
The active primary TYPE=LOGR couple data set must be formatted at the
HBB7705 format level or higher in order to specify the ZAIDATA keyword option. Otherwise the request will fail with return code 8, reason code X'0839'.
See 'LOGR parameters for format utility' in z/OS MVS Setting Up a Sysplex for more details.
Specifying NO_ZAIDATA indicates that a null value will be used for the log stream ZAIDATA attribute.
Specifying Xzaidata indicates the name of the input variable containing the value. The value must be 48 characters long and padded on the right with blanks if necessary.
Valid characters are alphanumeric or national ($, #, @) characters, and any of the special (graphical) characters listed below. Lower case alphabetic characters
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
673
IXGINVNT macro
will be folded to upper case. Any other characters will be converted into an
EBCDIC blank X'40', Valid special (graphical) characters:
Table 39. Valid special (graphical) characters:
Character Name
EBCDIC blank
Cent sign
Period
Less than sign
Left parenthesis
Plus sign
Or sign
Ampersand
Exclamation point
Asterisk
Right parenthesis
Semicolon
Not sign
Minus sign (hyphen)
Slash
Comma
Percent Sign
Underscore
Greater than sign
Question mark
Emphasis mark
Colon
Apostrophe
Equal sign
Quote
Tilde
Left brace
Right brace
Backslash
Symbol
;
)
!
*
¬
|
&
(
+
.
<
<blank>
¢
}
\
{
~
=
"
'
:
>
?
%
_
}
-
,
/
Hexidecimal (EBCDIC)
X'6C'
X'6D'
X'6E'
X'6F'
X'79'
X'7A'
X'7D'
X'7E'
X'7F'
X'A1'
X'C0'
X'D0'
X'E0'
X'5A'
X'5C'
X'5D'
X'5E'
X'5F'
X'60'
X'61'
X'6B'
X'40'
X'4A'
X'4B'
X'4C'
X'4D'
X'4E'
X'4F'
X'50'
If the resulting Xzaidata parameter value contains all X'40' (blanks), the
ZAIDATA keyword will be treated as if NO_ZAIDATA had been specified. The
NO_ZAIDATA is the default.
If you omit the ZAIDATA parameter, the default will be used unless the LIKE parameter is specified. If the LIKE parameter is specified, the ZAIDATA value will be copied from the referenced LIKE log stream entry.
If you specify the ZAIDATA parameter, the value will always override one specified on a model log stream used on the LIKE parameter.
,PLISTVER=IMPLIED_VERSION
674
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
,PLISTVER=2
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , which supports all parameters except those specifically referenced in higher versions.
v 1 , which supports both the following parameters and parameters from version 0:
– DESCRIPTION
– RMNAME
– RETPD
– AUTODELETE v 2 , which supports both the following parameters and parameters from version 0 and 1:
– DASDONLY
– LOGGERDUPLEX v 3 , which supports the following parameter and parameters from version 0, 1, and 2:
– EHLQ
To code
: Specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0, 1, 2, or 3
,RETCODE=retcode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
,MF=S
,MF=(L,list addr)
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
675
IXGINVNT macro
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
676
z/OS MVS Assembler Services Reference IAR-XCT
⌂
Syntax
name
IXGINVNT macro
REQUEST=DEFINE TYPE=STRUCTURE option of IXGINVNT
The IXGINVNT macro with the DEFINE TYPE=STRUCTURE parameters defines a coupling facility structure entry in the LOGR policy for a coupling facility log stream.
Syntax for REQUEST=DEFINE TYPE=STRUCTURE
The standard form of the IXGINVNT REQUEST=DEFINE TYPE=STRUCTURE macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede IXGINVNT.
IXGINVNT
⌂
One or more blanks must follow IXGINVNT.
REQUEST=DEFINE
,TYPE=STRUCTURE
,ANSAREA=ansarea
,ANSLEN=anslen
,STRUCTNAME=structname
,LOGSNUM=logsnum
,MAXBUFSIZE=maxbufsize
,AVGBUFSIZE=avgbufsize
ansarea: RS-type address or register (2) - (12).
anslen: RS-type address or register (2) - (12).
structname: RS-type address or register (2) - (12).
Default
: NO_STRUCTNAME
logsnum: RS-type address or register (2) - (12).
maxbufsize: RS-type address or register (2) - (12).
Default
: 65532
avgbufsize: RS-type address or register (2) - (12).
Default
: 1/2 of maxbufsize
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
,PLISTVER=2
Default
: IMPLIED_VERSION
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
677
IXGINVNT macro
Syntax
,PLISTVER=3
,RETCODE=retcode
,RSNCODE=rsncode
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Description
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: MF=S
Parameters for REQUEST=DEFINE,TYPE=STRUCTURE
The parameters are explained as follows:
REQUEST=DEFINE
Requests that an entry for a log stream or coupling facility structure be defined in the LOGR policy.
,TYPE=STRUCTURE
Indicates that the entry to be defined in the LOGR policy is a coupling facility entry being defined for a coupling facility log stream.
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,STRUCTNAME=structname
When specified with TYPE=STRUCTURE, specifies the name (or address in a register) of a 16-byte input field that contains the name of the coupling facility structure you are defining to the LOGR policy.
STRUCTNAME is required for TYPE=STRUCTURE.
The following rules apply for the structname:
678
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
v It can contain numeric, alphabetic, or national ($, #, or @) characters, or an underscore(_), padded on the right with blanks if necessary.
v
The first character must be an alphabetic character.
,LOGSNUM=logsnum
Specifies the name (or address in a register) of a 4-byte input field that contains the number of log streams that can be allocated to the coupling facility structure being defined in the LOGR policy. logsnum must be a value between 1 and 512.
IBM recommends
that you keep the value for LOGSNUM as small as possible, particularly if your coupling facility structure is small. The more log streams that map to a coupling facility, the less coupling facility space for each log stream and the more chance you stand of running out of space for log streams.
See z/OS MVS Programming: Assembler Services Guide for more information.
LOGSNUM is required for TYPE=STRUCTURE.
,MAXBUFSIZE=maxbufsize
Specifies the name (or address in a register) of a 4-byte input field that contains the size, in bytes, of the largest log block that can be written to log streams allocated to the coupling facility specified in this request.
The value for MAXBUFSIZE must be between 1 and 65,532 bytes. The default is 65,532 bytes.
,AVGBUFSIZE=avgbufsize
Specifies the name (or address in a register) of a 4-byte input field of the average size, in bytes, of log blocks written to all the log streams using this coupling facility structure.
System logger uses the average buffer size to control the entry-to-element ratio for this coupling facility structure.
The system logger uses the AVGBUFSIZE specified simply to make an initial determination of the entry-to-element ratio for the structure. After that, system logger monitors structure usage and dynamically manages the entry-to-element ratio accordingly. System logger uses the last entry-to-element ratio in effect for a structure for subsequent structure reallocation requests.
avgbufsize must be between 1 and the value for MAXBUFSIZE. The default value is 1/2 of the MAXBUFSIZE value.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
,PLISTVER=2
,PLISTVER=3
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX
, if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
679
IXGINVNT macro
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , which supports all parameters except those specifically referenced in higher versions.
To code
: Specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0, 1, 2, or 3
,RETCODE=retcode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms in the following order:
680
z/OS MVS Assembler Services Reference IAR-XCT
⌂
Syntax
name
IXGINVNT macro
v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v
Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
REQUEST=UPDATE option of IXGINVNT
The IXGINVNT macro with the UPDATE parameter allows a program to update a log stream entry in the LOGR policy for a coupling facility or DASD-only log stream. Except for the RETPD and AUTODELETE parameters, note that you cannot update a log stream while there are active connections to it.
Syntax for REQUEST=UPDATE
The standard form of the IXGINVNT REQUEST=UPDATE macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede IXGINVNT.
IXGINVNT
⌂
One or more blanks must follow IXGINVNT.
REQUEST=UPDATE
,TYPE=LOGSTREAM
,ANSAREA=ansarea
,ANSLEN=anslen
ansarea: RS-type address or register (2) - (12).
anslen: RS-type address or register (2) - (12).
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
681
IXGINVNT macro
Syntax
,STREAMNAME=streamname
,NEWSTREAMNAME=newstreamname
,GROUP=PRODUCTION
,GROUP=TEST
,STRUCTNAME=structname
,RMNAME=rmname
,DESCRIPTION=description
,MAXBUFSIZE=maxbufsize
,LOGGERDUPLEX=UNCOND
,LOGGERDUPLEX= COND
,STG_DUPLEX=NO
,STG_DUPLEX=YES
,DUPLEXMODE=COND
,DUPLEXMODE=UNCOND
,DUPLEXMODE=DRXRC
,STG_MGMTCLAS=stg_mgmtclas
,STG_DATACLAS=stg_dataclas
,STG_STORCLAS=stg_storclas
,STG_SIZE=stg_size
,LS_ALLOCAHEAD={xls_allocahead | *}
,LS_MGMTCLAS=ls_mgmtclas
,LS_DATACLAS=ls_dataclas
682
z/OS MVS Assembler Services Reference IAR-XCT
Description
streamname: RS-type address or register (2) - (12).
newstreamname: RS-type address or register (2) - (12).
Default
: GROUP=PRODUCTION
structname: RS-type address or register (2) - (12).
rmname: RS-type address or register (2) - (12).
description: RS-type address or register (2) - (12).
maxbufsize: RS-type address or register (2) - (12).
Default
: LOGGERDUPLEX=UNCOND
Default
: DUPLEXMODE=COND
stg_mgmtclas: RS-type address or register (2) - (12).
stg_dataclas: RS-type address or register (2) - (12).
stg_storclas: RS-type address or register (2) - (12).
stg_size: RS-type address or register (2) - (12).
xls_allocahead: RS-type address or register (2) - (12).
Default
: *
ls_mgmtclas: RS-type address or register (2) - (12).
ls_dataclas: RS-type address or register (2) - (12).
IXGINVNT macro
Syntax Description
,LS_STORCLAS=ls_storclas
,LS_SIZE=ls_size
,RETPD=retpd
ls_storclas: RS-type address or register (2) - (12).
ls_size: RS-type address or register (2) - (12).
retpd: RS-type address or register (2) - (12).
Default
: NO_RETPD
Default
: AUTODELETE=NO ,AUTODELETE=NO
,AUTODELETE=YES
,LOWOFFLOAD=lowoffload
,HIGHOFFLOAD=highoffload
,WARNPRIMARY=NO_WARNPRIMARY
,WARNPRIMARY=YES
,WARNPRIMARY=NO
,OFFLOADRECALL=NO
,OFFLOADRECALL=YES
,DIAG=NO_DIAG
,DIAG=NO
,DIAG=YES
,ZAI=NO
,ZAI=YES
,ZAI=NO_ZAI
,ZAIDATA=NO_ZAIDATA
,ZAIDATA=Xzaidata
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
,PLISTVER=2
,PLISTVER=3
,RETCODE=retcode
lowoffload: RS-type address or register (2) - (12).
highoffload: RS-type address or register (2) - (12).
Default
: WARNPRIMARY=NO_WARNPRIMARY
Default
: OFFLOADRECALL=NO_OFFLOADRECALL
Default
: DIAG=NO_DIAG
Default
: ZAI=NO
Default
: ZAIDATA=NO_ZAIDATA
Default
: IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
683
IXGINVNT macro
Syntax
,RSNCODE=rsncode
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Description
rsncode: RS-type address or register (2) - (12).
Default
: MF=S
Parameters for REQUEST=UPDATE
The parameters are explained as follows:
REQUEST=UPDATE
Requests that an entry for a log stream be updated in the LOGR policy.
,TYPE=LOGSTREAM
Requests that the entry to be updated in the LOGR policy is a log stream entry.
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,STREAMNAME=streamname
Specifies the name (or address in a register) of the 26-byte input field containing the name of the log stream that you want to define in the LOGR policy.
The stream name must be 26 characters, padded on the right with blanks if necessary. The name can be made up of one or more segments separated by periods, up to the maximum length of 26 characters. The following rules apply: v Each segment can contain up to eight numeric, alphabetic, or national ($, #, or @) characters.
v The first character of each segment must be an alphabetic or national character.
v Each segment must be separated by periods, which you must count as characters.
684
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
STREAMNAME is required with the TYPE=LOGSTREAM parameter.
NEWSTREAMNAME={newstreamname|NO_NEWSTREAMNAME}
Specifies a new name for the log stream identified in the STREAMNAME parameter. With this keyword, you can maintain the current data in a log stream under a new name and get new work going after timely defining a new instance of the log stream with the original name. This keyword is the name
(RS-type), or address in register (2)-(12), of an optional 26 character input that specifies the new name that should be assigned to the log stream being updated as identified on the STREAMNAME parameter.
The new log stream name must be 26 characters long, padded on the right with blanks if necessary. Lowercase alphabetic characters will be folded to uppercase. The name is made up of one or more segments, up to the maximum length of 26 characters. Each segment can validly contain 1-8 numeric characters, alphabetic characters, or national ($, #, @) characters.
Segments are joined by periods. The first character of each segment must be an alphabetic or national ($, #, @) character.
For detailed description about this keyword, see Renaming a log stream dynamically in z/OS MVS Setting Up a Sysplex.
Omitting the NEWSTREAMNAME parameter will not affect the current name of the log stream. If NO_NEWSTREAMNAME is specified for
NEWSTREAMNAME, the macro will be invoked as if the
NEWSTREAMNAME parameter was not specified.
The default is NO_NEWSTREAMNAME.
GROUP=(PRODUCTION | TEST)
An optional keyword input that lets you specify whether the log stream is in the test group or the production group. This keyword allows you to keep processing and resources for log streams in the two groups separate on a single system, including requests such as data set allocation and data set recalls. If the TEST group fails, the failure does not normally affect the PRODUCTION group. You can only specify the GROUP parameter on an UPDATE request when: v The LOGR couple data set for the sysplex is formatted at the HBB7705 level or higher.
v The structure has no log streams, failed or active, connected. (The request will fail with return code 8, reason code X'0810' if there are connectors to the structure.)
If you specify GROUP(PRODUCTION), System logger places this log stream in the PRODUCTION group. A PRODUCTION log stream can use at least 75% of the system logger couple data set DSEXTENT records and connection slots.
If you specify GROUP(TEST), system logger places this log stream in the TEST group. TEST log streams are limited to at most 25% of the system logger couple data set DS EXTENT records and connection slots.
The GROUP value you specify must match the group setting for the structure that the log stream is being defined for, because system logger does not allow you to define a mixture of TEST and PRODUCTION log streams to a single structure. When you define the first log stream to a structure, the structure becomes either a TEST or PRODUCTION structure. After that, the GROUP value for subsequent log streams defined to a structure must match the
GROUP value of the initial log stream. For example, if you specify or default to GROUP(PRODUCTION) for the first log stream defined to a structure, you
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
685
IXGINVNT macro
will only be able to define PRODUCTION log streams to that structure
subsequently. See “Example 11” on page 757.
If you update a log stream from PRODUCTION to TEST, this might affect the
DS EXTENT records allocation because the limit changes from 75% to 25% of the system logger couple data set DS EXTENT records and connection slots.
The system will issue message IXC270I indicating that there is a shortage of DS
EXTENT records for TEST log streams. If you update a log stream from TEST to PRODUCTION, more DS EXTENTS will be available to the log stream and message IXG270I might be DOMed.
To update the log stream GROUP type for an existing structure, you need to take one of the following actions: v Remove all of the log streams from the structure and define a log stream of the desired type to the structure. The log stream will accept only log streams of that type in the future.
v Issue an update request against the last remaining structure in a group to change it to the desired GROUP.
,STRUCTNAME=structname
With REQUEST=UPDATE, specifies the name (or address in a register) of a
16-byte input field containing the name of the coupling facility list structure where all of this log stream's log blocks will be written before being offloaded to DASD. This keyword is allowed when there are no connections (failed or active) to the log stream in the sysplex; otherwise the UPDATE request will be rejected with return code 8, reason code X'0810'.
This keyword can be specified when the existing log stream to be modified is a
DASD only log stream. With specification of this keyword, the DASD only log stream will be upgraded to use a coupling facility structure and become a structure-based log stream.
When the active primary LOGR couple data set in the sysplex is formatted at a
HBB7705 level or higher, this keyword can also be specified for a log stream that is currently structure-based in order to update the log stream to use a different coupling facility structure. If the LOGR couple data set is not formatted at the appropriate level, the request will fail with return code 8, reason code X'0839'.
STRUCTNAME must be 16 alphanumeric or national ($,#,or @) characters, or underscore (_), padded on the right with blanks if necessary. Lowercase alphabetic characters will be folded to uppercase. The first character must be alphabetic.
Note that the MAXBUFSIZE value in the structure definition for this structure must be equal to or greater than the MAXBUFSIZE specified for the log stream before the update. Otherwise, the UPDATE request will be rejected with a return code 8, reason code X'083C'.
,RMNAME=rmname
Specifies the name (or address in a register) of the 8-byte input field containing the name of the resource manager program associated with the log stream.
RNAME must be 8 alphanumeric or national ($,#,or @) characters, padded on the right with blanks if necessary.
You must define RMNAME in the LOGR policy before the recovery resource manager can connect to the log stream.
If you specify RMNAME to associate a resource manager with a log stream in the LOGR policy, the resource manager specified must subsequently connect to
686
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
the log stream. If the resource manager does not connect to that log stream, system logger will not process any IXGDELET requests to delete log data. This is so that the resource manager will not miss any delete requests issued against the log stream.
,DESCRIPTION=description
Specifies the name (or address in a register) of the 16 character input field containing user defined data describing the log stream.
DESCRIPTION must be 16 alphanumeric or national ($,#,@) characters, underscore (_) or period (.), padded on the right with blanks if necessary.
,MAXBUFSIZE=maxbufsize
Specifies the name (or address in a register) of a fullword input field that contains the size, in bytes, of the largest log block that can be written to this
DASD-only log stream.
The value for MAXBUFSIZE must be between 1 and 65,532 bytes and cannot be less than the current MAXBUFSIZE for the DASD-only log stream.
This keyword can be updated even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 format level. The change will be immediately reflected in the log stream definition, but will not take effect until the subsequent first connection to the DASD-only log stream in the sysplex.
There is no default for the MAXBUFSIZE parameter on an UPDATE request. If you omit this parameter, there will be no change to the MAXBUFSIZE value for this log stream definition.
,LOGGERDUPLEX=UNCOND
,LOGGERDUPLEX=COND
An optional input keyword specifies whether system logger continues to provide its own log data duplexing, or, conditionally, not provide its own duplexing based on an alternative duplexing configuration that provides an equivalent or better recoverability of the log data.
The active primary TYPE=LOGR couple data set in the sysplex must be formatted at HBB7705 or higher to specify this keyword. Otherwise, the request fails with a return code 8, reason code X'0839'.
For DASD only log streams:
You are allowed to specify LOGGERDUPLEX(UNCOND), however, it will have no effect on the log stream as DASD only log streams are unconditionally duplexed to staging data sets. If you specify LOGGERDUPLEX(COND), the request will fail unless you are upgrading a DASD only log stream to a coupling facility log stream.
This keyword can be specified even when the log stream is actively connected when the LOGR couple data set is formatted at HBB7705 or higher. If a lower format level LOGR couple data set is being used, the request will fail with a return code 8, reason code X'0810'.
The change will be immediately reflected in the log stream definition. It will take effect on the subsequent first connection to the log stream in the sysplex or following a successful coupling facility user-managed structure rebuild.
Omitting the Update log stream LOGGERDUPLEX parameter will not change how system logger handles the duplexing of the log stream's log data.
See z/OS MVS Setting Up a Sysplex sections " logger and Coupling Facility
Duplexing Combinations" and "System logger Recovery" for additional
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
687
IXGINVNT macro
considerations on using the LOGGERDUPLEX keyword. Refer to Case 5 in
Logger and coupling facility duplexing combinations in z/OS MVS Setting Up a
Sysplex for additional details about the LOGGERDUPLEX parameter and a coupling facility log stream.
LOGGERDUPLEX=UNCOND, which is the default, indicates that system logger should provide its own specific duplexing of the log data regardless of any other duplexing (such as structure -system-managed duplexing rebuild) that occur.
LOGGERDUPLEX=COND indicates that system logger should provide its own specific duplexing of the log data unless the log stream is in an alternative duplexing configuration that provides an equivalent or better recoverability of the log data. For example, system logger does not provide its own duplexing of the log data in the following configuration: v when the log stream is in a non-volatile CF list structure that is handled by system-managed duplexing rebuild. (duplex-mode), v there is a failure-independent relationship between the two structure instances, and v there is a failure-independent connection between connecting system and composite structure view.
,STG_DUPLEX=NO
,STG_DUPLEX=YES
Specifies whether the log stream data for a coupling facility log stream should be considered for duplexing in DASD staging data sets.
This keyword can be specified even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 format level. If a lower format level LOGR couple data set is being used, the request will fail with return code 8, reason code X'0810'.
The change will be immediately reflected in the log stream definition. It will take effect on the subsequent first connection to the log stream in the sysplex or following a successful coupling facility user-managed structure rebuild.
If you specify STG_DUPLEX=NO, log data for a coupling facility log stream is not duplexed in staging data sets, regardless of the failure independence/dependence coupling facility. The coupling facility resident log data will be duplexed in the local buffers of the z/OS Version 1 Release 7 and higher release levels, with z/OS image that wrote the data. A coupling facility is considered failure independent when it is non-volatile and resides on a different CPC from the MVS image using it. Otherwise, the coupling facility is failure dependent.
If you specify STG_DUPLEX=YES, the log data for a coupling facility log stream will be duplexed in staging data sets if the conditions defined by the
DUPLEXMODE keyword are fulfilled.
For DASD only log streams:
You are allowed to specify STG_DUPLEX=YES, however, it will have no effect on the log stream as DASD only log streams are unconditionally duplexed to staging data sets. If you specify STG_DUPLEX=NO, the request will fail unless you are upgrading a DASD only log stream to a coupling facility log stream.
There is no default for the STG_DUPLEX keyword on an UPDATE request. If you omit this keyword, there is no change to the staging duplexing status for the log stream definition.
688
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|
IXGINVNT macro
You can use the DUPLEXMODE keyword with STG_DUPLEX and with
LOGGERDUPLEX to specify the type of duplexing desired and whether you want conditional or unconditional duplexing by logger.
,DUPLEXMODE=COND
,DUPLEXMODE=UNCOND
Specifies the conditions under which the coupling facility log data for a coupling facility log stream should be duplexed in DASD staging data sets.
If you specify DUPLEXMODE=COND, the coupling facility log data will be duplexed in staging data sets only if a system's connection to the coupling facility log stream contains a single point of failure and is therefore vulnerable to permanent log data loss: v A connection to a log stream contains a single point of failure if the coupling facility is volatile and/or resides on the same CPC as the MVS system connecting to it. The coupling facility log data for the system connection containing the single point of failure will be duplexed to staging data sets..
v A connection to a log stream is failure-independent when the coupling facility for the log stream is non-volatile and resides on a different central processor complex (CPC) than the MVS system connecting to it. The coupling facility log data for that system connection will not be duplexed to staging data sets..
If you specify DUPLEXMODE=UNCOND, the log data for the coupling facility log stream will be duplexed in staging data sets, unconditionally, even if the connection is failure independent.
Note:
If DUPLEXMODE(DRXRC) is specified, the log data is duplexed same as if the COND option is specified. This means that in staging data sets, if a system's connection to the coupling facility log stream contains a single point of failure, it is therefore vulnerable to permanent log data loss. For more information, see the CONF DUPLEXMODE option.
Note:
The staging data set keywords STG_SIZE, STG_DATACLAS,
STG_MGMTCLAS, and STG_STORCLAS will remain set for the log stream and can be used for any dynamic staging data set allocation during local recovery even after the conversion to STG_DUPLEX=NO.
This keyword can be specified even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 level. If a lower format level LOGR couple data set is being used, the request will fail with return code 8, reason code X'0810'.
The change will be immediately reflected in the log stream definition. It will take effect on the subsequent first connection to the log stream in the sysplex or following a successful coupling facility user-managed structure rebuild.
There is no default for the DUPLEXMODE keyword on an UPDATE request. If you omit this keyword, there will be no change to the duplexing mode for the coupling facility log stream definition.
You can use the DUPLEXMODE keyword with STG_DUPLEX and with
LOGGERDUPLEX to specify the type of duplexing desired and whether you want conditional or unconditional duplexing by logger.
See z/OS MVS Programming: Assembler Services Guide for complete information about using staging data sets to duplex coupling facility log data.
DUPLEXMODE is valid only when STG_DUPLEX=YES has been specified for a coupling facility log stream.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
689
IXGINVNT macro
For DASD only log streams, you are allowed to specify
DUPLEXMODE=UNCOND, however, it will have no effect on the log stream as DASD only log streams are unconditionally duplexed to staging data sets. If you specify DUPLEXMODE=COND, the request will fail unless you are upgrading a DASD only log stream to a coupling facility log stream.
Note:
DUPLEXMODE may only be updated for a log stream that uses staging datasets. See STG_DUPLEX keyword.
,STG_DATACLAS=stg_dataclas
Specifies the name (or address in a register) of an 8-byte input field containing the name of the SMS data class that will be used for allocation of the DASD staging data set for this log stream.
The data class must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
This keyword can be updated even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 format level. If a lower format level LOGR couple data set is being used, the request will fail with return code 8, reason code X'0810'. The change will be immediately reflected in the log stream definition. It will take effect on the subsequent first connection to the log stream in the sysplex. For a structure-based log stream, the change will also take effect during the next structure rebuild.
An SMS value specified on the STG_DATACLAS parameter, including
NO_STG_DATACLAS, always overrides one specified on a model log stream used on the LIKE parameter.
There is no default for the STG_DATACLAS parameter on an UPDATE request. If you omit this parameter, there will be no change to the data class for staging data sets for this log stream definition.
STG_DATACLAS is only valid with STG_DUPLEX=YES or DASDONLY=YES.
,STG_MGMTCLAS=stg_mgmtclas
Specifies the name (or address in a register) of an 8-byte input field containing the name of the SMS management class that will be used for allocation of the
DASD staging data set for this log stream.
The management class must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
This keyword can be updated even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 format level. If a lower format level LOGR couple data set is being used, the request will fail with return code 8, reason code X'0810'. The change will be immediately reflected in the log stream definition. It will take effect on the subsequent first connection to the log stream in the sysplex. For a structure-based log stream, the change will also take effect during the next structure rebuild.
An SMS value specified on the STG_MGMTCLAS parameter, including
NO_STG_MGMTCLAS, always overrides one specified on a model log stream used on the LIKE parameter.
There is no default for the STG_MGMTCLAS parameter on an UPDATE request. If you omit this parameter, there will be no change to the management class for staging data sets for this log stream definition.
STG_MGMTCLAS is only valid with STG_DUPLEX=YES or DASDONLY=YES.
690
z/OS MVS Assembler Services Reference IAR-XCT
|
|
IXGINVNT macro
,STG_STORCLAS=stg_storclas
Specifies the name (or address in a register) of an 8-byte input field containing the name of the SMS storage class that will be used for allocation of the DASD staging data set for this log stream.
The storage class must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
This keyword can be updated even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 format level. If a lower format level LOGR couple data set is being used, the request will fail with return code 8, reason code X'0810'. The change will be immediately reflected in the log stream definition. It will take effect on the subsequent first connection to the log stream in the sysplex. For a structure-based log stream, the change will also take effect during the next structure rebuild.
An SMS value specified on the STG_STORCLAS parameter, including
NO_STG_STORCLAS, always overrides one specified on a model log stream used on the LIKE parameter.
There is no default for the STG_STORCLAS parameter on an UPDATE request.
If you omit this parameter, there will be no change to the storage class for staging data sets in this log stream definition.
STG_STORCLAS is only valid with STG_DUPLEX=YES or DASDONLY=YES.
,STG_SIZE=stg_size
Specifies the name (or address in a register) of a 4-byte input field containing the size, in 4K blocks, of the DASD staging data set for the log stream being updated.
The actual size of your data set depends on many factors including track size,
CI SIZE, and volume type, and may be smaller or larger than your parameter inputs expect. Because of this reason, see "Testing log data set parameter modifications" in z/OS MVS Setting Up a Sysplex for important notes on choosing a data set size.
Specifying STG_SIZE=0, will cause logger to make use of the SMS data class space allocation attribute of the new (if STG_DATACLAS is specified on the update) or existing STG_DATACLAS, or dynamic allocation rules if
STG_DATACLAS is not specified for DASD-only log streams, or the maximum structure size if STG_DATACLAS is not CF log streams.
Specifying STG_SIZE overrides the space allocation attribute on the
STG_DATACLAS parameter if STG_DATACLAS is specified on this update, a previous update, or define.
This keyword can be updated even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 format level. If a lower format level LOGR couple data set is used, the request will fail with return code 8, reason code X'0810'. The change will be immediately reflected in the log stream definition as a "pending update". It will take effect on the subsequent first connection to the log stream in the sysplex. For a structure-based log stream, the change will also take effect during the next structure rebuild.
Omitting this parameter causes the previous specification to remain in effect.
As of z/OS Version 2 Release 3, system logger supports staging data set sizes greater than 4GB. Use the STG_DATACLAS log stream specification and define
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
691
|
|
|
|
|
|
|
|
|
|
IXGINVNT macro
the corresponding DFSMS data class with space allocation attributes and include in the data class definition the following attributes: v
Data Set Name Type "EXT" (extended format) v Extended Addressability "Y"
Extended format is a means of storing data on a logical DASD volume.
Extended addressability is a means to allow VSAM Data Sets greater addressability beyond the 4GB address constraint.
For more information about planning and sizing for staging data sets, see Plan space for staging data sets and Set up the SMS environment for DASD data sets in z/OS MVS Setting Up a Sysplex .
LS_ALLOCAHEAD(xls_allocahead | *)
Specifies whether offload data sets should be proactively allocated and opened in advance on systems connected to the log stream. It is the name (or address in a register) of an optional full-word input. The xls_allocahead value can be from 0 to 3.
The active primary TYPE=LOGR couple data set must be formatted at an
HBB7705 or higher format level to specify this keyword. Otherwise, the request fails with return code 8 and reason code X'0839'. See “LOGR parameters for format utility” in z/OS MVS Setting Up a Sysplex for more information.
When the value is 0, logger does not proactively allocate and open advanced-current log stream offload data sets on any systems that are connected to the log stream.
When the value is between 1 and 3 (inclusively), all systems that are connected to and performing offloads for the log stream should be proactive in newly allocating up to the intended number (xls_allocahead) of advanced-current offload data sets. It also indicates these systems are proactive in opening the current offload data set as well as the first advanced-current offload data set.
The logger processing is potentially affected on a system with the
ALLOCAHEAD(NO) IXGCNFxx parmlib policy specification. See the
IXGCNFxx parmlib member in z/OS MVS Initialization and Tuning Reference for more information about the MANAGE OFFLOAD ALLOCAHEAD specification. Also see “Offloading log data from interim storage by freeing and/or moving it to DASD” in z/OS MVS Setting Up a Sysplex for more information about the logger behavior based on the ALLOCAHEAD and
LS_ALLOCAHEAD parameters.
This keyword can be updated even when the log stream is actively connected.
The change is immediately reflected as a pending update in the log stream definition. It takes effect when the next log stream offload data set is allocated
(data set switch event) or on the subsequent first connection to the log stream in the sysplex. For a structure-based log stream, the change also takes effect during the next structure rebuild. The new value is used on the subsequent log stream offload activity after the value takes effect.
The default is *. Omitting the parameter LS_ALLOCAHEAD results no change to the value for this log stream definition.
,LS_DATACLAS=ls_dataclas
Specifies the name (or address in a register) of an 8-byte input field containing the name of the SMS data class that will be used for allocation of the DASD log data set for this log stream.
692
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
The data class must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
This keyword can be updated even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 format level. If a lower format level LOGR couple data set is being used, the request will fail with return code 8, reason code X'0810'. The change will be immediately reflected in the log stream definition. It will take effect when the next log stream offload data set is allocated (data set switch event) or on the subsequent first connection to the log stream in the sysplex. For a structure-based log stream, the change will also take effect during the next structure rebuild.
An SMS value specified on the LS_DATACLAS parameter, including
NO_LS_DATACLAS, always overrides one specified on a model log stream used on the LIKE parameter.
There is no default for the LS_DATACLAS parameter on an UPDATE request.
If you omit this parameter, there will be no change to the data class for the log stream data sets for this log stream definition.
,LS_MGMTCLAS=ls_mgmtclas
Specifies the name (or address in a register) of an 8-byte input field containing the name of the SMS management class that will be used for allocation of the
DASD log data set for this log stream.
The management class must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
This keyword can be updated even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 format level. If a lower format level LOGR couple data set is being used, the request will fail with return code 8, reason code X'0810'. The change will be immediately reflected in the log stream definition. It will take effect when the next log stream offload data set is allocated (data set switch event) or on the subsequent first connection to the log stream in the sysplex. For a structure-based log stream, the change will also take effect during the next structure rebuild.
An SMS value specified on the LS_MGMTCLAS parameter, including
NO_LS_MGMTCLAS, always overrides one specified on a model log stream used on the LIKE parameter.
There is no default for the LS_MGMTCLAS parameter on an UPDATE request.
If you omit this parameter, there will be no change to the management class for the log stream data sets for this log stream definition.
,LS_STORCLAS=ls_storclas
Specifies the name (or address in a register) of an 8-byte input field containing the name of the SMS storage class that will be used for allocation of the DASD log data set for this log stream.
The storage class must be 8 alphanumeric or national ($,#, or @) characters, padded on the right with blanks if necessary. The first character must be an alphabetic or national character.
This keyword can be updated even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 format level. If a lower format level LOGR couple data set is being used, the request will fail with return code 8, reason code X'0810'. The change will be immediately reflected in the log stream definition. It will take effect when the next log
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
693
IXGINVNT macro
stream offload data set is allocated (data set switch event) or on the subsequent first connection to the log stream in the sysplex. For a structure-based log stream, the change will also take effect during the next structure rebuild.
An SMS value specified on the LS_STORCLAS parameter, including
NO_LS_STORCLAS, always overrides one specified on a model log stream used on the LIKE parameter.
There is no default for the LS_STORCLAS parameter on an UPDATE request.
If you omit this parameter, there will be no change to the storage class for the log stream data sets for this log stream definition.
,LS_SIZE=ls_size
Specifies the size, in 4K blocks, of the log stream offload DASD data sets for the log stream being updated.
The actual size of your data set depends on many factors including track size,
CI SIZE, and volume type, and may be smaller or larger than your parameter inputs expect. Because of this reason, see "Testing log data set parameter modifications" in z/OS MVS Setting Up a Sysplex for important notes on choosing a data set size.
Specifying LS_SIZE=0 will cause logger to make use of the SMS data class space allocation attribute of the new (if LS_DATACLAS is specified on the update) or existing LS_DATACLAS, or dynamic allocation rules if
LS_DATACLAS is not specified.
Specifying LS_SIZE overrides the space allocation attribute on the
LS_DATACLAS parameter if LS_DATACLAS is specified on this update, a previous update, or define.
This keyword can be updated even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 format level. If a lower format level LOGR couple data set is being used, the request will fail with return code 8, reason code X'0810'. The change will be immediately reflected in the log stream definition. It will take effect when the next log stream offload data set is allocated (data set switch event) or on the subsequent first connection to the log stream in the sysplex. For a structure-based log stream, the change will also take effect during the next structure rebuild.
Omitting this parameter causes the previous specification to remain in effect.
,AUTODELETE=NO
,AUTODELETE=YES
Specifies when system logger physically deletes log data from the log stream.
This keyword can be updated regardless of whether the log stream is actively connected or not. The change will be immediately reflected in the log stream definition. It will take effect upon the next data set switch event or on the subsequent first connection to the log stream in the sysplex.
If you specify AUTODELETE=NO, which is the default, system logger physically deletes an entire log data set only when both of the following are true: v Data is marked for deletion by a system logger application using the
IXGDELET service.
v The retention period for all the data in the log data set expires.
694
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
If you specify AUTODELETE=YES, system logger automatically physically deletes log data whenever data is either marked for deletion (using the
IXGDELET service or an archiving procedure) or the retention period for all the log data in a data set has expired.
Be careful when using AUTODELETE=YES if the system logger application manages log data deletion using the IXGDELET service. With
AUTODELETE=YES, system logger can delete data that the application expects to be accessible.
RETPD=0
RETPD=retpd
Specifies the name (or address in a register) of a fullword input field containing the number of days of the retention period for log data in the log stream. The retention period begins when data is written to the log stream.
Once the retention period for an entire log data set has expired, the data set is eligible for physical deletion. The point at which system logger physically deletes the data depends on what you have specified on the AUTODELETE parameter. System logger will not process a retention period or delete data on behalf of log streams that are not connected to or being written to by an application.
This keyword can be updated regardless of whether the log stream is actively connected or not. The change will be immediately reflected in the log stream definition. It will take effect upon the next data set switch event or on the subsequent first connection to the log stream in the sysplex.
The value specified for RETPD must be between 0 and 65,536.
,LOWOFFLOAD=lowoffload
Specifies the name (or address in a register) of a fullword input field containing the percent value you want to use as the low offload threshold for the coupling facility structure associated with this log stream. The low offload threshold is the target percent where you want offloading to stop, leaving approximately the specified LOWOFFLOAD percentage of log data in the coupling facility structure.
The value specified for LOWOFFLOAD must be less than the HIGHOFFLOAD value.
This keyword can be updated even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 format level. If a lower format level LOGR couple data set is being used, the request will fail with return code 8, reason code X'0810'. The change will immediately be reflected in the log stream definition. It will take effect on the subsequent first connection to the log stream in the sysplex. For a structure-based log stream, the change will also take effect during the next structure rebuild. For a
DASD-only log stream, the change will take effect upon the next offload data set switch event.
There is no default for the LOWOFFLOAD parameter on an UPDATE request.
If you omit this parameter, there will be no change to the low offload value for this log stream definition.
,HIGHOFFLOAD=highoffload
Specifies the name (or address in a register) of a fullword input field containing the percent value you want to use as the high offload threshold for the coupling facility structure associated with this log stream. When the
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
695
IXGINVNT macro
coupling facility is filled to the high offload threshold point or beyond, system logger begins offloading data from the coupling facility to the DASD log stream data sets.
IBM recommends
that you are careful in considering to define your
HIGHOFFLOAD value to greater than 80%. Defining a higher high offload threshold can leave you vulnerable to filling your coupling facility space for the log stream, which means that system logger will reject all write requests until the coupling facility log data can be offloaded to DASD log data sets.
The value specified for HIGHOFFLOAD must be higher than the
LOWOFFLOAD value.
This keyword can be updated even when the log stream is actively connected when the LOGR couple data set is at least at the HBB7705 format level. If a lower format level LOGR couple data set is being used, the request will fail with return code 8, reason code X'0810'. The change will immediately be reflected in the log stream definition. It will take effect on the subsequent first connection to the log stream in the sysplex. For a structure-based log stream, the change will also take effect during the next structure rebuild. For a
DASD-only log stream, the change will take effect upon the next offload data set switch event.
There is no default for the HIGHOFFLOAD parameter on an UPDATE request.
If you omit this parameter, there will be no change to the high offload value for this log stream definition.
,WARNPRIMARY=NO_WARNPRIMARY
,WARNPRIMARY=YES
,WARNPRIMARY=NO
is an optional keyword input that specifies whether monitoring warning messages should be issued based on the log stream primary (interim) storage consumption above the HIGHOFFLOAD value.
The active primary TYPE=LOGR couple data set must be formatted at an
HBB7705 (or higher) format level in order to specify WARNPRIMARY=YES.
Otherwise, the request will fail with return code 8, reason code X’0839’. See
'LOGR parameters for format utility' in z/OS MVS Setting Up a Sysplex for more details.
This keyword can be updated even when the log stream is actively connected.
The change will be immediately reflected as a pending update in the log stream definition. It will take effect on the subsequent first connection to the log stream in the sysplex. For a structure-based log stream, the change will also take effect during the next (user-managed or system-managed) structure rebuild. For a DASD-only log stream, the change will also take effect upon the next offload data set switch event.
DEFAULT: NO_WARNPRIMARY
NO_WARNPRIMARY
If you omit keyword WARNPRIMARY or specify the
NO_WARNPRIMARY (default update) option, there will be no change to the WARNPRIMARY specification for this log stream definition.
NO
Indicates that the primary storage consumption monitoring warning messages will not be issued for the log stream.
YES
Indicates that log stream monitoring warning messages should be issued for the following conditions:
696
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
v When the log stream primary (interim) storage consumption is 2/3 between the HIGHOFFLOAD value and 100% full (rounded down to the nearest whole number). This is called the log stream imminent alert threshold.
That is, assume the default value is used for the HIGHOFFLOAD percentage. That would mean a HIGHOFFLOAD value of 80 would be used, so the warning messages would be triggered for this case at (2(100
- 80)/3 +80) = 93%.
v For a CF based log stream, when a 90% entry full condition is encountered.
v When an interim (primary) storage full condition is encountered.
For more details on the messages and monitoring primary storage consumption, see z/OS MVS Setting Up a Sysplex.
Note:
The value can be overridden on the system level by logger parameter options for IXGCNF keyword
CONSUMPTIONALERT(SUPPRESS).
,OFFLOADRECALL=NO_OFFLOADRECALL
,OFFLOADRECALL=YES
,OFFLOADRECALL=NO
Specifies whether or not offload processing is to skip recalling the current offload data set.
This keyword can be updated even when the log stream is actively connected.
The change will immediately be reflected in the log stream definition. It will take effect on the subsequent first connection to the log stream in the sysplex.
For a structure-based log stream, the change will also take effect during the next structure rebuild.
Specifying OFFLOADRECALL=NO_OFFLOADRECALL indicates that the
OFFLOADRECALL attribute of the log stream should not be updated.
Specifying OFFLOADRECALL=YES indicates that offload processing should recall the current offload data set.
Specifying OFFLOADRECALL=NO indicates that offload processing should not recall the current offload data set and allocate a new one. Also with this setting, logger will not wait on any ENQ serialization contention to be resolved and will receive a class 2 type error (unavailable system resource) as described in z/OS MVS Programming: Authorized Assembler Services Guide in topic
Interpreting error reason codes from DYNALLOC
Note that this option can cause any or all of the current offload data set to be wasted space on DASD once it is recalled. Care should be taken when using this option to size the data sets appropriately.
,DIAG=NO_DIAG
,DIAG=NO
,DIAG=YES
Specifies whether or not dumping or additional diagnostics should be provided by logger for certain conditions. See the DIAG keyword on the
IXGCONN, IXGBRWSE and IXGDELET macro services.
If you specify DIAG=NO, which is the default, no special logger diagnostic activity is requested for this logstream regardless of the DIAG specifications on the IXGCONN, IXGDELET and IXGBRWSE requests.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
697
IXGINVNT macro
Specifying DIAG=YES indicates that special logger diagnostic activity is allowed for this log stream: v
Informational LOGREC software symptom records (denoted by RETCODE
VALU/H00000004) as well as other external alerts highlighting suboptimal conditions. For additional details, see z/OS MVS Diagnosis: Reference,
"Enabling additional log stream diagnostics".
v When the appropriate specifications are provided on IXGCONN, IXGDELET or IXGBRWSE requests by the exploiting application, further additional diagnostics may be captured. See z/OS MVS Programming: Assembler Services
Guide, "Dumping on data loss (804-type) conditions" for more details.
,ZAI=NO_ZAI
,ZAI=NO
,ZAI=YES
Optional keyword that specifies whether the log stream data should be included in the z/OS IBM zAware log stream client data sent to the IBM zAware server.
he active primary TYPE=LOGR couple data set must be formatted at the
HBB7705 format level or higher in order to specify ZAI=YES. Otherwise, the request will fail with return code 8, reason code X'0839'. See 'LOGR parameters for format utility' in z/OS MVS Setting Up a Sysplex for more details.
This parameter can be updated while there is an outstanding connection to the log stream. In this case, the change will immediately be reflected in the log stream definition. The updated specification will take effect on the following logger events for this log stream:
1.
On the subsequent first connection to the log stream on a system.
2.
As a result of a SETLOGR FORCE.ZAICONN.LSN= command on the target system, or
3.
As a result of a SETLOGR FORCE.ZAICONN.ALL command when there is a connection to this log stream currently using the ZAI=YES setting on the target system.
Note:
Because the updated value can be used on a system by system basis, the installation should ensure the proper actions are taken on all the systems with connections to the log stream in order to make use of the current value.
If you specify NO_ZAI, you omit this keyword or specify the NO_ZAI
(default) option, there will be no change to the ZAI specification for this log stream definition.
If you specify NO, it indicates that the log stream data will not be included in data sent from this z/OS IBM zAware log stream client to the IBM zAware server.
If you specify YES, it indicates that the log stream data will be included in data sent to the IBM zAware server provided the z/OS IBM zAware log stream client is established. See Preparing for z/OS IBM zAware log stream client usage in z/OS MVS Setting Up a Sysplex for more details on establish and using z/OS IBM zAware log stream clients. Also refer to the ZAIDATA keyword.
ZAIDATA=NO_ZAIDATA
ZAIDATA=Xzaidata
Is the name (RS-type), or address in register (2)-(12), of an optional 48 character input that specifies a value, if any, to be passed to the IBM zAware server when the z/OS IBM zAware log stream client is established (refer to
ZAI=YES keyword specification).
698
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
The value you specify is defined by and must match the intended log data type capabilities of the IBM zAware server. See Preparing for z/OS IBM zAware log stream client usage in z/OS MVS Setting Up a Sysplex for more details on establishing and using z/OS IBM zAware log stream clients.
The active primary TYPE=LOGR couple data set must be formatted at the
HBB7705 format level or higher in order to specify the ZAIDATA keyword option. Otherwise, the request will fail with return code 8, reason code X'0839'.
See 'LOGR parameters for format utility' in z/OS MVS Setting Up a Sysplex for more details.
This parameter can be updated while there is an outstanding connection to the log stream. For this case, the change will immediately be reflected in the log stream definition. The updated specification will take effect on the following logger events for this log stream:
1.
On the subsequent first connection to the log stream on a system.
2.
As a result of a SETLOGR FORCE.ZAICONN.LSN= command on the target system, or
3.
As a result of a SETLOGR FORCE,ZAICONN.ALL command when there is a connection to this log stream currently using the ZAI=YES setting on the target system.
Note:
Since the updated value can be used on a system by system basis, the installation should ensure the proper actions are taken on all the systems with connections to the log stream in order to make use of the current value.
Specifying NO_ZAIDATA indicates that a null value will be used for the log stream ZAIDATA attribute.
Specifying Xzaidata indicates the name of the input variable containing the value. The value must be 48 characters long and padded on the right with blanks if necessary.
Valid characters are alphanumeric or national ($, #, @) characters, and any of the special (graphical) characters listed below. Lower case alphabetic characters will be folded to upper case. Any other character will be converted into an
EBCDIC blank X'40'. Valid special (graphical) characters:
Table 40. Valid special (graphical) characters:
Character Name
EBCDIC blank
Cent sign
Period
Less than sign
Left parenthesis
Plus sign
Or sign
Ampersand
Exclamation point
Asterisk
Right parenthesis
Semicolon
Not sign
)
*
!
&
;
¬
+
|
(
<
.
¢
Symbol
<blank>
X'50'
X'5A'
X'5C'
X'5D'
X'5E'
X'5F'
Hexidecimal (EBCDIC)
X'40'
X'4A'
X'4B'
X'4C'
X'4D'
X'4E'
X'4F'
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
699
IXGINVNT macro
Table 40. Valid special (graphical) characters: (continued)
Character Name
Minus sign (hyphen)
Slash
Comma
Percent Sign
Underscore
Greater than sign
Question mark
Emphasis mark
Colon
Apostrophe
Equal sign
Quote
Tilde
Left brace
Right brace
Backslash
{
'
:
}
>
?
%
_
}
,
/
-
Symbol
=
"
~
\
X'79'
X'7A'
X'7D'
X'7E'
X'7F'
X'A1'
X'C0'
X'D0'
X'E0'
Hexidecimal (EBCDIC)
X'60'
X'61'
X'6B'
X'6C'
X'6D'
X'6E'
X'6F'
If the resulting Xzaidata parameter value contains all X'40' (blanks), the
ZAIDATA keyword will be treated as if NO_ZAIDATA had been specified. The default is NO_ZAIDATA.
If you omit this keyword, there will be no change to the ZAIDATA specification for this log stream definition.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
,PLISTVER=2
,PLISTVER=3
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX
, if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
700
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
v 0 , which supports all parameters except those specifically referenced in higher versions.
v 1
, which supports both the following parameters and parameters from version 0:
– DESCRIPTION
– RMNAME
– RETPD
– AUTODELETE v 2 , which supports both the following parameters and parameters from version 0 and 1:
– DASDONLY
– LOGGERDUPLEX v 3 , which supports the following parameter and parameters from version 0, 1, and 2:
– EHLQ
To code
: Specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0, 1, 2, or 3
,RETCODE=retcode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
701
IXGINVNT macro
Syntax
code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
REQUEST=CHECKDEF option of IXGINVNT
The IXGINVNT macro with the CHECKDEF parameter allows a program to check whether a particular log stream or logger structure entry name is defined in the
LOGR policy (LOGR CDS).
Syntax for REQUEST=CHECKDEF
The IXGINVNT REQUEST=CHECKDEF macro is written as follows:
Description
name
⌂
name: symbol. Begin name in column 1.
One or more blanks must precede IXGINVNT.
IXGINVNT
⌂ One or more blanks must follow IXGINVNT.
REQUEST=CHECKDEF
702
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Syntax
,TYPE=LOGSTREAM
,TYPE=STRUCTURE
,STREAMNAME=streamname
,STRUCTNAME=structname
,EXTRACT=NO
,EXTRACT=YES
,ANSAREA=ansarea
,ANSLEN=anslen
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0 - 4
,RETCODE=retcode
,RSNCODE=rsncode
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Description
streamname: RS-type address or register (2) - (12).
structname: RS-type address or register (2) - (12).
ansarea: RS-type address or register (2) - (12).
anslen: RS-type address or register (2) - (12).
Default
: IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: MF=S
Parameters for REQUEST=CHECKDEF
The parameters are explained as follows:
REQUEST=CHECKDEF
Requests that an entry for a log stream or coupling facility structure be checked in the LOGR policy.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
703
IXGINVNT macro
,TYPE=LOGSTREAM
Requests that the entry to be checked in the LOGR policy is a log stream entry.
If you specify TYPE=LOGSTREAM, you must also specify STREAMNAME,
ANSAREA, and ANSLEN.
,TYPE=STRUCTURE
Requests that the entry to be checked in the LOGR policy is a logger (coupling facility) structure entry.
If you specify TYPE=STRUCTURE, you must also specify STRUCTNAME,
ANSAREA, and ANSLEN.
,STREAMNAME=streamname
Specifies the 26-byte field (or address in a register) of the log stream that you want to check in the LOGR policy.
The stream name must be 26 characters, padded on the right with blanks, if necessary. The name can be made up of one or more segments, up to the maximum length of 26 characters. The following rules apply: v Each segment can contain 1-8 numeric, alphabetic, or national ($, #, or @) characters.
v Lowercase alphabetic characters will be folded to uppercase.
v The first character of each segment must be an alphabetic or national character.
v Each segment must be separated by periods, which count as characters.
STREAMNAME is required for TYPE=LOGSTREAM.
If the log stream name is defined, the check definition request is considered successful and provides return code 0 and reason code '0000'x.
If the log stream name is not defined, the check definition request fails with return code 8 and reason code '080B'x (IXGRSNCODENOSTREAM).
,STRUCTNAME=structname
Specify TYPE=STRUCTURE to specify the name (or address in a register) of a
16-byte input field that contains the name of the logger (coupling facility) structure you are checking in the LOGR policy. The following rules apply: v It can contain numeric, alphabetic, or national ($, #, or @) characters, or an underscore(_), padded on the right with blanks if necessary v Lowercase alphabetic characters will be folded to uppercase.
v The first character must be an alphabetic character.
STRUCTNAME is required for TYPE=STRUCTURE.
If the logger structure name is defined, the check definition request is considered successful and provides return code 0 and reason code '0000'x.
If the logger structure name is not defined, the check definition request would fail with return code 8 and reason code '0827'x
(IXGRSNCODENOSTRRECORD).
,EXTRACT=NO
Required keyword input that specifies the request is only to verify the resource name is defined in the LOGR CDS.
,EXTRACT=YES
Option is not yet supported. Use of this specification will fail with return code
8 and reason code '0845'x (IxgRsnCodeInvalidFunc).
704
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=4
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 4 , which supports the following parameter and parameters from version 0, 1,
2 and 3: EXTRACT
To code
: Specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 4
,RETCODE=retcode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
705
IXGINVNT macro
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
None.
Return and reason codes
When IXGINVNT macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.
706
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
The IXGCON macro provides equate symbols for the return and reason codes. The equate symbols associated with each hexadecimal return code are as follows:
00
04
IXGRETCODEOK - Service completes successfully.
IXGRETCODEWARNING - Service completes with a warning.
08
0C
IXGRETCODEERROR - Service does not complete.
IXGRETCODECOMPERROR - Service does not complete.
The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code. If your action requires you to see an IXG message, refer to IXG Messages in z/OS MVS System Messages, Vol 10 (IXC-IZP).
Table 41. Return and Reason Codes for the IXGINVNT Macro
Return Code Reason Code
00 xxxx0000
Meaning and Action
Equate Symbol
: IxgRsnCodeOk
Explanation
: Request processed successfully.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
707
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
04 xxxx0418
Meaning and Action
Equate Symbol
: IxgRsnCodeUpdateNewnameWarning
Explanation
: Environment error. Request to update the log stream with a new stream name processed successfully. However, at least one log stream staging data set was not renamed because of an IDCAMS
ALTER error.
08
08 xxxx0801 xxxx0802
Action
: Notify the system programmer and check for any IXG251I hard-copy messages and see the system programmer response for the message identifier that is included in message IXG251I. The system also issues logger message IXG277E. See z/OS DFSMS Access
Method Services Commands for the IDCAMS return code information and correct the condition that caused the error. If a staging data set is migrated, the IXG251I messages might indicate that the data set is a
"NONVSAM" type entry for the cluster. Migrated staging data sets for the log stream must be recalled before submitting the NEWSTREAMNAME update request as logger does not attempt to rename migrated data sets. The system programmer will need to rename the staging data set.
After correcting the error condition, the System
Programmer must submit the necessary IDCAMS
ALTER entryname NEWNAME() job to get the existing log stream staging data set name updated to match the new stream name change. The system programmer needs to do this before defining a new instance of a log stream that uses the same name as the log stream identified in this message.
Failure to get the staging data set renamed correctly can result in a "loss of data" condition when a connection occurs for the log stream that was renamed. If unable to identify the problem source or correct the error, contact the IBM Support Center.
If you received this reason code from IXCMIAPU, see message IXG445E.
Equate Symbol
: IxgRsnCodeBadParmlist
Explanation
: Program error. The parameter list could not be accessed.
Action
: Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.
Equate Symbol
: IxgRsnCodeXESError
Explanation
: System error. A severe cross-system extended services (XES) error has occurred.
Action
: See ANSAA_DIAG1 for the XES return code and ANSAA_DIAG2 for the XES reason code.
708
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0805
Meaning and Action
Equate Symbol
: IxgRsnCodeAllocError
Explanation
: Environment error. The system encountered a severe dynamic allocation (SVC 99) error while processing data sets related to the log stream.
If you have received this reason code while running a job that uses the IXCIAPU utility, then messages
IXG002E and IXG003I will appear in your joblog.
Investigating the diag fields in IXG003I may be helpful.
IXG003I is documented in z/OS MVS System Messages,
Vol 10 (IXC-IZP).
If your application has received this reason code from the IXGINVNT macro, follow the action steps below.
Action
:
IXGINVNT returns information about the error in the answer area, mapped by IXGANSAA. Investigate the meaning of ANSAA_Diag1 and ANSAA_Diag2.
ANSAA_Diag1
contains either an internal logger return code or the contents of the 4 byte field S99ERSN. More information on internal logger return codes and
S99ERSN appears below.
ANSAA_Diag2
contains either the contents of the 4 byte field S99ERSN or the contents of the 2 byte field
S99ERROR followed by the 2 byte field S99INFO.
More information on these fields appears below.
S99ERSN, S99ERROR and S99INFO are fields in the
IEFZB4D0 control block that logger uses to communicate with dynamic allocation.
If you receive any one of the following internal logger return codes in ANSAA_Diag1, contact IBM: X'04', x'10', x'14', x'1C'.
S99ERROR is documented in Interpreting error reason codes from DYNALLOC of the z/OS MVS Programming:
Authorized Assembler Services Guide.
S99ERSN is documented in S99RBX fields of the z/OS
MVS Programming: Authorized Assembler Services Guide.
S99INFO is documented in Interpreting error reason codes from DYNALLOC in the z/OS MVS Programming:
Authorized Assembler Services Guide.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
709
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code Meaning and Action
After you have researched the meaning of S99ERROR,
S99ERSN and S99INFO, you may be able to find even more information about the meaning of S99ERSN by looking up a DFSMS message whose ID is IGDxxxx.
You compute xxx: It is the value found in S99ERSN, converted to decimal. The information for this IGDxxxx message gives the meaning of the value found in
S99ERSN, even if the DFSMS message does not appear in syslog. Not all values of S99ERSN map to an
IGCxxxx message. Here are some examples of S99ERSN values and the related message ID: If S99ERSN is x'00042CF', the DFSMS message ID would be IGD17103.
Sometimes zeros must be inserted after IGD. For example, if S99ERSN is x'00003F6', the DFSMS message
ID would be IGD01014. IGD messages are documented in z/OS MVS System Messages, Vol 8 (IEF-IGD).
08 xxxx0808
Look in syslog for any messages that were issued near the time your application invoked the IXGINVNT macro. Look for messages that begin with IXG.
Messages of interest will often have 2 message IDs where the first message ID is IXG251I, and the second begins with IGD, IDC, IKJ, IEF or ICH.
If message IXG263E was issued, follow the actions documented for that message.
If the problem persists, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center.
Equate Symbol
: IxgRsnCodeIOError
08
08 xxxx080A xxxx080B
Explanation
: System error. A severe log data set I/O error has occurred.
Action
: Contact the IBM Support Center. Provide the return and reason code.
Equate Symbol
: IxgRsnCodeRequestLocked
Explanation
: Program error. The program issuing the request is holding a lock.
Action
: Ensure that the program issuing the request is not holding a lock.
Equate Symbol
: IxgRsnCodeNoStream
Explanation
: Program error. The log stream name specified has not been defined in the LOGR policy.
Action
: Ensure that the required log stream name has been defined in the LOGR policy. If the definition appears to be correct, ensure that the application is passing the correct log stream name to the service.
If you received this reason code from IXCMIAPU, see message IXG017E.
710
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx080D
Meaning and Action
Equate Symbol
: IxgRsnCodeNoSAFAuth
Explanation
: Environment error. The user does not have correct SAF authorization for the request. The caller is not authorized for one of the following objects: v The log stream being updated or defined v The log stream named on the LIKE parameter v The log stream named on the NEWSTREAMNAME parameter v
The structure specified v
The structure extracted from the log stream named on the LIKE parameter v The log stream name or logger structure name for a definition check (CHECKDEF) request v Requesting ZAI=YES for the log stream
Action
: IXGINVNT returns information about the error in the answer area that is mapped by IXGANSAA.
Investigate the meaning of ANSAA_Diag1,
ANSAA_Diag2 and ANSAA_Diag4.
v ANSAA_Diag1 contains the RACF or installation exit return code from the RACROUTE REQUEST=AUTH macro.
v
ANSAA_Diag2 contains the RACF or installation exit reason code from the RACROUTE REQUEST=AUTH macro.
v ANSAA_Diag4 contains the SAF return code from the
RACROUTE REQUEST=AUTH macro.
See z/OS Security Server RACROUTE Macro Reference for information about the RACROUTE macro.
Define SAF authorization for any log streams and structures specified.
If the ZAI keyword is provided, ensure the appropriate access is established for using it. If you received this reason code from IXCMIAPU, see message IXG033E.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
711
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx080E
Meaning and Action
Equate Symbol
: IxgRsnCodeStreamDefined
Explanation
: Program error. The log stream name specified on a define request or the new log stream name on an update request had already been defined in the LOGR inventory couple data set.
Action
: Do one of the following: v Use the existing definition for the log stream.
v Change the name of the log stream being defined on a define request or the new stream name for an update request.
v Delete the existing log stream definition from the inventory and then reissue the IXGINVNT request to redefine it.
08 xxxx0810
If you received this reason code from IXCMIAPU, see message IXG012E.
Equate Symbol
: IxgRsnCodeStreamInuse
Explanation
: Environment error. You cannot alter or delete a log stream while an application is connected to it. Some attributes can be updated while there are connections provided the appropriate LOGR couple data set and release levels are in effect.
Action
: Reissue the request when there are no active connections to the log stream or move to the appropriate release and LOGR couple data set format level.
08
08 xxxx0811 xxxx0814
If you received this reason code from IXCMIAPU, see message IXG014E.
Equate Symbol
: IxgRsnCodeBadStrname
Explanation
: Environment error. The structure name specified on the STRUCTNAME parameter is not defined in the CFRM policy.
Action
: Make sure that the structure you want to specify is defined in the CFRM policy.
Equate Symbol
: IxgRsnCodeNotAvailForIPL
Explanation
: Environment error. The system logger address space is not available for the remainder of this
IPL. The system issues messages about this error during system logger initialization.
Action
: See the explanation for system messages issued during system logger initialization.
712
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0815
Meaning and Action
Equate Symbol
: IxgRsnCodeNotEnabled
Explanation
: Program error. The program issuing the request is not enabled for I/O and external interrupts, so the request fails.
08
08
08 xxxx0816 xxxx0817 xxxx0819
Action
: Make sure the program issuing the request is enabled for I/O and external interrupts.
Equate Symbol
: IxgRsnCodeBadAnslen
Explanation
: Program error. The answer area length
(ANSLEN parameter) is not large enough. The system logger returned the required size in the
Ansaa_Preferred_Size field of the answer area, mapped by IXGANSAA macro.
Action
: Reissue the request, specifying an answer area of the required size.
Equate Symbol
: IxgRsnCodeBadAnsarea
Explanation
: Program error. The storage area specified on the ANSAREA parameter cannot be accessed. This might occur after the system logger address space has terminated.
Action
: Specify storage that is in the caller's primary address space and in the same key as the calling program at the time the system logger service was issued. This storage must be accessible until the request completes.
Equate Symbol
: IxgRsnCodeSRBMode
Explanation
: Program error. The calling program is in
SRB mode, but task mode is the required dispatchable unit mode for this system logger service.
Action
: Make sure the calling program is in task mode.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
713
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx081A
Meaning and Action
Equate Symbol
: IxgRsnCodeMaxStreamConn &
IXGINVNT requests
08 xxxx081B
Explanation
: Environment error. This system has reached the limit for the maximum number of log streams that can be concurrently active. One of the following is true: v The limit of 16,384 concurrently active DASDONLY log streams per system has been reached. For this case, the Answer Area field DIAG1 will contain
16,384.
v
Either the PRODUCTION or TEST GROUP cannot connect to any more log streams. Message IXG075E or
IXG076I is issued. In this case, the Answer Area field
DIAG1 will contain the number of structures that are in use for this GROUP.
v The TEST GROUP has previously failed and a request has been made to define a logstream with
GROUP(TEST). Message IXG074I has been previously issued. In this case, the Answer Area field DIAG1 will contain 0.
v A Log stream delete cannot be processed because logger needs to perform an internal connect to the
Log stream to complete the delete but no more connections are allowed.
Action
: Your workload need to be planned to either consolidate log streams or balance system activity such that fewer log streams are needed during this time frame.
Equate Symbol
: IxgRsnCodePrimaryNotHome
Explanation
: Program error. The primary address space does not equal the home address space.
08
08 xxxx081E xxxx081F
Action
: Make sure that the primary address space equals the home address space when issuing this system logger service.
Equate Symbol
: IxgRsnCodeXESStrNotAuth
Explanation
: Environment error. The system logger address space does not have access authority to the coupling facility structure associated with the log stream specified.
Action
: Make sure the system logger address space has
SAF access to the structure.
Equate Symbol
: IxgRsnCodeXcdsError
Explanation
: System error. System logger encountered an internal problem while processing the LOGR couple data set.
Action
: Contact the IBM Support Center. Provide the return and reason code and the contents of the answer area (ANSAREA field).
714
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0821
Meaning and Action
Equate Symbol
: IxgRsnCodeDspCreateFailed
Explanation
: System error. A data space create failed during logger inventory processing.
If you have received this reason code while running a job that uses the IXCMIAPU utility, then messages
IXG002E and IXG003I will appear in your joblog.
Investigating the diag fields in IXG003I may be helpful.
Message IXG003I is documented in z/OS MVS System
Messages, Vol 10 (IXC-IZP).
If your application has received this reason code from the IXGINVNT macro, follow the action steps below.
Action
: IXGINVNT returns information about the error in the answer area, mapped by IXGANSAA. Investigate the maning of ANSAA_Diag1 and ANSAA_Diag2.
ANSAA_Diag1
contains the return code from the
DSPSERV macro.
ANSAA_Diag2
contains the reason code from the
DSPSERV macro.
08
08 xxxx0822 xxxx0823
The DSPSERV macro's return and reason codes are documented in the z/OS MVS Programming: Assembler
Services Reference ABE-HSP.
Equate Symbol
: IxgRsnCodeBadHlq
Explanation
: Program error. The high level qualifier specified on the HLQ parameter was incorrect.
Action
: Specify a valid high level qualifier and reissue the request.
Equate Symbol
: IxgRsnCodeNoInvrecSpace
Explanation
: Environment error. The LOGR couple data set cannot be updated because the maximum number of entries for the specified type has already been reached.
Action
: v Format a new LOGR couple data set using the
IXCL1DSU utility. In the new LOGR couple data set either delete unused entries or increase the allowed number of entries on the LSR parameter (for log stream entries) or the LSTRR parameter (for coupling facility structure entries).
v PSWITCH the current alternate LOGR couple data set to primary.
v Add the new LOGR couple data set as alternate.
v PSWITCH the new LOGR couple data set from alternate to primary.
If you received this reason code from IXCMIAPU, see message IXG010E.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
715
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0824
Meaning and Action
Equate Symbol
: IxgRsnCodeMaxStreamStr
Explanation
: Program error. A program issued
IXGINVNT to associate a structure with a log stream, but the maximum number of log streams allowed (as defined on the LOGSNUM parameter) has been reached for the specified structure.
Action
: Either specify a structure that has not reached its LOGSNUM limit, or specify a larger LOGSNUM value on the definition for the structure.
08
08
08 xxxx0825 xxxx0826 xxxx0827
If you received this reason code from IXCMIAPU, see message IXG011E.
Equate Symbol
: IxgRsnCodeStrDefined
Explanation
: Program error. The structure specified on the IXGINVNT request is already defined in the LOGR inventory couple data set.
Action
: Either use the existing structure definition, change the name of the structure being defined or delete the existing structure and redefine it.
If you received this reason code from IXCMIAPU, see message IXG013E.
Equate Symbol
: IxgRsnCodeBadLogsnum
Explanation
: Program error. The LOGSNUM value specified for a structure definition was not within the valid range between 1 and 512.
Action
: Change the LOGSNUM value to be within the valid range.
If you received this reason code from IXCMIAPU, see message IXG016E.
Equate Symbol
: IxgRsnCodeNoStrRecord
Explanation
: Program error. The coupling facility structure specified in the definition for a log stream or the name specified on a CHECKDEF request is not defined in the LOGR inventory couple data set.
Action
: Either define the coupling facility structure before referencing it in a log stream definition, or specify an existing structure definition.
If you received this reason code from IXCMIAPU, see message IXG018E
716
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0828
Meaning and Action
Equate Symbol
: IxgRsnCodeStrRecordInuse
Explanation
: Program error. The request to delete a structure definition from the LOGR inventory couple data set cannot be completed because several log stream definitions reference it. You cannot delete a structure definition until all the log streams associated with it have been deleted first.
Action
: Delete all the log streams associated with the structure you wish to delete, and then reissue the request.
08
08 xxxx0829 xxxx082A
If you received this reason code from IXCMIAPU, see message IXG015E.
Equate Symbol
: IxgRsnCodeBadStgStorClas
Explanation
: Program error. The name specified on the
STG_STORCLAS parameter is incorrect.
Action
: Change the staging data set storage class specified to meet the STG_STORCLAS syntax requirements.
Equate Symbol
: IxgRsnCodeBadLSStorClas
Explanation
: The name specified on the LS_STORCLAS parameter is incorrect.
08
08 xxxx082B xxxx082C
Action
: Change the log stream data set storage class specified to meet the LS_STORCLAS syntax requirements.
Equate Symbol
: IxgRsnCodeBadStreamLike
Explanation
: Program error. The log stream name specified on the LIKE parameter was not valid.
Action
: Reissue the request with a valid log stream name on the LIKE parameter.
If you received this reason code from IXCMIAPU, see message IXG031E.
Equate Symbol
: IxgRsnCodeBadStructName
Explanation
: Program error. The coupling facility structure name specified on the STRUCTNAME parameter is not valid.
Action
: Reissue the request with a valid structure name on the STRUCTNAME parameter.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
717
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx082E
Meaning and Action
Equate Symbol
: IxgRsnCodeNoLogrCDSAvail
08
08 xxxx082F xxxx0830
Explanation
: Environment error. The request failed because no LOGR couple data set is available. The operator was prompted to either make a couple data set available or to indicate that the current request should be rejected. The operator specified that the current request should be rejected.
Action
: System logger services are unavailable for the remainder of this IPL.
Equate Symbol
: IxgRsnCodeBadStgDataClas
Explanation
: Program error. The name specified on the
LS_DATACLAS parameter is not valid.
Action
: Change the data class specified to meet the
LS_DATACLAS syntax requirements.
Equate Symbol
: IxgRsnCodeBadLSDataClas
08
08
08 xxxx0831 xxxx0832 xxxx0833
Explanation
: Program error. The name specified on the
STG_DATACLAS parameter is not valid.
Action
: Change the data class specified to meet the
STG_DATACLAS syntax requirements.
Equate Symbol
: IxgRsnCodeBadStreamName
Explanation
: Program error. The log stream name specified on the STREAMNAME parameter is not valid.
Action
: Reissue the request with a valid log stream name on the STREAMNAME parameter.
If you received this reason code from IXCMIAPU, see message IXG021E.
Equate Symbol
: IxgRsnCodeBadStgMgmtClas
Explanation
: Program error. The name specified on the
STG_MGMTCLAS parameter is not valid.
Action
: Change the staging data set management class specified to meet the STG_MGMTCLAS syntax requirements.
Equate Symbol
: IxgRsnCodeBadLSMgmtClas
Explanation
: Program error. The name specified on the
LS_MGMTCLAS parameter is not valid.
Action
: Change the log stream data set management class specified to meet the LS_MGMTCLAS syntax requirements.
718
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0834
Meaning and Action
Equate Symbol
: IxgRsnCodeInvalidLSSize
08 xxxx0835
Explanation
: Program error. A non-zero LS_SIZE is specified, but is not in the range valid for a VSAM linear data set.
Action
: Either change the LS_SIZE or omit it from the
DEFINE request to accept the default value.
If you received this reason code from IXCMIAPU, see message IXG040E.
Equate Symbol
: IxgRsnCodeInvalidStgSize
08 xxxx0838
Explanation
: Program error. A non-zero STG_SIZE is specified, but is not in the range valid for a VSAM linear data set.
Action
: Either change the STG_SIZE or omit it from the
DEFINE request to accept the default value.
If you received this reason code from IXCMIAPU, see message IXG040E.
Equate Symbol
: IxgRsnCodeUnDefSmsClas
Explanation
: Program error. At least one of the names specified for DATACLAS, MGMTCLAS, or STORCLAS is not defined to SMS.
08 xxxx0839
Action
: Specify names that are defined to the active
SMS configuration.
If you received this reason code from IXCMIAPU, see message IXG007E.
Equate Symbol
: IxgRsnCodeBadCdsLevel
Explanation
: The active primary LOGR couple data set is not formatted at the level required for the request. See the explanation of the parameters for the level each requires.
Action
: Take one of the following actions: v Bring a new new active primary LOGR couple data set at the required level into the sysplex and then retry the request.
v Remove the keywords requiring an new level of the
LOGR couple data set and retry the request.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
719
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx083C
Meaning and Action
Equate Symbol
: IxgRsnCodeBadMaxBufSize
Explanation
: Program error. For a DEFINE or UPDATE request, the value specified for MAXBUFSIZE was incorrect. It must be a value between 1 and 65,532.
For an UPDATE request, one of the following is causing the error: v The value specified is less than the MAXBUFSIZE value currently associated with a DASD-only log stream, or v
The current DASD-only MAXBUFSIZE value is greater than the MAXBUFSIZE value associated with the STRUCTNAME specified on the update request, or v The current structure MAXBUFSIZE value is greater than the MAXBUFSIZE value associated with the
STRUCTNAME specified on the UPDATE request.
Action
: Do one of the following, depending on the request:
For a DEFINE request
, specify a valid value for
MAXBUFSIZE and reissue the request.
For an UPDATE request,
do one of the following: v Specify a value within the valid range for
MAXBUFSIZE that is greater than or equal to the current DASD-only MAXBUFSIZE value.
v Ensure that the structure specified on the
STRUCTNAME parameter has a maximum buffer size that is greater than or equal to the current
MAXBUFSIZE value associated with the log stream specified on the UPDATE request.
08
08 xxxx083E xxxx0840
If you received this reason code from IXCMIAPU, see message IXG009E.
Equate Symbol
: IxgRsnCodeNoAvailSysRec
Explanation
: System error. There were no available system records.
Action
: Contact the IBM support center. Provide the return and reason codes and the contents of the system logger trace.
Equate Symbol
: IxgRsnCodeBadVersion
Explanation
: Environment error. The parameter list passed to the service routine had an invalid version indicator.
Action
: Ensure the level of MVS executing the request and the macro library used to compile the invoking routine are compatible.
720
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0842
Meaning and Action
Equate Symbol
: IxgRsnCodeBadAvgBufSize
Explanation
: Program error. The value specified for
AVGBUFSIZE was specified as incorrect. It must be a value between and 65,536 that is less than
MAXBUFSIZE.
Action
: Reissue the request with a valid AVGBUFSIZE value.
08
08 xxxx0843 xxxx0844
If you received this reason code from IXCMIAPU, see message IXG022E.
Equate Symbol
: IxgRsnCodeXcdsReformat
Explanation
: Program error. A couple data set record is not valid.
Action
: Reformat the system logger couple data set.
If you received this reason code from IXCMIAPU, see message IXG030E.
Equate Symbol
: IxgRsnCodeNoStreamLike
08
08 xxxx0845 xxxx084E
Explanation
: Program error. The log stream name specified on the LIKE parameter is not defined in the
LOGR couple data set.
Action
: Do one of the following: v Define the log stream you wish to reference in the
LOGR inventory couple data set and reissue the request.
v Reissue the request, specifying a different log stream that is already defined in the LOGR couple data set.
If you received this reason code from IXCMIAPU, see message IXG019E.
Equate Symbol
: IxgRsnCodeInvalidFunc
Explanation
: System error. The parameter list for this service contains an unrecognizable function code. The parameter list storage might have been overlaid.
Action
: Fix the problem and then reissue the request.
Equate Symbol
: IxgRsnCodeStrSpaceTooSmall
Explanation
: Environment error. Structure resources are not available to satisfy the request. All structure resources are allocated as system logger control resources. This condition occurs when the structure resources are consumed by the log streams connection.
Action
: Increase the size of the structure in the CFRM policy, or use SETXCF ALTER support to dynamically increase the size of the structure.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
721
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0850
Meaning and Action
Equate Symbol
: IxgRsnCodeBadVectorLen
08 xxxx0851
Explanation
: Environment error. The connect request was rejected. System logger was unable to locate a vector table in the hardware system area (HSA) that is large enough for the number of log streams associated with it.
Action
: Add storage to the vector storage table or retry the connect request later when storage is available.
Equate Symbol
: IxgRsnCodeBadCFLevel
Explanation
: Environment error. The connect request was rejected. The operational level of the coupling facility is not sufficient to support logger functions.
08
08
08 xxxx0853 xxxx0854 xxxx0855
Action
: Ensure that the coupling facility operational level for logger structures is at least CFLEVEL=1.
Equate Symbol
: IxgRsnCodeNoCF
Explanation
: The connect request was rejected. System logger could not allocate coupling facility structure space, because no suitable coupling facility was available.
Action
: Check accompanying message IXG206I for a list of the coupling facilities, where space allocation was attempted and the reason why each attempt failed.
Equate Symbol
: IxgRsnCodeBadLowoffload
Explanation
: Program error. The value specified for
LOWOFFLOAD is not valid.
Action
: Change the value to meet the LOWOFFLOAD syntax requirements.
If you received this reason code from IXCMIAPU, see message IXG035E.
Equate Symbol
: IxgRsnCodeBadHighoffload
Explanation
: Program error. The value specified for
HIGHOFFLOAD is invalid.
Action
: Change the value to meet the HIGHOFFLOAD syntax requirements.
If you received this reason code from IXCMIAPU, see message IXG036E.
722
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0856
Meaning and Action
Equate Symbol
: IxgRsnCodeBadLowHighOffLoad
Explanation
: Program error. The value specified or defaulted to for the low offload value is equal to or higher than the high offload value. The low offload value must be lower than the high offload value.
08 xxxx0857
Action
: Change either the LOWOFFLOAD parameter or the HIGHOFFLOAD parameter so that the low offload value is less than the high offload value.
If you received this reason code from IXCMIAPU, see messages IXG442E and either IXG035E or IXG036E.
Equate Symbol
: IxgRsnCodeDuplexmodeDuplexNo
Explanation
: Program error. DUPLEXMODE was specified, but the log stream was defined with
STG_DUPLEX=NO. The DUPLEXMODE parameter is only valid with STG_DUPLEX=YES.
Action
: Either change the log stream definition to specify STG_DUPLEX=YES or else omit DUPLEXMODE from the request.
08
08
08
08
08 xxxx0858 xxxx0859 xxxx085A xxxx085B xxxx085E
If you received this reason code from IXCMIAPU, see message IXG037E.
Equate Symbol
: IxgRsnCodeStgSizeDuplexNo
Explanation
: This reason code is obsolete and will no longer be returned.
Equate Symbol
: IxgRsnCodeDataClasDuplexNo
Explanation
: This reason code is obsolete and will no longer be returned.
Equate Symbol
: IxgRsnCodeMgmtClasDuplexNo
Explanation
: This reason code is obsolete and will no longer be returned.
Equate Symbol
: IxgRsnCodeStorClasDuplexNo
Explanation
: This reason code is obsolete and will no longer be returned.
Equate Symbol
: IxgRsnCodeNoStructName
Explanation
: Program error. A structure name was not provided for this log stream via the STRUCTNAME parameter or defined for a log stream named on a LIKE parameter. A STRUCTNAME value is required to successfully define a log stream to the LOGR couple data set.
Action
: Provide a value for the STRUCTNAME parameter or define a structure for the log stream referenced on the LIKE parameter.
If you received this reason code from IXCMIAPU, see message IXG041E.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
723
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0890
Meaning and Action
Equate Symbol
: IxgRsnCodeAddrSpaceNotAvail
08 xxxx0891
Explanation
: System error. The system logger address space failed and is not available.
Action
: Do not issue system logger requests.
If you received this reason code from IXCMIAPU, see message IXG008E.
Equate Symbol
: IxgRsnCodeAddrSpaceInitializing
08 xxxx08D4
Explanation
: System error. The system logger address space is not available because it is IPLing.
Action
: Listen for ENF signal 48, which will indicate when the system logger address space is available.
Reissue this request. You can also listen for ENF signal
48, which will indicate if the system logger address space will not be available for the life of the IPL. In that case, do not issue system logger services.
If you received this reason code from IXCMIAPU, see message IXG008E.
Equate Symbol
: IxgRsnCodeBadRMName
08
08 xxxx08D5 xxxx08D8
Explanation
: Program Error. The name of the resource manager specified on the RMNAME parameter was not valid.
Action
: Correct the RMNAME and retry the request.
Equate Symbol
: IxgRsnCodeBadLSDescription
Explanation
: Program Error. The name of the field specified in the DESCRIPTION parameter was not valid.
DESCRIPTION must be 16 alphanumeric or national
($,#,@) characters, underscore (_) or period (.), padded on the right with blanks if necessary.
Action
: Correct the DESCRIPTION field name and retry the request.
Equate Symbol
: IxgRsnCodeBadRetpd
Explanation
: Program Error. The value specified for
RETPD was incorrect. It must be a value >= 0 and <=
65,536.
Action
: Specify a valid value for RETPD and reissue the request.
724
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx08E0
Meaning and Action
Equate Symbol
: IxgRsnCodeStgDuplexDasdOnly
08 xxxx08E1
Explanation
: Program Error. The STG_DUPLEX keyword was specified with an invalid parameter when a DASD only logstream was defined or updated. When you define or update a DASD only logstream you must omit the STG_DUPLEX keyword or specify
STG_DUPLEX=YES. No other option is allowed because
DASD only log streams are unconditionally duplexed to staging data sets.
Action
: For DASD only log stream DEFINE and
UPDATE requests specify STG_DUPLEX=YES or omit the STG_DUPLEX keyword.
This error code may also result when using the
IXCMIAPU DATA TYPE(LOGR) utility when the
STG_DUPLEX option is specified for a DASD only log stream. See system logger error messages IXG002E or
IXG447I.
Equate Symbol
: IxgRsnCodeDuplexModeDasdOnly
08 xxxx08E2
Explanation
: Program Error. The DUPLEXMODE keyword was specified with an invalid parameter when a DASD only logstream was defined or updated. When you define or update a DASD only logstream you must omit the DUPLEXMODE keyword or specify
DUPLEXMODE=UNCOND. No other option is allowed because DASD only log streams are unconditionally duplexed to staging data sets.
Action
: For DASD only log stream DEFINE and
UPDATE requests specify DUPLEXMODE=UNCOND or omit the DUPLEXMODE keyword.
This error code may also result when using the
IXCMIAPU DATA TYPE(LOGR) utility when the
DUPLEXMODE option is specified for a DASD only log stream. See system logger messages IXG002E or
IXG447I.
Equate Symbol
: IxgRsnCodeDasdOnlyConnected
Explanation
: Environment error. System logger rejected an attempt to connect to a DASD-only log stream because another log stream in the sysplex is already connected to that log stream. Only one system at a time can connect to a DASD-only log stream.
Action
: Determine which system you want to have a connection to the log stream. If you need this connection, disconnect the first system connection to the log stream and retry this connect request.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
725
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx08E3
Meaning and Action
Equate Symbol
: IxgRsnCodeLogstreamNotSupported
Explanation
: Environment error. An attempt to connect or effect the LOGR inventory for the log stream is rejected on this system. The system release level does not support this type of log stream, or a log stream attribute such as EHLQ, Duplexmode(Drxrc),
GROUP(TEST), or NewStreamName cannot be processed on this system release level.
Action
: When attempting to connect or delete a log stream that has the EHLQ attribute, you must do so on at least a z/OS Version 1 Release 3 system release level.
If you must use a log stream with the
DUPLEXMODE(DRXRC) attribute specified, make sure you do so from a system that is at a release level between z/OS Version 1 Release 7 andz/OS Version 2
Release 2, inclusively.
If you must use a log stream with the
NEWSTREAMNAME attribute specified, make sure you do so from a system that is at z/OS Version 1 Release 8 release or higher.
If you must use a log stream with the GROUP attribute specified, make sure you do so from a system that is at z/OS Version 1 Release 8 release or higher.
08 xxxx08E4
If you received this reason code from IXCMIAPU, see message IXG233I.
Equate Symbol
:
IXGRSNCODEMAXBUFSIZEDASDONLY
Explanation
: Program error. A value was specified for
MAXBUFSIZE on this request, but the log stream was defined as a coupling facility log stream
(DASDONLY=NO). MAXBUFSIZE is not a valid parameter on a log stream definition request for a coupling facility log stream.
Action
: Either remove the MAXBUFSIZE parameter from this request or specify DASDONLY=YES with
MAXBUFSIZE.
If you received this reason code from IXCMIAPU, see messages IXG433E and IXG434E.
726
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx08E5
Meaning and Action
Equate Symbol
: IxgRsnCodeloggerDuplexDasdOnly
08 xxxx08E6
Explanation
: Program error. The LOGGERDUPLEX keyword was specified with an invalid parameter when a DASD only logstream was defined or updated. When you define or update a DASD only logstream you must omit the LOGGERDUPLEX keyword or specify
LOGGERDUPLEX=UNCOND. No other option is allowed because DASD only log streams are unconditionally duplexed to staging data sets.
Action
: For DASD only log stream DEFINE and
UPDATE requests specify LOGGERDUPLEX=UNCOND or omit the LOGGERDUPLEX keyword.
This error code may also result when using the
IXCMIAPU DATA TYPE(LOGR) utility when the
LOGGERDUPLEX option is specified for a DASD only log stream. See system logger error messages IXG002E or IXG447I.
Equate Symbol
: IxgRsnCodeBadEhlq
08 xxxx08E7
Explanation
: Program error. The extended high level qualifier for the log stream data sets specified on the
EHLQ parameter was incorrect. This could be from a syntax error or by specifying EHLQ and HLQ on the same request.
Action
: Specify a valid extended high level qualifier
(EHLQ) or high level qualifier (HLQ) and reissue the request.
If you received this reason code from IXCMIAPU, see message IXG440E.
Equate Symbol
: IxgRsnCodeEhlqTooLong
Explanation
: Program error. The combined length of the extended high level qualifier (EHLQ value) and the log stream name (with a period delimiter) exceeds 35 characters. The combined length of the EHLQ value, the log stream name, and the logger suffix (with period delimiters) cannot exceed 44 characters.
Action
: Specify a valid extended high-level qualifier
(EHLQ) or high-level qualifier (HLQ) and reissue the request.
If you received this reason code from IXCMIAPU, see message IXG441E.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
727
IXGINVNT macro
Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx08E8
Meaning and Action
Equate Symbol
: IxgRsnCodeBadNewStreamName
Explanation
: Program error. The log stream name specified on the NEWSTREAMNAME parameter was not valid. This error code might also result when using the IXCMIAPU DATA TYPE(LOGR) utility when the
NEWSTREAMNAME option is specified for a log stream.
Action
: Reissue the request with a valid log stream name on the NEWSTREAMNAME parameter.
08
08
0C xxxx08E9 xxxx08EA xxxx0000
If you received this reason code from IXCMIAPU, see message IXG031E.
Equate Symbol
: IxgRsnCodeBadGroup
Explanation
: Program error. For DEFINE requests, the
GROUP value is not allowed because the specified structure is not the same GROUP. For UPDATE requests, the GROUP value is not allowed because the specified
(or current) structure is not the same GROUP.
Action
: Specify a valid GROUP value or use a different structure that matches the desired GROUP value.
Equate Symbol
: IxgRsnCodeBadLsAllocAhead
Explanation
: Program error. The LS_ALLOCAHEAD value that was specified for a log stream definition was not within the valid range between 0 and 3 (inclusive).
Action
: Change the LS_ALLOCAHEAD value to be within the valid range. If you received this reason code from IXCMIAPU, see message IXG016E.
Equate Symbol
: IxgRetCodeCompError
Explanation
: User or System error. One of the following occurred: v You issued the FORCE IXGLOGR,ARM command to terminate the system logger address space.
v System logger component error occurred.
Action
: If this reason code is not the result of forcing the system logger address space, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center. Provide the diagnostic data in the answer area (IXGANSAA) and any dumps or LOGREC entries from system logger.
REQUEST=DELETE option of IXGINVNT
The IXGINVNT macro with the DELETE parameter allows a program to delete a log stream entry or coupling facility structure entry in the LOGR policy.
728
z/OS MVS Assembler Services Reference IAR-XCT
⌂
Syntax
name
Syntax for REQUEST=DELETE
The IXGINVNT REQUEST=DELETE macro is written as follows:
Description
IXGINVNT macro
name: symbol. Begin name in column 1.
One or more blanks must precede IXGINVNT.
IXGINVNT
⌂ One or more blanks must follow IXGINVNT.
REQUEST=DELETE
,TYPE=LOGSTREAM
,TYPE=STRUCTURE
,ANSAREA=ansarea
,ANSLEN=anslen
,STREAMNAME=streamname
,STRUCTNAME=structname
ansarea: RS-type address or register (2) - (12).
anslen: RS-type address or register (2) - (12).
streamname: RS-type address or register (2) - (12).
structname: RS-type address or register (2) - (12).
Default
: NO_STRUCTNAME
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
,PLISTVER=2
,PLISTVER=3
,RETCODE=retcode
,RSNCODE=rsncode
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
Default
: IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: MF=S
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
729
IXGINVNT macro
Syntax
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Description
Parameters for REQUEST=DELETE
The parameters are explained as follows:
REQUEST=DELETE
Requests that an entry for a log stream or coupling facility structure be deleted from the LOGR policy.
,TYPE=LOGSTREAM
Requests that the entry to be deleted from the LOGR policy is a log stream entry.
If you specify TYPE=LOGSTREAM, you must also specify STREAMNAME,
ANSAREA, and ANSLEN.
,TYPE=STRUCTURE
Requests that the entry to be deleted from the LOGR policy is a coupling facility entry.
If you specify TYPE=STRUCTURE, you must also specify STRUCTNAME,
ANSAREA, and ANSLEN.
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
,STREAMNAME=streamname
Specifies the 26-byte field (or address in a register) of the log stream that you want to delete from the LOGR policy.
The stream name must be 26 characters, padded on the right with blanks, if necessary. The name can be made up of one or more segments, up to the maximum length of 26 characters. The following rules apply: v Each segment can contain 1-8 numeric, alphabetic, or national ($, #, or @) characters.
v The first character of each segment must be an alphabetic or national character.
v Each segment must be separated by periods, which count as characters.
STREAMNAME is required for TYPE=LOGSTREAM.
730
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
,STRUCTNAME=structname
Specify TYPE=STRUCTURE to specify the name (or address in a register) of a
16-byte input field that contains the name of the coupling facility structure you are deleting from the LOGR policy.
STRUCTNAME is required for TYPE=STRUCTURE.
The following rules apply for the structname: v It can contain numeric, alphabetic, or national ($, #, or @) characters, or an underscore(_), padded on the right with blanks if necessary v The first character must be an alphabetic character.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
,PLISTVER=2
,PLISTVER=3
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , which supports all parameters except those specifically referenced in higher versions.
To code
: Specify in this input parameter one of the following: v IMPLIED_VERSION v
MAX v A decimal value of 0, 1, 2, or 3
,RETCODE=retcode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
731
IXGINVNT macro
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms in the following order: v
Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
None.
732
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Return and reason codes
When IXGINVNT macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.
The IXGCON macro provides equate symbols for the return and reason codes. The equate symbols associated with each hexadecimal return code are as follows:
00
04
IXGRETCODEOK - Service completes successfully.
IXGRETCODEWARNING - Service completes with a warning.
08
0C
IXGRETCODEERROR - Service does not complete.
IXGRETCODECOMPERROR - Service does not complete.
The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code. If your action requires you to see an IXG message, refer to IXG Messages in z/OS MVS System Messages, Vol 10 (IXC-IZP).
Table 42. Return and Reason Codes for the IXGINVNT Macro
Return Code Reason Code
00 xxxx0000
Meaning and Action
Equate Symbol
: IxgRsnCodeOk
Explanation
: Request processed successfully.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
733
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
04 xxxx0418
Meaning and Action
Equate Symbol
: IxgRsnCodeUpdateNewnameWarning
Explanation
: Environment error. Request to update the log stream with a new stream name processed successfully. However, at least one log stream staging data set was not renamed because of an IDCAMS
ALTER error.
08
08 xxxx0801 xxxx0802
Action
: Notify the system programmer and check for any IXG251I hard-copy messages and see the system programmer response for the message identifier that is included in message IXG251I. The system also issues logger message IXG277E. See z/OS DFSMS Access
Method Services Commands for the IDCAMS return code information and correct the condition that caused the error. If a staging data set is migrated, the IXG251I messages might indicate that the data set is a
"NONVSAM" type entry for the cluster. Migrated staging data sets for the log stream must be recalled before submitting the NEWSTREAMNAME update request as logger does not attempt to rename migrated data sets. The system programmer will need to rename the staging data set.
After correcting the error condition, the System
Programmer must submit the necessary IDCAMS
ALTER entryname NEWNAME() job to get the existing log stream staging data set name updated to match the new stream name change. The system programmer needs to do this before defining a new instance of a log stream that uses the same name as the log stream identified in this message.
Failure to get the staging data set renamed correctly can result in a "loss of data" condition when a connection occurs for the log stream that was renamed. If unable to identify the problem source or correct the error, contact the IBM Support Center.
If you received this reason code from IXCMIAPU, see message IXG445E.
Equate Symbol
: IxgRsnCodeBadParmlist
Explanation
: Program error. The parameter list could not be accessed.
Action
: Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.
Equate Symbol
: IxgRsnCodeXESError
Explanation
: System error. A severe cross-system extended services (XES) error has occurred.
Action
: See ANSAA_DIAG1 for the XES return code and ANSAA_DIAG2 for the XES reason code.
734
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0805
Meaning and Action
Equate Symbol
: IxgRsnCodeAllocError
Explanation
: Environment error. The system encountered a severe dynamic allocation (SVC 99) error while processing data sets related to the log stream.
If you have received this reason code while running a job that uses the IXCIAPU utility, then messages
IXG002E and IXG003I will appear in your joblog.
Investigating the diag fields in IXG003I may be helpful.
IXG003I is documented in z/OS MVS System Messages,
Vol 10 (IXC-IZP).
If your application has received this reason code from the IXGINVNT macro, follow the action steps below.
Action
:
IXGINVNT returns information about the error in the answer area, mapped by IXGANSAA. Investigate the meaning of ANSAA_Diag1 and ANSAA_Diag2.
ANSAA_Diag1
contains either an internal logger return code or the contents of the 4 byte field S99ERSN. More information on internal logger return codes and
S99ERSN appears below.
ANSAA_Diag2
contains either the contents of the 4 byte field S99ERSN or the contents of the 2 byte field
S99ERROR followed by the 2 byte field S99INFO.
More information on these fields appears below.
S99ERSN, S99ERROR and S99INFO are fields in the
IEFZB4D0 control block that logger uses to communicate with dynamic allocation.
If you receive any one of the following internal logger return codes in ANSAA_Diag1, contact IBM: X'04', x'10', x'14', x'1C'.
S99ERROR is documented in Interpreting Error Reason
Codes from DYNALLOC of the z/OS MVS Programming:
Authorized Assembler Services Guide.
S99ERSN is documented in S99RBX Fields of the z/OS
MVS Programming: Authorized Assembler Services Guide.
S99INFO is documented in Interpreting Information
Reason Codes from DYNALLOC in the z/OS MVS
Programming: Authorized Assembler Services Guide.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
735
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code Meaning and Action
After you have researched the meaning of S99ERROR,
S99ERSN and S99INFO, you may be able to find even more information about the meaning of S99ERSN by looking up a DFSMS message whose ID is IGDxxxx.
You compute xxx: It is the value found in S99ERSN, converted to decimal. The information for this IGDxxxx message gives the meaning of the value found in
S99ERSN, even if the DFSMS message does not appear in syslog. Not all values of S99ERSN map to an
IGCxxxx message. Here are some examples of S99ERSN values and the related message ID: If S99ERSN is x'00042CF', the DFSMS message ID would be IGD17103.
Sometimes zeros must be inserted after IGD. For example, if S99ERSN is x'00003F6', the DFSMS message
ID would be IGD01014. IGD messages are documented in z/OS MVS System Messages, Vol 8 (IEF-IGD).
08 xxxx0808
Look in syslog for any messages that were issued near the time your application invoked the IXGINVNT macro. Look for messages that begin with IXG.
Messages of interest will often have 2 message IDs where the first message ID is IXG251I, and the second begins with IGD, IDC, IKJ, IEF or ICH.
If message IXG263E was issued, follow the actions documented for that message.
If the problem persists, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center.
Equate Symbol
: IxgRsnCodeIOError
08
08 xxxx080A xxxx080B
Explanation
: System error. A severe log data set I/O error has occurred.
Action
: Contact the IBM Support Center. Provide the return and reason code.
Equate Symbol
: IxgRsnCodeRequestLocked
Explanation
: Program error. The program issuing the request is holding a lock.
Action
: Ensure that the program issuing the request is not holding a lock.
Equate Symbol
: IxgRsnCodeNoStream
Explanation
: Program error. The log stream name specified has not been defined in the LOGR policy.
Action
: Ensure that the required log stream name has been defined in the LOGR policy. If the definition appears to be correct, ensure that the application is passing the correct log stream name to the service.
If you received this reason code from IXCMIAPU, see message IXG017E.
736
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx080D
Meaning and Action
Equate Symbol
: IxgRsnCodeNoSAFAuth
Explanation
: Environment error. The user does not have correct SAF authorization for the request. The caller is not authorized for one of the following objects: v The log stream being updated or defined v The log stream named on the LIKE parameter v The log stream named on the NEWSTREAMNAME parameter v
The structure specified v
The structure extracted from the log stream named on the LIKE parameter v Requesting ZAI=YES for the log stream.
Action
: IXGINVNT returns information about the error in the answer area that is mapped by IXGANSAA.
Investigate the meaning of ANSAA_Diag1,
ANSAA_Diag2 and ANSAA_Diag4.
v ANSAA_Diag1 contains the RACF or installation exit return code from the RACROUTE REQUEST=AUTH macro.
v ANSAA_Diag2 contains the RACF or installation exit reason code from the RACROUTE REQUEST=AUTH macro.
v ANSAA_Diag4 contains the SAF return code from the
RACROUTE REQUEST=AUTH macro.
See z/OS Security Server RACROUTE Macro Reference for information about the RACROUTE macro.
08 xxxx080E
Define SAF authorization for any log streams and structures specified.
If the ZAI keyword is provided, ensure the appropriate access is established for using it. If you received this reason code from IXCMIAPU, see message IXG033E.
Equate Symbol
: IxgRsnCodeStreamDefined
Explanation
: Program error. The log stream name specified on a define request or the new log stream name on an update request had already been defined in the LOGR inventory couple data set.
Action
: Do one of the following: v Use the existing definition for the log stream.
v Change the name of the log stream being defined on a define request or the new stream name for an update request.
v Delete the existing log stream definition from the inventory and then reissue the IXGINVNT request to redefine it.
If you received this reason code from IXCMIAPU, see message IXG012E.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
737
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0810
Meaning and Action
Equate Symbol
: IxgRsnCodeStreamInuse
08 xxxx0811
Explanation
: Environment error. You cannot alter or delete a log stream while an application is connected to it. Some attributes can be updated while there are connections provided the appropriate LOGR couple data set and release levels are in effect.
Action
: Reissue the request when there are no active connections to the log stream or move to the appropriate release and LOGR couple data set format level.
If you received this reason code from IXCMIAPU, see message IXG014E.
Equate Symbol
: IxgRsnCodeBadStrname
08
08
08 xxxx0814 xxxx0815 xxxx0816
Explanation
: Environment error. The structure name specified on the STRUCTNAME parameter is not defined in the CFRM policy.
Action
: Make sure that the structure you want to specify is defined in the CFRM policy.
Equate Symbol
: IxgRsnCodeNotAvailForIPL
Explanation
: Environment error. The system logger address space is not available for the remainder of this
IPL. The system issues messages about this error during system logger initialization.
Action
: See the explanation for system messages issued during system logger initialization.
Equate Symbol
: IxgRsnCodeNotEnabled
Explanation
: Program error. The program issuing the request is not enabled for I/O and external interrupts, so the request fails.
Action
: Make sure the program issuing the request is enabled for I/O and external interrupts.
Equate Symbol
: IxgRsnCodeBadAnslen
Explanation
: Program error. The answer area length
(ANSLEN parameter) is not large enough. The system logger returned the required size in the
Ansaa_Preferred_Size field of the answer area, mapped by IXGANSAA macro.
Action
: Reissue the request, specifying an answer area of the required size.
738
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0817
Meaning and Action
Equate Symbol
: IxgRsnCodeBadAnsarea
08
08 xxxx0819 xxxx081A
Explanation
: Program error. The storage area specified on the ANSAREA parameter cannot be accessed. This might occur after the system logger address space has terminated.
Action
: Specify storage that is in the caller's primary address space and in the same key as the calling program at the time the system logger service was issued. This storage must be accessible until the request completes.
Equate Symbol
: IxgRsnCodeSRBMode
Explanation
: Program error. The calling program is in
SRB mode, but task mode is the required dispatchable unit mode for this system logger service.
Action
: Make sure the calling program is in task mode.
Equate Symbol
: IxgRsnCodeMaxStreamConn &
IXGINVNT requests
08 xxxx081B
Explanation
: Environment error. This system has reached the limit for the maximum number of log streams that can be concurrently active. One of the following is true: v The limit of 16,384 concurrently active DASDONLY log streams per system has been reached. For this case, the Answer Area field DIAG1 will contain
16,384.
v Either the PRODUCTION or TEST GROUP cannot connect to any more log streams. Message IXG075E or
IXG076I is issued. In this case, the Answer Area field
DIAG1 will contain the number of structures that are in use for this GROUP.
v The TEST GROUP has previously failed and a request has been made to define a logstream with
GROUP(TEST). Message IXG074I has been previously issued. In this case, the Answer Area field DIAG1 will contain 0.
v A Log stream delete cannot be processed because logger needs to perform an internal connect to the
Log stream to complete the delete but no more connections are allowed.
Action
: Your workload need to be planned to either consolidate log streams or balance system activity such that fewer log streams are needed during this time frame.
Equate Symbol
: IxgRsnCodePrimaryNotHome
Explanation
: Program error. The primary address space does not equal the home address space.
Action
: Make sure that the primary address space equals the home address space when issuing this system logger service.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
739
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx081E
Meaning and Action
Equate Symbol
: IxgRsnCodeXESStrNotAuth
08 xxxx081F
Explanation
: Environment error. The system logger address space does not have access authority to the coupling facility structure associated with the log stream specified.
Action
: Make sure the system logger address space has
SAF access to the structure.
Equate Symbol
: IxgRsnCodeXcdsError
Explanation
: System error. System logger encountered an internal problem while processing the LOGR couple data set.
08 xxxx0821
Action
: Contact the IBM Support Center. Provide the return and reason code and the contents of the answer area (ANSAREA field).
Equate Symbol
: IxgRsnCodeDspCreateFailed
Explanation
: System error. A data space create failed during logger inventory processing.
If you have received this reason code while running a job that uses the IXCMIAPU utility, then messages
IXG002E and IXG003I will appear in your joblog.
Investigating the diag fields in IXG003I may be helpful.
Message IXG003I is documented in z/OS MVS System
Messages, Vol 10 (IXC-IZP).
If your application has received this reason code from the IXGINVNT macro, follow the action steps below.
Action
: IXGINVNT returns information about the error in the answer area, mapped by IXGANSAA. Investigate the maning of ANSAA_Diag1 and ANSAA_Diag2.
ANSAA_Diag1
contains the return code from the
DSPSERV macro.
08 xxxx0822
ANSAA_Diag2
contains the reason code from the
DSPSERV macro.
The DSPSERV macro's return and reason codes are documented in the z/OS MVS Programming: Assembler
Services Reference ABE-HSP.
Equate Symbol
: IxgRsnCodeBadHlq
Explanation
: Program error. The high level qualifier specified on the HLQ parameter was incorrect.
Action
: Specify a valid high level qualifier and reissue the request.
740
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0823
Meaning and Action
Equate Symbol
: IxgRsnCodeNoInvrecSpace
Explanation
: Environment error. The LOGR couple data set cannot be updated because the maximum number of entries for the specified type has already been reached.
08
08 xxxx0824 xxxx0825
Action
: v Format a new LOGR couple data set using the
IXCL1DSU utility. In the new LOGR couple data set either delete unused entries or increase the allowed number of entries on the LSR parameter (for log stream entries) or the LSTRR parameter (for coupling facility structure entries).
v PSWITCH the current alternate LOGR couple data set to primary.
v Add the new LOGR couple data set as alternate.
v PSWITCH the new LOGR couple data set from alternate to primary.
If you received this reason code from IXCMIAPU, see message IXG010E.
Equate Symbol
: IxgRsnCodeMaxStreamStr
Explanation
: Program error. A program issued
IXGINVNT to associate a structure with a log stream, but the maximum number of log streams allowed (as defined on the LOGSNUM parameter) has been reached for the specified structure.
Action
: Either specify a structure that has not reached its LOGSNUM limit, or specify a larger LOGSNUM value on the definition for the structure.
If you received this reason code from IXCMIAPU, see message IXG011E.
Equate Symbol
: IxgRsnCodeStrDefined
08 xxxx0826
Explanation
: Program error. The structure specified on the IXGINVNT request is already defined in the LOGR inventory couple data set.
Action
: Either use the existing structure definition, change the name of the structure being defined or delete the existing structure and redefine it.
If you received this reason code from IXCMIAPU, see message IXG013E.
Equate Symbol
: IxgRsnCodeBadLogsnum
Explanation
: Program error. The LOGSNUM value specified for a structure definition was not within the valid range between 1 and 512.
Action
: Change the LOGSNUM value to be within the valid range.
If you received this reason code from IXCMIAPU, see message IXG016E.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
741
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0827
Meaning and Action
Equate Symbol
: IxgRsnCodeNoStrRecord
08 xxxx0828
Explanation
: Program error. The coupling facility structure specified in the definition for a log stream is not defined in the LOGR inventory couple data set.
Action
: Either define the coupling facility structure before referencing it in a log stream definition, or specify an existing structure definition.
If you received this reason code from IXCMIAPU, see message IXG018E
Equate Symbol
: IxgRsnCodeStrRecordInuse
08 xxxx0829
Explanation
: Program error. The request to delete a structure definition from the LOGR inventory couple data set cannot be completed because several log stream definitions reference it. You cannot delete a structure definition until all the log streams associated with it have been deleted first.
Action
: Delete all the log streams associated with the structure you wish to delete, and then reissue the request.
If you received this reason code from IXCMIAPU, see message IXG015E.
Equate Symbol
: IxgRsnCodeBadStgStorClas
Explanation
: Program error. The name specified on the
STG_STORCLAS parameter is incorrect.
08
08 xxxx082A xxxx082B
Action
: Change the staging data set storage class specified to meet the STG_STORCLAS syntax requirements.
Equate Symbol
: IxgRsnCodeBadLSStorClas
Explanation
: The name specified on the LS_STORCLAS parameter is incorrect.
Action
: Change the log stream data set storage class specified to meet the LS_STORCLAS syntax requirements.
Equate Symbol
: IxgRsnCodeBadStreamLike
Explanation
: Program error. The log stream name specified on the LIKE parameter was not valid.
Action
: Reissue the request with a valid log stream name on the LIKE parameter.
If you received this reason code from IXCMIAPU, see message IXG031E.
742
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx082C
Meaning and Action
Equate Symbol
: IxgRsnCodeBadStructName
Explanation
: Program error. The coupling facility structure name specified on the STRUCTNAME parameter is not valid.
08
08 xxxx082E xxxx082F
Action
: Reissue the request with a valid structure name on the STRUCTNAME parameter.
Equate Symbol
: IxgRsnCodeNoLogrCDSAvail
Explanation
: Environment error. The request failed because no LOGR couple data set is available. The operator was prompted to either make a couple data set available or to indicate that the current request should be rejected. The operator specified that the current request should be rejected.
Action
: System logger services are unavailable for the remainder of this IPL.
Equate Symbol
: IxgRsnCodeBadStgDataClas
08
08
08 xxxx0830 xxxx0831 xxxx0832
Explanation
: Program error. The name specified on the
LS_DATACLAS parameter is not valid.
Action
: Change the data class specified to meet the
LS_DATACLAS syntax requirements.
Equate Symbol
: IxgRsnCodeBadLSDataClas
Explanation
: Program error. The name specified on the
STG_DATACLAS parameter is not valid.
Action
: Change the data class specified to meet the
STG_DATACLAS syntax requirements.
Equate Symbol
: IxgRsnCodeBadStreamName
Explanation
: Program error. The log stream name specified on the STREAMNAME parameter is not valid.
Action
: Reissue the request with a valid log stream name on the STREAMNAME parameter.
If you received this reason code from IXCMIAPU, see message IXG021E.
Equate Symbol
: IxgRsnCodeBadStgMgmtClas
Explanation
: Program error. The name specified on the
STG_MGMTCLAS parameter is not valid.
Action
: Change the staging data set management class specified to meet the STG_MGMTCLAS syntax requirements.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
743
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0833
Meaning and Action
Equate Symbol
: IxgRsnCodeBadLSMgmtClas
Explanation
: Program error. The name specified on the
LS_MGMTCLAS parameter is not valid.
08
08 xxxx0834 xxxx0835
Action
: Change the log stream data set management class specified to meet the LS_MGMTCLAS syntax requirements.
Equate Symbol
: IxgRsnCodeInvalidLSSize
Explanation
: Program error. A non-zero LS_SIZE is specified, but is not in the range valid for a VSAM linear data set.
Action
: Either change the LS_SIZE or omit it from the
DEFINE request to accept the default value.
If you received this reason code from IXCMIAPU, see message IXG040E.
Equate Symbol
: IxgRsnCodeInvalidStgSize
Explanation
: Program error. A non-zero STG_SIZE is specified, but is not in the range valid for a VSAM linear data set.
Action
: Either change the STG_SIZE or omit it from the
DEFINE request to accept the default value.
08
08 xxxx0838 xxxx0839
If you received this reason code from IXCMIAPU, see message IXG040E.
Equate Symbol
: IxgRsnCodeUnDefSmsClas
Explanation
: Program error. At least one of the names specified for DATACLAS, MGMTCLAS, or STORCLAS is not defined to SMS.
Action
: Specify names that are defined to the active
SMS configuration.
If you received this reason code from IXCMIAPU, see message IXG007E.
Equate Symbol
: IxgRsnCodeBadCdsLevel
Explanation
: The active primary LOGR couple data set is not formatted at the level required for the request. See the explanation of the parameters for the level each requires.
Action
: Take one of the following actions: v
Bring a new new active primary LOGR couple data set at the required level into the sysplex and then retry the request.
v Remove the keywords requiring an new level of the
LOGR couple data set and retry the request.
744
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx083C
Meaning and Action
Equate Symbol
: IxgRsnCodeBadMaxBufSize
Explanation
: Program error. For a DEFINE or UPDATE request, the value specified for MAXBUFSIZE was incorrect. It must be a value between 1 and 65,532.
For an UPDATE request, one of the following is causing the error: v The value specified is less than the MAXBUFSIZE value currently associated with a DASD-only log stream, or v
The current DASD-only MAXBUFSIZE value is greater than the MAXBUFSIZE value associated with the STRUCTNAME specified on the update request, or v The current structure MAXBUFSIZE value is greater than the MAXBUFSIZE value associated with the
STRUCTNAME specified on the UPDATE request.
Action
: Do one of the following, depending on the request:
For a DEFINE request
, specify a valid value for
MAXBUFSIZE and reissue the request.
For an UPDATE request,
do one of the following: v Specify a value within the valid range for
MAXBUFSIZE that is greater than or equal to the current DASD-only MAXBUFSIZE value.
v Ensure that the structure specified on the
STRUCTNAME parameter has a maximum buffer size that is greater than or equal to the current
MAXBUFSIZE value associated with the log stream specified on the UPDATE request.
08
08 xxxx083E xxxx0840
If you received this reason code from IXCMIAPU, see message IXG009E.
Equate Symbol
: IxgRsnCodeNoAvailSysRec
Explanation
: System error. There were no available system records.
Action
: Contact the IBM support center. Provide the return and reason codes and the contents of the system logger trace.
Equate Symbol
: IxgRsnCodeBadVersion
Explanation
: Environment error. The parameter list passed to the service routine had an invalid version indicator.
Action
: Ensure the level of MVS executing the request and the macro library used to compile the invoking routine are compatible.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
745
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0842
Meaning and Action
Equate Symbol
: IxgRsnCodeBadAvgBufSize
Explanation
: Program error. The value specified for
AVGBUFSIZE was specified as incorrect. It must be a value between and 65,536 that is less than
MAXBUFSIZE.
Action
: Reissue the request with a valid AVGBUFSIZE value.
08
08 xxxx0843 xxxx0844
If you received this reason code from IXCMIAPU, see message IXG022E.
Equate Symbol
: IxgRsnCodeXcdsReformat
Explanation
: Program error. A couple data set record is not valid.
Action
: Reformat the system logger couple data set.
If you received this reason code from IXCMIAPU, see message IXG030E.
Equate Symbol
: IxgRsnCodeNoStreamLike
08
08 xxxx0845 xxxx084E
Explanation
: Program error. The log stream name specified on the LIKE parameter is not defined in the
LOGR couple data set.
Action
: Do one of the following: v Define the log stream you wish to reference in the
LOGR inventory couple data set and reissue the request.
v Reissue the request, specifying a different log stream that is already defined in the LOGR couple data set.
If you received this reason code from IXCMIAPU, see message IXG019E.
Equate Symbol
: IxgRsnCodeInvalidFunc
Explanation
: System error. The parameter list for this service contains an unrecognizable function code. The parameter list storage might have been overlaid.
Action
: Fix the problem and then reissue the request.
Equate Symbol
: IxgRsnCodeStrSpaceTooSmall
Explanation
: Environment error. Structure resources are not available to satisfy the request. All structure resources are allocated as system logger control resources. This condition occurs when the structure resources are consumed by the log streams connection.
Action
: Increase the size of the structure in the CFRM policy, or use SETXCF ALTER support to dynamically increase the size of the structure.
746
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0850
Meaning and Action
Equate Symbol
: IxgRsnCodeBadVectorLen
08 xxxx0851
Explanation
: Environment error. The connect request was rejected. System logger was unable to locate a vector table in the hardware system area (HSA) that is large enough for the number of log streams associated with it.
Action
: Add storage to the vector storage table or retry the connect request later when storage is available.
Equate Symbol
: IxgRsnCodeBadCFLevel
Explanation
: Environment error. The connect request was rejected. The operational level of the coupling facility is not sufficient to support logger functions.
08
08
08 xxxx0853 xxxx0854 xxxx0855
Action
: Ensure that the coupling facility operational level for logger structures is at least CFLEVEL=1.
Equate Symbol
: IxgRsnCodeNoCF
Explanation
: The connect request was rejected. System logger could not allocate coupling facility structure space, because no suitable coupling facility was available.
Action
: Check accompanying message IXG206I for a list of the coupling facilities, where space allocation was attempted and the reason why each attempt failed.
Equate Symbol
: IxgRsnCodeBadLowoffload
Explanation
: Program error. The value specified for
LOWOFFLOAD is not valid.
Action
: Change the value to meet the LOWOFFLOAD syntax requirements.
If you received this reason code from IXCMIAPU, see message IXG035E.
Equate Symbol
: IxgRsnCodeBadHighoffload
Explanation
: Program error. The value specified for
HIGHOFFLOAD is invalid.
Action
: Change the value to meet the HIGHOFFLOAD syntax requirements.
If you received this reason code from IXCMIAPU, see message IXG036E.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
747
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0856
Meaning and Action
Equate Symbol
: IxgRsnCodeBadLowHighOffLoad
Explanation
: Program error. The value specified or defaulted to for the low offload value is equal to or higher than the high offload value. The low offload value must be lower than the high offload value.
08 xxxx0857
Action
: Change either the LOWOFFLOAD parameter or the HIGHOFFLOAD parameter so that the low offload value is less than the high offload value.
If you received this reason code from IXCMIAPU, see messages IXG442E and either IXG035E or IXG036E.
Equate Symbol
: IxgRsnCodeDuplexmodeDuplexNo
Explanation
: Program error. DUPLEXMODE was specified, but the log stream was defined with
STG_DUPLEX=NO. The DUPLEXMODE parameter is only valid with STG_DUPLEX=YES.
Action
: Either change the log stream definition to specify STG_DUPLEX=YES or else omit DUPLEXMODE from the request.
08
08
08
08
08 xxxx0858 xxxx0859 xxxx085A xxxx085B xxxx085E
If you received this reason code from IXCMIAPU, see message IXG037E.
Equate Symbol
: IxgRsnCodeStgSizeDuplexNo
Explanation
: This reason code is obsolete and will no longer be returned.
Equate Symbol
: IxgRsnCodeDataClasDuplexNo
Explanation
: This reason code is obsolete and will no longer be returned.
Equate Symbol
: IxgRsnCodeMgmtClasDuplexNo
Explanation
: This reason code is obsolete and will no longer be returned.
Equate Symbol
: IxgRsnCodeStorClasDuplexNo
Explanation
: This reason code is obsolete and will no longer be returned.
Equate Symbol
: IxgRsnCodeNoStructName
Explanation
: Program error. A structure name was not provided for this log stream via the STRUCTNAME parameter or defined for a log stream named on a LIKE parameter. A STRUCTNAME value is required to successfully define a log stream to the LOGR couple data set.
Action
: Provide a value for the STRUCTNAME parameter or define a structure for the log stream referenced on the LIKE parameter.
If you received this reason code from IXCMIAPU, see message IXG041E.
748
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx0890
Meaning and Action
Equate Symbol
: IxgRsnCodeAddrSpaceNotAvail
08 xxxx0891
Explanation
: System error. The system logger address space failed and is not available.
Action
: Do not issue system logger requests.
If you received this reason code from IXCMIAPU, see message IXG008E.
Equate Symbol
: IxgRsnCodeAddrSpaceInitializing
08 xxxx08D4
Explanation
: System error. The system logger address space is not available because it is IPLing.
Action
: Listen for ENF signal 48, which will indicate when the system logger address space is available.
Reissue this request. You can also listen for ENF signal
48, which will indicate if the system logger address space will not be available for the life of the IPL. In that case, do not issue system logger services.
If you received this reason code from IXCMIAPU, see message IXG008E.
Equate Symbol
: IxgRsnCodeBadRMName
08
08 xxxx08D5 xxxx08D8
Explanation
: Program Error. The name of the resource manager specified on the RMNAME parameter was not valid.
Action
: Correct the RMNAME and retry the request.
Equate Symbol
: IxgRsnCodeBadLSDescription
Explanation
: Program Error. The name of the field specified in the DESCRIPTION parameter was not valid.
DESCRIPTION must be 16 alphanumeric or national
($,#,@) characters, underscore (_) or period (.), padded on the right with blanks if necessary.
Action
: Correct the DESCRIPTION field name and retry the request.
Equate Symbol
: IxgRsnCodeBadRetpd
Explanation
: Program Error. The value specified for
RETPD was incorrect. It must be a value >= 0 and <=
65,536.
Action
: Specify a valid value for RETPD and reissue the request.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
749
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx08E0
Meaning and Action
Equate Symbol
: IxgRsnCodeStgDuplexDasdOnly
08 xxxx08E1
Explanation
: Program Error. The STG_DUPLEX keyword was specified with an invalid parameter when a DASD only logstream was defined or updated. When you define or update a DASD only logstream you must omit the STG_DUPLEX keyword or specify
STG_DUPLEX=YES. No other option is allowed because
DASD only log streams are unconditionally duplexed to staging data sets.
Action
: For DASD only log stream DEFINE and
UPDATE requests specify STG_DUPLEX=YES or omit the STG_DUPLEX keyword.
This error code may also result when using the
IXCMIAPU DATA TYPE(LOGR) utility when the
STG_DUPLEX option is specified for a DASD only log stream. See system logger error messages IXG002E or
IXG447I.
Equate Symbol
: IxgRsnCodeDuplexModeDasdOnly
08 xxxx08E2
Explanation
: Program Error. The DUPLEXMODE keyword was specified with an invalid parameter when a DASD only logstream was defined or updated. When you define or update a DASD only logstream you must omit the DUPLEXMODE keyword or specify
DUPLEXMODE=UNCOND. No other option is allowed because DASD only log streams are unconditionally duplexed to staging data sets.
Action
: For DASD only log stream DEFINE and
UPDATE requests specify DUPLEXMODE=UNCOND or omit the DUPLEXMODE keyword.
This error code may also result when using the
IXCMIAPU DATA TYPE(LOGR) utility when the
DUPLEXMODE option is specified for a DASD only log stream. See system logger messages IXG002E or
IXG447I.
Equate Symbol
: IxgRsnCodeDasdOnlyConnected
Explanation
: Environment error. System logger rejected an attempt to connect to a DASD-only log stream because another log stream in the sysplex is already connected to that log stream. Only one system at a time can connect to a DASD-only log stream.
Action
: Determine which system you want to have a connection to the log stream. If you need this connection, disconnect the first system connection to the log stream and retry this connect request.
750
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx08E3
Meaning and Action
Equate Symbol
: IxgRsnCodeLogstreamNotSupported
Explanation
: Environment error. An attempt to connect or effect the LOGR inventory for the log stream is rejected on this system. The system release level does not support this type of log stream, or a log stream attribute such as EHLQ, Duplexmode(Drxrc),
GROUP(TEST), or NewStreamName cannot be processed on this system release level.
Action
: When attempting to connect or delete a log stream that has the EHLQ attribute, you must do so on at least a z/OS Version 1 Release 3 system release level.
If you must use a log stream with the
DUPLEXMODE(DRXRC) attribute specified, make sure you do so from a system that is at a release level between z/OS Version 1 Release 7 and z/OS Version 1
Release 7 and higher release levels, with z/OS Version 2
Release 2, inclusively.
If you must use a log stream with the
NEWSTREAMNAME attribute specified, make sure you do so from a system that is at z/OS Version 1 Release 8 release or higher.
If you must use a log stream with the GROUP attribute specified, make sure you do so from a system that is at z/OS Version 1 Release 8 release or higher.
08 xxxx08E4
If you received this reason code from IXCMIAPU, see message IXG233I.
Equate Symbol
:
IXGRSNCODEMAXBUFSIZEDASDONLY
Explanation
: Program error. A value was specified for
MAXBUFSIZE on this request, but the log stream was defined as a coupling facility log stream
(DASDONLY=NO). MAXBUFSIZE is not a valid parameter on a log stream definition request for a coupling facility log stream.
Action
: Either remove the MAXBUFSIZE parameter from this request or specify DASDONLY=YES with
MAXBUFSIZE.
If you received this reason code from IXCMIAPU, see messages IXG433E and IXG434E.
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
751
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx08E5
Meaning and Action
Equate Symbol
: IxgRsnCodeloggerDuplexDasdOnly
08 xxxx08E6
Explanation
: Program error. The LOGGERDUPLEX keyword was specified with an invalid parameter when a DASD only logstream was defined or updated. When you define or update a DASD only logstream you must omit the LOGGERDUPLEX keyword or specify
LOGGERDUPLEX=UNCOND. No other option is allowed because DASD only log streams are unconditionally duplexed to staging data sets.
Action
: For DASD only log stream DEFINE and
UPDATE requests specify LOGGERDUPLEX=UNCOND or omit the LOGGERDUPLEX keyword.
This error code may also result when using the
IXCMIAPU DATA TYPE(LOGR) utility when the
LOGGERDUPLEX option is specified for a DASD only log stream. See system logger error messages IXG002E or IXG447I.
Equate Symbol
: IxgRsnCodeBadEhlq
08 xxxx08E7
Explanation
: Program error. The extended high level qualifier for the log stream data sets specified on the
EHLQ parameter was incorrect. This could be from a syntax error or by specifying EHLQ and HLQ on the same request.
Action
: Specify a valid extended high level qualifier
(EHLQ) or high level qualifier (HLQ) and reissue the request.
If you received this reason code from IXCMIAPU, see message IXG440E.
Equate Symbol
: IxgRsnCodeEhlqTooLong
Explanation
: Program error. The combined length of the extended high level qualifier (EHLQ value) and the log stream name (with a period delimiter) exceeds 35 characters. The combined length of the EHLQ value, the log stream name, and the logger suffix (with period delimiters) cannot exceed 44 characters.
Action
: Specify a valid extended high-level qualifier
(EHLQ) or high-level qualifier (HLQ) and reissue the request.
If you received this reason code from IXCMIAPU, see message IXG441E.
752
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
Table 42. Return and Reason Codes for the IXGINVNT Macro (continued)
Return Code Reason Code
08 xxxx08E8
Meaning and Action
Equate Symbol
: IxgRsnCodeBadNewStreamName
Explanation
: Program error. The log stream name specified on the NEWSTREAMNAME parameter was not valid. This error code might also result when using the IXCMIAPU DATA TYPE(LOGR) utility when the
NEWSTREAMNAME option is specified for a log stream.
Action
: Reissue the request with a valid log stream name on the NEWSTREAMNAME parameter.
08
08
0C xxxx08E9 xxxx08EA xxxx0000
If you received this reason code from IXCMIAPU, see message IXG031E.
Equate Symbol
: IxgRsnCodeBadGroup
Explanation
: Program error. For DEFINE requests, the
GROUP value is not allowed because the specified structure is not the same GROUP. For UPDATE requests, the GROUP value is not allowed because the specified
(or current) structure is not the same GROUP.
Action
: Specify a valid GROUP value or use a different structure that matches the desired GROUP value.
Equate Symbol
: IxgRsnCodeBadLsAllocAhead
Explanation
: Program error. The LS_ALLOCAHEAD value that was specified for a log stream definition was not within the valid range between 0 and 3 (inclusive).
Action
: Change the LS_ALLOCAHEAD value to be within the valid range. If you received this reason code from IXCMIAPU, see message IXG016E.
Equate Symbol
: IxgRetCodeCompError
Explanation
: User or System error. One of the following occurred: v You issued the FORCE IXGLOGR,ARM command to terminate the system logger address space.
v System logger component error occurred.
Action
: If this reason code is not the result of forcing the system logger address space, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center. Provide the diagnostic data in the answer area (IXGANSAA) and any dumps or LOGREC entries from system logger.
Example 1
Issue IXGINVNT REQUEST=DEFINE to define a coupling facility structure associated with one or more log streams.
IXGINVNT REQUEST=DEFINE,
TYPE=STRUCTURE,
STRUCTNAME=STRUCT,
LOGSNUM=LOGNUM,
AVGBUFSIZE=AVGBUF,
X
X
X
X
X
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
753
IXGINVNT macro
MAXBUFSIZE=MAXBUF,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
STRUCT DC
LOGNUM DC
AVGBUF
MAXBUF
RETCODE
RSNCODE
DC
DC
ANSAREA DS
ANSLEN DC
DS
DS
MF=S,
RETCODE=RETCODE
CL16’LIST01’
F’10’
F’256’
F’4096’
CL(ANSAA_LEN)
A(L’ANSAREA)
F
F
DATAREA DSECT
IXGANSAA LIST=YES structure name num allocated logstreams allowed average buffer size maximum buffer size answer area for log requests length of logger’s answer area return code from logger reason code from logger answer area
X
X
X
X
X
Example 2
Issue IXGINVNT REQUEST=DEFINE to define a log stream that writes to both the coupling facility and DASD log data sets as a model and issue IXGINVNT
REQUEST=DEFINE a second time to define another log stream modeled on the first using the LIKE parameter.
IXGINVNT REQUEST=DEFINE,
TYPE=LOGSTREAM,
STREAMNAME=STRNAME,
STRUCTNAME=STRUCT,
DATACLAS=DATACLAS,
MGMTCLAS=MGMTCLAS,
STORCLAS=STORCLAS,
HLQ=HLQ,
MODEL=YES,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
IXGINVNT REQUEST=DEFINE,
TYPE=LOGSTREAM,
STREAMNAME=STRNAME1,
LIKE=STRNAME,
STRUCTNAME=STRUCT,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
ANSLEN DC
STRNAME DC
STRNAME1 DC
STRUCT DC
DATACLAS DC
MGMTCLAS DC
STORCLAS DC
HLQ DC
ANSAREA DS
RETCODE=RETCODE
A(L’ANSAREA) length of logger’s answer area
CL26’LOG.STREAM.NAME’ stream name for model
CL26’LOG.STREAM1.NAME’ stream name for like
CL16’LIST01’
CL8’VSAMLS’
CL8’INTERIM’
CL8’STANDARD’
CL8’USERNAME’
CL(ANSAA_LEN)
RETCODE DS
RSNCODE DS
F
F
DATAREA DSECT
IXGANSAA LIST=YES associated structure name data class name management class name storage class name high level qualifier answer area for log requests return code from logger reason code from logger answer area
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
Example 3
Issue IXGINVNT REQUEST=UPDATE to update a log stream definition.
754
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
IXGINVNT REQUEST=UPDATE,
TYPE=LOGSTREAM,
STREAMNAME=STRNAME,
DATACLAS=DATACLAS,
MGMTCLAS=MGMTCLAS,
STORCLAS=STORCLAS,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
STRNAME DC
DATACLAS DC
MGMTCLAS DC
STORCLAS DC
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
CL26’LOG.STREAM.NAME’ stream name
CL8’NEWCLASS’
CL8’NEWMGMNT’
CL8’NEWSTOR’
CL(ANSAA_LEN) data class name management class name storage class name answer area for log requests ANSAREA DS
ANSLEN
RETCODE
RSNCODE
DC
DS
DS
A(L’ANSAREA)
F
F
DATAREA DSECT
IXGANSAA LIST=YES length of logger’s answer area return code from logger reason code from logger answer area
X
X
X
X
X
X
X
X
X
X
Example 4
Issue IXGINVNT to define a log stream with a resource manager associated with it.
IXGINVNT REQUEST=DEFINE,
TYPE=LOGSTREAM,
STREAMNAME=SNAME,
STRUCTNAME=STRUCT,
RMNAME=RMNAME,
STG_DUPLEX=NO,
DESCRIPTION=DESCR,
ANSAREA=XANSAREA,
ANSLEN=XANSLEN,
RSNCODE=RSCODE
*
SNAME DS
STRUCT DS
CL26
CL16
RMNAME DS
DESCR DS
XANSAREA DS
XANSLEN DC
CL8
CL16
CL(ANSAA_LEN)
A(ANSAA_LEN)
RSCODE DS F
DSECT ,
IXGANSAA ,
Stream name
Structure name
Res Man name
Description logger answer area
Answer area length
Reason code
The answer area macro
Example 5
Issue IXGINVNT to define a log stream with no retention period and autodeletion.
This means that log data is deleted whenever IXGDELET is issued against the log stream.
SNAME DS
STRUCT DS
XANSAREA DS
XANSLEN DC
IXGINVNT REQUEST=DEFINE,
TYPE=LOGSTREAM,
STREAMNAME=SNAME,
STRUCTNAME=STRUCT,
STG_DUPLEX=NO,
RETPD=0,AUTODELETE=YES,
ANSAREA=XANSAREA,
ANSLEN=XANSLEN,
RSNCODE=RSCODE
CL26
CL16
CL(ANSAA_LEN)
A(ANSAA_LEN)
Stream name
Structure name logger answer area
Answer area length
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
755
IXGINVNT macro
RSCODE DS F
DSECT ,
IXGANSAA ,
Reason code
The answer area macro
Example 6
Issue IXGINVNT to define a log stream with staging data sets and a policy of unconditional duplexing. This means that data will always be duplexed to staging data sets, even if the configuration is not volatile.
IXGINVNT REQUEST=DEFINE,
TYPE=LOGSTREAM,
STREAMNAME=SNAME,
STRUCTNAME=STRUCT,
STG_DUPLEX=YES,DUPLEXMODE=UNCOND,
ANSAREA=XANSAREA,
ANSLEN=XANSLEN,
RSNCODE=RSCODE
SNAME
STRUCT
XANSAREA DS
XANSLEN
DS
DS
DC
CL26
CL16
CL(ANSAA_LEN)
A(ANSAA_LEN)
RSCODE DS F
DSECT ,
IXGANSAA ,
Stream name
Structure name logger answer area
Answer area length
Reason code
The answer area macro
Example 7
Issue IXGINVNT REQUEST=DELETE to delete a structure definition.
IXGINVNT REQUEST=DELETE,
TYPE=STRUCTURE,
STRUCTNAME=STRUCT,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
STRUCT
ANSAREA
ANSLEN
RETCODE
DC
DS
DC
DS
CL16’LIST01’
CL(ANSAA_LEN)
A(L’ANSAREA)
F
F RSNCODE DS
DATAREA DSECT
IXGANSAA LIST=YES structure name answer area for log requests length of logger’s answer area return code from logger reason code from logger answer area
X
X
X
X
X
X
X
Example 8
Issue IXGINVNT with in list, execute and modify forms.
IXGINVNT MF=(L,IXGINVNT_PLIST)
IXGINVNT REQUEST=DEFINE,
STREAMNAME=STRNAME,
MF=(M,IXGINVNT_PLIST,NOCHECK)
ANSLEN DC
STRNAME DC
ANSAREA DS
RETCODE DS
IXGINVNT REQUEST=DEFINE,
TYPE=LOGSTREAM,
MODEL=NO,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=(E,IXGINVNT_PLIST,NOCHECK)
RETCODE=RETCODE
A(L’ANSAREA) length of logger’s answer area
CL26’LOG.STREAM.NAME’ stream name
CL(ANSAA_LEN)
F answer area for log requests return code from logger
X
X
X
X
X
X
X
X
X
756
z/OS MVS Assembler Services Reference IAR-XCT
IXGINVNT macro
RSNCODE DS
DATAREA DSECT
F
IXGANSAA LIST=YES
Example 9
Issue IXGINVNT using registers.
LA R6,STRUCT
IXGINVNT REQUEST=DELETE,
TYPE=STRUCTURE,
STRUCTNAME=(6),
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
STRUCT DC
ANSAREA DS
ANSLEN DC
RETCODE DS
RETCODE=RETCODE
CL16’LIST01’
CL(ANSAA_LEN)
A(L’ANSAREA)
RSNCODE DS
DATAREA DSECT
R6
F
F
IXGANSAA LIST=YES
EQU 6 reason code from logger answer area load struture name into reg 6 structure name answer area for log requests length of logger’s answer area return code from logger reason code from logger answer area set up register 6
X
X
X
X
X
X
X
Example 10
Issue IXGINVNT REQUEST=DEFINE to define a log stream as DASD-only:
IXGINVNT REQUEST=DEFINE,
TYPE=LOGSTREAM,
STREAMNAME=STRNAME,
DASDONLY=YES,
GROUP=PRODUCTION,
MAXBUFSIZE=MAXBUF,
HLQ=HLQ,
ANSAREA=ANSAREA,
ANSLEN DC
STRNAME DC
MAXBUF DC
HLQ DC
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
A(L’ANSAREA)
CL26’LOG.STREAM.NAME’
F’65532’
CL8’USERNAME’
ANSAREA DS
RETCODE DS
RSNCODE DS
DATAREA DSECT
CL(ANSAA_LEN)
F
F
IXGANSAA LIST=YES length of logger’s answer area log stream name maximum buffer size high level qualifier answer area for log requests return code from logger reason code from logger answer area
X
X
X
X
X
X
X
X
X
X
X
Example 11
Issue IXGINVNT REQUEST=DEFINE to define a log stream as DASD-only and then issue the IXGINVNT REQUEST=UPDATE request to upgrade the DASD-only log stream to a coupling facility log stream, associating it with structure 1:
IXGINVNT REQUEST=DEFINE,
TYPE=LOGSTREAM,
STREAMNAME=STRNAME,
DASDONLY=YES,
GROUP=PRODUCTION,
MAXBUFSIZE=MAXBUF,
HLQ=HLQ,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
X
X
X
X
X
X
X
X
X
X
Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set
757
IXGINVNT macro
MF=S,
RETCODE=RETCODE
IXGINVNT REQUEST=UPDATE,
TYPE=LOGSTREAM,
STREAMNAME=STRNAME,
STRUCTNAME=STRUCT,
GROUP=TEST,
ANSLEN
STRNAME
STRUCT
ANSAREA
DC
DC
DC
DS
RETCODE DS
RSNCODE DS
F
F
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
A(L’ANSAREA) length of logger’s answer area
CL26’LOG.STREAM.NAME’ log stream name
CL16’STRUCTURE1’
CL(ANSAA_LEN) structure name answer area for log requests return code from logger reason code from logger
DATAREA DSECT
IXGANSAA LIST=YES answer area
X
X
X
X
X
X
X
X
X
X
758
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 72. IXGOFFLD — Initiate offload to DASD log data sets
Description
The IXGOFFLD macro allows the caller to intiate an offload of log data from the coupling facility structure for coupling facility log streams and from local storage buffers for DASD-only log streams to DASD log data sets.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state. Any PSW key
Task
Any PASN, any HASN, any SASN
31-bit or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
The caller's parameter list must be resident in the caller's primary address space.
All storage areas specified must be in the same storage key as the caller.
No locks may be held.
None.
Programming requirements
v Before issuing this request, the caller must have issed IXGCONN to connect to the log stream. The caller must specify specify AUTH=WRITE on the IXGCONN request.
v The current primary address space must be the same as the HOME address space at the time you issued the IXGCONN macro.
v The parameter list for this service must be addressable in the caller's primary address space.
v Include the IXGCON mapping macro in your program. This macro provides a list of equate symbols for the system logger services.
v Include mapping macro IXGANSAA in your program. This macro shows the format of the answer area output returned for each system logger service in the
ANSAREA parameter.
Restrictions
All storage areas specified must be in the same storage key as the caller. Storage areas must exist in the caller's primary address space.
Input register information
Before issuing the IXGOFFLD macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
© Copyright IBM Corp. 1988, 2017
759
IXGOFFLD
Syntax
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0
2-13
Reason code, if register 15 contains a non-zero return code
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Used as a work register by the system
2-13
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
IBM recommends that you use IXGOFFLD only when essential. The offloading process does entail some overhead and may degrade system logger performance.
Syntax
The IXGOFFLD macro is written as follows:
Description
name
⌂
name: symbol. Begin name in column 1.
One or more blanks must precede IXGOFFLD.
IXGOFFLD
⌂
STREAMTOKEN=streamtoken
,ANSAREA=ansarea
,ANSLEN=anslen
One or more blanks must follow IXGOFFLD.
streamtoken: RS-type address or address in register (2) - (12).
ansarea: RS-type address or address in register (2) - (12).
anslen: RS-type address or address in register (2) - (12).
760
z/OS MVS Assembler Services Reference IAR-XCT
IXGOFFLD
Syntax
,RETCODE=retcode
Description
retcode: RS-type address or register (2) - (12).
,RSNCODE=rsncode rsncode: RS-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
Default
: PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
Default
: MF=S
list addr: RS-type address or register (1) - (12).
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IXGOFFLD macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
STREAMTOKEN=streamtoken
A required input parameter that specifies the log stream token that was returned on the IXGCONN service.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,ANSAREA=ansarea
A required input parameter of a virtual storage area, called the answer area.
The ANSAREA contains additional error status when the IXGOFFLD service generates an error return code. The format of the returned data is defined by the IXGANSAA mapping macro.
To code:
Specify the RS-type address, or address in register (2)-(12), of a field.
,ANSLEN=anslen
A required input parameter that contains the length in bytes of the virtual storage area provided for ANSAREA.
The length of the answer area is described by the IXGANSAA mapping macro.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
Chapter 72. IXGOFFLD — Initiate offload to DASD log data sets
761
IXGOFFLD
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , which supports all parameters except those referenced in higher versions.
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the
762
z/OS MVS Assembler Services Reference IAR-XCT
IXGOFFLD
parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
1C5 Ixg_Abend_Code - A System Logger abend has occurred.
Reason Code (Hex)
Explanation xxxx085F
IxgRsnCodePercToRequestor -
Explanation:
Environment error. Percolation to the service requestor's task occurred because of an abend during system logger processing. Retry was not allowed.
Action:
Issue the request again. If the problem persists, contact the IBM
Support Center.
Chapter 72. IXGOFFLD — Initiate offload to DASD log data sets
763
IXGOFFLD
Return and reason codes
When the IXGOFFLD macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded
RSNCODE) contains a reason code.
00
04
08
0C
IxgRetCodeOk - Successful completion
IxgRetCodeWarning - The request was processed successfully, however a warning condition was encountered.
IxgRetCodeError - An error has been encountered. The associated reason code provides more information.
IxgRetCodeCompError - A system logger component error has been encountered.
The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code.
Table 43. Return and Reason Codes for the IXGOFFLD Macro
Return Code
00
Reason Code
xxxx0000
Meaning and Action
IxgRsnCodeOk -
08
08
08 xxxx0801 xxxx0802 xxxx0806
Explanation:
Request processed successfully.
IxgRsnCodeBadParmlist -
Explanation:
Program error. The parameter list is not valid.
Either the parameter list storage is inaccessible, or the version of the macro used was not valid.
Action:
Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request, and that the macro version is correct. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.
IxgRsnCodeXESError -
Explanation:
System error. A severe cross-system extended services (XES) error has occurred.
Action:
In the answer area mapped by IXGANSAA, see
ANSAA_DIAG1 for the XES return code and
ANSAA_DIAG2 for the XES reason code.
IxgRsnCodeBadStmToken -
Explanation:
Program error. One of the following occurred: v The stream token was not valid.
v The specified request was issued from an address space other than the connector's address space.
Action:
Do one of the following: v Make sure that the stream token specified is valid.
v Ensure that IXGOFFLD requests were issued from the connector's address space.
764
z/OS MVS Assembler Services Reference IAR-XCT
IXGOFFLD
Table 43. Return and Reason Codes for the IXGOFFLD Macro (continued)
Return Code
08
Reason Code
xxxx080A
Meaning and Action
IxgRsnCodeRequestLocked -
08
08 xxxx0814 xxxx0815
Explanation:
Program error. The program issuing the request is holding a lock.
Action:
Ensure that the program issuing the request is not holding a lock.
IxgRsnCodeNotAvailForIPL -
Explanation:
Environment error. The system logger address space is not available for the remainder of this IPL. The system issues messages about this error during system logger initialization.
Action:
See the explanation for system messages issued during system logger initialization.
IxgRsnCodeNotEnabled -
Explanation:
Program error. The program issuing the request is not enabled for I/O and external interrupts, so the request fails.
08
08
08
08 xxxx0816 xxxx0817 xxxx0819 xxxx081C
Action:
Make sure the program issuing the request is enabled for I/O and external interrupts.
IxgRsnCodeBadAnslen -
Explanation:
Program error. The answer area length
(ANSLEN parameter) is not large enough. The system logger returned the required size in the
Ansaa_Preferred_Size field of the answer area, mapped by
IXGANSAA macro.
Action:
Reissue the request, specifying an answer area of the required size.
IxgRsnCodeBadAnsarea -
Explanation:
Program error. The storage area specified on the ANSAREA parameter cannot be accessed. This might occur after the system logger address space has terminated.
Action:
Specify storage that is in the callers primary address space and in the same key as the calling program at the time the system logger service was issued. This storage must be accessible until the request completes.
IxgRsnCodeSRBMode -
Explanation:
Program error. The calling program is in SRB mode, but task mode is the required dispatchable unit mode for this system logger service.
Action:
Make sure the calling program is in task mode.
IxgRsnCodeNotAuthFunc -
Explanation:
Program error. The program connected to the log stream with the AUTH=READ parameter and then tried to delete, write, offload or update data. You cannot write, delete, update or offload data when connected with read authority.
Action:
Issue the IXGCONN service with AUTH=WRITE authority and then reissue this request.
Chapter 72. IXGOFFLD — Initiate offload to DASD log data sets
765
IXGOFFLD
Table 43. Return and Reason Codes for the IXGOFFLD Macro (continued)
Return Code
08
Reason Code
xxxx082D
Meaning and Action
IxgRsnCodeExpiredStmToken -
08
08 xxxx0840 xxxx0861
Explanation:
Environment error. The stream token is no longer valid because the connector has been disconnected.
Action:
Reconnect to the logstream before issuing any functional requests.
IxgRsnCodeBadVersion -
Explanation:
Environment error. The parameter list passed to the service routine has an incorrect version indicator.
Action:
Make sure that the level of MVS executing the request and the macro library used to compile the invoking routine are compatible.
IxgRsnCodeRebuildInProgress -
Explanation:
Environment error. No requests can be processed for this log stream because a coupling facility structure rebuild is in progress for the structure associated with this log stream.
08
08 xxxx0862 xxxx0863
Action:
Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the rebuild completed successfully. Reissue the request.
v The rebuild failed and the log stream is not available.
IxgRsnCodeXESPurge -
Explanation:
Environment error. An cross-system extended services (XES) request has been purged due to rebuild processing.
Action:
Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the rebuild completed successfully. Reissue the request.
v The rebuild failed and the log stream is not available.
IxgRsnCodeStructureFailed -
Explanation:
Environment error. Either the coupling facility structure associated with the log stream has failed or the coupling facility itself has failed.
Action:
Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the rebuild completed successfully. Reissue the request.
v The rebuild failed and the log stream is not available.
766
z/OS MVS Assembler Services Reference IAR-XCT
IXGOFFLD
Table 43. Return and Reason Codes for the IXGOFFLD Macro (continued)
Return Code
08
Reason Code
xxxx0864
Meaning and Action
IxgRsnCodeNoConnectivity -
08
08
08
0C xxxx0890 xxxx0891 xxxx08DF xxxx0000
Explanation:
Environment error. No connectivity exists to the coupling facility associated with the log stream. The system logger will either attempt to rebuild the log stream in another coupling facility or the log stream will be disconnected.
Action:
Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the rebuild completed successfully. Reissue the request.
v The rebuild failed and the log stream is not available.
v The log stream has been disconnected from this system.
If a re-build initiated because of a loss of connectivity previously failed, an ENF corresponding to this reason code might not be issued. Further action by the installation might be necessary to cause the change of the log stream status again. Check the log for messages IXG101I, IXG107I and related rebuild messages for information on resolving any outstanding issues.
IxgRsnCodeAddrSpaceNotAvail -
Explanation:
System error. The system logger address space failed and is not available.
Action:
Do not issue system logger requests.
IxgRsnCodeAddrSpaceInitializing -
Explanation:
System error. The system logger address space is not available because it is IPLing.
Action:
Listen for ENF signal 48, which will indicate when the system logger address space is available. When it's available, reconnect to the log stream, then reissue this request. You can also listen for ENF signal 48, which will indicate if the system logger address space will not be available for the life of the IPL. In that case, do not issue system logger services.
IxgRsnCodeOffLoadFlushError -
Explanation:
System error. The flush service called by
IXGOFFLD encountered a XES error.
Action:
Examine the answer area, which contains more detailed information about the error.
Equate Symbol
: IxgRetCodeCompError
Explanation:
User or System error. One of the following occurred: v You issued the FORCE IXGLOGR,ARM command to terminate the system logger address space.
v System logger component error occurred.
Action:
If this reason code is not the result of forcing the system logger address space, search problem reporting data bases for a fix for the problem. If no fix exists, contact the
IBM Support Center. Provide the diagnostic data in the answer area (IXGANSAA) and any dumps or LOGREC entries from system logger.
Chapter 72. IXGOFFLD — Initiate offload to DASD log data sets
767
IXGOFFLD
Example
Issue IXGOFFLD to initiate offload processing for a log stream.
IXGOFFLD
STREAMTOKEN=OTOKEN,
ANSAREA=XANSAREA,
ANSLEN=XANSLEN,
OTOKEN DS
XANSAREA DS
XANSLEN DC
RSCODE DS
RSNCODE=RSCODE
CL16
CL(ANSAA_LEN)
A(ANSAA_LEN)
F
DSECT ,
IXGANSAA ,
Output Stream token
Logger answer area
Answer area length
Reason code
The answer area macro
@
@
@
@
768
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 73. IXGQUERY — Query a log stream for information
Description
The IXGQUERY macro allows a user to retrieve information about a log stream or system logger parameter information.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state. Any PSW key
Task
Any PASN, any HASN, any SASN
31-bit or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks may be held.
None.
Programming requirements
v
The parameter list for this service must be addressable in the caller's primary address space.
v Include the IXGCON mapping macro in your program. This macro provides a list of equate symbols for the system logger services.
v Include mapping macro IXGANSAA in your program. This macro shows the format of the answer area output returned for each system logger service in the
ANSAREA parameter.
When coding REQUEST=LSCONNINFO or when using default: v The caller must have a valid connection to the log stream.
v The current primary address space must be the same as the HOME address space at the time you issued the IXGCONN macro.
v
Include mapping macro IXGQBUF in your program when
CHECKCONNSTATUS=NO is specified. This macro shows the format of the data returned by IXGQUERY.
When coding REQUEST=ZAILOCINFO: v The current primary address space must be the same as the HOME address space, unless a log stream connection (IXGCONN connect) request was previously performed from the primary address space.
v Include mapping macro IXGQZBUF in your program. This macro shows the format of the data returned by IXGQUERY.
Restrictions
v
The caller's output buffer (see BUFFER and BUFFER64) must be in the caller's primary address space and cannot be ALET-qualified.
v All storage areas specified must be in the same storage key as the caller.
v The caller cannot have any enabled, unlocked task (EUT) FRRs established.
© Copyright IBM Corp. 1988, 2017
769
IXGQUERY
Syntax
v There is more than one version of this macro available. The parameters you can use depend on the version you specify on the PLISTVER parameter. See the description of the PLISTVER parameter for more information.
v You can call any of the system logger services in either AMODE 31 or 64, but the parameter list and all other data addresses, with the exception of BUFFER64 must reside in 31-bit storage.
Input register information
Before issuing the IXGQUERY macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0
2-13
Reason code, if register 15 contains a non-zero return code
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Used as a work register by the system
2-13
Unchanged
14-15
Used as a work register by the system
64 Bit Register Usage
If the caller is in Amode 64, then 64-bit register 15 will be altered. If the caller uses Buffer64, then 64-bit registers 0, 1, and 15 may be altered.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The IXGQUERY macro is written as follows:
Description
name
name: symbol. Begin name in column 1.
� One or more blanks must precede IXGQUERY.
770
z/OS MVS Assembler Services Reference IAR-XCT
IXGQUERY
Syntax Description
IXGQUERY
�
REQUEST=LSCONNINFO
STREAMTOKEN=xstreamtoken
CHECKCONNSTATUS=NO
,BUFFER=xbuffer
,BUFFLEN=xbufflen
CHECKCONNSTATUS=YES
REQUEST=ZAILOCINFO
,BUFFER64=xbuffer64
,BUFFLEN=xbufflen
,ANSAREA=ansarea
,ANSLEN=anslen
,RETCODE=retcode
,RSNCODE=rsncode
One or more blanks must follow IXGQUERY.
Default
: LSCONNINFO
xstreamtoken: RS-type address or address in register (2) - (12).
Default
: NO
xbuffer: RS-type address or address in register (2) - (12).
xbufflen: RS-type address or address in register (2) - (12).
xbuffer64: RS-type address or address in register (2) - (12).
xbufflen: RS-type address or address in register (2) - (12).
ansarea: RS-type address or address in register (2) - (12).
anslen: RS-type address or address in register (2) - (12).
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
Default
: PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
,PLISTVER=2
Default
: MF=S
list addr: RS-type address or register (1) - (12).
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
Chapter 73. IXGQUERY — Query a log stream for information
771
IXGQUERY
Syntax
,MF=(M,list addr,NOCHECK)
Description
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IXGQUERY macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
REQUEST=LSCONNINFO|ZAILOCINFO
An optional keyword input that specifies the type of system logger related information being requested.
DEFAULT:
LSCONNINFO
REQUEST=LSCONNINFO
The program requests to obtain information for a connected log stream.
STREAMTOKEN=streamtoken
A required input parameter that specifies the log stream token that was returned by the IXGCONN service.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
CHECKCONNSTATUS=NO|YES
An optional keyword input that indicates whether or not only the connection status of the log is to be checked.
DEFAULT:
NO
CHECKCONNSTATUS=NO
Indicates that full IXGQUERY processing is to be performed.
,BUFFER=buffer
A required output parameter that specifies the buffer into which the requested data are to be copied. The contents of the buffer are mapped by IXGQBUF.
The buffer cannot be ALET qualified.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,BUFFLEN=bufflen
A required input parameter that specifies the size of the buffer, identified by the BUFFER keyword, relative to different output versions:
If you want to see the GROUP information specified for the log stream, you must specify at least 200 bytes. If you specify less than 200 bytes, IXGQUERY will not return the GROUP information.
If the user-specified buffer is less than 72 bytes, the query request will fail and a specific return or reason code (IxgRetCodeError, IxgRsnCodeBadBufSize) will be returned.
If the user-specified buffer is greater than or equal to 88 bytes, version one information will be returned.
772
z/OS MVS Assembler Services Reference IAR-XCT
IXGQUERY
If the user-specified buffer is greater than or equal to 168 bytes, version two information will be returned.
If the user-specified buffer is greater than or equal to 200 bytes, version three information will be returned. If you want to see the GROUP information specified for the log stream, you must specify at least 200 bytes. If you specify less than 200 bytes, IXGQUERY will not return the GROUP information.
See IXGQBUF in z/OS MVS Data Areas in the z/OS Internet library
(www.ibm.com/systems/z/os/zos/library/bkserv) for details.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
CHECKCONNSTATUS=YES
Indicates only the connection status of the log stream is to be checked.
REQUEST=ZAILOCINFO
The program requests to obtain information for the system logger ZAI parameter options pertaining to the IBM zAware server location.
,BUFFER64=xbuffer64
A required output parameter that specifies the buffer (starting on a full word boundary) into which the requested data are to be copied. The location of this buffer may be anywhere in 64-bit storage.
The contents of the buffer are mapped by IXGQZBUF.
The buffer cannont be ALET qualified.
To code:
Specify the RS-type address, or address in register (2)-(12), of a character field.
,BUFFLEN=bufflen
A required input parameter that specifies the size of the buffer, identified by the BUFFER64 keyword, relative to different output versions: v If the user-specified buffer is less than 96 bytes, the query request will fail and a specific return or reason code (IxgRetCodeError,
IxgRsnCodeBadBufSize) will be returned.
v If the user specified buffer is greater than or equal to 96 bytes, then version one information will be returned.
See IXGQZBUF in z/OS MVS Data Areas in the z/OS Internet library
(www.ibm.com/systems/z/os/zos/library/bkserv) for details.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
,ANSAREA=ansarea
A required input parameter of a virtual storage area, called the answer area.
The ANSAREA contains additional error status when the IXGQUERY service generates an error return code. The format of the returned data is defined by the IXGANSAA mapping macro.
To code:
Specify the RS-type address, or address in register (2)-(12), of a field.
,ANSLEN=anslen
A required input parameter that contains the length in bytes of the virtual storage area provided for ANSAREA.
The length of the answer area is described by the IXGANSAA mapping macro.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
Chapter 73. IXGQUERY — Query a log stream for information
773
IXGQUERY
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
,PLISTVER=2
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , which supports all parameters except those referenced in higher versions.
v 1 , which supports both the following parameters and parameters from version 0:
– CHECKCONNSTATUS
– REQUEST v 2
, which supports both the following parameters and parameters from version 0 and 1:
– BUFFER64
To code:
Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
774
z/OS MVS Assembler Services Reference IAR-XCT
IXGQUERY
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends
that you use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
The IXGQUERY service can issue abend X'1C5' with reason code X'0805'. This abend indicates an abend during system logger processing. If you receive this abend, reissue the request. If the problem persists, contact the IBM Support Center.
Return and reason codes
When the IXGQUERY macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.
Chapter 73. IXGQUERY — Query a log stream for information
775
IXGQUERY
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded
RSNCODE) contains a reason code.
00
04
IxgRetCodeOk - Successful completion
IxgRetCodeWarning - The request was processed successfully, however a warning condition was encountered.
08
0C
IxgRetCodeError - An error has been encountered. The associated reason code provides more information.
IxgRetCodeCompError - A system logger component error has been encountered.
The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code.
Table 44. Return and Reason Codes for the IXGQUERY Macro
Return Code
00
Reason Code
xxxx0000
Meaning and Action
IxgRsnCodeOk -
08 xxxx0801
Explanation:
Request processed successfully.
IxgRsnCodeBadParmlist -
Explanation:
Program error. The parameter list is not valid.
Either the parameter list storage is inaccessible, or the version of the macro used was not valid.
08
08
08 xxxx0802 xxxx0803 xxxx0806
Action:
Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request, and that the macro version is correct. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.
IxgRsnCodeXESError -
Explanation:
System error. A severe cross-system extended services (XES) error has occurred.
Action:
In the answer area mapped by IXGANSAA, see
ANSAA_DIAG1 for the XES return code and
ANSAA_DIAG2 for the XES reason code.
IxgRsnCodeBadBuffer -
Explanation:
The virtual storage area specified by the
BUFFER keyword not addressable.
Action:
Ensure the storage area is accessible to the Logger
Services for the duration of the request.
IxgRsnCodeBadStmToken -
Explanation:
Program error. One of the following occurred: v The stream token was not valid.
v The specified request was issued from an address space other than the connectors address space.
Action:
Do one of the following: v Make sure that the stream token specified is valid.
v Ensure that IXGQUERY requests were issued from the connectors address space.
776
z/OS MVS Assembler Services Reference IAR-XCT
IXGQUERY
Table 44. Return and Reason Codes for the IXGQUERY Macro (continued)
Return Code
08
Reason Code
xxxx080A
Meaning and Action
IxgRsnCodeRequestLocked -
08
08 xxxx080F xxxx0814
Explanation:
Program error. The program issuing the request is holding a lock.
Action:
Ensure that the program issuing the request is not holding a lock.
IxgRsnCodeBadBufsize -
Explanation:
The buffer specified (BUFFER or BUFFER64) is not large enough to contain the data being returned. No data is returned.
Action:
Obtain a buffer of the length of IXGQBUF or
IXGQZBUF (as appropriate) and retry the request.
IxgRsnCodeNotAvailForIPL -
Explanation:
Environment error. The system logger address space is not available for the remainder of this IPL. The system issues messages about this error during system logger initialization.
08
08
08
08 xxxx0815 xxxx0816 xxxx0817 xxxx0819
Action:
See the explanation for system messages issued during system logger initialization.
IxgRsnCodeNotEnabled -
Explanation:
Program error. The program issuing the request is not enabled for I/O and external interrupts, so the request fails.
Action:
Make sure the program issuing the request is enabled for I/O and external interrupts.
IxgRsnCodeBadAnslen -
Explanation:
Program error. The answer area length
(ANSLEN parameter) is not large enough. The system logger returned the required size in the
Ansaa_Preferred_Size field of the answer area, mapped by
IXGANSAA macro.
Action:
Reissue the request, specifying an answer area of the required size.
IxgRsnCodeBadAnsarea -
Explanation:
Program error. The storage area specified on the ANSAREA parameter cannot be accessed. This may occur after the system logger address space has terminated.
Action:
Specify storage that is in the callers primary address space and in the same key as the calling program at the time the system logger service was issued. This storage must be accessible until the request completes.
IxgRsnCodeSRBMode -
Explanation:
Program error. The calling program is in SRB mode, but task mode is the required dispatchable unit mode for this system logger service.
Action:
Make sure the calling program is in task mode.
Chapter 73. IXGQUERY — Query a log stream for information
777
IXGQUERY
Table 44. Return and Reason Codes for the IXGQUERY Macro (continued)
Return Code
08
Reason Code
xxxx081B
Meaning and Action
IxgRsnCodePrimaryNotHome -
08
08 xxxx082D xxxx0840
Explanation:
Program error. The primary address space does not equal the home address space.
Action:
Either make sure that the primary address space equals the home address space when issuing this type of system logger service or perform a log stream connection
(IXGCONN connect) request from the same primary address space and then reissue the IXGQUERY request.
IxgRsnCodeExpiredStmToken -
Explanation:
Environment error. The stream token is no longer valid because the connector has been disconnected.
Action:
Reconnect to the logstream before issuing any functional requests.
IxgRsnCodeBadVersion -
Explanation:
Environment error. The parameter list passed to the service routine has an incorrect version indicator.
08
08
08 xxxx0861 xxxx0862 xxxx0863
Action:
Make sure that the level of MVS executing the request and the macro library used to compile the invoking routine are compatible.
IxgRsnCodeRebuildInProgress -
Explanation:
Environment error. No requests can be processed for this log stream because a coupling facility structure rebuild is in progress for the structure associated with this log stream.
Action:
Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the rebuild completed successfully. Reissue the request.
v The rebuild failed and the log stream is not available.
IxgRsnCodeXESPurge -
Explanation:
Environment error. An cross-system extended services (XES) request has been purged due to rebuild processing.
Action:
Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the rebuild completed successfully. Reissue the request.
v The rebuild failed and the log stream is not available.
IxgRsnCodeStructureFailed -
Explanation:
Environment error. Either the coupling facility structure associated with the log stream has failed or the coupling facility itself has failed.
Action:
Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the rebuild completed successfully. Reissue the request.
v The rebuild failed and the log stream is not available.
778
z/OS MVS Assembler Services Reference IAR-XCT
IXGQUERY
Table 44. Return and Reason Codes for the IXGQUERY Macro (continued)
Return Code
08
Reason Code
xxxx0864
Meaning and Action
IxgRsnCodeNoConnectivity -
08
08
08
0C xxxx0890 xxxx0891 xxxx08D3 xxxx0000
Explanation:
Environment error. No connectivity exists to the coupling facility associated with the log stream. The system logger will either attempt to rebuild the log stream in another coupling facility or the log stream will be disconnected.
Action:
Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the rebuild completed successfully. Reissue the request.
v The rebuild failed and the log stream is not available.
v The log stream has been disconnected from this system.
If a rebuild initiated because of a loss of connectivity previously failed, an ENF corresponding to this reason code might not be issued. Further action by the installation might be necessary to cause the change of the log stream status again. Check the log for messages IXG101I, IXG107I and related rebuild messages for information on resolving any outstanding issues.
IxgRsnCodeAddrSpaceNotAvail -
Explanation:
System error. The system logger address space failed and is not available.
Action:
Do not issue system logger requests.
IxgRsnCodeAddrSpaceInitializing -
Explanation:
System error. The system logger address space is not available because it is IPLing.
Action:
Listen for ENF signal 48, which will indicate when the system logger address space is available. Once it's available, reconnect to the log stream, then reissue this request. You can also listen for ENF signal 48, which will indicate if the system logger address space will not be available for the life of the IPL. In that case, do not issue system logger services.
IxgRsnCodeFuncNotSupported -
Explanation:
Environment error. The query request failed because the LOGR couple data set is not at the correct level. The inventory must be at least at the OS390R3 level.
Equate Symbol
: IxgRetCodeCompError
Explanation:
User or System error. One of the following occurred: v You issued the FORCE IXGLOGR,ARM command to terminate the system logger address space.
v System logger component error occurred.
Action:
If this reason code is not the result of forcing the system logger address space, search problem reporting data bases for a fix for the problem. If no fix exists, contact the
IBM Support Center. Provide the diagnostic data in the answer area (IXGANSAA) and any dumps or LOGREC entries from system logger.
Chapter 73. IXGQUERY — Query a log stream for information
779
IXGQUERY
Examples
Example 1
:
Issue IXQUERY to get information about a log stream.
IXGQUERY STREAMTOKEN=OTOKEN,
BUFFER=QRYBUFF,
BUFFLEN=QRYBUFF_LEN,
ANSAREA=XANSAREA,
ANSLEN=XANSLEN,
RSNCODE=RSCODE
OTOKEN DS
QRYBUFF DS
CL16
CL(QBUF_LEN)
QRYBUFF_LEN DC A(QBUF_LEN)
XANSAREA DS CL(ANSAA_LEN)
XANSLEN DC
RSCODE DS
A(ANSAA_LEN)
F
DSECT ,
IXGQBUF ,
IXGANSAA ,
Output Stream token
IXGQUERY data area
IXGQUERY data length
Logger answer area
Answer area length
Reason code
The macro for IXGQUERY data
The answer area macro
Example 2
:
Issue IXQUERY to get system logger ZAI location (version 1) parameter information.
IXGQUERY REQUEST=ZAILOCINFO,
BUFFER64=QRYZAIBUFF,
BUFFLEN=QRYZAIBUFF_LEN,
ANSAREA=XANSAREA,
ANSLEN=XANSLEN,
RSNCODE=RSCODE
QRYZAIBUFF DS CL(IXGQZBUF_VERS1_LENGTH)
QRYZAIBUFF_LEN DC A(IXGQZBUF_VERS1_LENGTH)
XANSAREA DS
XANSLEN DC
RSCODE DS F
DSECT ,
CL(ANSAA_LEN)
A(ANSAA_LEN)
IXGQZBUF ,
IXGANSAA ,
IXGCON , output buffer buffer size
Logger answer area
Answer area length
Reason code
The macro for IXGQUERY data
The answer area mapping
Return/reason codes
+
+
+
+
+
@
@
@
@
@
780
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 74. IXGUPDAT — Update log stream control information
Description
The IXGUPDAT macro allows the caller to update the GMT time stamp maintained in the control information for a log stream. When this field is successfully updated, any future log blocks written to the log stream cannot will have a time stamp less than the updated time stamp. (Note that this service does not affect time stamps that the application imbeds in the log block.)
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state. Any PSW key
Task
Any PASN, any HASN, any SASN
31-bit or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks may be held.
None.
Programming requirements
v The caller must have a valid connection to the target log stream, specifying
AUTH=WRITE.
v The parameter list for this service must be addressable in the caller's primary address space.
v Include the IXGCON mapping macro in your program. This macro provides a list of equate symbols for the system logger services.
v Include mapping macro IXGANSAA in your program. This macro shows the format of the answer area output returned for each system logger service in the
ANSAREA parameter.
v The current primary address space must be the same as the HOME address space at the time you issued the IXGCONN macro.
Restrictions
All storage areas specified must be in the same storage key as the caller. Storage areas that must exist in the caller's primary address space.
Input register information
Before issuing the IXGUPDAT macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
© Copyright IBM Corp. 1988, 2017
781
IXGUPDAT
Syntax
Register
Contents
0
2-13
Reason code, if register 15 contains a non-zero return code
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as a work register by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The IXGUPDAT macro is written as follows:
Description
name
⌂
name: symbol. Begin name in column 1.
One or more blanks must precede IXGUPDAT.
IXGUPDAT
⌂
STREAMTOKEN=streamtoken
One or more blanks must follow IXGUPDAT.
streamtoken: RS-type address or address in register (2) -
(12).
,GMT_TIMESTAMP=gmt_timestamp
,GMT_TIMESTAMP=NO_GMT_TIMESTAMP
gmt_timestamp: RS-type address or address in register (2)
- (12).
Default
: GMT_TIMESTAMP=NO_GMT_TIMESTAMP
ansarea: RS-type address or address in register (2) - (12).
,ANSAREA=ansarea
782
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,ANSLEN=anslen
,RETCODE=retcode
,RSNCODE=rsncode
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
IXGUPDAT
Description
anslen: RS-type address or address in register (2) - (12).
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: PLISTVER=IMPLIED_VERSION
Default
: MF=S
list addr: RS-type address or register (1) - (12).
Parameters
The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the IXGUPDAT macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
STREAMTOKEN=streamtoken
A required input parameter that specifies the log stream token that was returned on the IXGCONN service.
To code:
Specify the RS-type address, or address in register (2)-(12), of a
16-character field.
,GMT_TIMESTAMP=gmt_timestamp
,GMT_TIMESTAMP=NO_GMT_TIMESTAMP
An optional input parameter that lets you modify the GMT time stamp in the coupling facility structure list controls. You must supply a time stamp that is equal to or greater than the current time stamp maintained in the Log Stream
Control information. Once modified, the next log blocks written to the log stream will be assigned a GMT time stamp equal to or greater than the one specified on the IXGUPDAT request. The default is NO_GMT_TIMESTAMP.
Chapter 74. IXGUPDAT — Update log stream control information
783
IXGUPDAT
If NO_Gmt_TimeStamp is specified for GMT_TimeStamp the macro will be invoked as if GMT_TimeStamp was not specified.
To code:
Specify the RS-type address, or address in register (2)-(12), of an
8-character field.
,ANSAREA=ansarea
A required input parameter of a virtual storage area, called the answer area.
The ANSAREA contains additional error status when the IXGUPDAT service generates an error return code. The format of the returned data is defined by the IXGANSAA mapping macro.
To code:
Specify the RS-type address, or address in register (2)-(12), of a field.
,ANSLEN=anslen
A required input parameter that contains the length in bytes of the virtual storage area provided for ANSAREA.
The length of the answer area is described by the IXGANSAA mapping macro.
To code:
Specify the RS-type address, or address in register (2)-(12), of a fullword field.
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from
GPR 15.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from
GPR 0.
To code:
Specify the RS-type address of a fullword field, or register (2)-(12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX
, if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , which supports all parameters except those referenced in higher versions.
To code:
Specify one of the following: v
IMPLIED_VERSION v MAX v A decimal value of 0
784
z/OS MVS Assembler Services Reference IAR-XCT
IXGUPDAT
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
Chapter 74. IXGUPDAT — Update log stream control information
785
IXGUPDAT
ABEND codes
The IXGUPDAT service can issue abend X'1C5' with reason code X'085F'. This abend indicates an abend during system logger processing. If you receive this abend, reissue the request. If the problem persists, contact the IBM Support Center.
Return and reason codes
When the IXGUPDAT macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.
v When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded
RSNCODE) contains a reason code.
00
04
08
0C
IxgRetCodeOk - Successful completion
IxgRetCodeWarning - The request was processed successfully, however a warning condition was encountered.
IxgRetCodeError - An error has been encountered. The associated reason code provides more information.
IxgRetCodeCompError - A system logger component error has been encountered.
The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code.
Table 45. Return and Reason Codes for the IXGUPDAT Macro
Return Code
00
Reason Code
xxxx0000
Meaning and Action
IxgRsnCodeOk -
08
08
08 xxxx0801 xxxx0802 xxxx0806
Explanation:
Request processed successfully.
IxgRsnCodeBadParmlist -
Explanation:
Program error. The parameter list is invalid.
Either the parameter list storage is inaccessible, or an invalid version of the macro was used.
Action:
Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request, and that the macro version is correct. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.
IxgRsnCodeXESError -
Explanation:
System error. A severe cross-system extended services (XES) error has occurred.
Action:
See ANSAA_DIAG1 for the XES return code and
ANSAA_DIAG2 for the XES reason code.
IxgRsnCodeBadStmToken -
Explanation:
Program error. One of the following occurred: v The stream token was not valid.
v
The specified request was issued from an address space other than the connectors address space.
Action:
Do one of the following: v Make sure that the stream token specified is valid.
v Ensure that IXGUPDAT requests were issued from the connectors address space.
786
z/OS MVS Assembler Services Reference IAR-XCT
IXGUPDAT
Table 45. Return and Reason Codes for the IXGUPDAT Macro (continued)
Return Code
08
Reason Code
xxxx080A
Meaning and Action
IxgRsnCodeRequestLocked -
08
08 xxxx0814 xxxx0815
Explanation:
Program error. The program issuing the request is holding a lock.
Action:
Ensure that the program issuing the request is not holding a lock.
IxgRsnCodeNotAvailForIPL -
Explanation:
Environment error. The system logger address space is not available for the remainder of this IPL. The system issues messages about this error during system logger initialization.
Action:
See the explanation for system messages issued during system logger initialization.
IxgRsnCodeNotEnabled -
Explanation:
Program error. The program issuing the request is not enabled for I/O and external interrupts, so the request fails.
08
08
08
08 xxxx0816 xxxx0817 xxxx0819 xxxx081C
Action:
Make sure the program issuing the request is enabled for I/O and external interrupts.
IxgRsnCodeBadAnslen -
Explanation:
Program error. The answer area length
(ANSLEN parameter) is not large enough. The system logger returned the required size in the
Ansaa_Preferred_Size field of the answer area, mapped by
IXGANSAA macro.
Action:
Reissue the request, specifying an answer area of the required size.
IxgRsnCodeBadAnsarea -
Explanation:
Program error. The storage area specified on the ANSAREA parameter cannot be accessed. This may occur after the system logger address space has terminated.
Action:
Specify storage that is in the callers primary address space and in the same key as the calling program at the time the system logger service was issued. This storage must be accessible until the request completes.
IxgRsnCodeSRBMode -
Explanation:
Program error. The calling program is in SRB mode, but task mode is the required dispatchable unit mode for this system logger service.
Action:
Make sure the calling program is in task mode.
IxgRsnCodeNotAuthFunc -
Explanation:
Program error. The program connected to the log stream with the AUTH=READ parameter and then tried to delete, write, offload or update data. You cannot write, delete, offload or update data when connected with read authority.
Action:
Issue the IXGCONN service with AUTH=WRITE authority and then reissue this request.
Chapter 74. IXGUPDAT — Update log stream control information
787
IXGUPDAT
Table 45. Return and Reason Codes for the IXGUPDAT Macro (continued)
Return Code
08
Reason Code
xxxx082D
Meaning and Action
IxgRsnCodeExpiredStmToken -
08
08 xxxx0840 xxxx0861
Explanation:
Environment error. The stream token is no longer valid because the connector has been disconnected.
Action:
Reconnect to the logstream before issuing any functional requests.
IxgRsnCodeBadVersion -
Explanation:
Environment error. The parameter list passed to the service routine has an incorrect version indicator.
Action:
Make sure that the level of MVS executing the request and the macro library used to compile the invoking routine are compatible.
IxgRsnCodeRebuildInProgress -
Explanation:
Environment error. No requests can be processed for this log stream because a coupling facility structure rebuild is in progress for the structure associated with this log stream.
08
08 xxxx0862 xxxx0863
Action:
Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the rebuild completed successfully. Reissue the request.
v The rebuild failed and the log stream is not available.
IxgRsnCodeXESPurge -
Explanation:
Environment error. An cross-system extended services (XES) request has been purged due to rebuild processing.
Action:
Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the rebuild completed successfully. Reissue the request.
v The rebuild failed and the log stream is not available.
IxgRsnCodeStructureFailed -
Explanation:
Environment error. Either the coupling facility structure associated with the log stream has failed or the coupling facility itself has failed.
Action:
Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the rebuild completed successfully. Reissue the request.
v The rebuild failed and the log stream is not available.
788
z/OS MVS Assembler Services Reference IAR-XCT
IXGUPDAT
Table 45. Return and Reason Codes for the IXGUPDAT Macro (continued)
Return Code
08
Reason Code
xxxx0864
Meaning and Action
IxgRsnCodeNoConnectivity -
08
08
08 xxxx0890 xxxx0891 xxxx08DD
Explanation:
Environment error. No connectivity exists to the coupling facility associated with the log stream. The system logger will either attempt to rebuild the log stream in another coupling facility or the log stream will be disconnected.
Action:
Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the rebuild completed successfully. Reissue the request.
v The rebuild failed and the log stream is not available.
v The log stream has been disconnected from this system.
If a re-build initiated because of a loss of connectivity previously failed, an ENF corresponding to this reason code might not be issued. Further action by the installation might be necessary to cause the change of the log stream status again. Check the log for messages IXG101I, IXG107I and related rebuild messages for information on resolving any outstanding issues.
IxgRsnCodeAddrSpaceNotAvail -
Explanation:
System error. The system logger address space failed and is not available.
Action:
Do not issue system logger requests.
IxgRsnCodeAddrSpaceInitializing -
Explanation:
System error. The system logger address space is not available because it is IPLing.
Action:
Listen for ENF signal 48, which will indicate when the system logger address space is available. Once it's available, reconnect to the log stream, then reissue this request. You can also listen for ENF signal 48, which will indicate if the system logger address space will not be available for the life of the IPL. In that case, do not issue system logger services.
IxgRsnCodeUpdateTimeStampTooSmall -
Explanation:
Program error. The replacement GMT time stamp is smaller than the time stamp maintained in the coupling facility for the log stream. This error can be caused because the application did in fact specify an invalid time stamp or the time stamp value has changed after its current value was retrieved (e.g., via the
IXGQUERY service) because a write or another update request was successfully processed for the log stream somewhere in the sysplex.
08 xxxx08DE
Action:
Invoke the IXGQUERY service to obtain the current time stamp value and determine if the update request should be retried.
IxgRsnCodeUpdateNoOptions -
Explanation:
Program error. The IXGUPDAT macro was invoked with no options specified.
Action -
- Specify at least one option and retry the request.
Chapter 74. IXGUPDAT — Update log stream control information
789
IXGUPDAT
Table 45. Return and Reason Codes for the IXGUPDAT Macro (continued)
Return Code
0C
Reason Code
xxxx0000
Meaning and Action
Equate Symbol
: IxgRetCodeCompError
Explanation:
User or System error. One of the following occurred: v You issued the FORCE IXGLOGR,ARM command to terminate the system logger address space.
v
System logger component error occurred.
Action:
If this reason code is not the result of forcing the system logger address space, search problem reporting data bases for a fix for the problem. If no fix exists, contact the
IBM Support Center. Provide the diagnostic data in the answer area (IXGANSAA) and any dumps or LOGREC entries from system logger.
Example
Issue IXGUPDAT to update the time stamp for a log stream.
IXGUPDAT
STREAMTOKEN=OTOKEN,
GMT_TIMESTAMP=GMTTIME,
ANSAREA=XANSAREA,
OTOKEN DS
GMTTIME DS
XANSAREA DS
XANSLEN DC
ANSLEN=XANSLEN,
RSNCODE=RSCODE
CL16
CL8
CL(ANSAA_LEN)
A(ANSAA_LEN)
RSCODE DS F
DSECT ,
IXGANSAA ,
Output Stream token
GMT
Logger answer area
Answer area length
Reason code
The answer area macro
@
@
@
@
@
790
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 75. IXGWRITE — Write log data to a log stream
Description
Use the IXGWRITE macro to allow a program to write a log block to a log stream.
IXGWRITE returns a unique identifier for each log block written to the log stream.
System logger generates a time stamp for each log block as they are received from applications issuing IXGWRITE and writes the blocks to the log stream in that order. Applications that imbed their own time stamps in log blocks will find that the blocks may not be in application-generated time stamp order, especially if multiple applications are writing to a log stream simultaneously. In order to ensure chronological order of log blocks by application-generated time stamp, applications should provide their own serialization on the log stream.
For information on using the system logger services and the LOGR policy, see z/OS
MVS Programming: Assembler Services Guide, which also includes information about related macros IXGCONN, IXGBRWSE, IXGINVNT, IXGDELET, and IXGQUERY.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state with any PSW key. The caller must be supervisor state with any system (0-7) PSW key to either invoke this service in SRB mode or to use the
MODE=SYNCEXIT keyword.
Task
Any PASN, any HASN, any SASN
31-bit or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts.
No locks held.
All control parameters must be in the primary address space with the following exceptions: v
The ECB should be addressable from the home address space.
v Any parameter area that is explicitly ALET-qualified as allowed by the input parameter (for example, the area referenced by the BUFFER parameter when the
BUFFALET parameter is specified) must be in an address or data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL). All storage areas specified must be in the same storage key as the caller, with the following exception:
The parameter area is explicitly storage key qualified as allowed by the input parameters (example: the area referenced by the BUFFER parameter when the
BUFFKEY parameter is also specified).
© Copyright IBM Corp. 1988, 2017
791
IXGWRITE macro
Programming requirements
v
Before issuing IXGWRITE, you must put the data you wish to write to the log stream into a buffer specified on the BUFFER parameter. IXGWRITE will then write this buffer to the log stream as a log block.
v The current primary address space from which you issue the IXGWRITE service must be the same as the primary address space at the time you issued the
IXGCONN request.
v The parameter list for this service must be addressable in the caller's primary address space.
v The calling program must be connected to the log stream with write authority through the IXGCONN service.
v IXGWRITE cannot be issued if the connection is an import connection
(IMPORTCONNECT=YES on the IXGCONN service). The IXGWRITE service must be issued under a write connection (IMPORTCONNECT=NO, which is the default).
v Include the IXGCON mapping macro in your program. This macro provides a list of equate symbols for the system logger services.
v Include mapping macro IXGANSAA in your program. This macro shows the format of the answer area output returned for each system logger service in the
ANSAREA parameter.
v When coding the MODE=SYNCECB and ECB parameters, you must ensure that:
– The virtual storage area specified for the ECB resides on a full word boundary.
– You initialize the ECB field to zero.
– The ECB resides in either the common or home address space storage at the time the IXGWRITE request is issued.
– The storage used for output parameters, such as ANSAREA, RETBLOCKID, and TIMESTAMP, are accessible by both the IXGWRITE invoker and the ECB waiter.
Restrictions
v All storage areas specified on this macro must be in the same storage key as the caller's storage key, with the exception of the BUFFKEY parameter.
Storage areas that are not ALET-qualified must exist in the caller's primary address space. The ECB should be addressable from the home address space.
v There is more than one version of this macro available. The parameters you can use depend on the version you specify on the PLISTVER parameter. See the description of the PLISTVER parameter for more information.
v You can call any of the system logger services in either AMODE 31 or 64, but the parameter list and all other data addresses, with the excption of BUFFER64 must reside in 31-bit storage.
Input register information
Before issuing the IXGWRITE macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
792
z/OS MVS Assembler Services Reference IAR-XCT
⌂
Syntax
name
IXGWRITE macro
0
1
Register
Contents
Reason code, if register 15 contains a non-zero return code
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as a work register by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the IXGWRITE macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede IXGWRITE.
IXGWRITE
⌂
,STREAMTOKEN=streamtoken
,BUFFER=buffer
BUFFER64=buffer64
,BLOCKLEN=blocklen
,RETBLOCKID=retblockid
One or more blanks must follow IXGWRITE.
streamtoken: RS-type address or register (2) - (12).
buffer: RS-type address or register (2) - (12).
buffer64: RS-type address or register (2) - (12).
blocklen: RS-type address or register (2) - (12).
retblockid: RS-type address or register (2) - (12).
Chapter 75. IXGWRITE — Write log data to a log stream
793
IXGWRITE macro
Syntax
,ANSAREA=ansarea
,ANSLEN=anslen
,TIMESTAMP=timestamp
MODE=SYNC
MODE=ASYNCNORESPONSE
MODE=SYNCECB
,ECB=ecb
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
,PLISTVER=0
,PLISTVER=1
,RETCODE=retcode
,RSNCODE=rsncode
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Description
ansarea: RS-type address or register (2) - (12).
anslen: RS-type address or register (2) - (12).
timestamp: RS-type address or register (2) - (12).
Default
: NO_TIMESTAMP
Default
: MODE=SYNC
ecb: RS-type address or register (2) - (12).
Default
: IMPLIED_VERSION
retcode: RS-type address or register (2) - (12).
rsncode: RS-type address or register (2) - (12).
Default
: MF=S
Parameters
The parameters are explained as follows:
,STREAMTOKEN=streamtoken
Specifies the name (or address in a register) of a required 16-byte input field containing the token for the log stream that you want to write to. The stream token is returned by the IXGCONN service at connection to the log stream.
794
z/OS MVS Assembler Services Reference IAR-XCT
IXGWRITE macro
,BUFFER=buffer
,BUFFER64=buffer64
Specifies the field name (or address in a register) of the data to be written to the log.
v BUFFER=buffer specifies that the location of the buffer is in 31-bit storage.
v BUFFER64=buffer64 specifies that the location of the buffer is in 64-bit storage.
The BUFFER and BUFFER64 parameters are mutually exclusive.
,BLOCKLEN=blocklen
Specifies the name (or address in a register) of a 4-byte input field that contains the length in bytes of the log block you are writing to the log stream.
The value of BLOCKLEN must be between 1 and the value for MAXBUFSIZE.
RETBLOCKID=retblockid
Specifies the name (or address in a register) of a 8-byte output field where
IXGWRITE returns the unique block identifier for the log block written to the log stream.
,ANSAREA=ansarea
Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.
,ANSLEN=anslen
Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.
To ascertain the optimal answer area length, look at the
ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
TIMESTAMP=timestamp
Specifies the name (or address in a register) of a 16-byte output field where the
Greenwich mean time and local time stamps associated with the requested log block are returned when the write request is successful. Both time stamps will be in time of day (TOD) clock format.
MODE=SYNC
MODE=ASYNCNORESPONSE
MODE=SYNCECB
Specifies that the request should be processed in one of the following ways: v MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
v MODE=ASYNCNORESPONSE: Specifies that the request process asynchronously. The caller is not notified when the request completes and the answer area (ANSAREA) fields will not contain valid information.
To use this parameter, the system where the application is running must be
IPLed.
v MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB keyword is posted when the request completes. The ECB keyword is required with MODE=SYNCECB.
Chapter 75. IXGWRITE — Write log data to a log stream
795
IXGWRITE macro
,ECB=ecb
Specifies the name (or address in a register) of a 4-byte input field that contains the event control block (ECB) to be posted when the request completes.
Before coding ECB, you must ensure that: v You initialize the ECB to zero.
v The ECB must reside in either common storage or the home address space where the IXGWRITE service was issued.
v The virtual storage area specified for the ECB must reside on a fullword boundary.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.
The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 0 , which supports all parameters except those specifically referenced in higher versions.
v 1 , which supports both the following parameters and parameters from version 0:
– REQDATA
To code
: Specify in this input parameter one of the following: v
IMPLIED_VERSION v MAX v A decimal value of 0 or 1
,RETCODE=retcode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=rsncode
Specifies a name (or address in a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.
,MF=S
,MF=(L,list addr)
796
z/OS MVS Assembler Services Reference IAR-XCT
IXGWRITE macro
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
,MF=(E,list addr,NOCHECK)
,MF=(M,list addr)
,MF=(M,list addr,COMPLETE)
,MF=(M,list addr,NOCHECK)
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.
IBM recommends that you use the modify and execute forms in the following order: v Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
v Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
v Use MF=(E,list_addr,NOCHECK), to execute the macro.
,list addr
The name of a storage area to contain the parameters.
,attr
An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK
Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.
ABEND codes
None.
Chapter 75. IXGWRITE — Write log data to a log stream
797
IXGWRITE macro
Return and reason codes
When IXGWRITE macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.
Note:
A program invoking the IXGWRITE service may indicate through the
MODE parameter that requests which can not be completed synchronously should have control returned to the caller prior to completion of the request. When the request does complete, the invoker will be notified and the return and reason codes are in the answer area mapped by IXGANSAA.
The IXGCON macro provides equate symbols for the return and reason codes. The equate symbols associated with each hexadecimal return code are as follows:
00
04
IXGRSNCODEOK - Successful completion.
IXGRSNCODEWARNING - The request was processed successfully, however a warning condition was encountered.
08
0C
IXGRETCODEERROR - An error has been encountered. The associated reason code provides more information.
IXGRETCODECOMPERROR - A system logger component error has been encountered.
The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code.
Table 46. Return and reason codes for the IXGWRITE macro
Return code
00
Reason code
xxxx0000
Meaning and action
Equate symbol
: IxgRsnCodeOk
04 xxxx0401
Explanation
: Request processed successfully.
Equate symbol
: IxgRsnCodeProcessedAsynch
Explanation
: Program error. The program specified
MODE=SYNCECB and the request must be processed asynchronously.
Action
: Wait for the ECB specified on the ECB parameter to be posted, indicating that the request is complete. Check the ANSAA_ASYNCH_RETCODE and
ANSAA_ASYNCH_RSNCODE fields, mapped by
IXGANSAA, to determine whether the request completed successfully.
798
z/OS MVS Assembler Services Reference IAR-XCT
IXGWRITE macro
Table 46. Return and reason codes for the IXGWRITE macro (continued)
Return code
04
Reason code
xxxx0405
Meaning and action
Equate symbol
: IxgRsnCodeWarningLossOfData
Explanation
: Environment error. Returned for
READCURSOR, START OLDEST and RESET OLDEST requests. This condition occurs when a system and coupling facility fail and not all of the log data in the log stream could be recovered.
v For READCURSOR: A log block has been returned, but there may be log blocks permanently missing between this log block and the one previously returned.
v For START OLDEST and RESET OLDEST: The oldest log blocks in the log stream may be permanently missing, the browse cursor is set at the oldest available log block.
04
04
04 xxxx0407 xxxx0408 xxxx0409
Action
: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
Equate symbol
: IxgRsnCodeConnPossibleLossOfData
Explanation
: Environment error. The request was successful, but there may be log blocks permanently missing between this log block and the one previously returned. This condition occurs when a system or coupling facility fails and not all of the data in the log stream could be recovered.
Action
: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
Equate symbol
: IxgRsnCodeDsDirectoryFullWarning
Explanation
: Environment error. The request was successful, but the log streams DASD data set directory is full. System logger cannot offload any further data from the coupling facility structure to DASD. The system logger will continue to process IXGWRITE requests until this log streams portion of the coupling facility structure becomes full.
Action
: Either delete enough data from the log stream to free up space in the log streams data set directory so that offloading can occur or disconnect from the log stream.
Equate symbol
: IxgRsnCodeWowWarning
Explanation
: Environment error. The request was successful, but an error condition was detected during a previous offload of data. System logger might not be able to offload further data. System logger will continue to process IXGWRITE requests only until the interim storage for the log stream is filled. (Interim storage is the coupling facility for a coupling facility log stream and local storage buffers for a DASD-only log stream.)
Action
: Do not issue any further requests for this log stream and disconnect. Connect to another log stream.
Check the system log for message IXG301I to determine the cause of the error. If you cannot fix the error, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center.
Chapter 75. IXGWRITE — Write log data to a log stream
799
IXGWRITE macro
Table 46. Return and reason codes for the IXGWRITE macro (continued)
Return code
04
Reason code
0000040A
Meaning and action
Equate symbol
: IxgRsnCodeDuplexFailureWarning
08
08
08 xxxx0801 xxxx0802 xxxx0803
Explanation
: Environment error. The request was successful, but the system logger was unable to duplex log data to staging data sets, even though the log stream definition requested unconditional duplexing to staging data sets by specifying the log stream attributes:
STG_DUPLEX=YES, DUPLEXMODE=UNCOND, or
STG_DUPLEX=YES,DUPLEXMODE=DRXRC. When
DUPLEXMODE=UNCOND is specified, but Logger was unable to obtain a staging data set to duplex the log data.
Therefore, the Logger duplexing is being done in local buffers (data space).
When DUPLEXMODE=DRXRC is specified for a logstream and being used for (non-local) disaster recovery duplexing, if the internal buffers used for asynchronous buffering of the log blocks become full. Meaning the internal buffers became full before at least one of the full buffers could be written to the staging data set.
Action
: For DUPLEXMODE=UNCOND, if duplexing to staging data sets is required, disconnect from this log stream and connect to a log stream that can be duplexed to staging data sets.
For DUPLEXMODE=DRXRC, if duplexing to a
DRXRC-type staging data sets is required, then cause the log data to be offload to the log stream secondary storage
(offload data sets) and then continue writing to the log stream.
Equate symbol
: IxgRsnCodeBadParmlist
Explanation
: Program error. The parameter list could not be accessed.
Action
: Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.
Equate symbol
: IxgRsnCodeXESError
Explanation
: System error. A severe cross-system extended services (XES) error has occurred.
Action
: See ANSAA_DIAG1 for the XES return code and
ANSAA_DIAG2 for the XES reason code.
Equate symbol
: IxgRsnCodeBadBuffer
Explanation
: Program error. The virtual storage area specified on the BUFFER or BUFFER64 parameter is not addressable.
Action
: Ensure that the storage area specified on the
BUFFER or BUFFER64 parameter is accessible to system logger for the duration of the request. If the BUFFKEY parameter is specified, make sure it contains a valid key associated with the storage area. If BUFFKEY is not used, ensure that the storage is in the same key as the program at the time the logger service was requested. The storage must be addressable in the caller's primary address space.
800
z/OS MVS Assembler Services Reference IAR-XCT
IXGWRITE macro
Table 46. Return and reason codes for the IXGWRITE macro (continued)
Return code
08
Reason code
xxxx0806
Meaning and action
Equate symbol
: IxgRsnCodeBadStmToken
08
08
08
08
08 xxxx0809 xxxx080A xxxx0814 xxxx0815 xxxx0816
Explanation
: Program error. One of the following occurred: v
The stream token was not valid.
v The specified request was issued from an address space other than the connector's address space.
Action
: Do one of the following: v Make sure that the stream token specified is valid.
v Ensure the request was issued from the connector's address space.
Equate symbol
: IxgRsnCodeBadWriteSize
Explanation
: Program error. The size of the log block specified in the BLOCKLEN parameter is not valid. The value for BLOCKLEN must be greater than zero and less than or equal to the maximum buffer size (MAXBUFSIZE) defined in the LOGR policy for the structure associated with this log stream.
Action
: Ensure that the value specified on the BLOCKLEN parameter is greater than 0 and less than or equal to the
MAXBUFSIZE which is returned on the log stream connect request.
Equate symbol
: IxgRsnCodeRequestLocked
Explanation
: Program error. The program issuing the request is holding a lock.
Action
: Ensure that the program issuing the request is not holding a lock.
Equate symbol
: IxgRsnCodeNotAvailForIPL
Explanation
: Environment error. The system logger address space is not available for the remainder of this IPL. The system issues messages about this error during system logger initialization.
Action
: See the explanation for system messages issued during system logger initialization.
Equate symbol
: IxgRsnCodeNotEnabled
Explanation
: Program error. The program issuing the request is not enabled for I/O and external interrupts, so the request fails.
Action
: Make sure the program issuing the request is enabled for I/O and external interrupts.
Equate symbol
: IxgRsnCodeBadAnslen
Explanation
: Program error. The answer area length
(ANSLEN parameter) is not large enough. The system logger returned the required size in the
Ansaa_Preferred_Size field of the answer area, mapped by
IXGANSAA macro.
Action
: Re-issue the request, specifying an answer area of the required size.
Chapter 75. IXGWRITE — Write log data to a log stream
801
IXGWRITE macro
Table 46. Return and reason codes for the IXGWRITE macro (continued)
Return code
08
Reason code
xxxx0817
Meaning and action
Equate symbol
: IxgRsnCodeBadAnsarea
08
08
08
08
08
08 xxxx0818 xxxx081C xxxx082D xxxx0837 xxxx083D xxxx083F
Explanation
: Program error. The storage area specified on the ANSAREA parameter cannot be accessed. This may occur after the system logger address space has terminated.
Action
: Specify storage that is in the caller's primary address space and in the same key as the calling program at the time the system logger service was issued. This storage must be accessible until the request completes.
Equate symbol
: IxgRsnCodeBadBlockidStor
Explanation
: Program error. The storage area specified by
BLOCKID cannot be accessed.
Action
: Ensure that the storage area is accessible to system logger for the duration of the request. The storage must be addressable in the caller's primary address space and in the same key as the caller.
Equate symbol
: IxgRsnCodeNotAuthFunc
Explanation
: Program error. The program connected to the log stream with the AUTH=READ parameter and then tried to delete or write data. You cannot write or delete data when connected with read authority.
Action
: Issue the IXGCONN service with AUTH=WRITE authority and then re-issue this request.
Equate symbol
: IxgRsnCodeExpiredStmToken
Explanation
: Environment error. The stream token is no longer valid because the connector has been disconnected.
Action
: Connect to the log stream again before issuing any functional requests.
Equate symbol
: IxgRsnCodeBadTimestamp
Explanation
: Program error. The storage area specified by
TIMESTAMP cannot be accessed.
Action
: Ensure that the storage area is accessible to the system logger service for the duration of the request. The storage must be addressable in the caller's primary address space and in the same key as the caller.
Equate symbol
: IxgRsnCodeBadECBStor
Explanation
: Program error. The ECB storage area was not accessible to the system logger.
Action
: Ensure that the storage area is accessible to the system logger for the duration of the request. The storage must be addressable in the caller's home address space and in the same key as the caller.
Equate symbol
: IxgRsnCodeTestartError
Explanation
: System error. An unexpected error was encountered while attempting to validate the buffer ALET.
Action
: See ANSAA_DIAG1 in the answer area mapped by the IXGANSAA macro for the return code from the
TESTART system service.
802
z/OS MVS Assembler Services Reference IAR-XCT
IXGWRITE macro
Table 46. Return and reason codes for the IXGWRITE macro (continued)
Return code
08
Reason code
xxxx0841
Meaning and action
Equate symbol
: IxgRsnCodeBadBufferAlet
Explanation
: Program error. The buffer ALET specified is not zero and does not represent a valid entry on the caller's dispatchable unit access list (DUAL). See the
ANSAA_DIAG1 field of the answer area, mapped by the
IXGANSAA macro, for the return code from the TESTART system service.
08
08 xxxx0849 xxxx084E
Action
: Ensure that the correct ALET was specified. If not, provide the correct ALET. Otherwise, add the correct ALET to dispatchable unit access list (DUAL).
Equate symbol
: IxgRsnCodeBadBuffkey
Explanation
: Program error. The buffer key specified on the
BUFFKEY parameter specifies an invalid key. Either the key is greater than 15 or the program is running in problem state and the specified key is not the same key as the PSW key at the time the system logger service was issued.
Action
: For problem state programs, either do not specify the BUFFKEY parameter or else specify the same key as the
PSW key at the time the system logger service was issued.
For supervisor state programs, specify a valid storage key
(0 <= key <= 15).
Equate symbol:
IXGRSNCODESTRSACETOOSMALL
Explanation:
Environment error. Structure resources are not available to satisfy the request. All structure resources are allocated as system logger control resources. This condition occurs when the structure resources are consumed by the logstreams connections.
Action:
Increase the size of the structure in the CFRM policy or use the SETXCF ALTER command to dynamically increase the size of the structure.
Chapter 75. IXGWRITE — Write log data to a log stream
803
IXGWRITE macro
Table 46. Return and reason codes for the IXGWRITE macro (continued)
Return code
08
Reason code
xxxx085C
Meaning and action
Equate symbol
: IxgRsnCodeDsDirectoryFull
Explanation
: Environment error. The interim storage (for example: the coupling facility structure space allocated or the staging data set space) for the log stream is full. System logger's attempts to offload the interim storage log data to
DASD has failed because the log stream's data set directory is full. If this reason code is issued by the IXGWRITE request, no further write requests can be processed until additional directory space is available for the log stream.
System logger will periodically re-drive its offload attempts for this condition, which is applicable to both coupling facility structure and DASD-only type log streams. If system logger is able to offload log data, then an ENF event will be issued informing the connectors that the log stream should be available for writing more log data.
However, the time that passes before you can write to the log stream is unpredictable.
The system issues related messages IXG257I, IXG261E,
IXG262A and IXG301I.
Action
: The system programmer must make more log stream data set directory space available.
For information about how an authorized application program might respond to this reason code, see Setting up the system logger configuration in the z/OS MVS
Programming: Authorized Assembler Services Guide.
For information about how an unauthorized application program might respond to this reason code, see
IXGWRITE: Writing to a log stream in the z/OS MVS
Programming: Assembler Services Guide.
804
z/OS MVS Assembler Services Reference IAR-XCT
IXGWRITE macro
Table 46. Return and reason codes for the IXGWRITE macro (continued)
Return code
08
Reason code
xxxx085D
Meaning and action
Equate symbol
: IxgRsnCodeWowError
08 xxxx0860
Explanation
: Environment error. The interim storage (for example: the coupling facility structure space allocated or the staging data set space) for the log stream is full. System logger's attempts to offload the interim storage log data to
DASD have failed because of severe errors. No further write requests can be processed until the offload error condition is cleared.
System logger will periodically re-drive its offload attempts for this condition, which is applicable to both coupling facility structure and DASD-only type log streams. If system logger is able to offload log data, then an ENF event will be issued informing the connectors that the log stream should be available for writing more log data.
However, the time that passes before you can write to the log stream is unpredictable.
The system issues related message IXG301I.
Action
: The system programmer must correct the severe error condition inhibiting the log stream offload. If you are unable to correct the error, search problem reporting data bases for a fix for the problem. If no fixt exists, contact the
IBM Support Center.
You can retry your write request periodically or wait for the ENF signal that the log stream is available, or disconnect from this log stream and connect to another log stream.
For information on how an authorized application program might respond to this reason code, see Setting up the system logger configuration in the z/OS MVS Programming:
Authorized Assembler Services Guide.
For information on how an authorized application program might respond to this reason code, see IXGWRITE: Writing to a log stream in the z/OS MVS Programming: Assembler
Services Guide.
Equate symbol
: IxgRsnCodeCFLogStreamStorFull
Explanation
: Environment error. The coupling facility structure space allocated for this log stream is full. No further requests can be processed until the log data in the coupling facility structure is offloaded to DASD log data sets.
Action
: Listen to the ENF signal 48 which will indicate that the log stream is available after the data has been offloaded to DASD. For IXGCONN requests, Listen to the ENF signal
48 which will indicate that the structure is available. Then, re-issue the request.
Chapter 75. IXGWRITE — Write log data to a log stream
805
IXGWRITE macro
Table 46. Return and reason codes for the IXGWRITE macro (continued)
Return code
08
Reason code
xxxx0861
Meaning and action
Equate symbol
: IxgRsnCodeRebuildInProgress
08
08
08 xxxx0862 xxxx0863 xxxx0864
Explanation
: Environment error. No requests can be processed for this log stream because a coupling facility structure re-build is in progress for the structure associated with this log stream.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v
The re-build failed and the log stream is not available.
Equate symbol
: IxgRsnCodeXESPurge
Explanation
: Environment error. An cross-system extended services (XES) request has been purged due to re-build processing.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v
The re-build failed and the log stream is not available.
Equate symbol
: IxgRsnCodeStructureFailed
Explanation
: Environment error. Either the coupling facility structure associated with the log stream has failed or the coupling facility itself has failed.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v
The re-build failed and the log stream is not available.
Equate symbol
: IxgRsnCodeNoConnectivity
Explanation
: Environment error. No connectivity exists to the coupling facility associated with the log stream. The system logger will either attempt to re-build the log stream in another coupling facility or the log stream will be disconnected.
Action
: Listen for ENF signal 48 that will indicate one of the following: v The log stream is available because the re-build completed successfully. Re-issue the request.
v The re-build failed and the log stream is not available.
v The log stream has been disconnected from this system.
If a re-build initiated because of a loss of connectivity previously failed, an ENF corresponding to this reason code might not be issued. Further action by the installation might be necessary to cause the change of the log stream status again. Check the log for messages IXG101I, IXG107I and related rebuild messages for information on resolving any outstanding issues.
806
z/OS MVS Assembler Services Reference IAR-XCT
IXGWRITE macro
Table 46. Return and reason codes for the IXGWRITE macro (continued)
Return code
08
Reason code
xxxx0865
Meaning and action
Equate symbol
: IxgRsnCodeStagingDSFull
08 xxxx0867
Explanation
: Environment error. The staging data set allocated for this log stream on this system is full. No further requests can be processed until enough log data in the coupling facility structure is offloaded to DASD log data sets to relieve the staging data set's full condition.
Action
: Listen to the ENF signal 48 which will indicate that the log stream is available after room becomes available in the staging data set. Then, re-issue the request.
Equate symbol
: IxgRsnCodeLocalBufferFull
Explanation
: Environment error. One of the two following problems was detected: v The available local buffer space (data space storage) for the system logger address space is full. Ansaa_Diag1 and
Ansaa_Diag2 in the Answer Area will contain 0 for this error return.
v The IXGWRITE is rejected because a caller attempted to write log data when the outstanding asynchronous write activity for this connection was considered too high. The limit for unauthorized IXGWRITE invokers is 2,000 and the limit of 10,000 is used for authorized callers. An unauthorized caller is a caller whose PSW key is >= 8 and that is not in supervisor state. ANSAA_DIAG1 in the answer area contains a value of 1 for this error return for unauthorized callers and a value of 2 for authorized callers. ANSAA_DIAG2 contains the total number of outstanding write requests for this connection.
No further writing requests can be processed until the log data in the local buffer space is offloaded to DASD log data sets or this connector's prior IXGWRITE requests complete.
Note:
This reason code applies to both CF and DASD only log stream requests.
Action
: v For authorized writers: Listen for the ENF signal 48 that will indicate that the log stream is available. With the first condition, logger issues the ENF signal after the data has been offloaded to DASD. With the second condition, logger issues the ENF signal 48 that the log stream is available when the number of in-flight authorized asynchronous writes is reduced below 85% of the limit. There will be no ENF signal issued when the unauthorized limit is relieved.
v For unauthorized callers: Wait for a short interval and then reissue the request.
v If the attempts continue to fail or the ENF signal is not issued for an unacceptable period, consider notifying operations or disconnecting from the log stream.
Chapter 75. IXGWRITE — Write log data to a log stream
807
IXGWRITE macro
Table 46. Return and reason codes for the IXGWRITE macro (continued)
Return code
08
Reason code
xxxx0868
Meaning and action
Equate symbol
: IxgRsnCodeStagingDSFormat
08
08 xxxx0890 xxxx0891
Explanation
: Environment error. The staging data set allocated for this log stream on this system has not finished being formatted for use by System Logger. No further
IXGWRITE requests can be processed until the formatting completes.
Action
: Listen to the ENF signal 48 which will indicate that the logstream is available after formatting process is finished. Then, re-issue the request.
Equate symbol
: IxgRsnCodeAddrSpaceNotAvail
Explanation
: System error. The system logger address space failed and is not available.
Action
: Do not issue system logger requests.
Equate symbol
: IxgRsnCodeAddrSpaceInitializing
Explanation
: System error. The system logger address space is not available because it is IPLing.
08
08
08 xxxx08D1 xxxx08D2 xxxx08D7
Action
: Listen for ENF signal 48, which will indicate when the system logger address space is available. Re-connect to the log stream, then re-issue this request. You can also listen for ENF signal 48, which will indicate if the system logger address space will not be available for the life of the
IPL. In that case, do not issue system logger services.
Equate symbol
: IxgRsnCodePrgramKey
Explanation
: Environment error. The request was rejected because of one of the following: v The request was issued in SRB mode while the requestor was in problem program key (key 8-F).
v The SYNCEXIT parameter was specified while the requestor's PSW key was in problem program key.
Action
: Change the invoking environment to a system key
(key 0-7).
Equate symbol
: IxgRsnCodeNoCompleteExit
Explanation
: Program error. MODE=SYNCEXIT was specified, but the connection request did not identify a complete exit.
Action
: Either change this request to a different MODE option, or reconnect to the log stream with a complete exit specified on the COMPLETEXIT parameter.
Equate symbol
: IxgRsnCodeRequestNotAllowed
Explanation
: Program error. The caller issued an
IXGWRITE request while an import connection was active on this system (IXGCONN IMPORTCONNECT=YES).
Action
: Re-issue the request, based on the type of connection active.
808
z/OS MVS Assembler Services Reference IAR-XCT
IXGWRITE macro
Table 46. Return and reason codes for the IXGWRITE macro (continued)
Return code
0C
Reason code
xxxx0000
Meaning and action
Equate symbol
: IxgRetCodeCompError
Explanation
: User or System error. One of the following occurred: v You issued the FORCE IXGLOGR,ARM command to terminate the system logger address space.
v
System logger component error occurred.
Action
: If this reason code is not the result of forcing the system logger address space, search problem reporting data bases for a fix for the problem. If no fix exists, contact the
IBM Support Center. Provide the diagnostic data in the answer area (IXGANSAA) and any dumps or LOGREC entries from system logger.
Example 1
Write data to the log stream synchronously.
IXGWRITE STREAMTOKEN=TOKEN,
BUFFER=BUFF,
BLOCKLEN=BLKLEN,
BUFFALET=BUFALET,
RETBLOCKID=RETBLK,
BUFFKEY=BUFKEY,
TIMESTAMP=RET_TIME,
MODE=SYNC,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
BUFF DC
BLKLEN DC
ANSLEN DC
BUFKEY DC
RETCODE=RETCODE
CL256’BUFFER TEXT’
F’256’
A(L’ANSAREA)
TOKEN DS
RET_TIME DS
ANSAREA DS
RETCODE DS
F’8’
CL16
CL16
CL(ANSAA_LEN)
RSNCODE DS
BUFALET DC
RETBLK DS
DATAREA DSECT
F
F
F’1’
CL8
IXGANSAA LIST=YES buffer to write to log stream length of block to be written length of logger’s answer area buffer key stream token from connect returned timestamp of block answer area for log requests return code reason code buffer alet secondary returned block id answer area
X
X
X
X
X
X
X
X
X
X
X
X
Example 2
Write data to the log stream asynchronously, if synchronous processing is not possible.
IXGWRITE STREAMTOKEN=TOKEN,
BUFFER=BUFF,
BLOCKLEN=BLKLEN,
BUFFALET=BUFALET,
RETBLOCKID=RETBLK,
MODE=SYNCECB,
ECB=ANECB,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
RETCODE=RETCODE
X
X
X
X
X
X
X
X
X
X
X
Chapter 75. IXGWRITE — Write log data to a log stream
809
IXGWRITE macro
*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* if return code = ’00000401’X then wait
* on the ecb ANECB for the request to complete
*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
BUFF DC
BLKLEN DC
ANSLEN DC
TOKEN DS
CL256’BUFFER TEXT’
F’256’
A(L’ANSAREA)
CL16 buffer to write to log stream length of block to be written length of logger’s answer area stream token from connect
ANSAREA
RETCODE
RSNCODE
BUFALET
ANECB
RETBLK
DS
DS
DS
DC
DS
DS
CL(ANSAA_LEN)
F
F
F’1’
F
CL8
DATAREA DSECT
IXGANSAA LIST=YES answer area for log requests return code reason code buffer alet secondary ecb to wait on returned block id answer area
Example 3
Write data to the log stream using registers.
BUFF
BLKLEN
ANSLEN
TOKEN
LA R6,TOKEN
IXGWRITE STREAMTOKEN=(6),
BUFFER=BUFF,
BLOCKLEN=BLKLEN,
RETBLOCKID=RETBLK,
MODE=SYNC,
ANSAREA=ANSAREA,
ANSLEN=ANSLEN,
RSNCODE=RSNCODE,
MF=S,
DC
DC
DC
DS
ANSAREA DS
RETCODE DS
RSNCODE DS
RETBLK DS
RETCODE=RETCODE
CL256’BUFFER TEXT’
F’256’
A(L’ANSAREA)
F
F
CL16
CL(ANSAA_LEN)
CL8
DATAREA DSECT
IXGANSAA LIST=YES
R6 EQU 6 load stream token in register 6 buffer to write to log stream length of block to be written length of logger’s answer area stream token from connect answer area for log requests return code reason code returned block id answer area set up register 6
X
X
X
X
X
X
X
X
X
810
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 76. LINK and LINKX — Pass control to a program in another load module
LINK and LINKX description
The LINK macro is used to pass control to a specified entry name in another load module; the entry name must be a member name or an alias in the directory of a partitioned data set (PDS) or must have been specified in an IDENTIFY macro. The load module containing the program is brought into virtual storage if a usable copy is not available.
If your program is in access register (AR) address space control (ASC) mode, use
LINKX. All the parameters on LINK are valid on LINKX.
Descriptions of the LINK and LINKX macro in this information are: v The standard form of the LINK macro, which includes general information about the LINK and LINKX macros with specific information about the LINK macro. The syntax of the LINK macro and all LINK parameters are explained.
v The standard form of the LINKX macro, which presents information specific to the LINKX macro and callers in AR mode.
v The list form of the LINK and LINKX macros.
v The execute form of the LINK and LINKX macros.
LINK and LINKX processing ensure that the called program receives control in the correct addressing mode. If the called program has an address mode of ANY, it receives control in the AMODE of the calling program. The program issuing the
LINK or LINKX macro regains control in its own addressing mode.
The caller optionally can provide a parameter list to be passed to the called program. If the called program terminates abnormally, or if the specified entry point cannot be located, the task is abnormally terminated unless the caller provides an ERRET exit.
Note:
The LINK and LINKX macros have the same environment specifications, register information, programming requirements, restrictions and limitations, performance implications, and return and reason codes described below, except where noted in the explanation for LINKX.
Environment
The requirements for the caller of LINK are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt Status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
24- or 31-bit for LINK. 24- or 31- or 64-bit for LINKX.
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space.
© Copyright IBM Corp. 1988, 2017
811
LINK and LINKX macros
Programming requirements
None.
Restrictions
v The caller cannot have an EUT FRR established.
Register information
After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.
If the LINK is successful, the GPRs contain the following when the called program receives control:
Register
Contents
0
One of the following: v Used as a work register by the system if SF is specified.
v Otherwise, unchanged.
1
One of the following: v Address of the PARAM address list if that is coded.
v Otherwise, unchanged if LSEARCH=YES not specified and LINKX not specified, and LINK not issued with SYSSTATE ASCENV=AR.
v Otherwise, used as a work register by the system.
2-13
14
15
Unchanged
Contains the return address the called module will return to. If the high-order bit of this register is on, the issuer of the LINK or LINKX macro is running in 31-bit mode; if off, the issuer is running in 24-bit mode.
Requested program's entry point address
When the target of the LINK or LINKX is AMODE(64), then reg 15 contains xxxxxxxY where Y is: v 0 if the caller was AMODE 24 v 2 if the caller was AMODE 31 v 4 if the caller was AMODE 64
Upon return to the caller, the GPRs contain whatever values the called program placed there.
If the LINK is not successful and the caller provided an ERRET exit to receive control, the GPRs contain the following:
Register
Contents
812
z/OS MVS Assembler Services Reference IAR-XCT
⌂
Syntax
name
LINK and LINKX macros
0
One of the following: v
Used as a work register by the system if SF is specified.
v Otherwise, unchanged.
1
2-13
14
15
Bits 0–31 of the 64 bit register contain the abend reason code for the abend code for the ABEND that would have been issued if the caller had not provided an ERRET exit.
Bits 32–63 of the 64 bit register contain the abend code for the ABEND that would have been issued if the caller had not provided an ERRET exit.
Unchanged
Used as a work register by the system
Address of the ERRET exit.
Performance implications
None.
Syntax
The standard form of the LINK macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede LINK.
LINK
⌂
EP=entry name
EPLOC=entry name addr
DE=list entry addr
,DCB=dcb addr
,PARAM=(addr)
,PARAM=(addr),VL=1
,ID=id nmbr
,ERRET=err rtn addr
,LSEARCH=NO
One or more blanks must follow LINK.
entry name: Symbol.
entry name addr: A-type address, or register (2) - (12).
list entry addr: A-type address, or register (2) - (12).
dcb addr: A-type address, or register (2) - (12).
addr: A-type address, or register (2) - (12).
Note
: addr is one or more addresses, separated by commas. For example,
(addr,addr,addr)
id nmbr: Symbol or decimal digit, with a maximum value of 4095.
err rtn addr: A-type address, or register (2) - (12).
Default
: No
Chapter 76. LINK and LINKX — Pass control to a program in another load module
813
LINK and LINKX macros
Syntax
,LSEARCH=YES
Description
Parameters
The parameters are explained as follows:
EP=entry name
EPLOC=entry name addr
DE=list entry addr
Specifies the entry name, the address of the entry name, or the address of the name field in a 62-byte list entry for the entry name that was constructed using the BLDL macro. If EPLOC is coded, entry name addr points to an eight-byte field. If the name is less than eight characters, left-justify the name and pad with blanks on the right to make up the eight characters.
The system ignores the information you specify on the DE parameter if the parameter does one or both of the following: v Specifies an entry in an authorized library (that is, defined in IEAAPFxx member of parmlib) v Requests access to a program or library that is controlled by the system authorization facility (SAF)
Instead, the system uses the BLDL macro to construct a new list entry containing the DE information.
Note:
When you use the DE parameter with the LINK macro, DE specifies the address of a list that was created by a BLDL macro. BLDL and LINK must be issued from the same task; otherwise, the system might terminate the program with an abend code of 106 and a return code of 15. Therefore, do not issue
ATTACH or DETACH between issuances of BLDL and LINK.
,DCB=dcb addr
Specifies the address of the opened data control block for the partitioned data set containing the entry name described above. This parameter must indicate the same DCB specified in the BLDL used to locate the entry name.
If the DCB parameter is omitted or if DCB=0 is specified when the LINK macro is issued by the job step task, the data sets referred to by either the
STEPLIB or JOBLIB DD statement are first searched for the entry point name.
If the entry point name is not found, the link library is searched.
If the DCB parameter is omitted or if DCB=0 is specified when the LINK macro is issued by a subtask, the data sets associated with one or more data control blocks referred to by the TASKLIB operand of previous ATTACH macros in the subtasking chain are first searched for the entry point name. If the entry point name is not found, the search is continued as if LINK had been issued by the job step task.
Note:
DCB must reside in 24-bit addressable storage.
,PARAM=(addr)
,PARAM=(addr),VL=1
Specifies address(es) to be passed to the called program. To form the parameter list, the macro expands each address inline to a fullword on a fullword boundary, in the order designated. GPR 1 contains the address of the first
814
z/OS MVS Assembler Services Reference IAR-XCT
LINK and LINKX macros
parameter when the program is given control. (If this parameter is not coded,
GPR 1 is not altered unless the execute form of the LINK macro is coded or
LSEARCH=YES is specified.)
Specify VL=1 only if the called program can be passed a variable number of parameters. VL=1 causes the high-order bit of the last address parameter to be set to 1; the bit can be checked to find the end of the list.
Note:
If you specify only one address for PARAM=, you do not need to enter the parentheses.
,ID=id nmbr
Specifies an identifier for this invocation of the macro, useful for debugging purposes. The last fullword of the macro expansion is a NOP instruction containing, in bytes 3 and 4, the identifier you specified.
,ERRET=err rtn addr
Specifies the address of an exit to receive control when an error condition that would cause abnormal termination of the task is detected. The ERRET exit does not receive control when input parameter errors are detected.
,LSEARCH=NO
,LSEARCH=YES
Specifies whether (YES) or not (NO) the search is to be limited to the job pack area and the first library in the normal search sequence.
Return and reason codes
None.
Example 1
Pass control to a specified entry name (PGMLKRUS) in another load module. Let the system find the module from available libraries.
LINK EP=PGMLKRUS
Example 2
Pass control to a specified entry name (PGMA) in another load module, specifying
(in registers 4, 6, 8) three addresses to be passed to the called program.
LINK EP=PGMA,PARAM=((4),(6),(8))
LINKX — Pass control to a program in another load module
The LINKX macro performs the same function as LINK. It passes control to a specified entry name in another load module. LINKX is intended for use by programs running in access register (AR) mode.
Note:
The LINKX macro has the same environment specifications, register information, programming requirements, restrictions and limitations, performance implications, and return and reason codes as the LINK macro, except where noted below.
Environment
The LINKX macro can be used by callers in AR or primary ASC mode.
Chapter 76. LINK and LINKX — Pass control to a program in another load module
815
LINK and LINKX macros
Syntax
Programming requirements
If your program is in AR mode, issue the SYSSTATE ASCENV=AR macro before you issue LINKX.
Parameters passed to the called program using the PARAM parameter must reside in your primary address space.
Register information
When the caller regains control or the ERRET exit receives control, the access registers (ARs) are unchanged.
Syntax
The standard form of the LINKX macro is written as follows:
Description
⌂
name
name: Symbol. Begin name in column 1.
One or more blanks must precede LINKX.
LINKX
⌂
EP=entry name
EPLOC=entry name addr
DE=list entry addr
,DCB=dcb addr
,PARAM=(addr)
,PARAM=(addr),VL=1
One or more blanks must follow LINKX.
entry name: Symbol.
entry name addr: A-type address, or register (2) - (12).
list entry addr: A-type address, or register (2) - (12).
dcb addr: A-type address, or register (2) - (12).
addr: A-type address, or register (2) - (12).
Note
: addr is one or more addresses, separated by commas. For example,
(addr,addr,addr)
Default
: None.
,PLIST4=YES
,PLIST4=NO
,PLIST8=YES
,PLIST8=NO
,PLISTARALETS=SYSTEM
,PLISTARALETS=NO
Default
: None.
Default
: ,PLISTARALETS=SYSTEM
Note
: ,PLISTARALETS is valid only with LINKX.
,PLIST8ARALETS=NO
,PLIST8ARALETS=YES
Default
: PLIST8ARALETS=NO
Note
: PLIST8ARALETS is valid only with LINKX.
816
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,ID=id nmbr
,ERRET=err rtn addr
,LSEARCH=NO
,LSEARCH=YES
,AMODE64OK=NO
,AMODE64OK=YES
LINK and LINKX macros
Description
id nmbr: Symbol or decimal digit, with a maximum value of 4095.
err rtn addr: A-type address, or register (2) - (12).
Default
: NO
Default
: NO
Parameters
The parameters are explained under LINK with the following exceptions. The parameter list on the PARAM parameter is different for callers in AR mode. It is described as follows:
PARAM=(addr)
PARAM=(addr),VL=1
Specifies an address or addresses to be passed to the called program. LINKX expands each address inline to a fullword boundary and builds a parameter list with the addresses in the order specified. When the called program receives control, GPR1 contains the address of the parameter list. If the program that issued the LINKX macro was in AR mode, access register 1 contains the ALET that qualifies the parameter list address.
When an AR mode caller uses either: v a parameter list with 4 bytes per entry without specifying
PLISTARALETS=NO; or v a parameter list with 8 bytes per entry and specifies PLIST8ARALETS=YES, the addresses passed to the subtask are in the first part of the parameter list and their associated ALETs are in the second part. For a non-AR mode caller, or for an AR mode caller using a parameter list with 4 bytes per entry with
PLISTARALETS=NO, or for an AR mode caller using a parameter list with 8 bytes per entry without PLIST8ARALETS=YES, ALETs are not passed in the parameter list. When ALETs are passed in the parameter list, the ALETs occupy consecutive 4-byte fields, whether the parameter list is 4 or 8 bytes per entry.
See the description of the PLIST4 and PLIST8 keywords below for more information about controlling the bytes-per-entry in the parameter list. See the description of the PLISTARALETS and PLIST8ARALETS keyword below for
When using a 4-bytes-per-entry parameter list, specify VL=1 when you pass a variable number of parameters. VL=1 results in setting the high-order bit of the last address to 1. The 1 in the high-order bit identifies the last address parameter (which is not the last word in the list when the ALETs are also saved). When using an 8-bytes-per-entry parameter list, VL=1 is not valid.
Chapter 76. LINK and LINKX — Pass control to a program in another load module
817
LINK and LINKX macros
Note:
If you specify only one address for PARAM= and you are not using register notation, you do not need to enter the parentheses.
,PLIST4=YES
,PLIST4=NO
,PLIST8=YES
,PLIST8=NO
Defines the size of the parameter list entries for a parameter list to be built by
LINKX based on the PARAM keyword.
PLIST4 and PLIST8 cannot be specified together. If neither is specified, the default is: v If running AMODE 64, PLIST8=YES v
If not running AMODE 64, PLIST4=YES
If running AMODE 64 and PLIST4=YES is specified, the system builds a
4-bytes-per-entry parameter list just as it would if the program were running
AMODE 24 or AMODE 31 and did not specify PLIST4 or PLIST8.
If running AMODE 24 or AMODE 31 and PLIST8 is specified, the system builds an 8-bytes-per-entry parameter list just as it would if the program were running AMODE 64 and did not specify PLIST4 or PLIST8.
,PLISTARALETS=SYSTEM
,PLISTARALETS=NO
If the invoker is in AR mode, indicates whether the parameter list is also to contain the ALETs associated with the addresses. If the invoker is not in AR mode, this parameter is ignored.
,PLISTARALETS=SYSTEM
Indicates to follow the default system rules that for an AR mode invoker.
v For AMODE 24/31, the parameter list is also to contain the ALETs.
v For AMODE 64 with PLIST8ARALETS=YES, the parameter list is also to contain the ALETs.
v For other cases, the parameter list is not to contain the ALETs.
,PLISTARALETS=NO
Indicates that the parameter list is not also to contain the ALETs. Do not specify this parameter with PLIST8ARALETS=YES.
,PLIST8ARALETS=NO
,PLIST8ARALETS=YES
If there is to be an 8-byte-per-entry parameter list and the invoker is in AR mode, indicates if the parameter list is also to contain the ALETs associated with the addresses. Otherwise, this parameter is ignored.
,PLIST8ARALETS=NO
Indicates that the 8-byte-per-entry parameter list is to consist of just the
8-byte addresses.
,PLIST8ARALETS=YES
Indicates that the 8-byte-per-entry parameter list is to consist of the following two parts: v All the 8-byte addresses, v
All the associated ALETs in consecutive 4-byte fields.
,AMODE64OK=NO
818
z/OS MVS Assembler Services Reference IAR-XCT
LINK and LINKX macros
,AMODE64OK=YES
Indicates if the system is to accept an attempt to link to an AMODE 64 target routine from an AMODE 24 or AMODE 31 routine.
NO
Indicates that the system is to abend such an attempt.
YES
Indicates that the system is to accept such an attempt.
|
LINK and LINKX—List form
Two parameter lists are used in a LINK or LINKX macro: a control program parameter list and problem program parameter list. Only the control program parameter list can be constructed in the list form of LINK or LINKX. Address parameters to be passed in a parameter list to the problem program can be provided using the list form of the CALL macro. These parameter lists can be referred to in the execute form of LINK or LINKX.
Syntax
Syntax
The list form of the LINK or LINKX macro is written as follows:
Description
name
⌂
name: Symbol. Begin name in column 1.
One or more blanks must precede LINK or LINKX.
LINK
LINKX
⌂
EP=entry name
EPLOC=entry name addr
DE=list entry addr
,DCB=dcb addr
,PLISTARALETS=SYSTEM
,PLISTARALETS=NO
,PLIST8ARALETS=NO
,PLIST8ARALETS=YES
,ERRET=err rtn addr
,LSEARCH=NO
,LSEARCH=YES
One or more blanks must follow LINK or LINKX.
entry name: Symbol.
entry name addr: A-type address.
list entry addr: A-type address.
dcb addr: A-type address.
Default
: ,PLISTARALETS=SYSTEM
Note
: ,PLISTARALETS is valid only with LINKX.
Default
: PLIST8ARALETS=NO
Note
: PLIST8ARALETS is valid only with LINKX.
err rtn addr: A-type address.
Default
: No
Chapter 76. LINK and LINKX — Pass control to a program in another load module
819
LINK and LINKX macros
Syntax
,AMODE64OK=NO
,AMODE64OK=YES
,SF=L
Description
AMODE64OK is valid only with LINKX.
Default
: NO
Parameters
The parameters are explained under the standard form of the LINK and LINKX macros, with the following exception:
,SF=L
Specifies the list form of the LINK or LINKX macro.
Note:
1.
Coding the LSEARCH parameter causes a parameter list to be created that is different from the list created when LSEARCH is omitted. If you code
LSEARCH=YES in either the list or execute form of the macro, you must code it in both forms.
2.
If ERRET is coded in the list form and not specified in the execute form, the error routine specified in the list form will be retained and used in the execute form of the macro. If ERRET is specified in both the list and the execute form, the error routine specified in the execute form of the macro will be used.
LINK and LINKX—Execute form
Two parameter lists are used in a LINK or LINKX macro: a control program parameter list and an optional problem program parameter list. Either or both of these lists can be remote and can be referred to and modified by the execute form of LINK or LINKX. If only one of the parameter lists is remote, parameters that require use of the other parameter list cause that list to be constructed inline as part of the macro expansion.
Syntax
Syntax
The execute form of the LINK or LINKX macro is written as follows:
Description
name
⌂
name: Symbol. Begin name in column 1.
One or more blanks must precede LINK or LINKX.
LINK
LINKX
⌂ One or more blanks must follow LINK or LINKX.
820
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
EP=entry name
EPLOC=entry name addr
DE=list entry addr
,DCB=dcb addr
,PARAM=(addr)
,PARAM=(addr),VL=1
,PLIST4=YES
,PLIST4=NO
,PLIST8=YES
,PLIST8=NO
,PLISTARALETS=SYSTEM
,PLISTARALETS=NO
,PLIST8ARALETS=NO
,PLIST8ARALETS=YES
,ID=id nmbr
,ERRET=err rtn addr
,LSEARCH=NO
,LSEARCH=YES
,AMODE64OK=NO
,AMODE64OK=YES
,MF=(E,prob addr)
,SF=(E,ctrl addr)
,MF=(E,prob addr),SF=(E,ctrl
addr)
LINK and LINKX macros
Description
entry name: Symbol.
entry name addr: RX-type address or register (2) - (12).
list entry addr: RX-type address, or register (2) - (12).
dcb addr: RX-type address, or register (2) - (12).
addr: RX-type address, or register (2) - (12).
Note
: addr is one or more addresses, separated by commas. For example,
(addr,addr,addr)
PLIST4 is valid only with LINKX.
Default
: None.
PLIST8 is valid only with LINKX.
Default
: None.
Default
: ,PLISTARALETS=SYSTEM
Note
: ,PLISTARALETS is valid only with LINKX.
Default
: PLIST8ARALETS=NO
Note
: PLIST8ARALETS is valid only with LINKX.
id nmbr: Symbol or decimal digit, with a maximum value of 4095.
err rtn addr: RX-type address or register (2) - (12).
Default
: No
AMODE64OK is valid only with LINKX.
Default
: NO
prob addr: RX-type address, or register (1) or (2) - (12).
ctrl addr: RX-type address, or register (2) - (12) or (15).
Parameters
The parameters are explained under the standard form of the LINK and LINKX macros, with the following exceptions:
Chapter 76. LINK and LINKX — Pass control to a program in another load module
821
LINK and LINKX macros
,MF=(E,prob addr)
,SF=(E,ctrl addr)
,MF=(E,prob addr),SF=(E,ctrl addr)
Specifies the execute form of the LINK or LINKX macro. This form uses a remote problem program parameter list, a remote control program parameter list, or both.
Note:
1.
Coding the LSEARCH parameter causes a parameter list to be created that is different from the list created when LSEARCH is omitted. If you code
LSEARCH=YES in either the list or execute form of the macro, you must code it in both forms.
2.
If ERRET is coded in the list form and not specified in the execute form, the error routine specified in the list form will be retained and used in the execute form of the macro. If ERRET is specified in both the list and the execute form, the error routine specified in the execute form of the macro will be used.
822
z/OS MVS Assembler Services Reference IAR-XCT
|
Chapter 77. LOAD — Bring a load module into virtual storage
|
|
LOAD description
The LOAD macro is used to bring the load module containing the specified entry name into virtual storage, if a usable copy is not available in virtual storage.
Control is not passed to the load module; instead, the load module's entry point address is returned in GPR 0.
LOAD services place the load module in storage above or below 16 megabytes or above 2 gigabytes, depending on the module's RMODE.
The responsibility count for the load module is increased by one.
The load module remains in virtual storage until the responsibility count is reduced to 0 through task terminations. The module also remains until the effects of all outstanding LOAD requests for the module are canceled by using the
DELETE macro. There are no other requirements for the module.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt Status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
24- or 31- or 64-bit
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space
Programming requirements
If you code the parameters LSEARCH, LOADPT, or LOADPT64, you obtain a macro-generated parameter list. Therefore, except for the error routine address, all addresses must be specified as A-type addresses or registers (2) - (12).
Restrictions
v Any module loaded by a task will not be removed from virtual storage unless the task that loaded the module invokes the DELETE macro or terminates.
v The load module entry name must be listed as a member name or alias in a partitioned data set directory or specified previously by using the IDENTIFY macro. If the LOAD macro cannot find the specified entry name, the caller's task is abended unless the caller provides an ERRET exit.
v The caller cannot have an EUT FRR established.
© Copyright IBM Corp. 1988, 2017
823
LOAD macro
|
|
|
Input register information
The caller does not have to place information into any register before issuing the
LOAD macro. If the caller is using the LOAD macro in register notation for a particular parameter, or as a base register, the caller must place information into the register.
Output register information
If the LOAD is successful, the GPRs contain the following when control returns to the caller:
Register
Contents
0
Entry point address of the requested load module. Load services set 64-bit
GPR 0 according to the load module's AMODE: v AMODE 24: bits 32 and 63 are both 0, and bits 0–31 are all set to 0.
v AMODE 31: bit 32 is 1, bit 63 is 0, and bits 0–31 are all set to 0.
v AMODE 64: bit 63 is 1
1
If the module's AMODE is ANY, it indicates AMODE 24 if the caller is
AMODE 24, or AMODE 31 if the caller is AMODE 31 or AMODE 64.
The high-order byte contains the load module's APF authorization code.
The low-order 3 bytes contain one of the following values (in priority order): v If the module is a program object with more than one segment (extent), zeros.
To obtain the length and load point information for each segment, use the information returned by way of the EXTINFO parameter or issue the
CSVQUERY macro with the OUTXTLST parameter.
2-13
14
15
Note:
A program object might have more than one segment. One example is the use of the binder RMODE(SPLIT) attribute.
v If the module’s length, in doublewords, is greater than or equal to 16 M
(2
24
) bytes, zeros.
To obtain the module length, use the information returned by way of the
EXTINFO parameter or issue the CSVQUERY macro with the
OUTLENGTH or OUTXTLST parameters.
v
Otherwise, the module length, in doublewords.
If the module is a program object, which is bound with the
FETCHOPT=NOPACK option, the returned length value is round to the full-page multiple area obtained with GETMAIN to hold the program object. If the program object is bound with the FETCHOPT=PACK option, the returned length value is the size indicated in the directory entry. For further information, view the z/OS MVS Program Management: User's Guide
and Reference and z/OS MVS Program Management: Advanced Facilities.
Unchanged.
Used as a work register by the system.
Zero, indicating successful completion.
If the LOAD is not successful and the caller provided an ERRET exit to receive control, the GPRs contain:
824
z/OS MVS Assembler Services Reference IAR-XCT
⌂
Syntax
name
LOAD macro
0
1
Register
Contents
Used as a work register by the system.
System completion code for the abend that would have been issued had the caller not provided an ERRET exit.
2-13
14
15
Unchanged.
Used as a work register by the system.
Reason code (never zero) associated with the system completion code contained in GPR 1.
When control returns to the caller or the ERRET exit receive control, the access registers (ARs) are unchanged.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the LOAD macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede LOAD.
LOAD
⌂
EP=entry name
EPLOC=entry name addr
DE=list entry addr
,DCB=dcb addr
,ERRET=err rtn addr
,LSEARCH=NO
One or more blanks must follow LOAD.
entry name: Symbol.
entry name addr: If LSEARCH or LOADPT is specified, A-type address or register (2) - (12); otherwise, RX-type address or register (0) or (2) - (12).
list entry addr: If EXTINFO, LOADPT, or LSEARCH is specified, A-type address or register (2) - (12); otherwise, RX-type address, or register (2) -
(12).
dcb addr: If EXTINFO, LOADPT, or LSEARCH is specified, A-type address or register (2) - (12); otherwise, RX-type address, or register (1) or (2) - (12).
err rtn addr: RX-type address or register (2) - (12).
Default
: NO
Chapter 77. LOAD — Bring a load module into virtual storage
825
LOAD macro
||
Syntax
,LSEARCH=YES
,LOADPT=addr
,LOADPT64=addr
,EXTINFO=addr
,RELATED=value
Description
addr: A-type address or register (2) - (12).
addr: A-type address or register (2) - (12).
addr: A-type address or register (2) - (12).
Parameters
The parameters are explained as follows:
EP=entry name
EPLOC=entry name addr
DE=list entry addr
Specifies the following: v When EP, specifies the entry name v When EPLOC, specifies the address of the name, which must be padded to 8 bytes if necessary v
When DE, specifies the address of the name field in a 62-byte list entry for the entry name that was constructed using the BLDL macro
The system ignores the information you specify on the DE parameter if the parameter does one or both of the following: v Specifies an entry in an authorized library (that is, defined in IEAAPFxx member of parmlib) v Requests access to a program or library that is controlled by the System
Authorization Facility (SAF)
Instead, the system uses the BLDL macro to construct a new list entry containing the DE information.
Note:
When you use the DE parameter with the LOAD macro, BLDL and
LOAD must be issued from the same task; otherwise, the system might terminate the program with an abend code of 106 and a return code of 15.
,DCB=dcb addr
Specifies the address of the opened data control block for the partitioned data set containing the entry name described previously. This parameter must indicate the same DCB specified in the BLDL used to locate the entry name.
If the DCB parameter is omitted or if DCB=0 is specified when the LOAD macro is issued by the job step task, the data sets referred to by either the
STEPLIB or JOBLIB DD statement is first searched for the entry name. If the entry name is not found, the link library is searched.
If the DCB parameter is omitted or if DCB=0 is specified when the LOAD macro is issued by a subtask, the data sets associated with one or more data control blocks. They are referred by the TASKLIB operand of previous
ATTACH macro in the sub-tasking chain and are first searched by the entry
826
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
LOAD macro
name. If the entry name is not found, the search is continued as if the LOAD had been issued by the job step task.get
Note:
DCB must exist in 24-bit addressable storage.
,ERRET=err rtn addr
Specifies the address of a routine to receive control when an error condition that would cause an abnormal termination of the task is detected. Register 1 contains the abend code that would have ended had the task abended, and register 15 contains the reason code that is associated with the abend. The routine does not receive control when input parameter errors are detected.
,LSEARCH=NO
,LSEARCH=YES
Specifies whether (YES) or not (NO) the search is to be limited to the job pack area and the first library in the normal search sequence.
,LOADPT=addr
Specifies that the starting address at which the module was loaded is to be returned to the caller at the indicated address.
,LOADPT64=addr
Specifies an 8-byte area at which the starting address at which the module was loaded is to be returned to the caller.
,EXTINFO=addr
Specifies a 304–byte area, which contains extended information upon return.
This area is mapped by dsect EXTI within macro CSVEXTI. Included in this area are: v
The extent list (each entry is mapped by dsect EXTIXE within macro
CSVEXTI) v The authorization code v The entry point address
By using the EXTINFO keyword, you can avoid the need to call CSVQUERY after doing the LOAD to obtain information that would not otherwise be returned by LOAD. For example, if a program object length were greater than
128 megabytes or had been bound with RMODE=SPLIT, LOAD would not otherwise return the length information.
,RELATED=value
Specifies information used to self-document macros by ‘relating’ functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and may be any valid coding values.
The RELATED parameter is available on macros that provide opposite services
(for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and
LOAD/DELETE), and on macros that relate to previous occurrences of the same macros (for example, CHAP and ESTAE).
For example, the RELATED parameter can be used as follows:
LOAD1 LOAD
.
.
.
DEL1 DELETE
EP=APGIOHK1,RELATED=(DEL1,’LOAD APGIOHK1’)
EP=APGIOHK1,RELATED=(LOAD1,’DELETE APGIOHK1’)
Chapter 77. LOAD — Bring a load module into virtual storage
827
LOAD macro
Return and reason codes
When the LOAD macro returns control to the caller, GPR 15 is set to zero if the load request was successful. If the load request was not successful and a caller-provided error routine (specified using the ERRET keyword) receives control,
GPR 1 contains the abend code for the abend that would have been issued had the caller not provided an ERRET exit. GPR 15 contains the reason code associated with the abend code in GPR 1.
Example 1
Bring a load module containing a specified entry name (PGMLKRUS) into virtual storage. Allows the system to find the module from available libraries.
LOAD EP=PGMLKRUS
Example 2
Bring a load module containing the entry name EPNAME into virtual storage.
Indicate that register 7 contains the address of the DCB associated with the partitioned data set that contains this load module. Return the load address of the requested module in the location pointed to by register 8. If an error occurs during this processing, transfer control to the error routine at ERRADDR.
LOAD EP=EPNAME,DCB=(7),LOADPT=(8),ERRET=ERRADDR
LOAD—List form
The list form of the LOAD macro builds a nonexecutable problem program parameter list that can be referred to or modified by the execute form of the LOAD macro.
Syntax
Syntax
The list form of the LOAD macro is written as follows:
Description
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede LOAD.
LOAD
�
EP=entry name
EPLOC=entry name addr
DE=list entry addr
,DCB=dcb addr
One or more blanks must follow LOAD.
entry name: Symbol.
entry name addr: A-type address.
list entry addr: A-type address.
dcb addr: A-type address.
,LSEARCH=NO
,LSEARCH=YES
Default
: No
828
z/OS MVS Assembler Services Reference IAR-XCT
LOAD macro
Syntax
,LOADPT=addr
,EXTINFO=addr
,RELATED=value
,SF=L
Description
addr: A-type address.
addr: A-type address.
Parameters
The parameters are explained under the standard form of the LOAD macro with the following exception:
,SF=L
Specifies the list form of the LOAD macro.
LOAD - Execute form
The execute form of the LOAD macro can refer to and modify the parameter list constructed by the list form of the macro.
Syntax
Syntax
The execute form of the LOAD macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede LOAD.
LOAD
�
EP=entry name
EPLOC=entry name addr
DE=list entry addr
,DCB=dcb addr
,ERRET=err rtn addr
,LSEARCH=NO
One or more blanks must follow LOAD.
entry name: Symbol.
entry name addr: RX-type address, or register (2) - (12).
list entry addr: RX-type address, or register (2) - (12).
dcb addr: RX-type address, or register (2) - (12).
err rtn addr: RX-type address, or register (2) - (12).
Default
: No
Chapter 77. LOAD — Bring a load module into virtual storage
829
LOAD macro
Syntax
,LSEARCH=YES
,LOADPT=addr
,EXTINFO=addr
,RELATED=value
,SF=(E,list addr)
Description
addr: RX-type address or register (2) - (12).
addr: A-type address.
list addr: RX-type address or register (2) - (12) or (15).
Parameters
The parameters are explained under the standard form of the LOAD macro with the following exception:
,SF=(E,list addr)
Specifies the execute form of the LOAD macro.
830
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 78. LSEXPAND — Expand the linkage stack capacity
Description
The LSEXPAND macro expands a normal linkage stack, or a recovery linkage stack, to support the specified number of entries by allocating additional DREF storage.
If a program does not specify the LSEXPAND macro, it receives a normal linkage stack with 96 entries and a recovery linkage stack with 24 entries.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN = HASN
31-bit
Primary or AR
Enabled for I/O and external interrupts
No locks held
Not applicable
Programming requirements
If the system has already issued a stack full program interruption, the system will not accept the LSEXPAND macro. In other words, do not wait until the normal or recovery linkage stacks are full to issue this macro.
Restrictions
None.
Input register information
Before issuing the LSEXPAND macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
© Copyright IBM Corp. 1988, 2017
831
LSEXPAND macro
Syntax
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as a work register by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The LSEXPAND macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede LSEXPAND.
LSEXPAND
�
NORMAL=n
RECOVERY=n
One or more blanks must follow LSEXPAND.
n: Symbol or number or value in register (2) - (12).
n: Symbol or number or value in register (2) - (12).
Parameters
LSEXPAND
Specifies the number of entries that a task has for its normal linkage stack or its recovery linkage stack.
NORMAL=n
Specifies the number of entries in the normal linkage table, where n can be between 97 and 16000. If you don't specify this parameter, the normal linkage stack has 96 entries.
RECOVERY=n
Specifies the number of entries in the recovery linkage stack, where n can be between 25 and 4000. If you don't specify this parameter, the recovery linkage stack has 24 entries.
832
z/OS MVS Assembler Services Reference IAR-XCT
LSEXPAND macro
ABEND codes
None.
Return codes
When LSEXPAND macro returns control to your program, GPR 15 contains a return code.
Table 47. Return and Reason Codes for the LSEXPAND Macro
Hexadecimal
Return Code
00
Meaning and Action
Meaning
: Successful completion.
08
Action
: None.
Meaning
: Program error. The caller was not unlocked.
0C
10
14
18
1C
20
24
28
Action
: Release locks before calling LSEXPAND.
Meaning
: Program error. The caller was not in task mode.
Action
: Change your code to run in task mode.
Meaning
: Program error. The specified normal stack size exceeds 16000.
Action
: Specify a stack size less than 16000.
Meaning
: Program error. The specified recovery stack size exceeds
4000.
Action
: Specify a stack size less than 4000.
Meaning
: Program error. The recovery stack cannot be expanded because it is currently in use.
Action
: Restructure your program to issue the LSEXPAND before the stack becomes full.
Meaning
: Program error. The normal stack cannot expand because the specified value is smaller than the current normal stack size.
Action
: Specify a larger stack size.
Meaning
: Program error. The recovery stack cannot expand because the specified value is smaller than the current recovery stack size.
Action
: Specify a larger stack size.
Meaning
: Environmental error. Not enough virtual storage was available for the normal linkage stack or the recovery linkage stack.
Action
: Retry the request one or more times. If the problem persists, check with the operator to see why there is a storage constraint.
Meaning
: System error. The normal linkage stack is unchanged. The recovery linkage stack might be expanded.
Action
: Retry the request.
Example 1
Expand the normal linkage stack to 192 entries.
LSEXPAND NORMAL=192
Chapter 78. LSEXPAND — Expand the linkage stack capacity
833
LSEXPAND macro
Example 2
Expand the recovery linkage stack to 96 entries.
LA 6,96
LSEXPAND RECOVERY=(6)
834
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 79. PGLOAD — Load virtual storage areas into central storage
Description
Syntax
Attention:
Use the PGSER macro rather than PGLOAD.
The PGLOAD macro is used to load specified virtual storage areas into central
(also called real) storage in anticipation of future needs. That is, PGLOAD is essentially a page-ahead function. The PGLOAD macro performs this function for virtual addresses below 16 megabytes; the LOAD option of the PGSER macro performs the same function for virtual addresses either above or below 16 megabytes. Note, however, that a page that has been loaded via PGLOAD is eligible for page-out selection in the same manner as a page that has been demand-paged into central storage.
The misuse of this function can have adverse effects on system performance.
Causing unnecessary pages to be brought into central storage will force other pages to be displaced and, consequently, cause unnecessary paging activity. Proper use of this function, however, will tend to decrease system overhead resulting from page faults.
Syntax
The standard form of the PGLOAD macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede PGLOAD.
PGLOAD
�
One or more blanks must follow PGLOAD.
R
,A=start addr
,ECB=ecb addr
,EA=end addr
,RELEASE=N
start addr: A-type address, or register (1) or (2) - (12).
ecb addr: A-type address, or register (0) or (2) - (12).
end addr: A-type address, or register (2) - (12) or (15).
Default:
start addr + 1
Default:
RELEASE=N
© Copyright IBM Corp. 1988, 2017
835
PGLOAD macro
Syntax
,RELEASE=Y
Description
Note:
RELEASE=Y may only be specified with EA above.
Parameters
The parameters are explained as follows:
R
Specifies that no parameter list is being supplied with this request.
,A=start addr
Specifies the start address of the virtual area to be loaded.
,ECB=ecb addr
Specifies the address of an ECB that is used to signal event completion.
,EA=end addr
Specifies the end address + 1 of the virtual area to be loaded.
,RELEASE=N
,RELEASE=Y
Specifies that the contents of the virtual area is to remain intact (N) or be released (Y).
When control is returned, register 15 contains one of the following return codes:
Hexadecimal Code
Meaning
00
08
Operation completed normally; ECB posted complete.
Operation proceeding; ECB will be posted when all page-ins are complete.
If control is not returned, an ABEND is issued with the following reason codes in register 15:
Hexadecimal Code
Meaning
10
Virtual subarea list entry or ECB address invalid. No ECB is posted.
If the ECB parameter is coded, the ECB is unchanged if the request was initiated but not complete (return code 8), or if an ABEND was issued with return code 10.
Otherwise, the ECB is posted complete with code
0 -
Operation completed successfully.
If the return code issued is 8, the ECB is posted asynchronously when paging I/O has completed, with code
0 -
Operation completed successfully.
Example 1
Page-in a single byte of virtual storage, causing the entire 4096-byte page containing that byte to be paged into central storage.
PGLOAD R,A=(R3)
836
z/OS MVS Assembler Services Reference IAR-XCT
PGLOAD macro
Example 2
Page-in the virtual storage lying in the range addressed by registers 3 and 4, and notify the requestor via posting of the ECB when the page-ins are complete.
PGLOAD R,A=(R3),EA=(R4),ECB=(R5)
Example 3
Discard the contents of the virtual pages totally encompassed by STARTAD and
ENDAD before new real frames are assigned.
PGLOAD R,A=STANDARD,EA=ENDAD,RELEASE=Y
PGLOAD—List form
The list form of the PGLOAD macro uses a virtual subarea list.
Syntax
Syntax
The list form of the PGLOAD macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede PGLOAD.
PGLOAD
�
L
,LA=list addr
,ECB=ecb addr
,RELEASE=N
,RELEASE=Y
One or more blanks must follow PGLOAD.
list addr: A-type address, or register (1) or (2) - (12).
ecb addr: A-type address, or register (0) - (2) or (15).
Default:
RELEASE=N
Parameters
The parameters are explained under the standard form of the PGLOAD macro, with the following exceptions:
L
Specifies that a parameter list is being supplied with this request.
,LA=list addr
Specifies the address of the first entry of a virtual subarea list.
Chapter 79. PGLOAD — Load virtual storage areas into central storage
837
PGLOAD macro
838
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 80. PGOUT — Page out virtual storage areas from central storage
Description
Syntax
Attention:
Use the PGSER macro rather than PGOUT.
The PGOUT macro is used to initiate page-out operations for specified virtual storage areas that are in central (also called real) storage. The PGOUT macro performs this function for virtual addresses below 16 megabytes; the OUT option of the PGSER macro performs the same function for virtual addresses either above or below 16 megabytes. The PGOUT function is complementary to the PGLOAD function. You have the option of specifying that the virtual pages to be paged out either remain valid in central storage, or be marked invalid and the real frames assigned to them be made available for reuse. The use of this option will not prevent page faults from occurring on the specified storage.
The misuse of this function, like the misuse of the PGLOAD function, can have adverse effects on system performance. On the other hand, proper use of this function will tend to clean out of central storage those pages no longer needed for program execution or not required for some period in the future.
Syntax
The standard form of the PGOUT macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede PGOUT.
PGOUT
�
One or more blanks must follow PGOUT.
R
,A=start addr
,EA=end addr
,KEEPREL=N
,KEEPREL=Y
start addr: A-type address, or register (1) or (2) - (12).
end addr: A-type address, or register (2) - (12) or (15).
Default
: KEEPREL=N
© Copyright IBM Corp. 1988, 2017
839
PGOUT macro
Parameters
The parameters are explained as follows:
R
Specifies that no parameter list is being supplied with this request.
,A=start addr
Specifies the start address of the virtual area to be paged out.
,EA=end addr
Specifies the end address + 1 of the virtual area to be paged out.
,KEEPREL=N
,KEEPREL=Y
Specifies that the virtual pages will be marked invalid and the real frames freed for reuse (N) or that the virtual pages will not be invalidated (Y).
When control is returned, register 15 contains one of the following return codes:
Hexadecimal Code
Meaning
00
0C
Operation completed normally; paging I/O proceeding asynchronously.
One or more pages specified to be paged out were not paged out. Either the pages were in the nucleus in unusable real frames, in SQA or LSQA, in
V=R area allocated region, were page fixed, or the system resources necessary to perform the page out operations were momentarily unavailable. Paging I/O is proceeding normally for all other pages.
10
Operation abnormally terminated. Virtual subarea list entry invalid.
Example 1
Page out the area of central storage totally encompassed by the start and end virtual boundaries specified.
PGOUT R,A=(R3),EA=(R4)
Example 2
Create an auxiliary storage copy of a virtual area before continuing to use the area.
The area will remain in central storage after the page-outs complete.
PGOUT R,A=(R3),EA=(R4),KEEPREL=Y
PGOUT—List form
The list form of the PGOUT macro uses a virtual subarea list.
Syntax
Syntax
The list form of the PGOUT macro is written as follows:
Description
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede PGOUT.
PGOUT
840
z/OS MVS Assembler Services Reference IAR-XCT
PGOUT macro
Syntax
�
L
,LA=list addr
,KEEPREL=N
,KEEPREL=Y
Description
One or more blanks must follow PGOUT.
list addr: A-type address, or register (1) or (2) - (12).
Default
: KEEPREL=N
Parameters
The parameters are explained under the standard form of the PGOUT macro, with the following exceptions:
L
Specifies that a parameter list is being supplied with this request.
,LA=list addr
Specifies the address of the first entry of a virtual subarea list (VSL). See the topic “Virtual Subarea List (VSL)” in z/OS MVS Programming: Assembler Services
Guide for a description of the VSL.
Chapter 80. PGOUT — Page out virtual storage areas from central storage
841
PGOUT macro
842
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 81. PGRLSE — Release virtual storage contents
Description
Syntax
Attention:
Use the PGSER macro rather than PGRLSE.
The PGRLSE macro is used to release to the system all central (also called real) storage and auxiliary storage associated with specified pageable virtual storage areas. The PGRLSE macro performs this function for virtual addresses below 16 megabytes; the RELEASE option of the PGSER macro performs the same function for virtual addresses either above or below 16 megabytes. Use PGRLSE when a large area (one or more complete pages) of virtual storage within your program no longer has significant contents.
Functionally, PGRLSE is equivalent to a FREEMAIN macro followed by a
GETMAIN macro. That is, the virtual space is maintained, but the data is discarded. When a released page is next referred to, its contents are binary zeros.
Thus, you can help reduce system overhead by releasing virtual storage when you no longer need it.
Note: PGRLSE, PGSER RELEASE, PGSER FREE with RELEASE=Y, and PGFREE
RELEASE=Y may ignore some or all of the pages in the input range and will not notify the caller if this was done.
Any pages in the input range that match any of the following conditions will be skipped, and processing continues with the next page in the range: v Storage is not allocated or all pages in a segment have not yet been referenced.
v Page is in PSA, SQA or LSQA.
v Page is V=R. Effectively, it's fixed.
v Page is in BLDL, (E)PLPA, or (E)MLPA.
v Page has a page fix in progress or a nonzero FIX count.
v Pages with COMMIT in progress or with DISASSOCIATE in progress.
Proper use of this function can increase the amount of storage available to the system and prevent needless paging I/O activity. Usage of PGRLSE may improve operating efficiency when the using program can discard the contents of a large virtual storage area and reuse the virtual storage pages; paging operations may be eliminated for those virtual storage pages when they are reused.
Syntax
The standard form of the PGRLSE macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede PGRLSE.
PGRLSE
© Copyright IBM Corp. 1988, 2017
843
PGRLSE macro
Syntax
�
LA=low addr
,HA=high addr
Description
One or more blanks must follow PGRLSE.
low addr: A-type address, or register (0) or (2) - (12).
high addr: A-type address, or register (1) or (2) - (12).
Parameters
The parameters are explained as follows:
LA=low addr
Specifies the address of the lower boundary of the area to be released.
,HA=high addr
Specifies the address of the upper boundary + 1 of the area to be released.
When control is returned, register 15 contains one of the following return codes:
Hexadecimal Code
Meaning
00
04
Successful completion.
Execution failed. The area specified, or a portion of the area, is protected from the requesting program. Any valid portion of the area preceding the protected area is released.
Example 1
Release the contents of the pages included within the specified areas. Only those pages fully encompassed will be nullified.
PGRLSE LA=(R4),HA=(R5)
Example 2
Perform the operation in Example 1, but use A-type addresses.
PGRLSE LA=LOWADDR,HA=HIGHADDR
PGRLSE - List form
The list form of the PGRLSE macro is used to construct a control program parameter list.
Syntax
Syntax
The list form of the PGRLSE macro is written as follows:
Description
name
name: Symbol. Begin name in column 1.
� One or more blanks must precede PGRLSE.
844
z/OS MVS Assembler Services Reference IAR-XCT
PGRLSE macro
Syntax
PGRLSE
�
LA=low addr,
,HA=high addr,
,MF=L
Description
One or more blanks must follow PGRLSE.
low addr: A-type address.
high addr: A-type address.
Parameters
The parameters are explained under the standard form of the PGRLSE macro, with the following exception:
,MF=L
Specifies the list form of the PGRLSE macro.
PGRLSE - Execute form
A remote control program parameter list is referred to, and can be modified by, the execute form of the PGRLSE macro.
Syntax
Syntax
The execute form of the PGRLSE macro is written as follows:
Description
name
�
PGRLSE
�
name: Symbol. Begin name in column 1.
One or more blanks must precede PGRLSE.
LA=low addr,
,HA=high addr,
,MF=(E,ctrl addr)
One or more blanks must follow PGRLSE.
low addr: A-type address, or register (0) or (2) - (12).
high addr: A-type address, or register (1) or (2) - (12).
ctrl addr: RX-type address, or register (2) - (12).
Chapter 81. PGRLSE — Release virtual storage contents
845
PGRLSE macro
Parameters
The parameters are explained under the standard form of the PGRLSE macro, with the following exception:
,MF=(E,ctrl addr)
Specifies the execute form of the PGRLSE macro using a remote control program parameter list.
846
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 82. PGSER — Page services
Description
Note: IBM recommends that you use the PGSER macro for paging services
.
The PGSER macro performs the same paging services as the PGLOAD, PGOUT, and PGRLSE macros. PGSER performs these services for addresses either above or below 16 megabytes.
The services are: v Page load equivalent to the PGLOAD macro.
v Page out equivalent to the PGOUT macro.
v Page release equivalent to the PGRLSE macro.
v The PGSER macro with the PROTECT parameter makes a range of virtual storage pages read-only.
v The PGSER macro with the UNPROTECT parameter makes a range of virtual storage pages modifiable.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state, and any PSW key. To use the PROTECT and
UNPROTECT options, the caller must have a PSW key that matches the key of the storage.
Task
PASN=HASN=SASN
24- or 31-bit
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space
Programming requirements
v The caller must include the IHAPVT mapping macro.
v Regardless of the addressing mode, all addresses passed in registers are used as
31-bit addresses.
v All RX-type addresses are assumed to be in the addressing mode of the caller.
Restrictions
None.
Input register information
Before issuing the PGSER macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
© Copyright IBM Corp. 1988, 2017
847
PGSER macro
Syntax
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-4
5-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) are unchanged.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The PGSER macro is written as follows:
Description
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede PGSER.
PGSER
� One or more blanks must follow PGSER.
R
L
,LOAD
,OUT
,PROTECT
,UNPROTECT
,RELEASE
,LA=list addr list addr: RX-type address or register (1), (2) - (12).
Note
: This parameter is valid only with L.
,A=start addr start addr: RX-type address or register (1), (2) - (12).
Note
: This parameter is valid only with R.
848
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,EA=end addr
,ECB=ecb addr
,RELEASE=Y
,RELEASE=N
,KEEPREL=Y
,KEEPREL=N
,RELATED=value
PGSER macro
Description
Default
: EA=start addr
end addr: RX-type address or register (15), (2) - (12).
Note
: This parameter is valid only with R.
Default
: If LOAD is specified, ECB=0.
ecb addr: RX-type address or register (0) or (2) - (12).
Note
: This parameter is optional if LOAD is specified and is not valid for
OUT and RELEASE.
Default
: RELEASE=N
Note
: This parameter may be specified only if LOAD is specified.
Default
: KEEPREL=N
Note
: This parameter may be specified only if OUT is specified.
value: Any valid macro keyword specification.
Parameters
R
L
Specifies the manner in which the input is supplied. If R is specified, the user supplies the starting and ending addresses of the virtual area for which the service needs to be performed. If L is specified, the user supplies the address of the page services list (PSL), which specifies the virtual area for which the service is to be performed. See the topic “Page Service List (PSL)” in z/OS MVS
Programming: Assembler Services Guide for a description of the PSL.
,LOAD
,OUT
,PROTECT
,UNPROTECT
,RELEASE
Indicates the function to be performed.
LOAD specifies that a page-in operation is to be initiated for the virtual storage area specified, in anticipation of future needs.
OUT specifies that a page-out operation is to be initiated for the virtual storage area specified.
PROTECT specifies that a range of virtual storage be made read-only. R, L, LA,
A, EA, and RELATED are valid keywords with the PROTECT option.
UNPROTECT specifies that a range of virtual storage be made modifiable. R,
L, LA, A, EA, and RELATED are valid keywords with the UNPROTECT option.
RELEASE specifies the release of all physical paging resources, including both processor storage and auxiliary storage. Functionally, RELEASE is equivalent to
Chapter 82. PGSER — Page services
849
PGSER macro
a FREEMAIN macro followed by a GETMAIN macro. That is, the virtual space is maintained, but the data is discarded. When a released page is next referred to, its contents are binary zeros.
Note:
You must unprotect protected storage before releasing it.
,LA=list addr
Specifies the address of the page services list (PSL) for L requests.
,A=start addr
Specifies the address of the start of the virtual area for R requests.
,EA=end addr
Specifies the address of the last byte on the last page of the virtual area for R requests.
,ECB=ecb addr
Specifies the address of the ECB that is used to signal event completion for a
LOAD request.
If an ECB is supplied, the caller must check the return code because the ECB will not be posted if the return code is zero. If an ECB is not supplied, it is not necessary to check the return code because control returns to the caller only if the request was successfully completed; if unsuccessful, page services abnormally terminates the caller. You must ensure that the storage area containing the ECB is not freed and that the key is not altered. If either test fails, page services does not post the ECB.
,RELEASE=Y
,RELEASE=N
Specifies that all the central (also called real) and auxiliary storage associated with the virtual storage areas is to be released to the system (Y), or that all the central and auxiliary storage associated with the virtual storage areas is not to be released to the system (N).
Note: PGRLSE, PGSER RELEASE, PGSER FREE with RELEASE=Y, and
PGFREE RELEASE=Y may ignore some or all of the pages in the input range and will not notify the caller if this was done.
Any pages in the input range that match any of the following conditions will be skipped, and processing continues with the next page in the range: v Storage is not allocated or all pages in a segment have not yet been referenced.
v
Page is in PSA, SQA or LSQA.
v Page is V=R. Effectively, it's fixed.
v Page is in BLDL, (E)PLPA, or (E)MLPA.
v Page has a page fix in progress or a nonzero FIX count.
v Pages with COMMIT in progress or with DISASSOCIATE in progress.
,KEEPREL=Y
,KEEPREL=N
Specifies that the virtual pages should be validated again after the page-out completes (Y), or that the virtual pages will be marked invalid and the real frames freed for reuse (N).
,RELATED=value
Provides information to document the macro by relating the service performed to some corresponding function or service. The format can be any valid coding value that the user chooses.
850
z/OS MVS Assembler Services Reference IAR-XCT
PGSER macro
ABEND codes
PGSER might abnormally terminate with one of the following abend codes: X'18A',
X'28A'. See z/OS MVS System Codes for explanations and programmer responses.
Return and reason codes
When the PGSER macro returns control to your program, GPR 15 contains one of the following hexadecimal return codes.
Option
LOAD
LOAD
OUT
OUT
RELEASE
Code
0
8
0
C
0
Meaning and Action
Meaning
: The operation completed normally and the ECB will not be posted. If no ECB is supplied, the operation is completed or proceeding.
Action
: None. If the ECB parameter was specified, do not issue a WAIT macro for the ECB after receiving this return code because it will not be posted.
Meaning
: The operation is proceeding. The ECB, if applicable and available, will be posted with X‘00’ when all page-ins are complete.
Action
: None. However, if the ECB parameter was specified, issuing a WAIT macro for this ECB will allow your program to synchronize with the completion of the page load operation.
Meaning
: The operation completed normally.
Action
: None.
Meaning
: At least one page specified to be paged out was not paged out. The page service is proceeding for the other pages.
Action
: None.
Meaning
: The operation completed normally.
Note: PGRLSE, PGSER RELEASE, PGSER FREE with
RELEASE=Y, and PGFREE RELEASE=Y may ignore some or all of the pages in the input range and will not notify the caller if this was done.
Any pages in the input range that match any of the following conditions will be skipped, and processing continues with the next page in the range: v Storage is not allocated or all pages in a segment have not yet been referenced.
v Page is in PSA, SQA or LSQA.
v Page is V=R. Effectively, it's fixed.
v Page is in BLDL, (E)PLPA, or (E)MLPA.
v Page has a page fix in progress or a nonzero FIX count.
v Pages with COMMIT in progress or with
DISASSOCIATE in progress.
Action
: None.
Chapter 82. PGSER — Page services
851
PGSER macro
Examples
Example 1
Perform the page-load function for the 4096-byte virtual area starting at BUFFER, supplying no ECB. Include the IHAPVT mapping macro.
PGSER R,LOAD,A=BUFFER,EA=BUFFER+4095,ECB=0
IHAPVT
Example 2
Release the virtual area specified in the PSL located at LOADWORD. Include the
IHAPVT mapping macro.
PGSER L,RELEASE,LA=LOADWORD
IHAPVT
Example 3
Protect the storage area that starts at the address in GPR 4 and ends at the address in the variable ENDIT. Include the IHAPVT mapping macro.
PGSER R,PROTECT,A=(4),EA=ENDIT
IHAPVT
852
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 83. POST — Signal event completion
Description
Use the POST macro to set an event control block (ECB) to indicate the occurrence of an event. If this event satisfies the requirements of an outstanding WAIT or
EVENTS macro, the waiting task is taken out of the wait state and dispatched according to its priority. POST processing sets the bits in the ECB as follows: v Bit 0 to 0 (wait bit) v Bit 1 to 1 (complete bit) v
Bits 2 through 31 to the specified completion code.
Note:
After the bits in the ECB are set, the ECB is considered posted and the awaited event can be recognized as having occurred by programs running in the system. If a program issues another POST against an ECB that is already posted, the other POST has no effect.
For more information on how to use the POST macro to synchronize tasks, see
z/OS MVS Programming: Assembler Services Guide.
Environment
The requirements for callers of POST are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
One of the following: v For LINKAGE=SVC: PASN=HASN=SASN v For LINKAGE=SYSTEM: PASN=HASN=SASN or
PASN¬=HASN¬=SASN
24- or 31- or 64-bit
Primary
Enabled for I/O and external interrupts v For LINKAGE=SVC: No locks held and no enabled unlocked task (EUT) functional recovery routines (FRR) established v For LINKAGE=SYSTEM: No locks held
The event control block (ECB) must be in the primary address space.
Programming requirements
None.
Restrictions
None.
© Copyright IBM Corp. 1988, 2017
853
POST macro
Syntax
Input register information
Before issuing the POST macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
14
15
Used as work registers by the system
Unchanged
Used as a work register by the system
One of the following: v If LINKAGE=SVC is specified: Used as a work register by the system v If LINKAGE=SYSTEM is specified: Return code of 0
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The POST macro is written as follows:
Description
name
⌂
name: Symbol. Begin name in column 1.
One or more blanks must precede POST.
POST
⌂
ecb addr
,comp code
,LINKAGE=SVC
One or more blanks must follow POST.
ecb addr: RX-type address, or register (1) or (2) - (12).
comp code: Symbol, decimal digit, or register (0) or (2) - (12). If specifying a symbol, it must be valid when used as an operand of a LA instruction.
Range of values
: 0 to (2
30
− 1)
Default
: 0
Default
: LINKAGE=SVC
854
z/OS MVS Assembler Services Reference IAR-XCT
POST macro
Syntax
,LINKAGE=SYSTEM
,RELATED=value
Description
value: Any valid macro keyword specification.
Parameters
The explanation of the parameters is as follows:
ecb addr
Specifies the address of the fullword event control block representing the event.
,comp code
Specifies the completion code to be placed in the event control block upon completion.
,LINKAGE=SVC
,LINKAGE=SYSTEM
Specifies the type of linkage that the caller is using to invoke the POST service routine.
For LINKAGE=SVC, the linkage is through an SVC instruction. This linkage is valid only when the caller is in primary mode and the primary, home, and secondary address spaces are the same.
For LINKAGE=SYSTEM, the linkage uses a non-SVC entry. This linkage is valid in cross memory mode or in non-cross memory mode. The ECB must be in the caller's primary address space. LINKAGE=SYSTEM is intended to be used by programs in cross memory mode.
The default is LINKAGE=SVC.
,RELATED=value
Specifies information used to self-document macros by ‘relating’ functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user and may be any valid coding values.
The RELATED parameter is available on macros that provide opposite services
(for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and
LOAD/DELETE) and on macros that relate to previous occurrences of the same macros (for example, CHAP and ESTAE).
The RELATED parameter may be used, for example, as follows:
WAIT1 WAIT
.
.
.
RESUME1 POST
1,ECB=ECB,RELATED=(RESUME1,’WAIT FOR EVENT’)
ECB,0,RELATED=(WAIT1,’RESUME WAITER’)
Return and reason codes
For LINKAGE=SYSTEM, the return code in register 15 is always zero. Otherwise, the POST macro has no return codes.
Chapter 83. POST — Signal event completion
855
POST macro
Example 1
Signal event completion with a default completion code. POSTECB is the address of an ECB.
POST POSTECB
Example 2
Signal event completion with a completion code of X‘7FF’. POSTECB is the address of an ECB.
POST POSTECB,X’7FF’
856
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 84. QRYLANG — Determine languages available for message translation
Description
The QRYLANG macro enables you to check if a particular language is available into which you can translate system or application messages. It can also provide a list of all active languages currently available for translation. Once you know that the language you want is available, you can issue TRANMSG to retrieve the translated message.
QRYLANG returns the information you request in the language query block (LQB).
This block contains the following: v The standard 3-character code for the language v The name of the language v A flag indicating whether the language contains double-byte characters
If you asked for a list of all available languages, QRYLANG returns an LQB with one language entry for each language.
See z/OS MVS Programming: Assembler Services Guide for more information on using
QRYLANG.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt Status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task or SRB
PASN=HASN=SASN or PASN¬=HASN¬=SASN
24- or 31-bit
Primary
Enabled for I/O and external interrupts
No locks held
Not applicable
Programming requirements
Before invoking QRYLANG you must allocate storage for the LQB.
You must include the following mapping macros: v CNLMLQB v CNLMMCA
Restrictions
None.
Input register information
Before issuing the QRYLANG macro, the caller must ensure that the following general purpose register (GPR) contains the specified information:
© Copyright IBM Corp. 1988, 2017
857
QRYLANG macro
Syntax
Register
Contents
13
Points to a save area
Output register information
When control returns to the caller, the output registers contain:
1
2-13
14
15
Register
Contents
0
v The contents of the high-order halfword are not part of the intended programming interface.
v
The low-order halfword contains a reason code.
Used as a work register by system
Unchanged
Used as a work register by system
Return code
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The QRYLANG macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede QRYLANG.
QRYLANG
�
LQB=lang qblock addr
,LQBLEN=length of block addr
,LANGNAME=lang addr
One or more blanks must follow QRYLANG.
lang qblock addr: RX-type address or register (2) - (12).
length of block addr: RX-type address or register (2) - (12).
lang addr: RX-type address or register (2) - (12).
858
z/OS MVS Assembler Services Reference IAR-XCT
QRYLANG macro
Parameters
The parameters are explained as follows:
LQB=lang qblock addr
Specifies the storage area or a register pointing to the storage area where
QRYLANG is to build the LQB.
,LQBLEN=length of block addr
Specifies the fullword or a register containing the length in bytes of the LQB.
You must supply the length of the LQB if you are querying more than one language. See z/OS MVS Programming: Authorized Assembler Services Guide for information on how to calculate the length of the LQB. If you do not specify
LQBLEN, QRYLANG will default to the assembled length of the LQB parameter. If you use an RX-type address or register notation for the LQB parameter, you must specify LQBLEN.
,LANGNAME=lang addr
Specifies the 24-byte character field or a register pointing to the 24-byte character field containing the name or code of the language to be queried. See
z/OS MVS Programming: Assembler Services Guide for a listing of the language codes. The language name must match the name specified on the NAME parameter of the LANGUAGE statement in the MMSLSTxx member of
SYS1.PARMLIB. If you omit this keyword, QRYLANG returns a list of all currently available languages.
Return and reason codes
When QRYLANG completes, register 15 contains one of the following hexadecimal return codes:
Meaning Hexadecimal
Code
00
04
08
0C
10
Processing completed successfully.
Processing did not complete, and storage is not freed.
Processing is complete but QRYLANG returned an incomplete LQB to the calling program. For example, the requested language may not be available.
Processing did not complete. The output is unusable.
The function did not complete. The output LQB is unusable.
The low-order halfword of register 0 contains the following hexadecimal reason codes from QRYLANG:
Meaning Hexadecimal
Return Code
00
04
Hexadecimal
Reason Code
00
07
04 08
Successful processing.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
Chapter 84. QRYLANG — Determine languages available for message translation
859
QRYLANG macro
08
08
0C
0C
0C
0C
0C
0C
0C
0C
0C
0C
10
Hexadecimal
Return Code
04
04
04
0F
2C
0A
16
17
26
27
28
2D
2E
2F
30
09
Hexadecimal
Reason Code
0B
0C
0D
Meaning
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
The passed storage address is not valid.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
There is insufficient LQB storage for LQB entries.
The language you requested is not available.
No storage was obtained.
The LQB is too small to handle returned data.
The MVS message service is not available.
The query request terminated. The MMS user exit has set the processing indicator to a nonzero value.
The entry installation exit has failed.
The exit installation exit has failed.
The acronym of the control block created when invoking QRYLANG is not "LQB" and is therefore not valid.
The length of the LQB is not valid.
QRYLANG was unable to move the LQB from the caller's address space.
QRYLANG was unable to move the LQB to the caller's address space.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
Example
Check if the language with a language code of JPN is active. If JPN is active,
QUERY2A sets a flag within the installation-created control block to "on", indicating that JPN is available.
QUERY2A CSECT
QUERY2A AMODE 31
QUERY2A RMODE ANY
STM 14,12,12(13)
BALR 12,0
USING *,12
ST
LA
13,SAVE+4
15,SAVE
ST
LR
15,8(13)
13,15
* *
***********************************************************************
* OBTAIN STORAGE AREA FOR INSTLCB AND LQB *
***********************************************************************
* *
GETMAIN RU,LV=STORLEN,SP=SP228
*
LR
ST
*
R3,R1 SAVE ADDRESS OF STORAGE AREA
R3,CVTUSER-CVT(R2) ANCHOR INSTALLATION CONTROL BLOCK C
860
z/OS MVS Assembler Services Reference IAR-XCT
QRYLANG macro
FROM GLOBAL COMMUNICATIONS WORD
IN MCA CONTROL BLOCK
XC 0(STORLEN,3),0(3) CLEAR STORAGE AREA
MVC INSTLACR-INSTLCB(4,R3),=C’INST’ SET ACRONYM IN
LA
LA
R4,INSTLLEN(,R3)
R5,LQBLEN
INSTALLATION CONTROL BLOCK
OBTAIN ADDRESS OF LQB
GET LQB LENGTH
* *
QRYLANG LANGNAME=JPN_CODE,LQB=(R4),LQBLEN=(R5)
* *
*
***********************************************************************
* RETURN *
***********************************************************************
*
END
LTR R15,R15
BNZ END
OI
IS JAPANESE AVAILABLE
NO, EXIT
INSTLFLG-INSTLCB(R3),INSTLJPN YES, SET AVAIL. FLAG
DS
L
LM
BR
0H
13,SAVE+4
14,12,12(13)
14
***********************************************************************
JPN_CODE DC CL24’JPN’
SAVE DC 18F’0’
SP228 EQU 228
LQBLEN EQU (LQBVDAT-LQB)+LQBEBL
STORLEN EQU INSTLLEN+LQBLEN
R1 EQU 1
R2
R3
EQU
EQU
2
3
R4
R5
EQU 4
EQU 5
R15 EQU 15
***********************************************************************
DSECT
CVT DSECT=YES
CNLMMCA
CNLMLQB
INSTLCB DSECT
INSTLACR DS
INSTLFLG DS
CL4’INST’
X
INSTLJPN EQU X’80’
DS CL23
INSTLLEN EQU *-INSTLCB
END QUERY2A
INSTALLATION CONTROL BLOCK
INSTALLATION CONTROL BLOCK ACRONYM
LANGUAGE AVAILABILITY FLAGS
JAPANESE IS AVAILABLE
RESERVED
C
C
Chapter 84. QRYLANG — Determine languages available for message translation
861
QRYLANG macro
862
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 85. REFPAT — Define and end a reference pattern
Description
The REFPAT macro identifies a large data area and tells the system how the program will be referencing that area. Additionally, the program tells the system how many bytes of data it wants the system to bring into central storage on a page fault (that is, each time the program references data that is not in central storage).
Use REFPAT if your program accesses a very large data area in a reference pattern that is consistently in a forward or backward direction. The system responds to
REFPAT by bringing multiple pages into central storage on a page fault. REFPAT might significantly improve the performance of the program.
REFPAT INSTALL defines the reference pattern and REFPAT REMOVE removes the definition.
Your program can reference an area with one pattern, then later reference the same area with another pattern. Use REFPAT INSTALL to define the first reference pattern and REFPAT REMOVE to remove the definition. Then, issue REFPAT
INSTALL to define another pattern for the same area.
On REFPAT INSTALL, you describe the data area, the reference pattern, and tell the system how many bytes of data you want it to bring into central storage on a page fault. Two parameters, UNITSIZE and GAP, determine the reference pattern: v UNITSIZE specifies the size of a “reference unit”. A reference unit is a grouping of contiguous bytes that the program references. You might decide a reference unit is the group of bytes that make up an element of an array, or the group of bytes that occur between gaps, or a page (4096 bytes).
v GAP defines the size of “gaps” in the reference pattern. Gaps are areas that the program does not reference; they must be uniform in size and appear throughout the data area at repeating intervals. Not all reference patterns include such a gap.
UNITS specifies how many reference units, as defined on UNITSIZE, you want the system to bring into central storage on a page fault.
The data area can be located in the primary address space, or in a data space identified by the STOKEN parameter.
Each pattern defined by REFPAT INSTALL is associated with the task that represents the caller. A task can have up to 100 reference patterns for different data areas, but cannot have multiple patterns for the same area. Multiple tasks can specify a different reference pattern for the same data area. REFPAT REMOVE removes the association between the pattern and the task.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
© Copyright IBM Corp. 1988, 2017
863
REFPAT macro
Environmental factor
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
31-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space.
Programming requirements
If your program is in AR mode, make sure the SYSSTATE ASCENV=AR macro has been issued to tell the system to generate code appropriate for AR mode.
Restrictions
If you specify STOKEN for a data space, the data space must be owned by a task in the primary address space.
Input register information
Before issuing the REFPAT macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0
Reason code if the return code in GPR 15 is not 0; otherwise, used as a work register by the system
1
2-13
Used as a work register by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
1
2-13
Used as a work register by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
The system rejects the REFPAT macro if the values you specify do not benefit the performance of your program. To make sure the system accepts the macro, ask the system to bring in more than three pages (that is, 12288 bytes) on each page fault.
864
z/OS MVS Assembler Services Reference IAR-XCT
�
Syntax
name
Syntax
The standard form of the REFPAT macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede REFPAT.
REFPAT
� One or more blanks must follow REFPAT.
INSTALL
REMOVE
,PSTART=start
,PEND=end
,STOKEN=stoken
,UNITSIZE=unit size
,GAP=gap variable
,UNITS=unit number
start: RX-type address or address in register (2) - (12).
end: RX-type address or address in register (2) - (12).
stoken: RX-type address or register (2) - (12).
Default
: STOKEN=0
unit size: RX-type address or register (2) - (12).
UNITSIZE is required with INSTALL.
gap variable: RX-type address or register (2) - (12).
Default
: GAP=0
unit number: RX-type address or register (2) - (12).
Default
: UNITS=1
REFPAT macro
Parameters
The parameters are explained as follows:
INSTALL
REMOVE
INSTALL indicates that the program is to begin referencing the data area according to a defined pattern. Required parameters on the INSTALL request are PSTART, PEND, and UNITSIZE. UNITS, GAP, and STOKEN are optional.
REMOVE indicates that the program has finished referencing the data area, as specified by the previous REFPAT INSTALL request. Required parameters on the REMOVE request are PSTART and PEND. STOKEN is optional on the
REMOVE request; UNITSIZE, GAP, and UNITS are not valid.
Chapter 85. REFPAT — Define and end a reference pattern
865
REFPAT macro
PSTART and PEND on the INSTALL request must be exactly the same as
PSTART and PEND on the REMOVE request for the same reference pattern.
,PSTART=start
A required parameter that contains the address of the first byte of the data area for which the reference pattern applies. PSTART and PEND addresses must not straddle the common area boundaries. That is, for data in the primary address space, all data must be either in low private, in common, or in high private storage.
When a gap exists, define PSTART according to the following rules: v If direction is forward, PSTART must be the first byte (low-address end) of a reference unit.
v If direction is backward, PSTART must be the last byte (high-address end) of a reference unit.
To code:
Specify the RX-type address, or address in register (2)-(12), of a pointer field.
,PEND=end
A required parameter that contains the address of the last byte of the data area for which the reference pattern applies. If start is a higher address than end, the system knows that data reference is in a backward direction.
Whether or not a gap exists, PEND can be any part of a reference unit or a gap.
To code:
Specify the RX-type address, or address in register (2)-(12), of a pointer field.
,STOKEN=stoken
Specifies the STOKEN that identifies the data space that contains the data area.
You received the STOKEN either from DSPSERV or from another program.
If you use STOKEN=0 or do not specify STOKEN, the system assumes the data is in the primary address space.
,UNITSIZE=unit size
Specifies the number of consecutive bytes that you want the system to treat as a reference unit. If the pattern includes a gap, the reference unit is the grouping of bytes that lie between the gaps. If the pattern does not include a gap, you can use any logical grouping of bytes that your data structure suggests, such as an element, a row or two, or a page (4096 bytes). UNITSIZE is required for the INSTALL request.
,GAP=gap variable
Specifies the gap, in bytes, of the reference pattern. The default is GAP=0.
,UNITS=unit number
Specifies the number of reference units, as defined on UNITSIZE, the system is to page in at one time. The default is one reference unit or UNITS=1. To figure out how many bytes the system brings in at a time: v If there is no gap, multiply the UNITS value by the UNITSIZE value and round up to the nearest 4096-byte boundary.
v If there is a gap, the number depends on values of UNITSIZE, GAP, UNITS, plus the location of the reference units and gaps relative to a page boundary.
The system brings in the pages that contain the reference units. It does not bring in pages that contain only data in the gap. z/OS MVS Programming:
Assembler Services Guide can help you code the parameters.
866
z/OS MVS Assembler Services Reference IAR-XCT
REFPAT macro
Return and reason codes
Return and reason codes, in hexadecimal, from REFPAT are:
Return Code
00
04
08
08
08
08
Reason Code
None.
xx0001xx xx0002xx xx0003xx xx0004xx xx0101xx
Meaning
REFPAT completed successfully.
REFPAT completed successfully; however, the system did not accept the reference pattern the caller specified. The system decided that the normal paging algorithms would be more efficient.
Unsuccessful completion. The range that the caller specified on the INSTALL request overlaps the range that a previous request specified.
Unsuccessful completion. The number of existing
REFPAT INSTALL requests for the task exceeds 100, the maximum number the system allows.
Unsuccessful completion. LSQA storage is not available for the macro service.
Unsuccessful completion. The caller specified the
REMOVE request; however, no INSTALL request was in effect for the specified range. Check to see if the system rejected the previous INSTALL request for the range.
Example 1
Define a reference pattern in which the program processes 8192 bytes and skips over 4096 bytes in a continuing way throughout an array. Registers 4 and 5 contain pointers to locations in storage which contain the starting and ending addresses of the array. Ask the system to bring in eight pages on each page fault.
REFPAT INSTALL,PSTART=(4),PEND=(R5),GAP=4096,UNITSIZE=8192,UNITS=4
Example 2
Tell the system you have finished using the array using that pattern:
REFPAT REMOVE,PSTART=(4),PEND=(R5)
REFPAT—List form
Use the list form of the REFPAT macro together with the execute form of the macro for programs that require reentrant code. The list form of the macro defines an area of storage, which the execute form of the macro uses to store the parameters.
Syntax
Syntax
The list form of the REFPAT macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede REFPAT.
Chapter 85. REFPAT — Define and end a reference pattern
867
REFPAT macro
Syntax
REFPAT
�
MF=(L,list addr)
MF=(L,list addr,attr)
Description
One or more blanks must follow REFPAT.
list addr: Symbol.
attr: 1- to 60-character input string.
Default
: 0D
Parameters
The parameters are explained under the standard form of the REFPAT macro with the following exception:
MF=(L,list addr,attr)
Specifies the list form of the REFPAT macro. list addr defines the area that the system is to use for the parameter list.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
REFPAT—Execute form
Use the execute form of the REFPAT macro together with the list form of the macro for programs that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Syntax
Syntax
The execute form of the REFPAT macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede REFPAT.
REFPAT
� One or more blanks must follow REFPAT.
INSTALL
REMOVE
,PSTART=start
start: RX-type address or register (2) - (12).
868
z/OS MVS Assembler Services Reference IAR-XCT
REFPAT macro
Syntax
,PEND=end
,STOKEN=stoken
,UNITSIZE=unit size
,GAP=gap variable
,UNITS=unit number
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Description
end: RX-type address or register (2) - (12).
stoken: RX-type address or register (2) - (12).
Default
: STOKEN=0
unit size: RX-type address or register (2) - (12).
UNITSIZE is required on INSTALL./.,pend
gap variable: RX-type address or register (2) - (12).
Default
: GAP=0
unit number: RX-type address or register (2) - (12).
Default
: UNITS=1
Parameters
The parameters are explained under the standard form of the REFPAT macro with the following exception:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Specifies the execute form of the REFPAT macro. list addr defines the area that the system uses for the parameter list.
COMPLETE specifies that the system is to check for required parameters and supply optional parameters that are not specified.
Chapter 85. REFPAT — Define and end a reference pattern
869
REFPAT macro
870
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 86. RESERVE — Reserve a device (shared DASD)
Description
The RESERVE macro reserves a device for use by a particular system; it must be issued by each task needing to reserve a device shared with one or more systems.
The RESERVE macro protects the caller from interference by other tasks in the system and locks out other systems. The reserve actually occurs when the first I/O is done to the device after the RESERVE macro is issued. When the reserving program no longer needs the reserved device, it should issue a DEQ macro to release the resource. For information about the synchronous reserve feature, see
z/OS MVS Planning: Global Resource Serialization and z/OS MVS Initialization and
Tuning Guide.
For information about how to obtain the UCB address for a device, see the section
“Accessing Unit Control Blocks (UCBs)” in z/OS MVS Programming: Assembler
Services Guide for information about using the UCBSCAN macro.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state with any PSW key.
Task
For LINKAGE=SVC: PASN=HASN=SASN
For LINKAGE=SYSTEM: PASN=HASN=SASN or
PASN¬=HASN¬=SASN
24- or 31- or 64-bit
Primary
Enabled for I/O and external interrupts
No locks held
If the caller's AMODE is 24-bit, all parameters must reside below 16 megabytes.
Programming requirements
None.
Restrictions
If a task issues two RESERVE macros for the same device without an intervening
DEQ macro, an abnormal termination results unless the second RESERVE specifies the keyword parameter RET. (If a restart occurs after the caller successfully issued the RESERVE macro for a resource, the system does not reserve the device again; the caller must reissue the RESERVE macro.) If a DEQ macro is not issued for a particular resource, the system releases the reserved resource when the task ends.
The system counts and limits the number of concurrent resource requests in an address space. If an unconditional RESERVE (a RESERVE macro with RET=NONE) causes the number of global resource serialization requests to exceed the limit, the
© Copyright IBM Corp. 1988, 2017
871
RESERVE macro
Syntax
caller is abnormally terminated with a system code of X'538'. For further information about limiting concurrent requests for resources, see in z/OS MVS
Programming: Assembler Services Guide.
Input register information
Before issuing the RESERVE macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
One of the following: v If you specify RET=TEST, RET=USE, or RET=HAVE: If all return codes for the resources named in the RESERVE macro are 0, register 15 contains 0. If any of the return codes are not 0, register 15 contains the address of a storage area containing the return codes.
v Otherwise: used as a work register by the system.
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Syntax
The standard form of the RESERVE macro is written as follows:
Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede RESERVE.
RESERVE
� One or more blanks must follow RESERVE.
872
z/OS MVS Assembler Services Reference IAR-XCT
RESERVE macro
Syntax
,
,E
,S
qname addr
,rname addr
,
,rname length
)
,SYSTEMS
,RET=TEST
,RET=USE
,RET=HAVE
,RET=NONE
,UCB=ucb addr
,LOC=BELOW
,LOC=ANY
,RELATED=value
,LINKAGE=SVC
,LINKAGE=SYSTEM
Description
qname addr: A-type address, or register (2) - (12).
rname addr: A-type address, or register (2) - (12).
Default:
E
rname length: symbol, decimal digit, or register (2) - (12).
ucb addr: A-type address, or register (2) - (12).
Default:
LOC=BELOW
value: any valid macro keyword specification.
DEFAULT
: LINKAGE=SVC
Parameters
The parameters are explained as follows:
(
Specifies the beginning of the resource description.
qname addr
Specifies the address in virtual storage of an 8-character name. The name should not start with SYS, so that it will not conflict with system names. Every task issuing RESERVE against the same resource must use the same qname and rname to represent the resource.
Chapter 86. RESERVE — Reserve a device (shared DASD)
873
RESERVE macro
,rname addr
Specifies the address in virtual storage of the name used together with qname to represent a single resource. The name can be qualified, and must be from 1 to 255 bytes long.
,
,E
,S
Specifies whether the request is for exclusive (E) or shared (S) control of the resource. If the resource is modified while under control of the task, the request must be for exclusive control; if the resource is not modified, the request should be for shared control.
,
,rname length
Specifies the length of the rname. If this parameter is omitted, the system uses the assembled length of the rname. To override the assembled length, specify this parameter; the value you can code depends on whether or not you also specify MASID and MTCB: v If you specify MASID and MTCB, you can code a value between 1 and 128.
v If you do not specify MASID and MTCB, you can code a value between 1 and 255.
In either case, you can specify 0, which means that the length of the rname must be contained in the first byte at the rname addr.
,SYSTEMS
Specifies that the resource is shared among systems.
)
Specifies the end of the resource description.
,RET=TEST
,RET=USE
,RET=HAVE
,RET=NONE
RET=TEST, RET=USE, and RET=HAVE specify a conditional request for the resource named on the macro, as follows:
RET=TEST
The availability of the resource is to be tested, but control of the resource is not requested.
RET=USE
Control of the resource is to be assigned to the active task only if the resource is immediately available.
RET=HAVE
Control of the resource is requested only if the same task does not already control or have an outstanding request for the same resource.
RET=NONE specifies an unconditional request for the resource named on the macro.
,UCB=ucb addr
Specifies the address of a fullword that contains the address of the UCB for the device to be reserved. The UCB must be allocated to the job step before
RESERVE is issued.
Note:
The UCB keyword might specify a UCB address for a UCB that resides in storage above or below 16 megabytes. If the UCB address might point to a
UCB above 16 megabytes you must also specify LOC=ANY.
874
z/OS MVS Assembler Services Reference IAR-XCT
RESERVE macro
,LOC=BELOW
,LOC=ANY
Specifies the location of the input UCB address. ANY specifies that the input
UCB address is to be treated as a 31-bit address. BELOW specifies that the input UCB address is to be treated as a 24-bit address. The default is
LOC=BELOW.
,RELATED=value
Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and may be any valid values.
,LINKAGE=SVC
,LINKAGE=SYSTEM
Specifies the type of linkage the caller is using to invoke the RESERVE service.
For LINKAGE=SVC, the linkage is through an SVC instruction. This linkage is valid only when the caller is in primary mode and the primary, home, and secondary address spaces are the same.
For LINKAGE=SYSTEM, the linkage uses a non-SVC entry. This linkage is valid in cross memory mode or in non-cross memory mode.
LINKAGE=SYSTEM is intended to be used by programs in cross memory mode.
v If ECB= is specified, the ECB (not the address of the ECB) must be addressable from the home address space.
The default is LINKAGE=SVC.
ABEND codes
For unconditional requests only, the caller might encounter abend code X'138' or
X'538'. For unconditional or conditional requests, the caller might encounter one of the following abend codes: v X'238' v X'338' v X'438' v X'738' v X'838' v X'938'
See z/OS MVS System Codes for explanations and responses for these codes.
Return and reason codes
The system provides return codes only if you specify RET=TEST, RET=USE, or
RET=HAVE; for RET=NONE, return to the task indicates that control of the resource has been assigned to the task. If the return code for the resource named in the RESERVE macro is 0, register 15 contains 0. If the return code is not 0, register
15 contains the address of a 12-byte storage area containing the return code, as
shown in Figure 4 on page 876.
Chapter 86. RESERVE — Reserve a device (shared DASD)
875
RESERVE macro
Address
Returned in
Register 15
0
1 2 3 4 12
BYTE 0
BYTE 1
BYTE 2
Return
Code
12
Figure 4. Return Code Area Used by RESERVE
The return codes for the RESERVE macro with the RET=TEST parameter are
Table 48. Return Codes for the RESERVE Macro with the RET=TEST Parameter
Hexadecimal
Return Code
0
Meaning and Action
Meaning
: The resource is immediately available.
4
8
14
Action
: None required. However, you might take some action based on your application.
Meaning
: The resource is not immediately available or There might be contention on the reservethe hardware reserve is done synchronously.
There might be contention on the reserve.
Action
: None required. However, you might take some action based on your application.
Meaning
: A previous request for control of the same resource has been made for the same task. The task has control of the resource.
Action
: None required. However, you might take some action based on your application.
To determine whether the task has exclusive control or shared control
of the resource, check bit 3 of Byte 0 as shown in Figure 4. If bit 3 is off,
the task has exclusive control; If bit 3 is on, the task has shared control.
Meaning
: A previous request for control of the same resource has been made for the same task. The task does not have control of the resource.
Action
: None required. However, you might take some action based on your application.
The return codes for the RESERVE macro with the RET=USE parameter are
Table 49. Return Codes for the RESERVE Macro with the RET=USE Parameter
Hexadecimal
Return Code
0
Meaning and Action
Meaning
: The active task now has control of the resource.
Action
: None.
876
z/OS MVS Assembler Services Reference IAR-XCT
RESERVE macro
Table 49. Return Codes for the RESERVE Macro with the RET=USE Parameter (continued)
Hexadecimal
Return Code
4
Meaning and Action
Meaning
: The resource is not immediately available.
8
Action
: None required. However, you might take some action based on your application.
Meaning
: A previous request for control of the same resource has been made for the same task. The task has control of the resource.
Action
: None required. However, you might take some action based on your application.
14
18
To determine whether the task has exclusive control or shared control
of the resource, check bit 3 of Byte 0 as shown in Figure 4 on page 876.
If bit 3 is off, the task has exclusive control; If bit 3 is on, the task has shared control.
Meaning
: A previous request for control of the same resource has been made for the same task. The task does not have control of the resource.
Action
: None required. However, you might take some action based on your application.
Meaning
: Environmental error. The limit for the number of concurrent resource requests has been reached. The task does not have control of the resource unless some previous ENQ or RESERVE request caused the task to obtain control of the resource.
Action
: Retry the request one or more times. If the problem persists, consult your system programmer, who might be able to tune the system so that the limit is no longer exceeded.
The return codes for the RESERVE macro with the RET=HAVE parameter are
Table 50. Return Codes for the RESERVE Macro with the RET=HAVE Parameter
Hexadecimal
Return Code
0
Meaning and Action
Meaning
: The active task now has control of the resource.
8
Action
: None.
Meaning
: A previous request for control of the same resource has been made for the same task. The task has control of the resource.
Action
: None required. However, you might take some action based on your application.
14
To determine whether the task has exclusive control or shared control of the
resource, check bit 3 of Byte 0 as shown in Figure 4 on page 876. If bit 3 is off,
the task has exclusive control; If bit 3 is on, the task has shared control.
Meaning
: A previous request for control of the same resource has been made for the same task. The task does not have control of the resource.
Action
: None required. However, you might take some action based on your application.
Chapter 86. RESERVE — Reserve a device (shared DASD)
877
RESERVE macro
Table 50. Return Codes for the RESERVE Macro with the RET=HAVE
Parameter (continued)
Meaning and Action Hexadecimal
Return Code
18
Meaning
: Environmental error. The limit for the number of concurrent resource requests has been reached. The task does not have control of the resource unless some previous ENQ or RESERVE request caused the task to obtain control of the resource.
Action
: Retry the request one or more times. If the problem persists, consult your system programmer, who might be able to tune the system so that the limit is no longer exceeded.
Example
Unconditionally reserve exclusive control of a device. The length of the rname is allowed to default.
RESERVE (MAJOR3,MINOR3,E,,SYSTEMS),UCB=(R3)
RESERVE—List form
The list form of the RESERVE macro is written as follows:
Syntax Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede RESERVE.
RESERVE
� One or more blanks must follow RESERVE.
(
,
,E
,S
qname addr
,
,rname addr
,
,
,rname length
qname addr: A-type address.
rname addr: A-type address.
rname length: symbol or decimal digit.
878
z/OS MVS Assembler Services Reference IAR-XCT
RESERVE macro
)
Syntax
,SYSTEMS
,RET=TEST
,RET=USE
,RET=HAVE
,RET=NONE
,UCB=ucb addr
,LOC=BELOW
,LOC=ANY
,RELATED=value
,MF=L
Description
ucb addr: A-type address or 0.
Default:
LOC=BELOW
value: A-type address.
Parameters
The parameters are explained under the standard form of the RESERVE macro, with the following exception:
,MF=L
Specifies the list form of the RESERVE macro.
RESERVE - Execute form
The execute form of the RESERVE macro is written as follows:
Syntax Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede RESERVE.
RESERVE
�
(
One or more blanks must follow RESERVE.
Note:
( and ) are the beginning and end of a parameter list. The entire list is optional. If nothing in the list is desired, the (, ), and all parameters between
( and ) should not be specified. If something in the list is desired, then (, ), and all parameters in the list should be specified as indicated at the left.
Chapter 86. RESERVE — Reserve a device (shared DASD)
879
RESERVE macro
Syntax
qname addr
,
,rname addr
,
,E
,S
,
,rname length
)
,
,SYSTEMS
,RET=TEST
,RET=USE
,RET=HAVE
,RET=NONE
,UCB=ucb addr
,LOC=BELOW
,LOC=ANY
,RELATED=value
,LINKAGE=SVC
,LINKAGE=SYSTEM
,MF=(E, list addr)
Description
qname addr: RX-type address, or register (2) - (12).
rname addr: RX-type address, or register (2) - (12).
rname length: symbol, decimal digit, or register (2) - (12).
Note:
rname length must be coded if a register is specified for rname addr above.
ucb addr: RX-type address, or register (2) - (12).
Default:
LOC=BELOW
value: any valid macro keyword specification.
DEFAULT
: LINKAGE=SVC
list addr: RX-type address, or register (1) - (12).
Parameters
The parameters are explained under the standard form of the RESERVE macro, with the following exception:
880
z/OS MVS Assembler Services Reference IAR-XCT
RESERVE macro
,MF=(E,ctrl addr)
Specifies the execute form of the RESERVE macro.
list addr specifies the area that the system uses to contain the parameters.
Chapter 86. RESERVE — Reserve a device (shared DASD)
881
RESERVE macro
882
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 87. RETURN — Return control
Description
Syntax
The RETURN macro restores the control to the calling program and signals normal termination of the called program. The return of control is always made by executing a branch instruction using the address in register 14. Because the
RETURN macro uses a BR 14 to pass control, it can be used only when the return is to a program that executes in the same addressing mode. The RETURN macro can restore a designated range of registers, provide a return code in register 15, and flag the save area used by the called program.
If registers are to be restored, or if an indicator is to be placed into the save area, register 13 must contain the address of the save area, which must have the standard format.
Syntax
The RETURN macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede RETURN.
RETURN
�
(reg1)
(reg1,reg2)
,T
,RC=ret code
One or more blanks must follow RETURN.
reg1 and reg2: Decimal digits, and in the order 14, 15, 0 through 12.
ret code: Decimal digit, symbol, or register (15). The maximum value is 4095.
Parameters
The parameters are explained as follows:
(reg1)
(reg1,reg2)
Specifies the register or range of registers to be restored from the save area pointed to by the address in register 13. If you omit this parameter, the contents of the registers are not altered. Do not code this parameter when returning control from a program interruption exit routine.
© Copyright IBM Corp. 1988, 2017
883
RETURN macro
,T
Causes the control program to flag the save area used by the called program.
The low-order bit of word 4 of the save area is set to 1 after the registers have been loaded; this designates that a called program has executed a return to its caller. Do not specify this parameter when returning control from an exit routine.
,RC=ret code
Specifies the return code to be passed to the calling program. If a symbol or decimal digit is coded, the return code is placed right-adjusted in register 15 before return is made; if register 15 is coded, the return code has been previously loaded into register 15 and the contents of register 15 are not altered or restored from the save area. (If you omit this parameter, the contents of register 15 are determined by the reg1 and reg2 parameters.)
Note:
If register 15 is coded and a return code greater than 4095 (decimal) is passed, the results could be either an invalid return code in the message or invalid RC testing.
Example
Restore registers 14-12, flag the save area, and return with a code of 0.
RETURN (14,12),T,RC=0
884
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 88. SAVE — Save register contents
Description
Syntax
The SAVE macro stores the contents of the specified general purpose registers in the save area at the address contained in register 13. If you wish, you may specify an entry point identifier. Write the SAVE macro only at the entry point of a program because the code resulting from the macro expansion requires that register 15 contain the address of the SAVE macro prior to its execution. Do not use the SAVE macro in a program interruption exit routine.
Syntax
The SAVE macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede SAVE.
SAVE
�
(reg1)
(reg1,reg2)
One or more blanks must follow SAVE.
reg1 and reg2: Decimal digits, and in the order 14, 15, 0 through 12.
,
,T
,id name
id name: Character string of up to 70 characters or as an *.
Parameters
The parameters are explained as follows:
(reg1)
(reg1,reg2)
Specifies the register or range of registers to be stored in the save area at the address contained in register 13. The registers are stored in words 4 through 18 of the save area.
,
,T
Specifies that registers 14 and 15 are to be stored in word 4 and 5, respectively, of the save area. This parameter permits you to save two noncontiguous sets of registers.
© Copyright IBM Corp. 1988, 2017
885
SAVE macro
If you specify both T and reg2, and reg1 is any of registers 14, 15, 0, 1, or 2, all of registers 14 through the reg2 value are saved.
,id name
Specifies an identifier to be associated with the SAVE macro. If an asterisk (*) is coded, the identifier is the name associated with the SAVE macro, or, if the
name field is blank, the control section name is used. The identifier aids in locating a program's save area in a dump. If the CSECT instruction name field is blank, the parameter is ignored.
Whenever a symbol or an asterisk is coded, the following macro expansion occurs: v A count byte containing the number of characters in the identifier name is assembled four bytes following the address contained in register 15.
v The character string containing the identifier name is assembled starting at five bytes following the address contained in register 15.
v An instruction to branch around the count and identifier fields is assembled.
Example
Save registers 14-12, and associate the identifier with the CSECT name.
SAVE (14,12),,*
886
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 89. SETRP — Set return parameters
Description
Use the SETRP macro within a recovery routine to indicate the various requests that the recovery routine can make. SETRP is valid for ESTAE-type recovery routines. For more information about recovery routines, see z/OS MVS
Programming: Assembler Services Guide.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task or SRB
Any PASN, any HASN, any SASN
24- or 31- or 64-bit
Primary, secondary, or access register (AR)
Note:
Callers in secondary ASC mode cannot specify the
DUMPOPX parameter.
Enabled or disabled for I/O and external interrupts
The caller may hold locks, but is not required to hold any.
None
Programming requirements
v If the program is in AR mode, issue the SYSSTATE ASCENV=AR macro before issuing SETRP. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.
v Include the IHASDWA mapping macro to map the system diagnostic work area
(SDWA). (See SDWA in z/OS MVS Data Areas in the z/OS Internet library
(www.ibm.com/systems/z/os/zos/library/bkserv) for the mapping provided by IHASDWA.) v If you plan to specify RETREGS=YES, RUB=reg info addr, you must obtain storage for and initialize the register update block (RUB). See the RETREGS parameter description for more information about this area.
Restrictions
v You can use SETRP only if the system provided an SDWA.
v Recovery routines established through the STAE macro, or the STAI parameter on the ATTACH or ATTACHX macro, cannot update registers on retry, so the
RETREGS parameter does not apply.
Input register information
Before issuing the SETRP macro, the caller must ensure that the following general purpose register (GPRs) contain the specified information:
Register
Contents
© Copyright IBM Corp. 1988, 2017
887
SETRP macro
1
13
If you do not specify the WKAREA parameter, address of the SDWA; otherwise, the caller does not have to place any information into this register.
If you specify the REGS parameter, address of a standard 72-byte save area containing the registers to be restored; otherwise, the caller does not have to place any information into this register.
Before issuing the SETRP macro, the caller must ensure that the following access registers (ARs) contain the specified information:
Register
Contents
1
If you do not specify the WKAREA parameter, ALET of the SDWA whose address is in GPR 1; otherwise, the caller does not have to place any information into this register.
13
If you specify the REGS parameter, ALET of the standard 72-byte save area whose address is in GPR 13; otherwise, the caller does not have to place any information into this register.
Output register information
Note:
Control does not return to the caller if the caller specifies the REGS parameter.
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
888
z/OS MVS Assembler Services Reference IAR-XCT
SETRP macro
�
Syntax
name
Syntax
The SETRP macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede SETRP.
SETRP
�
,WKAREA=(reg)
,REGS=(reg1)
,REGS=(reg1,reg2)
One or more blanks must follow SETRP.
reg: Decimal digits 1-12.
Default
: WKAREA=(1)
reg1: Decimal digits 0-12, 14, 15.
reg2: Decimal digits 0-12, 14, 15.
Note
: If you specify (reg1,reg2), specify the registers in the same order as in an STM instruction; for example, to restore all registers except register 13, specify REGS=(14,12).
Default
: DUMP=IGNORE ,DUMP=IGNORE
,DUMP=YES
,DUMP=NO
,DUMPOPT=parm list addr
,DUMPOPX=parm list addr
,REASON=code
parm list addr: RX-type address, or register (2) - (12).
Note
: Appropriate only with DUMP=YES.
code: Any four-byte number specified in decimal (31-bit) or hexadecimal
(32-bit).
Default
: RC=0 ,RC=0
,RC=4
,RC=16
,RETADDR=retry addr retry addr: RX-type address, or register (2) - (12).
Note
: This parameter may be specified only if RC=4 is specified above.
Default
: REMREC=NO ,REMREC=NO
,REMREC=YES
,RETREGS=NO
,RETREGS=YES
reg info addr: RX-type address, or register (2) - (12).
Default
: RETREGS=NO
Chapter 89. SETRP — Set return parameters
889
SETRP macro
Syntax
,RETREGS=YES,RUB=reg
info addr
,RETREGS=64
,FRESDWA=NO
,FRESDWA=YES
,COMPCOD=comp code
,COMPCOD=(comp
code,USER)
,COMPCOD=(comp
code,SYSTEM)
,RECPARM=record list addr
,RETRYAMODE=amode
Description
Note
: This parameter may be specified only if RC=4 is specified above.
Default
: FRESDWA=NO
Note
: This parameter may be specified only if RC=4 is specified above.
comp code: Symbol, decimal digit, or register (2) - (12).
Default
: COMPCOD=(comp code,USER)
record list addr: RX=type address, or register (2) - (12).
amode: decimal 24, 31, or 64. Only honored for ESTAE, ESTAI, ESTAEX, and
IEAARR recovery routines.
Parameters
The parameters are explained as follows:
,WKAREA=(reg)
Specifies the address of the SDWA passed to the recovery routine.
,REGS=(reg1)
,REGS=(reg1,reg2)
Specifies the register or range of registers to be restored from the 72-byte standard save area pointed to by the address in register 13. If you specify
REGS, a branch on register 14 instruction will also be generated to return control to the system. If you do not specify REGS, you must code your own branch on whichever register contains the return address.
Note:
If you specify reg1,reg2, specify the registers in the same order as in an
STM instruction; for example, to restore all registers except register 13, specify
REGS=(14,12).
,DUMP=IGNORE
,DUMP=YES
,DUMP=NO
Specifies that the dump option fields will not be changed (IGNORE), will be zeroed (NO), or will be merged with dump options specified in previous dump requests, if any (YES). If IGNORE is specified, a previous recovery routine had requested a dump or a dump had been requested through the
ABEND macro, and the previous request will remain intact. If NO is specified, no dump will be taken.
DUMP=YES does not guarantee that a SYSABEND/SYSUDUMP will be taken.
You may specify this request in an FRR for an SRB but you will get an abdump only if the SRB abend successfully percolates to a task and none of the
890
z/OS MVS Assembler Services Reference IAR-XCT
SETRP macro
FRRs for that task choose to retry and the final value of the DUMP= remains the same after every recovery routine has received control.
,DUMPOPT=parm list addr
,DUMPOPX=parm list addr
Specifies the address of a parameter list of options. To create the parameter list, use the list form of either the SNAP or SNAPX macro, or code data constants in your program. DUMPOPT specifies the address of a parameter list that the
SNAP macro creates. DUMPOPX specifies the address of a parameter list that the SNAPX macro creates. A program in secondary mode cannot use the
DUMPOPX parameter.
If the specified dump options include subpools for storage areas to be dumped, up to seven subpools can be dumped. Subpool areas are accumulated and wrapped, so that the eighth subpool area specified replaces the first.
If the dump options specified include ranges of storage areas to be dumped, only the storage areas in the first thirty ranges will be dumped.
The TCB, DCB, ID, and STRHDR options available on SNAP or SNAPX are ignored if they appear in the parameter list. The TCB used is the one for the task that encountered the error. The DCB used is one created by the system, and either SYSABEND, SYSMDUMP, or SYSUDUMP is used as a DDNAME.
,REASON=code
Specifies the reason code that the user wishes to pass to subsequent recovery routines.
,RC=0
,RC=4
,RC=16
Specifies the return code the recovery routine sends to recovery processing to indicate what further action is required:
0
Continue with error processing, causes entry into previously specified recovery routine, if any.
Retry using the retry address specified.
4
16
Valid only for an ESTAI/STAI recovery routine. The system should not give control to any further ESTAI/STAI routines, and should abnormally end the task.
,RETADDR=retry addr
Specifies the address of the retry routine to which control is to be given.
,REMREC=YES
,REMREC=NO
In an ESTAE environment, specifies that the ESTAE entry for the currently running ESTAE routine be removed (REMREC=YES) or not removed
(REMREC=NO). This parameter may be specified only when RC=4 is specified, indicating a retry request.
The entry is removed before control returns to the retry point. If REMREC=YES is not coded on any SETRP invocation before the system receives control, the effect is that of specifying REMREC=NO. The REMREC parameter may be used to remove a recovery routine that has been established with a token, although the token cannot be specified when you code the SETRP macro.
,RETREGS=NO
,RETREGS=YES
,RETREGS=YES,RUB=reg info addr
Chapter 89. SETRP — Set return parameters
891
SETRP macro
,RETREGS=64
Specifies the contents of the registers to be restored on entry to the retry routine. RETREGS=NO indicates that you do not want the system to restore any register contents from the SDWA.
If you specify RETREGS=YES, in a recovery routine defined through the
ESTAE or ESTAEX macro, the ESTAI parameter on the ATTACH or ATTACHX macro, or an associated recovery routine (ARR), the system does the following: v Initializes GPRs 0-15 from the SDWASRSV field of the SDWA v Initializes ARs 0-15 from the SDWAARSV field of the SDWA.
Specifying RETREGS=64 is the same as specifying RETREGS=YES, except the registers for retry are the 64-bit general purpose registers in field SDWAG64.
RUB (register update block) specifies the address of an area that contains register update information for the GPRs. The data you specify in this area will be moved into the SDWASRSV field of the SDWA and will be loaded into the
GPRs on entry to the retry routine. You cannot use the RUB to specify data to be moved into the SDWAARSV field for loading the ARs. The maximum length of the RUB is 66 bytes. You must acquire storage for and initialize this area as follows: v The first two bytes represent the registers to be updated, register 0 corresponding to bit 0, register 1 corresponding to bit 1, and so on. The user indicates which of the registers are to be stored in the SDWA by setting the corresponding bits in these two bytes.
v The remaining 64 bytes contain the update information for the registers, in the order 0-15. If all 16 registers are being updated, this field consists of 64 bytes. If only one register is being updated, this field consists of only 4 bytes for that one register.
For example, if only registers 4, 6, and 9 are being updated: v Bits 4, 6, and 9 of the first two bytes are set.
v The remaining field consists of 12 bytes for registers 4, 6, and 9; the first 4 bytes are for register 4, followed by 4 bytes for register 6, and 4 final bytes for register 9.
,FRESDWA=NO
,FRESDWA=YES
Specifies that the entire SDWA be freed (YES) or not be freed (NO) prior to entry into the retry routine.
,COMPCOD=comp code
,COMPCOD=(comp code,USER)
,COMPCOD=(comp code,SYSTEM)
Specifies the user or system completion code that the user wishes to pass to subsequent recovery routines.
,RECPARM=record list addr
Specifies the address of a user-supplied record parameter list used to update the SDWA with recording information. The parameter list consists of three
8-byte fields: v The first field contains the load module name.
v The second field contains the CSECT name (assembly module name).
v
The third field contains the recovery routine name (assembly module name).
If the recovery routine label is not the same as the assembly module name, the label can be used.
The three fields are left-justified, and padded with blanks.
892
z/OS MVS Assembler Services Reference IAR-XCT
SETRP macro
,RETRYAMODE=amode
Specifies an explicit AMODE in which a retry routine receives control. Valid values are 24, 31, and 64. This parameter is only honored for ESTAE, ESTAI,
ESTAEX, and IEARR recovery routines. If you do not specify this parameter,
RTM selects an AMODE as described in Providing recovery in z/OS MVS
Programming: Assembler Services Guide.
ABEND codes
None.
Return and reason codes
None.
Example 1
Request to continue terminating, suppress dumping, restore register 14 from the save area, and pass control to the location it contains, contain the SDWA in the location addressed by register 3, and change the completion code to 10.
SETRP RC=0,DUMP=NO,REGS=(14),WKAREA=(3),
COMPCOD=(X’00A’,USER)
X
Example 2
Retry using address X, take a dump before retry, use the contents of SDWASRSV to initialize the registers, free the SDWA before control is passed to the retry address, and restore registers 14-12.
SETRP RC=4,RETREGS=YES,DUMP=YES,FRESDWA=YES,
REGS=(14,12),RETADDR=X
X
Chapter 89. SETRP — Set return parameters
893
SETRP macro
894
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 90. SNAP and SNAPX — Dump virtual storage and continue
Description
You can use the SNAP macro to obtain a dump of some or all of the storage assigned to the current job step. You can also dump some or all of the control program fields. The SNAP macro causes the specified storage to be displayed in the addressing mode of the caller.
Descriptions of the SNAP and SNAPX macros in this information are: v
The standard form of the SNAP macro, which includes general information about the SNAP and SNAPX macros, with some specific information about
SNAP. The topic also describes the syntax of the SNAP macro and explains the
SNAP macro parameters.
v The standard form of the SNAPX macro, which presents specific information about the SNAPX macro. The topic describes the syntax of the SNAPX macro and explains the parameters that are valid only on the SNAPX macro.
v The list form of the SNAP and SNAPX macros.
v The execute form of the SNAP and SNAPX macros.
There are three ways to obtain a dump:
1.
Spool the dump by specifying SYSOUT=x on the DD statement. The dump is printed without a separate job but is deferred until after the job ends.
2.
Select a tape or direct access device. This method requires a separate job step to print the dump. This method might be used if the dump is to be printed more than once.
3.
Select a printer on the DD statement. This method is almost never used because the printer cannot be used by anyone else for the duration of the job step.
Both NUC and ALLVNUC are valid. Only ALLVNUC gives you the whole virtual nucleus. For more information about the SNAP macro, see z/OS MVS Programming:
Assembler Services Guide.
Note:
The SNAP and SNAPX macros have the same environment specifications, register information, programming requirements, restrictions and limitations, performance implications, and return codes described below. However, IBM
recommends
that programs in access register (AR) address space control (ASC) mode use SNAPX. All parameters on SNAP are valid on SNAPX.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
24- or 31-bit
© Copyright IBM Corp. 1988, 2017
895
SNAP and SNAPX macros
Environmental factor
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Primary or AR
Note:
If your program is in AR mode and you issue SNAP rather than SNAPX following SYSSTATE ASCENV=AR, the system substitutes the SNAPX macro and issues a message telling you that it made the substitution.
Enabled for I/O and external interrupts
No locks held, and no enabled, unlocked task (EUT) FRRs established
Must be in the primary address space
Input register information
Before issuing the SNAP(X) macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-14
15
Used as work registers by the system
Unchanged
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after regaining control.
Programming requirements
Before you issue the SNAP macro, you must open the DCB that you designate on the DCB parameter, and ensure that the DCB is not closed until the SNAP macro returns control. To open the DCB, issue the DCB macro with the following parameters, and issue an OPEN macro for the data set (the DCB and OPEN macros are described in MVS/DFP Macro Instructions for Data Sets):
DSORG=PS,RECFM=VBA,MACRF=(W),BLKSIZE=nnn,LRECL=xxx, and DDNAME=any name but SYSABEND, SYSMDUMP or SYSUDUMP
If the DD name for the SNAP dump has the XTIOT, UCB nocapture, or
DSAB-above-the-line options of dynamic allocation, your DCB must point to a
DCBE before you open the DCB. The DCBE must have the LOC=ANY option. You can code that even if the DD name does not have any of these dynamic allocation options. To point the DCB to the DCBE, code the DCBE operand on the DCB
896
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
⌂
Syntax
name
SNAP and SNAPX macros
macro, or store into the DCBDCBE field if you also turn on the DCBH0 and
DCBH1 bits. The DCBE can reside above the 16 MB line even if your program runs in 24-bit.
In order for the OPEN for the DCB to succeed, it is necessary for the
NON_VSAM_XTIOT=YES option in the DEVSUPxx member of PARMLIB to be active.
For dynamic allocation, XTIOT option bit is S99TIOTEX, the UCB nocapture option bit is S99ACUCB, and the DSAB-above-the-line option bit is S99DSABA. These options are defined by the IEFZB4D0 macro. For more information about the
XTIOT option for dynamic allocation of the dump data set, see S99PARMS programming interface in z/OS MVS Data Areas in the z/OS Internet library
(www.ibm.com/systems/z/os/zos/library/bkserv).
If a standard dump of 120 characters per line is requested, BLKSIZE must be either
882 or 1632, and LRECL must be 125. A high-density dump printed on a 3800
Printing Subsystem has 204 characters per line. To obtain a high-density dump, you must code CHARS=DUMP on the DD statement describing the dump data set.
The BLKSIZE= must be either 1470 or 2724, and the LRECL= must be 209. You can also code CHARS=DUMP on the DD statement describing a dump data set that will not be printed immediately. If you specify CHARS=DUMP and the output device is not a 3800, print lines are truncated and print data is lost. If you open a
SNAP data set in a problem program that will be processed by the system loader, your problem program must close the data set.
The DCB and TCB must reside in 24-bit addressable storage. All other parameters can reside above 16 megabytes if the issuer is executing in 31-bit addressing mode.
If the program is in AR mode, issue SNAPX rather than SNAP; issue the
SYSSTATE ASCENV=AR macro before SNAPX. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.
Note:
The SNAP and SNAPX parameters cannot be updated using the
CHNGDUMP command. Only ABDUMP,SYSMDUMP, SYSUDUMP and SVC
DUMP parameters can be altered using CHNGDUMP.
Restrictions
None.
Performance implications
None.
Syntax
The standard form of the SNAP macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede SNAP.
Chapter 90. SNAP and SNAPX — Dump virtual storage and continue
897
SNAP and SNAPX macros
Syntax
SNAP
⌂
DCB=dcb addr
,TCB=tcb addr
,ID=id nmbr
Description
One or more blanks must follow SNAP.
dcb addr: A-type address, or register (2) - (12).
tcb addr: A-type address, or register (2) - (12).
id nmbr: Symbol, decimal digit, or register (2) - (12).
Value range
: 0-255
,SDATA=ALL
,SDATA=(sys data code)
sys data code: Any combination of the following, separated by commas. If you specify only one code, you do not need the parentheses.
NUC
SQA
LSQA
PCDATA
SWA
CB
Q
TRT
DM
ERR
IO
ALLVNUC
SUM
,PDATA=ALL
,PDATA=(prob data code)
,STORAGE=(strt addr,end
addr)
,LIST=list addr
,STRHDR=(hdr addr)
,STRHDR=hdr list addr
prob data code: Any combination of the following, separated by commas. If you specify only one code, you do not need the parentheses.
PSW
REGS
SA or SAH
JPA or LPA or ALLPA
SPLS
SUBTASKS
strt addr: A-type address, or register (2) - (12).
end addr: A-type address, or register (2) - (12).
list addr: A-type address, or register (2) - (12).
Note
: One or more pairs of addresses may be specified, separated by commas. For example: STORAGE=(strt addr,end addr, strt addr,end addr)
hdr addr: A-type address, or register (2) - (12).
Note
: hdr addr is one or more addresses separated by commas. If you specify only one header address as an A-type address, you do not need the parentheses. If you specify one or more registers, then you must code double parentheses (one set enclosing each register and one set enclosing the list of registers). If STRHDR=(hdr addr) is specified, then STORAGE must also be specified.
hdr list addr: A-type address, or register (2) - (12).
Note
: If STRHDR=hdr list addr is specified, then LIST must also be specified.
898
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,SUBPLST=sbp list addr
SNAP and SNAPX macros
Description
sbp list addr: A-type address, or register (2) - (12).
Parameters
The parameters are explained as follows:
DCB=dcb addr
Specifies the address of a previously opened data control block for the data set that is to contain the dump.
Note:
1.
DCB must reside in 24-bit addressable storage.
2.
The DCB parameter is not required when you issue the list form of SNAP or SNAPX to format a parameter list for the DUMPOPT/DUMPOPX parameter of the ABEND, CALLRTM, or SETRP macros. If the parameter list you specify on DUMPOPT/DUMPOPX contains a DCB value, the system overrides it. The DCB parameter is required when you issue the list form of SNAP or SNAPX to format a parameter list for an execute form of
SNAP or SNAPX if the execute form does not specify the DCB parameter.
That is, if you specify both a list and execute form of SNAP or SNAPX, you must specify DCB on one or the other.
3.
If the DD name for the SNAP dump has the XTIOT, UCB nocapture, or
DSAB-above-the-line options of dynamic allocation, your DCB must point to a DCBE before you open the DCB. See the "Programming Requirements" section for more details.
,TCB=tcb addr
Specifies the address of a fullword on a fullword boundary containing the address of the task control block for a task of the current job step. If omitted, or if the fullword contains 0, the dump is for the active task. If a register is designated, the register can contain 0 to indicate the active task, or can contain the address of a TCB.
Note:
TCB must reside in 24-bit addressable storage.
,ID=id nmbr
Specifies the number that is to be printed in the identification heading with the dump. If the number specified is not in the acceptable value range, it will not be printed properly in the heading.
,SDATA=ALL
,SDATA=(sys data code)
Specifies the system control program information to be dumped:
ALL
All of the SDATA options except ALLVNUC (The read-only portion of the nucleus is not included in the dump unless ALLVNUC is also specified as an option.)
NUC
The PSA, SQA, LSQA, and the read/write portion of the nucleus (if the entire nucleus is required, specify the ALLVNUC option.)
Note:
The CVT will be included if this option is specified.
SQA
The system queue area (subpools 226, 239, and 245).
LSQA
The local system queue area and subpools 229, 230, and 249.
Chapter 90. SNAP and SNAPX — Dump virtual storage and continue
899
SNAP and SNAPX macros
Note
: Subpools 229, 230, and 249 will be dumped only for the current task.
SWA
The scheduler work area related to the task (subpools 236 and 237).
CB
The control blocks for the task.
Q
The global resource serialization control blocks for the task.
TRT
The GTF trace and system trace data. If system tracing is active and the requestor is authorized, all system trace entries for all address spaces are included in the dump. Unauthorized requestors obtain those system trace entries, after the job-start time stamp in the ASCB, for their current address space. If GTF tracing is active, only the GTF trace entries for the current address space are included in the dump.
DM
Data management control blocks for the task.
ERR
Recovery/termination control blocks for the task. These control blocks summarize information that describes abnormal terminations of the task.
IO
Input/Output supervisor control blocks for the task.
ALLVNUC
The entire virtual nucleus, the PSA, LSQA, and SQA. (The NUC option will not dump the read-only section of the nucleus.) If the SNAP parameter list is used for a SYSMDUMP, the ALLVNUC option is converted to ALLNUC on the SVC dump parameter list.
Note:
The CVT is included if this option is specified.
PCDATA
Program call information for the task.
The SUM option is valid for an abending task or on a list form of the SNAP macro pointed to by the DUMPOPT keyword of the ABEND or SETRP macro.
The option SUM causes the dump to contain a summary dump. If SUM is the only option requested, the dump contains a dump header, control blocks, and the other areas listed below. The header information, which is provided for all
ABEND dumps, consists of the following information: v The dump title v The ABEND code and program status word (PSW) at the time of the error v If the PSW contains the address of an active load module:
– The name and PSW address of the load module in error
– The offset, into the load module, at which the error occurred
The following control blocks and areas are also included in the dump: v The control blocks dumped for the CB option v The error control blocks (RTM2WAs and SCBs) v The save areas v The registers at the time of the error, except for register 1 v The contents of the load module (if the PSW contains the address of an active load module) v
The module pointed to by the last PRB (if it can be found) v 1K of storage before and after the addresses pointed to by the PSW and the registers at the time of the error
900
z/OS MVS Assembler Services Reference IAR-XCT
SNAP and SNAPX macros
Note:
This storage will only be dumped if the caller is authorized to obtain it. The storage is printed by ascending storage addresses with duplicate addresses removed.
v System trace entries after the job-start time stamp in the ASCB for the current address space
Note:
The GTF trace records are not included.
If other options are specified with SUM, the summary dump is dispersed throughout the dump.
,PDATA=ALL
,PDATA=(prob data code)
Specifies the problem program information to be dumped:
ALL
All of the following fields.
PSW
Program status word when the SNAP or ABEND macro was issued.
REGS
Contents of the floating-point registers and general-purpose registers
(except for GPR 1) when the SNAP or ABEND macro was issued. Also, contents of the vector registers, vector status register, and the vector mask register when the SNAP or ABEND macro was issued for any task that uses the Vector Facility.
SA
Save area linkage information, program call linkage information, and a back trace through save areas.
SAH
Save area linkage information and program call linkage information.
JPA
Contents of job pack area.
LPA
Contents of active link pack area for the requested task.
ALLPA
Contents of job pack area and active link pack area for the requested task.
SPLS
Virtual storage subpools 0-127, 131-132, 252.
SUBTASKS
The designated task and the program data information for all of its subtasks.
,STORAGE=(strt addr,end addr)
,LIST=list addr
Specifies one or more pairs of starting and ending addresses or a list of starting and ending addresses of areas to be dumped. Each starting address is rounded down to a fullword boundary; each ending address is rounded up to a fullword boundary. The area is then dumped in fullword increments. Callers executing in either 24-bit or 31-bit addressing mode must set the high-order bit of the fullword containing the last address in this list to 1. Callers executing in
31-bit addressing mode must ensure that this bit is cleared in all other addresses in the list because SNAP processing truncates the list at the first address that contains a 1 in the high order bit.
,STRHDR=(hdr addr)
,STRHDR=hdr list addr
Specifies one or more header addresses or the address of a list of header addresses. Each header address must be the address of a one byte header length field, which is followed by the text of the header. The header has a maximum length of 100 characters.
Chapter 90. SNAP and SNAPX — Dump virtual storage and continue
901
SNAP and SNAPX macros
If the STORAGE parameter was specified, the STRHDR (storage header) value must be one or more header addresses. The number of pairs of starting and ending addresses specified for STORAGE must be the same as the number of header addresses specified for STRHDR. If a header is not desired for a storage area, a comma must be used to indicate its absence.
If the LIST parameter was specified, the STRHDR value must be the address of a list of header addresses. The list of addresses must begin on a fullword boundary, and the high order bit of the fullword containing the last address of the list must be set to 1. The number of pairs of starting and ending addresses supplied with the LIST parameter must be the same as the number of addresses in the list supplied with STRHDR. If a header is not desired for a storage area, the STRHDR list must contain a zero address to indicate its absence.
,SUBPLST=sbp list addr
Specifies the address of a list of subpool numbers to be dumped. Each entry in the list must be a two-byte entry and must specify a valid subpool number.
The first halfword of the list must contain the number of subpools in the list and must be on a fullword boundary. If you specify an invalid subpool number or a subpool number for which you do not have authorization, the number is skipped and you receive a comment in the dump output indicating the error. If a subpool contains 4k blocks of data that are mapped from a linear data set, the dump includes only the blocks that have changed since the last
DIV SAVE function was invoked.
Note:
A maximum of seven subpool numbers is permitted on the list form of the SNAP macro pointed to by the DUMPOPT keyword of ABEND or SETRP.
Return and reason codes
Control is returned to the instruction following the SNAP macro. When control is returned, register 15 contains one of the following return codes:
Meaning Hexadecimal
Code
00
04
08
0C
10
Successful completion.
Data control block was not open, or an invalid page exception occurred during the validity check of the DCB parameters.
Task control block address was not valid, an invalid page reference occurred during the validity check of the TCB address, a subtask is a job step task, sufficient storage was not available, or the READ for JFCB or JFCBE failed. In all cases, the dump is canceled. (Message IEA997I is issued when the READ for JFCB or JFCBE fails.)
Or
, the ALET for SNAP parameter list or the ALETs for areas pointed to by the parameter list are not valid.
Data control block type (DSORG, RECFM, MACRF, BLKSIZE, or
LRECL) was incorrect, or the DCB's BLKSIZE and/or LRECL were not compatible with the dump format options specified on the dump-related DD statement.
DEBCHK TYPE=VERIFY function failed. This may be due to
DEBDCBAD not pointing to the DCB (or ACB) passed to DEBCHK.
902
z/OS MVS Assembler Services Reference IAR-XCT
SNAP and SNAPX macros
Example 1
Dump the storage ranges pointed to by register 9, and dump all PDATA and
SDATA options.
SNAP DCB=(8),TCB=(5),PDATA=ALL,SDATA=ALL,LIST=(9)
Example 2
Dump the storage ranges pointed to by register 9, and dump only the trace table and enqueue control blocks.
SNAP DCB=(8),TCB=(5),ID=4,LIST=(9),SDATA=(TRT,Q)
Example 3
Dump storage area 1000-2000 with no header, and dump storage area 3000-4000 with a header of ‘USER LABEL ONE’. The comma specified in the value for
STRHDR indicates that no header is wanted for storage area 1000-2000.
.
.
SNAP DCB=(8),STORAGE=(1000,2000,3000,4000), X
STRHDR=(,L1)
L1
.
DC
HDR1 DC
AL1(L’HDR1)
C’USER LABEL ONE’
Example 4
Dump storage area 1000-1999 with a header of ‘LABEL ONE’ and dump storage area 3000-3999 with a header of ‘LABEL TWO’.
X
L1
HDR1
HDR1A
HDR2
HDR2A
.
.
SNAP DCB=(8),LIST=X,STRHDR=L1
.
DC A(1000)
DC A(1999)
DC A(3000)
DC X’80’
DC AL3(3999)
DC A(HDR1)
Start address
End address
Start address
End of list indicator
End address
Address of length label for
DC
DC
DC
DC
DC
DC
X’80’
AL3(HDR2)
AL1(L’HDR1A)
C’LABEL ONE’
AL1(L’HDR2A)
C’LABEL TWO’ header one
End of list
Address of length label for header two
Length of header one
Header one
Length of header two
Header two
Example 5
Dump subpool 0, 1, and 2 storage related to the current TCB.
SNAP DCB=XYZ,TCB=0,SUBPLST=SUBADDR
.
.
.
SUBADDR DS OF
DC X’0003’
DC X’0000’
DC X’0001’
DC X’0002’
Fullword boundary
Number of entries in the list
Subpool 0
Subpool 1
Subpool 2
Chapter 90. SNAP and SNAPX — Dump virtual storage and continue
903
SNAP and SNAPX macros
SNAPX — Dump virtual storage and continue
The SNAPX macro performs the same function as SNAP: it enables you to obtain a dump of some or all of the storage assigned to the current job step. SNAPX is intended for use by programs running in access register (AR) mode. Programs running in primary mode can also use SNAPX.
Note:
The SNAPX macro has the same environment specifications, register information, programming requirements, restrictions and limitations, performance implications and return codes as the SNAP macro. However, IBM recommends that programs in AR ASC mode use SNAPX. All parameters on SNAP are valid on
SNAPX.
Syntax
Syntax
The standard form of the SNAPX macro is written as follows:
Description
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede SNAPX.
SNAPX
�
DCB=dcb addr
,TCB=tcb addr
,ID=id nmbr
One or more blanks must follow SNAPX.
dcb addr: A-type address, or register (2) - (12).
tcb addr: A-type address, or register (2) - (12).
id nmbr: Symbol, decimal digit, or register (2) - (12).
Value range
: 0-255
,SDATA=ALL
,SDATA=(sys data code) sys data code: Any combination of the following, separated by commas. If you specify only one code, you do not need the parentheses.
NUC
SQA
LSQA
PCDATA
SWA
CB
Q
TRT
DM
ERR
IO
ALLVNUC
SUM
,PDATA=ALL
,PDATA=(prob data code) prob data code: Any combination of the following, separated by commas. If you specify only one code, you do not need the parentheses.
904
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,STORAGE=(strt addr,end
addr)
,LIST=list addr
,STRHDR=(hdr addr)
,STRHDR=hdr list addr
SNAP and SNAPX macros
Description
PSW
REGS
SA or SAH
JPA or LPA or ALLPA
SPLS
SUBTASKS
strt addr: A-type address, or register (2) - (12).
end addr: A-type address, or register (2) - (12).
list addr: A-type address, or register (2) - (12).
Note
: One or more pairs of addresses may be specified, separated by commas. For example: STORAGE=(strt addr,end addr,strt addr,end addr)
hdr addr: A-type address, or register (2) - (12).
Note
: hdr addr is one or more addresses separated by commas. If you specify only one header address as an A-type address, you do not need the parentheses. If you specify one or more registers, then you must code double parentheses (one set enclosing each register and one set enclosing the list of registers). If you specify STRHDR=(hdr addr), you must also specify STORAGE.
hdr list addr: A-type address, or register (2) - (12).
Note
: If you specify STRHDR=hdr list addr, you must also specify LIST.
sbp list addr: A-type address, or register (2) - (12).
list addr: A-type address or reg (2) - (12).
,SUBPLST=sbp list addr
,DSPSTOR=list addr
Parameters
Parameters for the SNAPX macro are the same as those for the SNAP macro, except for the DSPSTOR parameter, which is valid only on SNAPX. SDATA=SUM has a different function for callers in AR mode. These two parameters are described as follows:
,SDATA=SUM
The SUM option is valid for an abending task or on a list form of the SNAPX macro pointed to by the DUMPOPX parameter of the ABEND or SETRP macro. For the contents of the summary dump, see the description of the
SDATA parameter in the SNAP macro.
,DSPSTOR=list addr
Specifies the address of a list of data space storage areas to be dumped. Use this parameter to dump data that is in a data space.
Each entry in the parameter list you create describes an area to be dumped; the entry must contain a start address, end address, and STOKEN. The list must begin on a fullword boundary, and the high order bit of the fullword containing the last end address in the list must be set to 1. The system dumps storage from any data space to which the caller has authority; it does not dump storage to which the caller does not have authority.
You can specify the DSPSTOR parameter for SNAPX parameter lists that are identified by the DUMPOPX parameter on the ABEND or SETRP macro.
Chapter 90. SNAP and SNAPX — Dump virtual storage and continue
905
SNAP and SNAPX macros
SNAP and SNAPX—List form
Use the list form of the SNAP or SNAPX macro to construct a control program parameter list. You can specify any number of storage addresses using the
STORAGE parameter. Therefore, the number of starting and ending address pairs in the list form of SNAP or SNAPX must be equal to the maximum number of addresses specified in any execute form of the macro, or a DS instruction must immediately follow the list form to allow for the maximum number of addresses.
Syntax
Syntax
The list form of the SNAP or SNAPX macro is written as follows:
Description
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede SNAP or SNAPX.
SNAP
SNAPX
�
DCB=dcb addr
,ID=id nmbr
One or more blanks must follow SNAP or SNAPX.
dcb addr: A-type address.
Note:
The DCB parameter is not required in all cases. See the parameter description for details.
id nmbr: Symbol or decimal digit.
Value range
: 0-255
,SDATA=ALL
,SDATA=(sys data code) sys data code: Any combination of the following, separated by commas. If you specify only one code, you do not need parentheses.
NUC
SQA
LSQA
PCDATA
SWA
CB
Q
TRT
DM
ERR
IO
ALLVNUC
SUM
,PDATA=ALL
,PDATA=(prob data code) prob data code: Any combination of the following, separated by commas. If you specify only one code, you do not need parentheses.
PSW
REGS
SA or SAH
JPA or LPA or ALLPA
SPLS
SUBTASKS
906
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,STORAGE=(strt addr,end
addr)
,LIST=list addr
,STRHDR=(hdr addr)
,STRHDR=hdr list addr
SNAP and SNAPX macros
Description
strt addr: A-type address.
end addr: A-type address.
list addr: A-type address.
Note
: One or more pairs of addresses may be specified, separated by commas. For example:
STORAGE=(strt addr,end addr,strt addr,end addr)
hdr addr: A-type address.
Note
: hdr addr is one or more addresses separated by commas. If you specify only one header address, you do not need the parentheses. If
STRHDR=(hdr addr) is specified, then STORAGE must also be specified.
hdr list addr: A-type address.
Note
: If STRHDR=hdr list addr is specified, then LIST must also be specified.
sbp list addr: A-type address.
list addr: A-type address or register (2) - (12).
,SUBPLST=sbp list addr
,DSPSTOR=list addr
,MF=L
Parameters
The parameters are explained under the standard form of the SNAP and SNAPX macros, with the following exception:
,MF=L
Specifies the list form of the SNAP or SNAPX macro.
SNAP and SNAPX—Execute form
A remote control-program parameter list is referred to and can be modified by the execute form of the SNAP or SNAPX macro.
Syntax
If you code only the DCB, ID, MF, or TCB parameters in the execute form of the macro, the bit settings in the parameter list corresponding to the SDATA, PDATA,
LIST, and STORAGE parameters are not changed. However, if you code the
SDATA, PDATA, or LIST parameters, the bit settings for the coded parameter from the previous request are reset to zero, and only the areas requested in the current macro are dumped.
Syntax
The execute form of the SNAP or SNAPX macro is written as follows:
Description
name
name: Symbol. Begin name in column 1.
Chapter 90. SNAP and SNAPX — Dump virtual storage and continue
907
SNAP and SNAPX macros
Syntax
�
SNAP
SNAPX
�
DCB=dcb addr
Description
One or more blanks must precede SNAP.
One or more blanks must follow SNAP.
dcb addr: RX-type address, or register (2) - (12).
Note:
The DCB parameter is not required in all cases. See the parameter description for details.
tcb addr: RX-type address, or register (2) - (12).
,TCB=tcb addr
,TCB=‘S’
,ID=id nmbr id nmbr: Symbol, decimal digit or register (2) - (12).
Value range
: 0-255
,SDATA=ALL
,SDATA=(sys data code) sys data code: Any combination of the following, separated by commas. If you specify only one code, you do not need parentheses.
NUC
SQA
LSQA
PCDATA
SWA
CB
Q
TRT
DM
ERR
IO
ALLVNUC
SUM
,PDATA=ALL
,PDATA=(prob data code)
,STORAGE=(strt addr,end
addr)
,LIST=list addr
prob data code: Any combination of the following, separated by commas. If you specify only one code, you do not need parentheses.
PSW
REGS
SA or SAH
JPA or LPA or ALLPA
SPLS
SUBTASKS
strt addr: RX-type address, or register (2) - (12).
end addr: RX-type address, or register (2) - (12).
list addr: RX-type address, or register (2) - (12).
Note
: One or more pairs of addresses may be specified, separated by commas. For example:
STORAGE=(strt addr,end addr,strt addr,end addr)
908
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,STRHDR=(hdr addr)
,STRHDR=hdr list addr
SNAP and SNAPX macros
Description
hdr addr: RX-type address, or register (2) - (12).
Note:
hdr addr is one or more addresses separated by commas. If you specify only one header address as an RX-type address, you do not need the parentheses. If you specify one or more registers, then you must code double parentheses (one set enclosing each register and one set enclosing the list of registers). If STRHDR=(hdr addr) is specified, then STORAGE must also be specified.
hdr list addr: RX-type address, or register (2) - (12).
Note:
If STRHDR=hdr list addr is specified, then LIST must also be specified.
sbp list addr: RX-type address, or register (2) - (12).
list addr: A-type address or register (2) - (12).
ctrl addr: RX-type address, or register (1) or (2) - (12).
,SUBPLST=sbp list addr
,DSPSTOR=list addr
,MF=(E,ctrl addr)
Parameters
The parameters are explained under the standard form of the SNAP and SNAPX macros, with the following exceptions:
,TCB=‘S’
Specifies the task control block of the active task.
Note:
TCB=‘S’ causes a dump of the active task if this is the first use of the list form of the SNAP or SNAPX macro or if the TCB specified on a previous execute form of the SNAP or SNAPX macro was the current TCB or TCB=‘S’.
,MF=(E,ctrl addr)
specifies the execute form of the SNAP or SNAPX macro using a remote control program parameter list.
Chapter 90. SNAP and SNAPX — Dump virtual storage and continue
909
SNAP and SNAPX macros
910
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 91. SPIE — Specify program interruption exit
Description
Note:
IBM recommends that you use the ESPIE macro rather than SPIE. Callers in
31-bit addressing mode must use the ESPIE macro, which performs the same function as the SPIE macro for callers in both 24-bit and 31-bit addressing mode.
The SPIE macro specifies the address of an interruption exit routine and the program interruption types that are to cause the exit routine to get control.
Note:
In MVS/370 the SPIE environment existed for the life of the task. In later versions of MVS, the SPIE environment is deleted when the request block that created it is deleted. That is, when a program running under a later version of
MVS completes, any SPIE environments created by the program are deleted. This might create an incompatibility with MVS/SP Version 1 for programs that depend on the SPIE environment remaining in effect for the life of the task rather than the request block.
Each succeeding SPIE macro completely overrides any previous SPIE macro specifications for the task. The specified exit routine is given control in the key of the TCB when one of the specified program interruptions occurs in any problem program of the task. When a SPIE macro is issued from a SPIE exit routine, the program interruption element (PIE) is reset (zeroed). Thus, a SPIE exit routine should save any required PIE data before issuing a SPIE. If a caller issues an ESPIE macro from within a SPIE exit routine, it has no effect on the contents of the PIE.
However, if an ESPIE macro deletes the last SPIE/ESPIE environment, the PIE is freed and the SPIE exit cannot retry.
If the current SPIE environment is cancelled during SPIE exit routine processing, the control program will not return to the interrupted program when the SPIE program terminates. Therefore, if the SPIE exit routine wishes to retry within the interrupted program, a SPIE cancel should not be issued within the SPIE exit routine.
The SPIE macro can be issued by any problem program being executed in the performance of the task. The control program automatically deletes the SPIE exit routine when the request block (RB) that issued the SPIE macro terminates.
A PICA (program interruption control area) is created as part of the expansion of
SPIE. The PICA contains the exit routine's address and a code indicating the interruption types specified in SPIE.
For more information on the SPIE macro, see the information on program interruption services in z/OS MVS Programming: Assembler Services Guide.
© Copyright IBM Corp. 1988, 2017
911
SPIE macro
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
To issue SPIE without encountering an abnormal end, callers must be in problem state, with a PSW key value that is equal to the TCB assigned key.
Task
PASN=HASN=SASN
24-bit
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space
Programming requirements
The caller must include the following mapping macros: v IHAPIE v IHAPICA
Restrictions
None.
Input register information
Before issuing the SPIE macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain the following information:
0
1
Register
Contents
Used as a work register by the system.
If a SPIE environment is already active when you issue the SPIE macro, the
SPIE service routine returns the address of the previous PICA in register 1.
You can use this PICA to restore the previously active SPIE environment.
However, if an ESPIE environment is active when you issue the SPIE macro, the SPIE service returns the address, in register 1, of a PICA in which the first word contains binary zeros. You cannot modify the contents of this PICA, and it contains no useful information except to restore the previous SPIE or ESPIE environment. If no previous SPIE/ESPIE environment is active, the service routine returns a zero in register 1.
2-13
Unchanged.
14-15
Used as work registers by the system.
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
912
z/OS MVS Assembler Services Reference IAR-XCT
⌂
⌂
Syntax
name
SPIE macro
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the SPIE macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede SPIE.
SPIE
exit addr
,(interrupts)
One or more blanks must follow SPIE.
exit addr: A-type address, or register (2) - (12).
interrupts: Decimal numbers 1-15 expressed as: single values: (2,3,4,7,8,9,10) ranges of values: ((2,4),(7,10)) combinations: (2,3,4,(7,10))
Parameters
The parameters are explained as follows:
exit addr
Specifies the address of the exit routine to be given control when a specific program interruption occurs. The exit routine receives control in 24-bit addressing mode.
,(interrupts)
Indicates the type of interruption for which the exit routine is to be given control. The interruption types are as follows:
Number
Interruption Type
1
Operation
Chapter 91. SPIE — Specify program interruption exit
913
SPIE macro
10
11
12
13
14
15
8
9
6
7
4
5
2
3
Privileged operation
Execute
Protection
Addressing
Specification
Data
Fixed-point overflow (maskable)
Fixed-point divide
Decimal overflow (maskable)
Decimal divide
Exponent overflow
Exponent underflow (maskable)
Significance (maskable)
Floating-point divide
Note:
1.
If an exit address is zero or no parameters are specified, the current SPIE and any previously active ESPIE environments are cancelled.
2.
If a program interruption type is maskable, the corresponding program mask bit in the PSW (program status word) is set to 1 when specified and to 0 when not specified. Interruption types that are not maskable and not specified above are handled by the system, which forces an abend with the program check as the completion code. If an ESTAE-type recovery routine is also active, the SDWA indicates a system-forced abnormal termination.
The registers at the time of the error are those of the system.
3.
If you are using vector instructions and an interruption of 8, 12, 13, 14, or
15 occurs, your recovery routine can check the exception extension code
(the first byte of the two-byte interruption code in the EPIE or PIE) to determine whether the exception was a vector or scalar type of exception.
ABEND codes
The SPIE macro might return abend codes X'10E', X'30E', or X'46D'. See z/OS MVS
System Codes for explanations and programmer responses.
Return and reason codes
None.
Example
Give control to an exit routine for interruption 1, 5, 7, 8, 9, and 10. DOITSPIE is the address of the SPIE exit routine.
SPIE DOITSPIE,(1,5,(7,10))
SPIE—List form
Use the list form of the SPIE macro to construct a control program parameter list in the form of a program interruption control area.
914
z/OS MVS Assembler Services Reference IAR-XCT
SPIE macro
�
Syntax
name
Syntax
The list form of the SPIE macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede SPIE.
SPIE
�
exit addr
,(interrupts)
One or more blanks must follow SPIE.
exit addr: A-type address.
interrupts: Decimal numbers 1-15 expressed as: single values: (2,3,4,7,8,9,10) ranges of values: ((2,4),(7,10)) combinations: (2,3,4,(7,10))
,MF=L
Parameters
The parameters are explained under the standard form of the SPIE macro, with the following exception:
,MF=L
Specifies the list form of the SPIE macro.
SPIE - Execute form
A remote control program parameter list is used in, and can be modified by, the execute form of the SPIE macro. The PICA (program interruptions control area) can be generated by the list form of SPIE, or you can use the address of the PICA returned in register 1 following a previous SPIE macro. If this macro is being issued to reestablish a previous SPIE environment, code only the MF parameter.
Syntax
Syntax
The execute form of the SPIE macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede SPIE.
Chapter 91. SPIE — Specify program interruption exit
915
SPIE macro
Syntax
SPIE
�
exit addr
,(interrupts)
Description
One or more blanks must follow SPIE.
exit addr: RX-type address, or register (2) - (12).
interrupts: Decimal numbers 1-15, expressed as single values: (2,3,4,7,8,9,10) ranges of values: ((2,4),(7,10)) combinations: (2,3,4,(7,10))
ctrl addr: RX-type address, or register (1) or (2) - (12).
,MF=(E,ctrl addr)
Parameters
The parameters are explained under the standard form of the SPIE macro, with the following exception:
,MF=(E,ctrl addr)
Specifies the execute form of the SPIE macro using a remote control program parameter list.
Note:
If SPIE is coded with a 0 as the control address, the SPIE environment is canceled.
916
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 92. SPLEVEL — Set macro level
Description
Use the SPLEVEL macro to ensure that the assembler generates the correct level for a particular macro that your program issues. You might need to control the level of a macro expansion if you assemble your program on one version and release of
MVS, then run the program on a different version and release of MVS, and one of the following is true: v Your program issues MVS macros that are downward incompatible to
MVS/System Product Version 1.
v Your program issues installation- or vendor-written macros that are incompatible between versions and releases.
See “Compatibility of MVS macros” on page 1 for additional information about the
downward incompatible MVS macros. Authorized callers of SPLEVEL should consult “Selecting the Macro Level” in the following for the lists of downward incompatible MVS macros that are authorized: v
z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
v
z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG
v
z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU
v
z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
For installation- or vendor-written macros, see the installation or vendor information to determine if incompatibilities between versions and releases exist.
You can use SPLEVEL in two ways: v Within your program, issue SPLEVEL with the SET=n parameter prior to issuing another macro to set the desired level for that macro. SPLEVEL SET=n sets a global symbol (&SYSSPLV) to the value n. Certain macros (including all the downward incompatible macros) check this global symbol during assembly to determine which expansion of the macro to generate. Once you set the macro level, all macros in your program that check the &SYSSPLV global symbol expand at that level until you change the level to some other value.
Authorized callers of SPLEVEL should consult the Macro Summary in the chapter entitled “Using the Macros” in the following publications for the lists of authorized macros that check the SPLEVEL global symbol:
– z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
– z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG
– z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU
– z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
See High Level Assembler Language Reference for information about global set symbols.
v Within a macro you are writing, issue SPLEVEL with the TEST parameter to ensure that the macro level is set:
1.
Define the &SYSSPLV global symbol within your macro.
2.
Issue SPLEVEL TEST, which checks to see if the caller set the macro level.
3.
Define different logical paths within your macro to correspond to the macro level that is in effect.
© Copyright IBM Corp. 1988, 2017
917
SPLEVEL macro
Existing programs that were assembled using Version 2, Version 3, Version 4, and
Version 5 macros will run properly on z/OS.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task or SRB
Any PASN, any HASN, any SASN
24- or 31-bit
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
The caller may hold locks, but is not required to hold any.
None.
�
Syntax
name
Programming requirements
None.
Restrictions
None.
Input register information
Before issuing the SPLEVEL macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) and access registers (ARs) are all unchanged.
Performance implications
None.
Syntax
The SPLEVEL macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede SPLEVEL.
SPLEVEL
� One or more blanks must follow SPLEVEL.
TEST
918
z/OS MVS Assembler Services Reference IAR-XCT
SPLEVEL macro
Syntax
SET=n
SET
Description
n: 2, 3, 4, 5 or 6
Default
: SET=6
Parameters
The parameters are explained as follows:
TEST
TEST checks the &SYSSPLV global variable, and does the following: v Sets &SYSSPLV to the default value if &SYSSPLV does not contain a value indicating that you did not issue SPLEVEL SET during this assembly.
v Leaves the value of &SYSSPLV unchanged, if &SYSSPLV does contain a value indicating that you issued SPLEVEL SET during this assembly.
SET=n
SET
Specifies the macro level by setting the global symbol &SYSSPLV.
v SET=n places a value in &SYSSPLV equal to n, where n must be 2, 3, 4, 5 or
6.
v SET without n, results in the assembler using the default value, 6.
ABEND codes
None.
Return and reason codes
None.
Example 1
Select the version 1 expansion of a specific downward incompatible macro.
SPLEVEL SET=1
Example 2
Use SPLEVEL TEST within your own macro to ensure the &SYSSPLV global symbol is set.
.V5
.V1
.
.
.
GBLC
SPLEVEL
AIF
ANOP
&SYSSPLV
TEST
Define global symbol
If global symbol has no value, set to the default.
(’&SYSSPLV’ EQ ’1’).V1
Use code for V1
This logical path contains instructions appropriate for a V2, V3, V4, or V5 expansion.
.
.
.
AGO
ANOP
.COMMON
This logical path contains instructions appropriate for a V1 expansion.
Chapter 92. SPLEVEL — Set macro level
919
SPLEVEL macro
.
.
.
.COMMON ANOP
920
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 93. STAE — Specify task abnormal exit
Note: IBM recommends that you use the ESTAEX macro or ESTAE macro rather than STAE
.
Description
Syntax
The STAE macro enables the user to intercept a scheduled ABEND and to have control returned to him at a specified exit routine address. The STAE macro operates in both problem program and supervisor modes.
Note:
The STAE macro is not supported for users executing in 31-bit addressing mode. Such users will be abended.
Syntax
The standard form of the STAE macro is written as follows:
Description
name
⌂
name: Symbol. Begin name in column 1.
One or more blanks must precede STAE.
STAE
⌂
exit addr
0
,CT
,OV
,PARAM=list addr
,XCTL=NO
,XCTL=YES
,PURGE=QUIESCE
,PURGE=HALT
,PURGE=NONE
,ASYNCH=NO
,ASYNCH=YES
© Copyright IBM Corp. 1988, 2017
One or more blanks must follow STAE.
exit addr: A-type address, or register (2) - (12).
Default
: CT
list addr: A-type address, or register (2) - (12).
Default
: XCTL=NO
Default
: PURGE=QUIESCE
Default
: ASYNCH=NO
921
STAE macro
Syntax
,RELATED=value
Description
value: Any valid macro keyword specification.
Parameters
The parameters are explained as follows:
exit addr
0
Specifies the address of a STAE exit routine to be entered if the task issuing this macro terminates abnormally. If 0 is specified, the most recent STAE request is canceled.
,CT
,OV
Specifies the creation of a new STAE exit (CT) or indicates that the parameters passed in this STAE macro are to overlay the data contained in the previous
STAE exit (OV).
,PARAM=list addr
Specifies the address of a user-defined parameter list containing data to be used by the STAE exit routine when it is scheduled for execution.
,XCTL=NO
,XCTL=YES
Specifies that the STAE macro will be canceled (NO) or will not be canceled
(YES) if an XCTL macro is issued by this program.
,PURGE=QUIESCE
,PURGE=HALT
,PURGE=NONE
Specifies that all outstanding requests for I/O operations are not saved when the STAE exit is taken (HALT), that I/O processing is allowed to continue normally when the STAE exit is taken (NONE), or that all outstanding requests for I/O operations are saved when the STAE exit is taken (QUIESCE). For
QUIESCE, at the end of the STAE exit routine, the user can code a retry routine to handle the outstanding I/O requests.
Note:
If any IBM-supplied access method, except EXCP, is being used, the
PURGE=NONE option is recommended. If you use PURGE=NONE, all control blocks affected by input/output processing can continue to change during STAE exit routine processing.
If PURGE=NONE is specified and the ABEND was originally scheduled because of an error in input/output processing, an ABEND recursion develops when an input/output interruption occurs, even if the exit routine is in progress. Thus, it appears that the exit routine failed when, in reality, input/output processing caused the failure.
ISAM Notes: If ISAM is being used and PURGE=HALT is specified or
PURGE=QUIESCE is specified but I/O is not restored: v
Only the input/output event on which the purge is done is posted. Subsequent event control blocks (ECBs) are not posted.
v The ISAM check routine treats purged I/O as normal I/O.
922
z/OS MVS Assembler Services Reference IAR-XCT
STAE macro
v Part of the data set may be destroyed if the data set is being updated or added to when the failure occurred.
,ASYNCH=NO
,ASYNCH=YES
Specifies that asynchronous exit processing is allowed (YES) or is not allowed
(NO) while the STAE exit is executing.
ASYNCH=YES must be coded if: v The STAE exit routine requests any supervisor services that require asynchronous interruptions to complete their normal processing.
v PURGE=QUIESCE is specified for any access method that requires asynchronous interruptions to complete normal input/output processing.
v PURGE=NONE is specified and the CHECK macro is issued in the STAE exit routine for any access method that requires asynchronous interruptions to complete normal input/output processing.
Note:
If ASYNCH=YES is specified and the ABEND was originally scheduled because of an error in asynchronous exit handling, an ABEND recursion develops when an asynchronous interruption occurs. Thus, it appears that the exit routine failed when, in reality, asynchronous exit handling caused the failure.
,RELATED=value
Specifies information used to self-document macros by relating functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and may be any valid coding values. Control returns to the instruction following the STAE macro.
Return codes
Register 15 contains one of the following hexadecimal return codes from
TIMEUSED:
Table 51. Return and Reason Codes for the STAE Macro
Hexadecimal
Return Code
00
04
08
0C
10
Meaning
Successful completion of STAE request.
STAE was unable to obtain storage for STAE request.
Attempt was made to cancel or overlay a nonexistent STAE request.
Exit routine or parameter list address was invalid, or STAI request was missing a TCB address.
Attempt was made to cancel or overlay a STAE request of another user, or an unexpected error was encountered while processing this request.
Example
Request an overlay of the existing STAE recovery exit with the following options: new exit address is ADDR, parameter list is at PLIST, halt I/O, do not take asynchronous exits, transfer ownership to the new request block resulting from any
XCTL macros.
STAE ADDR,OV,PARAM=PLIST,XCTL=YES,PURGE=HALT,ASYNCH=NO
Chapter 93. STAE — Specify task abnormal exit
923
STAE macro
STAE - List form
The list form of the STAE macro is used to construct a remote control program parameter list.
Syntax
Syntax
The list form of the STAE macro is written as follows:
Description
name
�
STAE
�
name: Symbol. Begin name in column 1.
One or more blanks must precede STAE.
exit addr
,PARAM=list addr
,PURGE=QUIESCE
,PURGE=HALT
,PURGE=NONE
,ASYNCH=NO
,ASYNCH=YES
,RELATED=value
,MF=L
One or more blanks must follow STAE.
exit addr: A-type address.
list addr: A-type address.
Default
: PURGE=QUIESCE
Default
: ASYNCH=NO
value: Any valid macro keyword specification.
Parameters
The parameters are explained under the standard form of the STAE macro, with the following exception:
,MF=L
Specifies the list form of the STAE macro.
STAE - Execute form
A remote control program parameter list is used in, and can be modified by, the execute form of the STAE macro. The control program parameter list can be generated by the list form of the STAE macro. If you want to dynamically change the contents of the remote STAE parameter list, you can do so by coding a new
924
z/OS MVS Assembler Services Reference IAR-XCT
�
Syntax
name
STAE macro
exit address and/or a new parameter list address. If exit address or PARM= is coded, only the associated field in the remote STAE parameter list is changed. The other field remains as it was before the current STAE request was made.
Syntax
The execute form of the STAE macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede STAE.
STAE
� One or more blanks must follow STAE.
exit addr: RX-type address, or register (2) - (12).
exit addr
0
,CT
,OV
,PARAM=list addr
,XCTL=NO
,XCTL=YES
,PURGE=QUIESCE
,PURGE=HALT
,PURGE=NONE
,ASYNCH=NO
,ASYNCH=YES
,RELATED=value
,MF=(E,ctrl addr)
list addr: RX-type address, or register (2) - (12).
value: Any valid macro keyword specification.
ctrl addr: RX-type address, or register (1) or (2) - (12).
Parameters
The parameters are explained under the standard form of the STAE macro, with the following exception:
Chapter 93. STAE — Specify task abnormal exit
925
STAE macro
,MF=(E, ctrl addr)
Specifies the execute form of the STAE macro using a remote control program parameter list.
Example
Provide the pointer to the recovery code in the register called EXITPTR, and the address of the STAE exit parameter list in register 9. Register 8 points to the area where the STAE parameter list (created with the MF=L option) was moved.
STAE (EXITPTR),PARAM=(9),MF=(E,(8))
926
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 94. STATUS — Start and stop a subtask
Description
Use the STATUS macro to change the dispatchability status of one or all of a program's subtasks. For example, the STATUS macro can be used to restart subtasks that were stopped when an attention exit routine was entered.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN or PASN¬=HASN¬=SASN
31-bit
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
No locks held.
No requirements.
Programming requirements
None.
Restrictions
The caller cannot have an EUT FRR established.
Input register information
Before issuing the STATUS macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
© Copyright IBM Corp. 1988, 2017
927
STATUS macro
Syntax
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
Using STATUS will degrade performance of the calling program's address space while STATUS runs.
Syntax
The STATUS macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede STATUS.
STATUS
�
One or more blanks must follow STATUS.
START
STOP
,TCB=tcb addr
,RELATED=value
tcb addr: RX-type address or address in register (2) - (12).
value: Any valid macro keyword specification.
Parameters
The parameters are explained as follows:
START
STOP
Specifies that the task identified on the TCB parameter is to be stopped (STOP) or started (START). If you omit the TCB parameter, all subtasks of the originating task are stopped or started.
Note:
This parameter does not ensure that the subtask is stopped when control is returned to the issuer. A subtask can have a “stop deferred” condition that would cause that particular subtask to remain dispatchable until stops are no longer deferred. In a multiprogramming environment, it would be possible to have a task issue the STATUS macro with the STOP parameter and resume processing while the subtask (for which the STOP was issued) is redispatched to another processor.
928
z/OS MVS Assembler Services Reference IAR-XCT
STATUS macro
,TCB=tcb addr
Specifies the address of a fullword on a fullword boundary containing the address of the task control block that is to have its START/STOP count adjusted. (If a register is specified, however, the address is of the TCB itself.) If this parameter is not coded, the count is adjusted in the task control blocks for all the subtasks of the originating task.
Note:
TCB must reside in 24-bit addressable storage.
,RELATED=value
Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user and may be any valid coding values.
The RELATED parameter is available on macros that provide opposite services
(for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and
LOAD/DELETE) and on macros that relate to previous occurrences of the same macros (for example, CHAP and ESTAE).
The RELATED parameter may be used, for example, as follows:
STAT1 STATUS STOP,TCB=YOURTCB,RELATED=(STAT2,
’STOP A SUBTASK’)
.
.
.
STAT2 STATUS START,TCB=YOURTCB,RELATED=(STAT1,
’START A SUBTASK’)
Note:
Each of these macros will fit on one line when coded, so there is no need for a continuation indicator.
Return codes
Return codes from execution of STATUS are as follows:
Table 52. Return Codes for the STATUS Macro
Hexadecimal
Return Code
00
Meaning and Action
Meaning
: Processing completed successfully.
04
Action
: No action necessary.
Meaning
: Program error. START/STOP request failed. The task you specified is not a subtask of the calling program's task.
Action
: Ensure that you specify a task on the TCB parameter that is a subtask of the calling program.
Example 1
Stop all subtasks.
STATUS STOP
Example 2
Create a subtask. Stop the subtask, then restart it.
PRINT NOGEN
STATUS CSECT
STATUS AMODE 31
Chapter 94. STATUS — Start and stop a subtask
929
STATUS macro
*
*
*
*
STATUS RMODE ANY
*********************************************************************
* The following code performs the following functions:
* 1.
Creates a subtask by issuing the ATTACH macro.
*
*
2.
Stops the subtask by issuing the STATUS macro with the
STOP parameter.
*
*
3.
Starts the stopped subtask by issuing the STATUS macro * with the START parameter.
*
* *
*********************************************************************
SPACE 3
***************************************
* Entry linkage *
***************************************
SPACE 3
STM R14,R12,12(R13)
BEGN
BALR R12,0
USING BEGN,R12
DS
ST
0H
R13,SAVE+4
LA
ST
LR
EJECT
R15,SAVE
R15,8(0,R13)
R13,R15
**********************************************************************
* Attach a subtask and request that it be notified by an ECB when
* the subtask completes.
*
*
* *
**********************************************************************
SPACE 3
ATTCH1 ATTACH EP=SUBTASK,ECB=AMYECB
SPACE 3
ST R1,TCBADDR SAVE SUBTASK TCB ADDRESS
EJECT
******************************************************************
* Stop the subtask by issuing STATUS STOP, then restart it by *
* issuing STATUS START.
*
* *
******************************************************************
SPACE 3
STATUS STOP,TCB=TCBADDR
SPACE 3
.
****************************************************
* Processing of other subtasks continues.
*
****************************************************
.
STATUS START,TCB=TCBADDR
SPACE 3
EJECT
*****************************************************
* Wait until subtask completes, then detach it.
*
*****************************************************
SPACE 3
WAIT 1,ECB=AMYECB
SPACE 3
DETACH TCBADDR
WAIT ON E-O-T ECB
DETACH SUBTASK
SPACE 3
EJECT
***************************************
* End of job *
***************************************
SPACE 3
FINI DS
L
0H
R13,SAVE+4
DROP R12
LM R14,R12,12(R13)
930
z/OS MVS Assembler Services Reference IAR-XCT
XR
BR
R15,R15
R14
EJECT
***********************************
* Define constants *
***********************************
SAVE
*
DC 18F’0’
TCBADDR DC
AMYECB DC
F’0’
F’0’
ADDRESS OF SUBTASK TCB
END-OF-SUBTASK ECB
EJECT
***********************************************
* Register equates *
***********************************************
R1
R12
R13
R14
R15
SPACE 3
EQU 1
EQU
EQU 13
EQU
12
14
EQU 15
LTORG
END
STATUS macro
Chapter 94. STATUS — Start and stop a subtask
931
STATUS macro
932
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 95. STCKCONV — Store clock conversion routine
Description
The STCKCONV macro converts an input time-of-day (TOD) clock value to time of day and date, and returns the converted values to the caller in the format requested. The input clock value can be either the basic time-of-day (TOD) format or the extended time-of-day (ETOD) format.
v TOD — Unsigned 64-bit binary number v ETOD — Unsigned 128-bit binary number
See z/OS MVS Programming: Assembler Services Guide and z/Architecture Principles of
Operation for information comparing the formats of the TOD and ETOD.
The STCKCONV time of day and date formats are compatible with the formats returned by the TIME macro, which returns a time of day and date value or the contents of the TOD clock. The STCKCONV time of day and date formats are also compatible with the input formats accepted by the CONVTOD macro, which converts a time of day and date value to TOD clock format.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task or SRB
PASN=HASN=SASN or PASN¬=HASN¬=SASN
24-bit or 31-bit addressing mode
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
No requirement
Must be in the primary address space or be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
Programming requirements
If the program is in AR mode, issue the SYSSTATE ASCENV=AR macro before
STCKCONV. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.
Restrictions
None.
Input register information
Primary-mode callers must make sure that access register 1 is zero before issuing the execute form of the STCKCONV macro. For other registers, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
© Copyright IBM Corp. 1988, 2017
933
STCKCONV macro
Syntax
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the STCKCONV macro is written as follows:
Description
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede STCKCONV.
STCKCONV
�
STCKVAL=TOD clock addr
STCKEVAL=ETOD clock addr
,CONVVAL=conv addr
One or more blanks must follow STCKCONV.
TOD clock addr: RX-type address or register (2) - (12).
ETOD clock addr: RX-type address or register (2) - (12).
conv addr: RX-type address or register (2) - (12).
,TIMETYPE=DEC
,TIMETYPE=BIN
,TIMETYPE=MIC
Default
: TIMETYPE=DEC
934
z/OS MVS Assembler Services Reference IAR-XCT
STCKCONV macro
Syntax
,DATETYPE=YYYYDDD
,DATETYPE=DDMMYYYY
,DATETYPE=MMDDYYYY
,DATETYPE=YYYYMMDD
Description
Default
: DATETYPE=YYYYDDD
Parameters
The parameters are explained as follows:
STCKVAL=TOD clock addr
Specifies the address of an 8-byte storage area containing the 64-bit TOD clock value to be converted.
STCKEVAL=ETOD clock addr
Specifies the address of a 16-byte storage area containing the 128-bit ETOD clock value to be converted. Only values with the first byte less than x'02' (that is, values before the end of the second epoch) can be converted successfully.
Only one of STCLVAL or STCKEVAL can be specified.
,CONVVAL=conv addr
Specifies the address of a 16-byte storage area where the system returns the converted value in the requested format. The first two words contain the time of day and the third word contains the date. Do not use the contents of the fourth word.
,TIMETYPE=DEC
,TIMETYPE=BIN
,TIMETYPE=MIC
Specifies the format in which the converted time of day is returned, as follows:
DEC
Returns the converted time of day as packed decimal digits (without a sign) of the form HHMMSSthmiju0000, where
HH
is hours, based on a 24-hour clock
MM
is minutes
SS t
is seconds is tenths of a second
i j h m
is hundredths of a second is milliseconds is ten-thousandths of a second is hundred-thousandths of a second
u
is microseconds
BIN
Returns the converted time of day as an unsigned 32-bit binary number with the low-order bit equivalent to 0.01 second. The second word of the converted time value is zero.
MIC
Returns the converted time of day in microseconds as 8 bytes of information, where bit 51 is equivalent to one microsecond.
,DATETYPE=YYYYDDD
,DATETYPE=DDMMYYYY
Chapter 95. STCKCONV — Store clock conversion routine
935
STCKCONV macro
,DATETYPE=MMDDYYYY
,DATETYPE=YYYYMMDD
Specifies the format in which the converted date is returned, as follows:
Parameter
Form of returned date
YYYYDDD
0YYYYDDD
DDMMYYYY
DDMMYYYY
MMDDYYYY
MMDDYYYY
YYYYMMDD
YYYYMMDD
The date is returned as 4 bytes of packed decimal digits (without a sign), where:
YYYY
is the year
DDD
is the day of the year
DD
is the day of the month
MM
is the month of the year
ABEND codes
None.
Return codes
When STCKCONV macro returns control to your program, GPR 15 contains a return code.
Table 53. Return Codes for the STCKCONV Macro
Hexadecimal
Return Code
0
Meaning and Action
Meaning
: Successful completion.
C
Action
: None.
Meaning
: System error.
10
14
Action
: Retry the request.
Meaning
: Program error. The user's parameter list is not in addressable storage.
Action
: Ensure that the parameter list address is valid and the storage is addressable.
Meaning
: Unsuccessful completion. The ETOD value was not valid.
Action
: Avoid specifying a date or time that occurs after the second epoch (the corresponding ETOD value would have a value greater than x'01' in the first byte).
936
z/OS MVS Assembler Services Reference IAR-XCT
STCKCONV macro
Example 1
Convert a TOD clock value to time of day in decimal digits, and date in month-day-year format.
STCKCONV STCKVAL=TODSTAMP,CONVVAL=OUTAREA,TIMETYPE=DEC,
DATETYPE=MMDDYYYY
TODSTAMP DC X’A0569832F1241000’
OUTAREA DS CL16
TOD CLOCK VALUE
CONVERTED VALUE
X
Example 2
Convert a TOD clock value to time of day in hundredths of seconds, and date in year-month-day format.
STCK TODCLOCK
STCKCONV STCKVAL=TODCLOCK,CONVVAL=OUTVAL,TIMETYPE=BIN,
TODCLOCK DS XL8
DATETYPE=YYYYMMDD
TOD CLOCK VALUE
OUTVAL DS CL16 CONVERTED VALUE
X
STCKCONV—List form
Use the list form of the STCKCONV macro together with the execute form of the macro for applications that require reentrant code. The list form of the macro defines an area of storage that the execute form of the macro uses to store the parameters.
Syntax
Syntax
The list form of the STCKCONV macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede STCKCONV.
STCKCONV
�
One or more blanks must follow STCKCONV.
MF=L
Parameter
The parameter is explained as follows:
MF=L
Specifies the list form of the STCKCONV macro. Do not specify any other keywords with MF=L. Precede the STCKCONV list form macro invocation with a name starting in column 1 to label the generated parameter list so you can refer to it.
Chapter 95. STCKCONV — Store clock conversion routine
937
STCKCONV macro
Example
Establish the correct amount of storage for the STCKCONV parameter list.
LIST1 STCKCONV MF=L
STCKCONV - Execute form
Use the execute form of the STCKCONV macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Syntax
Syntax
The execute form of the STCKCONV macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede STCKCONV.
STCKCONV
�
STCKVAL=TOD clock addr
STCKEVAL=ETOD clock addr
,CONVVAL=conv addr
,TIMETYPE=DEC
,TIMETYPE=BIN
,TIMETYPE=MIC
,DATETYPE=YYYYDDD
,DATETYPE=DDMMYYYY
,DATETYPE=MMDDYYYY
,DATETYPE=YYYYMMDD
,MF=(E,list addr)
One or more blanks must follow STCKCONV.
TOD clock addr: RX-type address or register (2) - (12).
ETOD clock addr RX-type address or register (2) - (12).
conv addr: RX-type address or register (2) - (12).
Default
: TIMETYPE=DEC
Default
: DATETYPE=YYYYDDD
list addr: RX-type address or register (1) - (12).
Parameters
The parameters are explained under the standard form of the STCKCONV macro with the following exception:
,MF=(E,list addr)
Specifies the execute form of the STCKCONV macro. list addr specifies the address of the parameter list created by the list form of the macro.
938
z/OS MVS Assembler Services Reference IAR-XCT
STCKCONV macro
Example
Convert a TOD clock value to time of day in microseconds and date in year-day of the year format. Specify the address of the appropriate parameter list in LIST1.
STCKCONV STCKVAL=TODCLOCK,CONVVAL=OUTVAL,TIMETYPE=MIC,
DATETYPE=YYYYDDD,MF=(E,LIST1)
TODCLOCK DC X’9FE4781301ABE000’
OUTVAL DS CL16
TOD CLOCK VALUE
CONVERTED VALUE
X
Chapter 95. STCKCONV — Store clock conversion routine
939
STCKCONV macro
940
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 96. STCKSYNC — Store clock synchronous service
Description
The STCKSYNC macro obtains the time-of-day (TOD) clock contents and indicates whether the TOD clock is synchronized with an external time reference (ETR
1
) or with Server Time Protocol (STP).
STCKSYNC is for use by programs that are dependent upon synchronized TOD clocks in a multisystem environment. STCKSYNC also provides an optional parameter, ETRID, that returns the network ID of the ETR source with which the
TOD clock is synchronized, and, if applicable, CTNID, that returns the timing mode and the Coordinated Timing Network ID (CTN-ID) of the timing network to which the current processor is synchronized.
The time-of-day clock specified can be either the basic time-of-day clock format
(TOD) or the extended time-of-day clock format (ETOD).
v TOD — Unsigned 64-bit binary number v ETOD — Unsigned 128=bit binary number
See z/OS MVS Programming: Assembler Services Guide or z/Architecture Principles of
Operation for information comparing the formats of the TOD and ETOD.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task or SRB
PASN=HASN=SASN or PASN¬=HASN¬=SASN
31-bit
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
Any locks may be held, no locks required
Must be in the primary address space or be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
Programming requirements
If the program is in AR mode, issue the SYSSTATE ASCENV=AR macro before
STCKSYNC. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.
Restrictions
None.
1. External time reference (ETR) is the MVS generic name for the IBM Sysplex Timer.
© Copyright IBM Corp. 1988, 2017
941
STCKSYNC macro
Syntax
Input register information
For primary ASC mode callers, GPR 13 must contain the address of a 72-byte save area. For AR mode callers, AR/GPR 13 must contain the address of a 72-byte save area.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
14
15
Used as work registers by the system
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The STCKSYNC macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede STCKSYNC.
name
�
STCKSYNC
�
TOD =TOD clock addr
ETOD=ETOD clock addr
One or more blanks must follow STCKSYNC.
TOD clock addr: RX-type address
ETOD clock addr: RX-type address
942
z/OS MVS Assembler Services Reference IAR-XCT
STCKSYNC macro
Syntax
,ETRID=ETR-id addr
,CTNID=CTN-id addr
Description
ETR-id addr: RX-type address
CTN-id addr: RX-type address: RX-type address
Parameters
The parameters are explained as follows:
TOD=TOD clock addr
Specifies the address of a doubleword that receives the TOD clock value.
ETOD=ETOD clock addr
Specifies the address of a 16-byte area, aligned on a double-word boundary, that receives the extended TOD clock value (ETOD).
Only one of either TOD or ETOD can be specified.
,ETRID=ETR-id addr
Specifies the address of a byte that receives the ETR network ID of the ETR with which the TOD clock is synchronized. No ETRID value is returned if the
TOD clock is not synchronized with an ETR.
,CTNID=CTN-id addr
Specifies the address of a 16–byte area that contains the timing mode and the
CTN-ID of the timing network to which the current CEC is synchronized. The
CTN-ID is the first 12 bytes and the timing mode is the last byte (15) of this area. If the clock is synchronized to a CTN, the timing mode is either in ETR timing mode (X'80') or STP timing mode (X'40'). If the clock is not synchronized to a CTN, the mode is local (X'00'). The CTN-ID consists of two parts, the STP-ID which is 8 characters in bytes 0 - 7 and the ETR-ID which is a hexadecimal integer value in byte 11 of the returned area. A value of X'FF' in byte 11 should be ignored. Bytes 12 to 14 are not used and will be zeros.
Only one of either TOD or ETOD can be specified.
ABEND codes
None.
Return codes
Return codes from the STCKSYNC macro are returned as hexadecimal values in register 15, as follows:
Table 54. Return Codes for the STCKSYNC Macro
Hexadecimal
Return Code
0
Meaning and Action
Meaning
: The TOD clock is synchronized with an ETR or a CTN, or a simulated ETR was requested (through SYS1.PARMLIB member
CLOCKxx). If ETRID was specified, the ID of the ETR is returned at id
addr.
4
Action
: None.
Meaning
: The TOD clock is not synchronized with an ETR or a CTN.
Action
: None required. However, you might take some action based upon your application.
Chapter 96. STCKSYNC — Store clock synchronous service
943
STCKSYNC macro
Table 54. Return Codes for the STCKSYNC Macro (continued)
Hexadecimal
Return Code
8
Meaning and Action
Meaning
: System error. The TOD clock is unusable.
C
Action
: Reissue the request until it succeeds.
Meaning
: System error. Timer in the middle of a timing Mode Switch.
No data is returned.
Action
: Reissue the request.
Example 1
Obtain the TOD clock contents and an indication of whether the TOD clock is synchronized with an ETR.
STCKSYNC TOD=TODAREA
TODAREA DS XL8 TOD CLOCK CONTENTS
Example 2
For a caller in AR mode, obtain the TOD clock contents, an indication of whether the TOD clock is synchronized with an ETR, and the network ID of the ETR source with which the TOD clock is synchronized.
.
.
SYSSTATE ASCENV=AR
.
STCKSYNC TOD=TODAREA,ETRID=IDAREA
TODAREA DS XL8 TOD CLOCK CONTENTS
IDAREA DS XL1 ETR NET ID
944
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 97. STIMER — Set interval timer
Description
The STIMER macro sets a timer to a specified time interval or to an interval that will expire at a specified time of day. An optional asynchronous timer completion exit is given control when the time interval expires; if no asynchronous timer completion routine is specified, no indication that the time interval has expired is provided. A second STIMER macro issued before the first time interval expires overrides the first interval and exit routine.
The time interval may be a ‘real-time interval’ (measured continuously in real time by the clock comparator), or a ‘task-time interval’ (measured, only while the task is in execution, by the CPU timer). See Principles of Operation for information on the clock comparator and CPU timer. If a real-time interval is specified, the task may elect to either continue (REAL) or suspend (WAIT) execution during the interval. If the task elects to continue execution, it may optionally specify an exit routine to be given control on completion of the time interval. If the task elects to suspend execution, it is restarted at the next sequential instruction, sometime after completion of the time interval. If a task-time interval is specified, the task must continue. It may optionally specify an exit routine to be given control on completion of the interval.
STIMER allows you to set one time interval for one task; STIMERM allows you to set 16 separate time intervals for a task. Using the two macros together allows you to set 17 separate intervals for a task.
For information on how to select an MVS/SP version other than the current
version, see “Compatibility of MVS macros” on page 1. If your program is to
execute in 31-bit addressing mode, you must use the SP Version 2 expansion of this macro or a later version.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
24- or 31- or 64-bit
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space.
Programming requirements
The timer completion exit routine must be in virtual storage when it is required.
Restrictions
The following restrictions apply to the STIMER macro:
© Copyright IBM Corp. 1988, 2017
945
STIMER macro
v Only one STIMER invocation can be active at a time. Ensure that any processing your program performs after issuing the STIMER macro does not also invoke the STIMER macro. For concurrent requests, use the STIMERM macro.
v Do not issue the STIMER macro before invoking dynamic allocation. Use
STIMERM instead.
v For REAL or WAIT requests:
– If you specify a time of day at which the interval will expire (GMT
(Greenwich Mean Time), LT (local time), or TOD (Time of Day) parameters), the time of day you specify must not exceed 24:00:00:00; otherwise, your program receives a X'12F' abend.
– If you specify a time interval on the MICVL parameter, the interval you specify, when added to the current TOD clock contents, must not exceed the maximum value for the clock comparator (X'FFFFFFFFFFFFFFFF'); otherwise, your program receives a X'12F' abend.
v For TASK requests, the time interval you specify on MICVL must not exceed the maximum positive value for the CPU timer (X'7FFFFFFFFFFFFFFF'); otherwise, your program receives a X'12F' abend.
v You can issue STIMER REAL with a timer completion exit routine, and within that routine, you can issue STIMER REAL and specify the same timer completion exit routine. Under these circumstances, IBM recommends that you specify a time interval rather than a time of day on the STIMER you issue within the timer completion exit routine. If you specify a time of day, it is possible for the timer completion exit routine to receive control later than the time of day you specified, resulting in an infinite loop.
v
The caller can have no enabled, unlocked task (EUT) FRRs established.
v The time interval you specify on the BINTVL parameter must not exceed
X'7FFFFFFF'. If the time interval exceeds X'7FFFFFFF', your program receives a
X'12F' abend.
v If you make use of JES2 main task exit routines or have vendor code that could run under the JES2 main task, then this code cannot use the STIMER macro.
Such use would usurp the timer JES2 sets with its use of the STIMER macro.
The exit or vendor code would destroy JES2 processing and lead to unpredictable errors. STIMERM is the macro this code must use instead.
Input register information
Before issuing the STIMER macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the registers contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
0 (zero)
When control returns to the caller, the access registers (ARs) contain:
946
z/OS MVS Assembler Services Reference IAR-XCT
�
Syntax
name
STIMER macro
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The STIMER macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede STIMER.
STIMER
� One or more blanks must follow STIMER.
exit rtn addr: RX-type address, or register (0) or (2) - (12).
REAL
REAL,exit rtn addr
TASK
TASK,exit rtn addr
WAIT
,BINTVL=stor addr
,DINTVL=stor addr
,MICVL=stor addr
,GMT=stor addr
,TUINTVL=stor addr
,TOD=stor addr
,LT=stor addr
stor addr: RX-type address, or register (1) or (2) - (12).
Note
: The GMT, TOD, and LT parameters must not be specified with TASK above.
Note:
The ERRET parameter is obsolete and is ignored by the system. Therefore, the syntax and parameter descriptions for STIMER no longer contain ERRET.
However, the system still accepts ERRET, and it is not necessary to delete it from existing code.
Chapter 97. STIMER — Set interval timer
947
STIMER macro
Parameters
The parameters are explained as follows:
REAL
REAL,exit rtn addr
TASK
TASK,exit rtn addr
WAIT
Specifies whether the timer interval is a real-time interval (REAL or WAIT) or a task-time interval (TASK). You must specify one of these parameters.
For REAL, the interval is decreased continuously. If the TOD, GMT, or LT parameter is coded, the interval expires at the indicated time of day.
For TASK, the interval is decreased only when the associated task is running.
For WAIT, the interval is decreased continuously. The task is to be placed in the wait condition until the interval expires.
The exit rtn addr is the address of the timer completion exit routine to be given control after the specified time interval expires. The routine does not get control immediately when the interval completes, but at some time after the interval completes, depending on the system's work load and the relative dispatching priority of the associated task. The routine must be in virtual storage when it is required. The exit routine receives control in the same environment that the caller had when the caller issued the STIMER macro. The contents of the registers when the exit routine is given control are as follows:
Register
Contents
0-12
13
14
15
Do not contain any information for use by the routine.
Address of a system-provided, 72-byte save area.
Return address (to the system).
Address of the exit routine.
The exit routine is responsible for saving and restoring registers. The exit routine runs as a subroutine, and must return control to the address identified in register 14. Although timing services allows only one active time interval for a task, it does not serialize the use of an asynchronous timer completion exit routine.
,BINTVL=stor addr
,DINTVL=stor addr
,GMT=stor addr
,MICVL=stor addr
,TOD=stor addr
,TUINTVL=stor addr
,LT=stor addr
Specifies the storage address and format for the time of day, or time interval, to be set. You must specify one of these parameters.
For BINTVL, the address is a 4-byte area containing the time interval. The time interval is represented as an unsigned 32-bit binary number; however, the high-order bit of the time interval must not be set. Therefore, the time interval specified cannot exceed X'7FFFFFFF'. The low-order bit of the time interval has a value of 0.01 second.
948
z/OS MVS Assembler Services Reference IAR-XCT
STIMER macro
For DINTVL, the address is a doubleword in virtual storage containing the time interval. The time interval is presented as zoned decimal digits of the form:
HHMMSSth, where:
HH
is hours (24-hour clock)
t h
MM
is minutes
SS
is seconds is tenths of seconds is hundredths of seconds
For GMT, the address is an 8-byte area containing the Greenwich mean time at which the interval is to be completed. The time is presented as zoned decimal digits of the form HHMMSSth, as described above under DINTVL.
For MICVL, the address is a doubleword containing the time interval. The time interval is represented as an unsigned 64-bit binary number; bit 51 is the low-order bit of the interval value and equivalent to 1 microsecond.
For TUINTVL, the address is a fullword containing the time interval. The time interval is presented as an unsigned 32-bit binary number; the low-order bit has a value of one timer unit (approximately 26.04166 microseconds).
For TOD and LT, the address is a doubleword containing the local time of day at which the interval is to be completed. The time is presented as zoned decimal digits of the form HHMMSSth, as described under DINTVL.
The LT and TOD parameters perform identical functions. However, the name for the LT parameter (LT, or local time) describes the function more accurately than does the name for the TOD parameter (TOD, or time-of-day). Therefore, for clarity purposes, IBM recommends the use of the LT parameter instead of
TOD.
Note:
For the DINTVL, GMT, TOD, and LT parameters, the zoned decimal digits are not checked for validity. Thus, the specification of incorrect digits can result in an X'0C7' abend, or a time interval different from that desired.
Note:
1.
The time interval specified by an STIMER macro has no relation to the time interval specified in an EXEC statement.
2.
If no exit routine address is specified, there is no indication of completion except when WAIT is specified.
3.
The TTIMER and CPUTIMER macros provide a facility for determining the remaining time interval associated with STIMER.
The priorities of other tasks in the system can also affect the accuracy of the time interval measurement. If you code REAL or WAIT, the interval is decreased continuously and can expire when the task is not active. After the time interval expires, assuming the task is not in the wait condition for any other reasons, the task is placed in the ready condition and competes for control with the other ready tasks in the system. The additional time required before the task becomes active depends on the relative dispatching priority of the task.
Chapter 97. STIMER — Set interval timer
949
STIMER macro
ABEND codes
STIMER might abnormally terminate with one the following abend codes: X'12F'
(with reason code X'0', X'4', X'C', X'10', X'14', X'28'), or X'AC7' (with reason code
X'2'). See z/OS MVS System Codes for an explanation and response for these codes.
Return and reason codes
STIMER returns a return code of 0 in register 15.
Examples
Example 1
: Request the installation's asynchronous exit routine, located at location
EXIT, to receive control after fourteen hundredths of a second (specified by
INTVLONG) have elapsed in real time.
STIMER REAL,EXIT,BINTVL=INTVLONG
.
.
INTVLONG DC F ’14’ TIME INTERVAL
Example 2
: Request that this task's exit routine, located at location EXIT, receive control when the local time of day specified at location LOCAL occurs.
STIMER REAL,EXIT,LT=LOCAL
.
.
LOCAL DS 2F
Example 3
: Request that this task be put into a wait state until 60 seconds have passed.
STIMER WAIT,BINTVL=INTV2
.
.
INTV2 DC F’6000’
Example 4
: Request that this task's exit routine, located at location EXIT, receive control when the task has executed 60 seconds.
STIMER TASK,EXIT,BINTVL=INTV1
.
.
INTV1 DC F’6000’
950
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 98. STIMERM — Set, test, cancel multiple interval timer
Description
The STIMERM macro: v Sets a timer to a specified time interval (SET parameter) v Tests the remaining time interval for a timer request (TEST parameter) v Cancels a specific timer request (CANCEL parameter)
The SET request sets a timer to a specified time interval or to an interval that will expire at a specified time of day.
v A program that is problem state and key 8-15 may not set an STIMERM, if there are currently 16 or more requests in effect for the issuing task.
v A program that is supervisor state or key 0-7 may not set an STIMERM, if there are currently 128 requests in effect for the issuing task.
The time interval is a real-time interval, measured continuously. The task can continue (WAIT=NO) or suspend execution (WAIT=YES). If the task continues execution, it can pass control to an exit routine (EXIT parameter) when the time interval is complete. If you specify an exit routine, the task can optionally pass a parameter to the exit routine (PARM parameter). The task grants control to the optional asynchronous timer completion exit when the time interval expires. If the task did not specify either an asynchronous timer completion routine or
WAIT=YES, the task receives no indication that the time interval has expired.
The TEST request tests the remaining time interval for a timer request established through the SET parameter. The ID parameter identifies the particular timer request to be tested and must be established by the current task.
The CANCEL request cancels a specific timer request or all of the current task's timer requests that were established through the SET parameter. The ID parameter identifies the timer request or requests of the current task to be cancelled. If the macro cancels a specific timer request, it may return the remaining time interval for that request to a storage area designated by the TU (Timer Units) or MIC
(Microseconds) parameters.
On the TEST and CANCEL requests, the TU and MIC parameters specify the location where the system returns the remaining time: v If you specify TU, the STIMERM macro returns the amount of time remaining to the designated 4-byte storage area as an unsigned 32-bit binary number containing the number of timer units (approximately 26.04166 microseconds per unit) remaining in the interval.
v If you specify MIC, the STIMERM macro returns the remaining time to the designated 8-byte storage area. Bit 51 of the area is the low-order bit of the interval value and is equivalent to approximately one microsecond.
If the specified timer request does not exist for the current task, or if the timer request exists but has expired, the system sets to zero the storage area designated by TU or MIC.
© Copyright IBM Corp. 1988, 2017
951
STIMERM macro
When you cancel a timer request that specified a timer exit, specify TU or MIC to determine whether the cancel operation was successful: v
If STIMERM returned a value of zero to the storage area designated by TU or
MIC, then any associated timer exit has run or will run because its interval expired before the cancel operation completed.
v If STIMERM returned a non-zero value to the storage area designated by TU or
MIC, then the timer interval was cancelled and any associated timer exit will not run.
It is your responsibility to set up your program to determine whether the timer exit has run. For information about interval timing, see z/OS MVS Programming:
Assembler Services Guide.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
24- or 31- or 64-bit
Primary
Enabled for I/O or external interrupts
No locks held.
Must be in the primary address space.
Programming requirements
v All input and output addresses are treated as full 31-bit addresses.
v The parameter lists may be above or below 16 megabytes.
v There is no interaction between the TTIMER macro support and the STIMERM macro support or between the STIMER macro support and the STIMERM macro support.
v If the STIMERM macro service cannot access the macro parameter list or any in-storage parameters, the system abnormally ends the calling program whether or not it specified an ERRET routine.
Restrictions
No enabled, unlocked task (EUT) FRRs may be established.
For SET requests: v If you specify a time of day at which the interval will expire (GMT, LT, or TOD parameters), the time of day you specify must not exceed 24:00:00.00; otherwise, you receive a X'32E' abend unless you specify ERRET.
v If you specify a time interval on the MICVL parameter, the interval you specify, when added to the current TOD clock contents, must not exceed the maximum value for the clock comparator (X'FFFFFFFFFFFFFFFF'); otherwise, you receive a
X'32E' abend unless you specify ERRET.
v The time interval specified by a STIMERM macro has no relation to the time interval specified in an EXEC statement.
v
You can issue STIMERM with a timer completion exit routine and, within that routine, you can issue STIMERM and specify the same timer completion exit routine. Under these circumstances, IBM recommends that you specify a time
952
z/OS MVS Assembler Services Reference IAR-XCT
�
Syntax
name
STIMERM macro
interval rather than a time of day on the STIMERM you issue within the timer completion exit routine. If you specify a time of day, it is possible for the timer completion exit routine to receive control later than the time of day you specified, resulting in a infinite loop.
v The time interval you specify on the BINTVL parameter must not exceed
X'7FFFFFFF'. If the time interval exceeds X'7FFFFFFF', your program receives a
X'32E' abend unless you use the ERRET parameter to specify a recovery routine.
v No enabled, unlocked task (EUT) FRRs can be established.
TEST and CANCEL requests have no restrictions.
Input register information
Before issuing the STIMERM macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service and restore them after the system returns control.
Performance implications
Syntax
The standard form of the STIMERM macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede STIMERM.
Chapter 98. STIMERM — Set, test, cancel multiple interval timer
953
STIMERM macro
Syntax
STIMERM
�
SET
TEST
CANCEL
,ID=stor addr
,ID=ALL
,TU=stor addr
,MIC=stor addr
,BINTVL=stor addr
,DINTVL=stor addr
,MICVL=stor addr
,GMT=stor addr
,TUINTVL=stor addr
,TOD=stor addr
,LT=stor addr
,ERRET=err rtn addr
,EXIT=exit rtn addr
,PARM=stor addr
Description
One or more blanks must follow STIMERM.
Valid parameters (Required parameters are underlined)
For SET
: ID, BINTVL or DINTVL or GMT or MICVL or TOD or TUINTVL or LT, ERRET, WAIT, EXIT, PARM, RELATED
For TEST
: ID, TU or MIC, ERRET, RELATED
For CANCEL
: ID, TU or MIC, ERRET, RELATED
stor addr: RX-type address or register (2) - (12).
Note
: ID=ALL is only valid on the CANCEL request.
stor addr: RX-type address or register (2) - (12).
stor addr: RX-type address or register (2) - (12).
err rtn addr: RX-type address or register (2) - (12).
exit rtn addr: RX-type address or register (2) - (12).
Note
: EXIT must not be specified if WAIT=YES is specified.
stor addr: RX-type address or register (2) - (12).
Note
: If PARM is specified, EXIT must be specified and WAIT=YES must not be specified.
Default
: WAIT=NO ,WAIT=YES
,WAIT=NO
,RELATED=value
Parameters
The parameters are explained as follows:
SET
954
z/OS MVS Assembler Services Reference IAR-XCT
STIMERM macro
TEST
CANCEL
Request to establish, return, or cancel a real-time interval. You must specify one of these parameters.
SET indicates a request to establish a real-time interval.
TEST indicates a request to return the remaining time for a request made using the SET parameter.
CANCEL indicates a request to cancel and optionally return the remaining time for a timer request.
If the CANCEL parameter specifies (through ID=) a timer request that was established with the WAIT=YES parameter, the task will still remain in the wait condition.
,ID=stor addr
,ID=ALL
Specifies the address of a 4-byte area containing the identifier assigned to a particular timer request by the timer service routine. When you specify
STIMERM SET, the ID is returned in the 4-byte area. Specify this ID on
STIMERM TEST or STIMERM CANCEL. ID=ALL, valid only on STIMERM
CANCEL, cancels all the current task's timer requests as established by
STIMERM SET. If you specify ID=ALL, the system does not return a remaining time interval. Do not specify MIC or TU with ID=ALL.
,TU=stor addr
,MIC=stor addr
Specifies that the remaining time in the interval be returned to the 4-byte or
8-byte area specified in stor addr. TU or MIC is required for STIMERM TEST and is optional for STIMERM CANCEL (providing you do not also specify
ID=ALL). TU and MIC are mutually exclusive.
For TU, the time is returned to the specified 4-byte area as an unsigned 32-bit binary number. The low-order bit is approximately 26.04166 microseconds (one timer unit). If the time remaining is too great to be expressed in 4 bytes, the remaining time interval is set to the maximum possible value (X'FFFFFFFF') and the return code is set to 4.
For MIC, the time is returned to the specified 8-byte area as microseconds. The
8-byte area stores the remaining interval, which is represented as an unsigned
64-bit binary number; bit 51 is equivalent to one microsecond.
,BINTVL=stor addr
,DINTVL=stor addr
,GMT=stor addr
,MICVL=stor addr
,TUINTVL=stor addr
,TOD=stor addr
,LT=stor addr
Specifies the storage address and format of the time of day, or time interval, to be set. You must specify one of these parameters.
For BINTVL, the address is a 4-byte area containing the time interval. The time interval is represented as an unsigned 32-bit binary number; however, the high-order bit of the time interval must not be set. Therefore, the time interval specified cannot exceed X'7FFFFFFF'. The low-order bit of the time interval has a value of 0.01 second.
Chapter 98. STIMERM — Set, test, cancel multiple interval timer
955
STIMERM macro
For DINTVL, the address is an 8-byte area in virtual storage containing the time interval. The time interval is represented as zoned decimal digits of the form:
HHMMSSth, where:
HH
is hours
t h
MM
is minutes
SS
is seconds is tenths of seconds is hundredths of seconds
For GMT, the address is an 8-byte area containing the Greenwich mean time at which the interval will complete. The time is represented as zoned decimal digits of the form HHMMSSth, as described previously under DINTVL.
For MICVL, the address is an 8-byte storage area containing the time interval.
The time interval is represented as an unsigned 64-bit binary number; bit 51 is the low-order bit of the interval value and equivalent to one microsecond.
For TUINTVL, the address is a 4-byte area containing the time interval. The time interval is represented as an unsigned 32-bit binary number; the low-order bit has a value of one timer unit (approximately 26.04166
microseconds).
For TOD and LT, the address is an 8-byte storage area containing the local time of day at which the interval is to be completed. The time of day is represented as zoned decimal digits of the form HHMMSSth, as described previously under DINTVL.
The LT and TOD parameters perform identical functions. However, the name for the LT parameter (LT or local time) describes the function more accurately than does the name for the TOD parameter (TOD or time-of-day). Therefore, for clarity purposes, IBM recommends the use of the LT parameter instead of
TOD.
Notes on setting the time interval
: For the DINTVL, GMT, TOD, and LT parameters, the zoned decimal digits are not checked for validity. Thus, specifying invalid digits can cause a X'0C7' abend or an undesired time interval.
,ERRET=err rtn addr
Specifies the address of the routine to receive control when the STIMERM function cannot be performed. If you omit this parameter and your program encounters an error, the system abnormally ends your program. The specified error routine will be entered in the addressing mode and environment of the
STIMERM invoker.
When the routine receives control, the register contents are:
Register
Contents
0
1
2-13
Address of a 24-byte STIMERM parameter list.
Does not contain any information for use by the routine.
14
The contents are the same as they were when the caller issued
STIMERM.
Return address.
956
z/OS MVS Assembler Services Reference IAR-XCT
STIMERM macro
15
Return code.
If the macro parameter list or any in-storage parameters are not accessible, the system abnormally ends your program regardless of whether or not you specified ERRET. No error routine will receive control.
,EXIT=exit rtn addr
Specifies the address of an exit routine that will gain asynchronous control after the requested timer interval expires. The system's workload and the relative dispatching priority of the associated task determine exactly when, after the interval completes, the exit routine gets control. The specified exit routine will be entered in the environment of the STIMERM invoker. It will be entered in AMODE 24 if the STIMERM invoker was AMODE 24, and it will be entered in AMODE 31 if the STIMERM invoker was either AMODE 31 or
AMODE 64. If you specify WAIT=YES, you must not specify the EXIT parameter.
Exit Routine Interface:
The timer exit routine, established with the EXIT parameter in the STIMERM macro, receives control with the following register values:
R0 -
Does not contain any information for use by the routine
R1 -
Points to an 8-byte fetch-protected storage area below 16 megabytes and in the protect key of the program that issued the STIMERM SET macro
R1
Word 1 TIMER REQUEST ID
Word 2 USER PARAMETER (specified in the PARM keyword)
R2-R12 -
Do not contain any information for use by the routine
R13 -
Address of a 72-byte save area provided by the system
R14 -
Return address (to the system)
R15 -
Address of the exit routine
The exit routine receives control in the addressing mode of the STIMERM issuer. If multiple asynchronous exits are established, the exit routines may not receive control in the same order that the intervals expire.
,PARM=stor addr
Specifies the address of a 4-byte parameter that the exit routine receives when the requested timer interval expires. You must not specify PARM=stor addr if you specified WAIT=YES. If you specify PARM=stor addr, you must also specify EXIT=exit rtn addr.
An exit routine will be unable to distinguish between the case where PARM= was not specified and the case where the specified PARM value was zero.
,WAIT=YES
,WAIT=NO
Specifies whether the task should be suspended until the requested time interval expires. WAIT=YES specifies that the task should be suspended until the requested time interval expires. If you specify WAIT=NO without specifying EXIT, you will receive no indication when the timer expires.
WAIT=NO is the default.
Chapter 98. STIMERM — Set, test, cancel multiple interval timer
957
STIMERM macro
,RELATED=value
Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the specified information are at your discretion and may be any valid macro keyword expression.
ABEND codes
On STIMERM SET requests: v X'32E'
Abend code X'32E' might yield the following reason codes:
– X'10C'
– X'110'
– X'11C'
– X'120'
– X'128' v X'AC7'
Abend code X'AC7' might yield the following reason code:
– X'2'
On STIMERM TEST requests: v X'32E'
Abend code X'32E' might yield the following reason codes:
– X'210'
– X'220'
– X'224'
On STIMERM CANCEL requests: v X'32E'
Abend code X'32E' might yield the following reason codes:
– X'310'
– X'320'
– X'324'
See z/OS MVS System Codes for explanations and programmer responses for these codes.
Return codes
When control is returned, register 15 contains one of the following hexadecimal return codes. Note that for non-zero return codes, the ERRET routine receives control (if you specified ERRET). If you did not specify ERRET, a non-zero return code causes the STIMERM invoker to end abnormally.
Table 55. Return Codes for the STIMERM Macro
Hexadecimal
Return Code
00
Meaning and Action
Meaning
: The STIMERM service has completed successfully.
Action
: None.
958
z/OS MVS Assembler Services Reference IAR-XCT
STIMERM macro
Table 55. Return Codes for the STIMERM Macro (continued)
Hexadecimal
Return Code
04
Meaning and Action
Meaning
: For TEST and CANCEL requests, the time remaining is too great to be expressed in 4 bytes. The maximum value (X'FFFFFFFF') is returned.
0C
10
Action
: None required. However, you might take some action based upon your application.
Meaning
: Program error. For SET requests, the GMT, LT, or TOD at which the interval is to complete exceeds 24:00:00.00.
Action
: Specify a time of day value that is less than or equal to 2400 hours.
Meaning
: Program error. Parameters passed to STIMERM are not valid.
1C
24
28
Action
: Ensure that all input parameters are valid.
Meaning
: Program error. The request would cause the limit of concurrent STIMERM SET requests for a task to be exceeded.
Action
: Change your application logic so that fewer STIMERM requests are required.
Meaning
: Program error. The specified STIMERM ID number was zero, which is not valid.
Action
: Ensure that the input ID is a valid value.
Meaning
: Program error. For SET requests, either you specified a time interval on the MICVL parameter that, when added to the current TOD clock contents, exceeds the maximum value for the clock comparator
(X'FFFFFFFFFFFFFFFF') or you specified a value greater than
X'7FFFFFFF' for BINTVL.
Action
: Request a smaller time interval.
Example 1
SET a timer to a specified time interval. Specify: v The address of a 4-byte area in which the identifier assigned by the timer service to this request will be returned v That control should be given to an asynchronous timer completion exit named
TIME, when the time interval expires v The address of a 4-byte area (containing the time interval of 32 hundredths of seconds) named INTERVAL. Include an error exit routine named ERROR.
STIMERM SET,ID=ADDRESS,BINTVL=INTERVAL,EXIT=TIME,ERRET=ERROR
ADDRESS DS F ID RETURNED
INTERVAL DC X’00000020’ TIME INTERVAL
Example 2
SET a timer to a time interval that specifies the address of a 4-byte area in which the identifier assigned by timer service will be returned. Specify the address of an
8-byte area named INTERVAL that contains the Greenwich mean time at which the interval is to be completed (2:06 PM). Specify that the task should be suspended until the requested time interval expires. Include an error exit routine named
EXITX.
Chapter 98. STIMERM — Set, test, cancel multiple interval timer
959
STIMERM macro
STIMERM SET,ID=ADDRESS,GMT=INTERVAL,WAIT=YES,ERRET=EXITX
ADDRESS DS F ID RETURNED
INTERVAL DC X’F1F4F0F6F0F0F0F0’ EXPIRATION TIME OF DAY
Example 3
SET a timer to a time interval that specifies the address of a 4-byte area in which the identifier assigned by timer service will be returned. Specify the address of an
8-byte area in register 8 that contains the time interval (represented as zoned decimal digits). Specify, in register 10, the address of the exit routine that will gain control asynchronously when the requested time interval expires. Specify the address of a 4-byte parameter to be passed to the exit routine when the requested time interval expires. Include the address of an exit error routine in register 9.
STIMERM SET,ID=(7),DINTVL=(8),PARM=USERDATA,ERRET=(9),EXIT=(10)
USERDATA DC CL4’ABCD’ PARAMETER PASSED TO EXIT ROUTINE
Example 4
Test the remaining time interval for a timer request established with the SET parameter, specifying (in register 4) the address of a 4-byte area from which the identifier assigned by the timer service will be obtained. Specify that the time be returned as an unsigned 32-bit binary number in a 4-byte area called INTERVAL.
Include the address of an exit error routine called XYZ.
STIMERM TEST,ID=(4),TU=INTERVAL,ERRET=XYZ
INTERVAL DS XL4 REMAINING TIME
Example 5
Test the remaining time interval for a timer request established with the SET parameter, specifying the address of a 4-byte area from which the identifier assigned by the timer service will be obtained. Specify that the time be returned in microseconds in an 8-byte area called INTERVAL. Include the address of an exit error routine called ERRORADD.
ADDR
STIMERM TEST,ID=ADDR,MIC=INTERVAL,ERRET=ERRORADD
DS F
INTERVAL DS XL8
ID TO BE TESTED
REMAINING TIME
Example 6
Cancel a timer request established with a SET parameter, specifying the address of a 4-byte area named ADDRESS containing the identifier assigned by the timer service. The time interval remaining should be returned as an unsigned 32-bit binary number in a 4-byte area called INTERVAL. An exit error routine named
ERROR is also specified.
STIMERM CANCEL,ID=ADDRESS,TU=INTERVAL,ERRET=ERROR
ADDRESS DS F ID TO BE CANCELLED
INTERVAL DS XL4 REMAINING TIME
Example 7
Cancel a timer request established with a SET parameter, specifying the address of a 4-byte area named PLACE containing the identifier assigned by the timer service.
The time interval remaining should be returned in an 8-byte area called
INTERVAL. An exit error routine named EXITA is also specified.
PLACE
STIMERM CANCEL,ID=PLACE,MIC=INTERVAL,ERRET=EXITA
DS F
INTERVAL DS XL8
ID TO BE CANCELLED
REMAINING TIME
960
z/OS MVS Assembler Services Reference IAR-XCT
STIMERM macro
Example 8
Cancel all the timer requests established with STIMERM SET for the current task.
STIMERM CANCEL,ID=ALL
STIMERM—List form
Use the list form of the STIMERM macro together with the execute form of the macro for applications that require reentrant code. The list form of the macro defines an area of storage, which the execute form of the macro uses to store the parameters.
Syntax
Syntax
The list form of the STIMERM macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede STIMERM.
STIMERM
� One or more blanks must follow STIMERM.
SET
TEST
CANCEL
,MF=L
,RELATED=value
Parameters
The parameters are explained as follows:
,MF=L
Specifies the list form of the STIMERM macro. If you do not specify MF=L, the standard form of the macro is expanded. If you do specify MF=L, the only keyword allowed is RELATED.
Example 1
Establish a remote STIMERM SET parameter list.
REMOTE STIMERM SET,MF=L
Chapter 98. STIMERM — Set, test, cancel multiple interval timer
961
STIMERM macro
Example 2
Establish a remote STIMERM TEST or CANCEL parameter list.
STIMERM TEST,MF=L
Example 3
Establish the appropriate storage for the execute form of the STIMERM CANCEL macro.
STIMERM CANCEL,MF=L
STIMERM - Execute form
Use the execute form of the STIMERM macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Syntax
Syntax
The execute form of the STIMERM macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede STIMERM.
STIMERM
�
SET
TEST
CANCEL
,ID=stor addr
,ID=ALL
,TU=stor addr
,MIC=stor addr
,BINTVL=stor addr
,DINTVL=stor addr
,GMT=stor addr
,MICVL=stor addr
,TOD=stor addr
,TUINTVL=stor addr
,LT=stor addr
One or more blanks must follow STIMERM.
Valid parameters (Required parameters are underlined)
For SET
: ID, BINTVL or DINTVL or GMT or MICVL or TOD or TUINTVL or LT, ERRET, WAIT, EXIT, PARM, RELATED
For TEST
: ID, TU or MIC, ERRET, RELATED
For CANCEL
: ID, TU or MIC, ERRET, RELATED
stor addr: A-type address or register (2) - (12).
Note
: ID=ALL is valid only on the CANCEL request.
stor addr: A-type address or register (2) - (12).
stor addr: A-type address or register (2) - (12).
962
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,ERRET=err rtn addr
,WAIT=YES
,WAIT=NO
,EXIT=exit rtn addr
,PARM=stor addr
STIMERM macro
Description
err rtn addr: A-type address or register (2) - (12).
Default
: WAIT=NO
exit rtn addr: A-type address or register (2) - (12).
Note
: EXIT must not be specified if WAIT=YES is specified.
stor addr: A-type address or register (2) - (12).
Note
: If PARM is specified, EXIT must be specified and WAIT=YES must not be specified.
ctrl addr: A-type address or register (0), (2)-(12) for TEST and CANCEL, register (1)-(12) for SET.
,MF=(E,ctrl addr)
,RELATED=value
Parameters
The parameters are explained in the standard form of the STIMERM macro, with the following exception.
,MF=(E,ctrl addr)
Specifies the execute form of the STIMERM macro using a remote problem-program parameter list.
Example 1
Set a timer to a time interval of 15 microseconds, specifying the address of a 4-byte area in which the identifier assigned to this request by timer service will be returned. Specify: v The address of an 8-byte area in INTERVAL that contains the time interval
(represented as an unsigned 64-bit binary number) v The address of a program to receive asynchronous control after the requested timer interval expires v The address of a 4-byte parameter to be passed to the exit routine when the requested time interval expires v The address of the appropriate parameter list in REMOTE
Include the address of an error routine in register 9.
STIMERM SET,ID=(4),MICVL=(INTERVAL),EXIT=ROUTE,PARM=DATA,
MF=(E,REMOTE),ERRET=(9)
DATA DC CL4’WXYZ’ PARAMETER PASSED TO THE EXIT ROUTINE
INTERVAL DC X’000000000000F000’ TIME INTERVAL
X
Example 2
Test the remaining time interval for a timer request established with the SET parameter, specifying the address of a 4-byte area from which the identifier
Chapter 98. STIMERM — Set, test, cancel multiple interval timer
963
STIMERM macro
assigned by timer service will be obtained. Specify that register 3 will point to the appropriate list. Specify that the time be returned in microseconds in an 8-byte area at the address named INTERVAL. Include the address of an exit error routine called ERR.
STIMERM TEST,ID=ADDR,MIC=INTERVAL,MF=(E,(3)),ERRET=ERR
INTERVAL DS XL8 REMAINING TIME
Example 3
Cancel the timer request established with a SET parameter. Specify the address of a
4-byte identifier (assigned by timer service) named ADDRESS and that the time interval remaining be returned as an unsigned binary number in a 4-byte area named INTERVAL. Specify that register 0 will point to the appropriate list. Specify an error exit routine named ERROR.
STIMERM CANCEL,ID=ADDRESS,TU=INTERVAL,MF=(E,(0)),ERRET=ERROR
ADDRESS DS F ID TO BE CANCELLED
INTERVAL DS XL4 REMAINING TIME
964
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 99. STORAGE — Obtain and release storage
||
Description
The STORAGE macro requests that the system obtain or release an area of virtual storage in the primary address space. The two functions of the macro are: v STORAGE OBTAIN, which obtains virtual storage in an address space v STORAGE RELEASE, which releases virtual storage in an address space.
If you use STORAGE OBTAIN to request real storage backing above 2 gigabytes, but your system does not support 64-bit storage, your request will be treated as a request for backing above 16 megabytes, even on earlier releases of z/OS that do not support backing above 2 gigabytes. However, boundary requirements indicated by the CONTBDY and STARTBDY parameters will be ignored by earlier releases of z/OS.
Environment
The requirements on the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
RMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
For subpools 0-127: problem state and PSW key 8-15.
For subpools 131 and 132: a PSW key mask (PKM) that allows the calling program to switch its PSW key to match the key of the storage to be obtained or released.
Task
Any PASN, any HASN, any SASN
24- or 31- or 64-bit
Includes 64-bit
For LINKAGE=SYSTEM: Primary or AR
For LINKAGE=SVC: Primary
Enabled for I/O and external interrupts
No locks held.
No requirement.
Programming requirements
None.
Restrictions
None.
Register information
Register usage varies depending on the type of STORAGE request. For specific information, see the descriptions of STORAGE OBTAIN and STORAGE RELEASE.
Performance implications
None.
© Copyright IBM Corp. 1988, 2017
965
STORAGE macro
|
|
|
|
OBTAIN option of STORAGE
The STORAGE macro with the OBTAIN parameter requests that the system allocate an area of virtual storage to the active task. Each virtual storage area begins on a doubleword or page boundary. The amount of storage you request must not exceed the amount available; the amount available depends on how much storage has already been allocated, and on your user region size. Valid subpools available for problem-state callers are 0 - 127, 129 - 132, 240, and 250 -
252. When a task terminates, the system frees any storage in subpools 0 - 127 which is allocated to the terminating task. The system does not free storage in subpools 131 and 132 until the job-step task terminates.
Note:
When you obtain storage, the system clears the requested storage to zeros if you obtain either: v
8192 bytes or more from a pageable, private storage subpool and
PAGEFRAMESIZE1M is not specified on the LOC keyword.
v 4096 bytes or more from a pageable, private storage subpool, with
BNDRY=PAGE or STARTBDY=12 specified and PAGEFRAMESIZE1M is not specified on the LOC keyword..
In all other cases, you must not assume that the storage is cleared to zeros.
The caller can specify CHECKZERO=YES to detect these and other cases where the system clears the requested storage to zeros.
Input register information for LINKAGE=SYSTEM
Before issuing the STORAGE macro with the OBTAIN parameter, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information for LINKAGE=SYSTEM
When control returns to the caller, the general-purpose registers (GPRs) contain:
Register
Contents
0
For a successful request in which maximum and minimum lengths were specified, contains the length of the storage obtained. Otherwise, used as a work register by the system.
1
The address of the allocated storage when STORAGE OBTAIN is successful; otherwise, used as a work register by the system.
2-13
14
15
Note:
A successful STORAGE OBTAIN returns a 64-bit pointer to the obtained area (bits 0-32 is zero).
Unchanged.
Used as a work register by the system.
For a conditional request, contains the return code. For an unconditional request, which is used as a work register by the system.
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0
Used as work registers by the system.
966
z/OS MVS Assembler Services Reference IAR-XCT
STORAGE macro
1
0 when the STORAGE OBTAIN is successful; otherwise, used as work register by the system.
2-13
Unchanged
14-15
Used as work registers by the system.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the service returns control.
Input register information for LINKAGE=SVC
Before issuing the STORAGE macro with the OBTAIN parameter, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information for LINKAGE=SVC
When control returns to the caller, the general-purpose registers (GPRs) contain:
Register
Contents
0
For a successful request in which maximum and minimum lengths were specified, contains the length of the storage obtained. Otherwise, used as a work register by the system.
1
The address of the allocated storage when STORAGE OBTAIN is successful; otherwise, used as a work register by the system.
2-13
14
15
Note:
A successful STORAGE OBTAIN returns a 64-bit pointer to the obtained area (bits 0-32 is zero).
Unchanged.
Used as a work register by the system.
Contains the return code.
When control returns to the caller, the access registers (ARs) contain:
0
1
Register
Contents
Used as work registers by the system.
0 when the STORAGE OBTAIN is successful; otherwise, used as work register by the system.
2-13
Unchanged
14-15
Used as work registers by the system.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the service returns control.
Chapter 99. STORAGE — Obtain and release storage
967
STORAGE macro
Syntax
Syntax
The STORAGE macro with the OBTAIN parameter is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede STORAGE.
STORAGE
� One or more blanks must follow STORAGE.
OBTAIN
,LENGTH=length value
,LENGTH=(max amount,min amount)
,ADDR=stor addr
,INADDR=stor addr
,SP=subpool number
length value: Symbol, decimal number, or register (0),
(2) - (12).
max amount: Symbol, decimal number, or register (0),
(2) - (12).
min amount: Symbol, decimal number, or register (1) -
(12).
stor addr: RX-type address or register (1) - (12).
Default
: ADDR=(1).
stor addr: RX-type address or register (1)-(12).
Note
: This parameter can only be specified with
LOC=EXPLICIT.
subpool number: Symbol, decimal number 0-127, 131,
132, or register (2) - (12), (15). Default: SP=0.
,BNDRY=DBLWD
,BNDRY=PAGE
,CONTBDY=containing_bdy
,STARTBDY=starting_bdy
,KEY=key number
Default
: BNDRY=DBLWD
containing_bdy: Decimal number 3-31 or register (2) -
(12).
starting_bdy: Decimal number 3-31 or register (2) -
(12).
key number: Decimal number 0-15 or register (2) - (12).
Note
: KEY is valid only when you also specify SP.
You cannot specify both KEY and CALLRKY=YES.
Default
: CALLRKY=NO ,CALLRKY=NO
968
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,CALLRKY=YES
,LOC=24
,LOC=(24,31)
,LOC=(24,64)
,LOC=31
,LOC=(31,31)
,LOC=(31,64)
,LOC=(31,PAGEFRAMESIZE1MB)
,LOC=RES
,LOC=(RES,31)
,LOC=(RES,64)
,LOC=EXPLICIT
,LOC=(EXPLICIT,24)
,LOC=(EXPLICIT,31)
,LOC=(EXPLICIT,64)
,LOC=(EXPLICIT,PAGEFRAMESIZE1MB)
,LINKAGE=SYSTEM
,LINKAGE=SVC
,RTCD=rtcd addr
|
,COND=YES
,COND=NO
,CHECKZERO=YES
,CHECKZERO=NO
,BACK=BYSPT
,BACK=NONE
,BACK=ALL
,FIX=NONE
,FIX=SHORT
,FIX=LONG
,EXECUTABLE=YES
STORAGE macro
Description
Notes
: You cannot specify both CALLRKY=YES and
KEY.
Valid only with LINKAGE=SYSTEM.
Default
: LOC=RES
Note
: You must specify the INADDR parameter with
EXPLICIT.
Default
: LINKAGE=SYSTEM
rtcd addr: RX-type address, register (15), or register (2) - (12). Default: RTCD=(15).
Default
: COND=NO
Default
: CHECKZERO=NO
Default
: BACK=BYSPT
Default
: FIX=NONE
Default:
EXECUTABLE=YES
Chapter 99. STORAGE — Obtain and release storage
969
STORAGE macro
|
Syntax
,EXECUTABLE=NO
,RELATED=value
Description
value: Any valid macro parameter specification.
Parameters
The parameters are explained as follows:
OBTAIN
Requests that the system obtain virtual storage.
,LENGTH=length value
,LENGTH=(max amount,min amount)
Specifies the amount of storage the system is to obtain. length value specifies the length, in bytes, of the requested virtual storage. max length and min length specify the maximum and minimum amounts of storage. These numbers should be a multiple of 8; if they are not, the system uses the next higher multiple of 8.
If you specify LENGTH=(max amount,min amount), the system returns a value in general-purpose register 0 to tell you the amount of storage it obtained.
,ADDR=stor addr
Specifies the location where the system returns the address of the storage it allocates.
,INADDR=stor addr
Specifies the desired virtual address for the storage to be obtained. When you specify INADDR, you must specify EXPLICIT on the LOC parameter.
Note:
1.
The address specified on INADDR must be on a doubleword boundary.
2.
Make sure that the virtual storage address specified on INADDR and the central storage backing specified on the LOC=EXPLICIT parameter are a valid combination. For example, if the address specified on INADDR is for virtual storage above 16 megabytes, specify LOC=EXPLICIT or
LOC=(EXPLICIT,ANY). Valid combinations include: v Virtual above, central any v Virtual any, central any v Virtual below, central below v Virtual below, central any
,SP=subpool number
Specifies the subpool number for the storage. Valid subpools for programs in problem state are 0 - 127, 131, and 132. See the discussion of subpool handling in z/OS MVS Programming: Assembler Services Guide for information and requirements which pertain to specific subpools. If you specify a register, the subpool number must be in bits 24-31 of the register, with bits 0-23 set to zero.
If you omit this parameter, the system uses subpool 0.
,BNDRY=DBLWD
,BNDRY=PAGE
Specifies whether the storage is to be aligned on a doubleword boundary
(DBLWD) or a page boundary (PAGE). The default is BNDRY=DBLWD.
970
z/OS MVS Assembler Services Reference IAR-XCT
STORAGE macro
,CONTBDY=containing_bdy
Specifies the boundary that the obtained storage must be contained within.
Specify a power of 2 that represents the containing boundary. Supported values are 3-31. For example, CONTBDY=10 means that the containing boundary is 2**10, or 1024 bytes. The containing boundary must be at least as large as the maximum requested boundary. The obtained storage will not cross an address that is a multiple of the requested boundary.
If a register is specified, the value must be in bits 24-31 of the register. Do not specify CONTBDY on a variable-length request.
CONTBDY is not valid with LOC=EXPLICIT or BNDRY=PAGE.
CONTBDY applies to all subpools.
If you omit this parameter, there is no containing boundary.
,STARTBDY=starting_bdy
Specifies the boundary that the obtained storage must start on. Specify a power of 2 that represents the start boundary. Supported values are 3-31. For example,
STARTBDY=10 means the start boundary is 2**10, or 1024 bytes. The obtained storage will begin on an address that is a multiple of the requested boundary.
If a register is specified, the value must be in bits 24-31 of the register. Do not specify STARTBDY on a variable-length request.
STARTBDY is not valid with LOC=EXPLICIT or BNDRY=PAGE.
STARTBDY applies to all subpools.
If you omit this parameter, the start boundary is 8 bytes (equivalent to specifying STARTBDY=3).
,KEY=key number
Indicates the storage key of the storage to be obtained. You can obtain storage in your storage key or in key 9. If you pass the storage key in a register, it must be in bits 56-59 in that register. KEY is valid only when SP is specified, and applies to subpools 129 - 132, 227 - 231, 241, and 249. See the discussion of subpool handling in z/OS MVS Programming: Assembler Services Guide for information on system-assigned defaults and authorization requirements which pertain to specific subpools.
,CALLRKY=NO
,CALLRKY=YES
Specifies how the system assigns the key for the storage to be obtained:
CALLRKY=NO
The system assigns the value according to the specified subpool: v For subpools 129 - 132, 227 - 231, 241, and 249, the system assigns the value specified on the KEY parameter (or 0, if the KEY parameter is omitted) as the storage key v For subpools 0 - 127, the system assigns the value from the TCB key at the time of the first request to obtain storage. See the discussion of subpool handling in z/OS MVS Programming: Assembler Services
Guide for information on system-assigned defaults and authorization requirements which pertain to specific subpools.
v For all other subpools, the system ignores the CALLRKY parameter.
CALLRKY=YES
The system assigns the caller's current PSW key as the storage key.
When you specify CALLRKY=YES, do not also specify KEY. Specify
Chapter 99. STORAGE — Obtain and release storage
971
STORAGE macro
CALLRKY only when obtaining storage from subpools 129 - 132, 227 -
231, 241, 244, and 249. For all other subpools, the system ignores the
CALLRKY parameter.
The default is CALLRKY=NO.
CALLRKY is valid only with LINKAGE=SYSTEM.
,LOC=24
,LOC=(24,31)
,LOC=(24,64)
,LOC=31
,LOC=(31,31)
,LOC=(31,64)
,LOC=(31,PAGEFRAMESIZE1MB)
,LOC=RES
,LOC=(RES,31)
,LOC=(RES,64)
,LOC=EXPLICIT
,LOC=(EXPLICIT,24)
,LOC=(EXPLICIT,31)
,LOC=(EXPLICIT,64)
,LOC=(EXPLICIT,PAGEFRAMESIZE1MB)
Specifies the location of virtual storage and central (also called real) storage.
This is especially helpful for callers with 24-bit dependencies. When LOC is specified, central storage is allocated anywhere until the storage is fixed (for example, using the PGSER macro). You can specify the location of central storage (after the storage is fixed) and virtual storage (whether the storage is fixed) using the following LOC parameter values:
LOC=24 indicates that central and virtual storage is to be located below 16 megabytes. LOC=24 must not be used to allocate disabled reference (DREF) storage.
Note:
Specifying LOC=BELOW is the same as specifying LOC=24.
LOC=BELOW is still supported, but IBM recommends using LOC=24 instead.
LOC=(24,31) indicates that virtual storage is to be located below 16 megabytes and central storage can be located anywhere below 2 gigabytes.
Note:
Specifying LOC=(BELOW,ANY) is the same as specifying LOC=(24,31).
LOC=(BELOW,ANY) is still supported, but IBM recommends using
LOC=(24,31) instead.
LOC=(24,64) indicates that virtual storage is to be located below 16 megabytes and central storage can be located anywhere in 64-bit storage.
LOC=31 and LOC=(31,31) indicate that virtual and central storage can be located anywhere below 2 gigabytes.
Note:
Specifying LOC=ANY or LOC=(ANY,ANY) is the same as specifying
LOC =31 or LOC=(31,31). LOC=ANY and LOC=(ANY,ANY) are still supported, but IBM recommends using LOC=31 or LOC=(31,31) instead.
LOC=(31,64) indicates that virtual storage is to be located below 2 gigabytes and central storage can be located anywhere in 64-bit storage.
LOC=(31,PAGEFRAMESIZE1MB) locates virtual storage below 2 gigabytes and backs central storage anywhere in 64-bit storage, preferably by 1 MB page
972
z/OS MVS Assembler Services Reference IAR-XCT
STORAGE macro
frames. PAGEFRAMESIZE1MB is only allowed for user region low private unauthorized subpools 0-127, 131, and 132.
When you use LOC=RES to allocate storage that can reside either above or below 16 megabytes, LOC=RES indicates that the location of virtual and central storage depends on the location of the caller. If the caller resides below
16 megabytes, virtual and central storage is to be located below 16 megabytes.
If the caller resides above 16 megabytes, virtual and central storage is to be located either above or below 16 megabytes.
LOC=(RES,31) indicates that the location of virtual storage depends upon the location of the caller. If the caller resides below 16 megabytes, virtual storage is to be located below 16 megabytes; if the caller resides above 16 megabytes, virtual storage can be located anywhere below 2 gigabytes. In either case, central storage can be located anywhere below 2 gigabytes.
Note:
Specifying LOC=(RES,ANY) is the same as specifying LOC=(RES,31).
LOC=(RES,ANY) is still supported, but IBM recommends using LOC=(RES,31) instead.
LOC=(RES,64) indicates that the location of virtual storage depends upon the location of the caller. If the caller resides below 16 megabytes, virtual storage is to be located below 16 megabytes; if the caller resides above 16 megabytes, virtual storage can be located anywhere in 31-bit storage. In either case, central storage can be located anywhere in 64-bit storage.
Note:
If your program resides below 16 megabytes but runs with 31-bit addressing mode, you can specify LOC=RES (as a default or explicitly) or
LOC=(RES,31) to obtain storage from a subpool supported only above 16 MB.
Do not specify subpools supported only above 16 megabytes on requests using
LOC=RES or LOC=(RES,31) if your program resides below 16 megabytes and runs with 24-bit addressing.
LOC=EXPLICIT, LOC=(EXPLICIT,24), LOC=(EXPLICIT,31), or
LOC=(EXPLICIT,64) specify that the requested virtual storage is to be at the address which is specified with the INADDR parameter, which is required with EXPLICIT. EXPLICIT is valid only for subpools 0 - 127, 129 - 132, 240,
244, 250, 251, and 252. You cannot specify the BNDRY or LENGTH=(max
amount,min amount) parameter with EXPLICIT.
Note:
Specifying LOC=(EXPLICIT,BELOW) is the same as specifying
LOC=(EXPLICIT,24). Specifying LOC=(EXPLICIT,ANY is the same as specifying LOC=(EXPLICIT,31). The newer specifications are recommended, but the older specifications are still supported.
LOC=(EXPLICIT,31) indicates that virtual storage is to be at the address which is specified on the INADDR parameter, and central storage can be located anywhere below 2 gigabytes.
LOC=(EXPLICIT,24) indicates that virtual storage is to be at the address which is specified on the INADDR parameter, and central storage is to be located below 16 megabytes. The virtual storage address specified on the INADDR parameter must be below 16 megabytes.
LOC=EXPLICIT and LOC=(EXPLICIT,64) indicate that virtual storage is to be at the address specified on the INADDR parameter, and central storage can be located anywhere in 64-bit storage.
When you specify EXPLICIT on a request for storage from the same virtual page as previously requested storage, you must request it in the same key,
Chapter 99. STORAGE — Obtain and release storage
973
STORAGE macro
subpool, and central storage area as on the previous storage request. For example, if you request virtual storage backed with central storage below 16 megabytes, any subsequent requests for storage from that virtual page must be specified as LOC=(EXPLICIT,24).
LOC=(EXPLICIT,PAGEFRAMESIZE1MB) locates virtual storage at the address specified by the INADDR parameter and backs central storage anywhere in
64-bit storage, preferably by 1 MB page frames. PAGEFRAMESIZE1MB can be specified only for user region low private unauthorized subpools 0-127, 131, and 132.
,LINKAGE= SYSTEM
,LINKAGE=SVC
Specifies the type of entry linkage to be used.
LINKAGE=SYSTEM
The STORAGE OBTAIN macro receives control through PC entry.
LINKAGE=SVC
The STORAGE OBTAIN macro receives control through SVC entry.
,BACK=BYSPT
,BACK=NONE
,BACK=ALL
Specifies a preference for how much storage should be backed by real storage at the time the storage is obtained.
BACK=BYSPT
Storage should be backed by pageable storage subpools.
BACK=NONE
No storage should be backed.
BACK=ALL
All storage should be backed.
,FIX=NONE
,FIX=SHORT
,FIX=LONG
Indicates to the system the anticipated amount of time that the storage obtained by this STORAGE OBTAIN is fixed.
FIX=NONE
The storage will not be fixed.
FIX=SHORT
The amount of time anticipated for the FIX is short.
FIX=LONG
The amount of time anticipated for the FIX is long. (In general, the duration of a fix is long if it can be measured in seconds.)
,RTCD=rtcd addr
Specifies the location where the system is to store the return code. This parameter is valid only with COND=YES. The return code is also in GPR 15.
,COND=NO
,COND=YES
COND=YES specifies that the active unit of work should not be abnormally terminated if there is insufficient contiguous virtual storage to satisfy the request, and instead should return to the caller with a nonzero return code.
Use of COND=YES does not prevent all abnormal terminations. For example, if the request has incorrect or inconsistent parameters, the system abnormally
974
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|
|
|
|
|
|
|
|
|
|
STORAGE macro
terminates the active unit of work. If you specify COND=YES, you may also specify the RTCD parameter to define the location where the system is to store the return code.
COND=NO indicates that the request is unconditional. The system abnormally terminates the active unit of work if the STORAGE OBTAIN request cannot complete successfully. This situation occurs if the parameters passed on the request are incorrect or inconsistent, if the system encounters internal errors, or if there is not enough contiguous virtual storage to satisfy the request.
COND=NO is the default.
,CHECKZERO=YES
,CHECKZERO=NO
Specifies whether the return code for a successful completion should indicate if the system has cleared the requested storage to zeros. When
CHECKZERO=NO is specified or defaulted, the return code for a successful completion is 0. When CHECKZERO=YES is specified, the return code for a successful completion is X'14' if the system has cleared the requested storage to zeros, and 0 if the system has not cleared the requested storage to zeros.
There is no performance cost to specifying CHECKZERO=YES.
Programs that issue the STORAGE macro with the CHECKZERO parameter can run on any z/OS system. On a down-level system, CHECKZERO is ignored, and the return code for a successful completion (conditional or unconditional) is 0.
,EXECUTABLE=YES
,EXECUTABLE=NO
Specifies if code can be executed from the obtained storage on a system that has implemented instruction-execution-protection. It is only valid when requesting storage from a private storage subpool.
,EXECUTABLE=YES
This parameter indicates that code is able to be executed from the obtained storage.
,EXECUTABLE=NO
This parameter indicates that code will not be able to be executed from the obtained storage on a system that has implemented instruction-executionprotection. The specification of NO will be ignored when executed on a system that has not implemented instruction-execution-protection or is not running an appropriate level of z/OS.
,RELATED=value
Specifies information used to self-document macro by “relating” functions or services to corresponding functions or services. The format and contents of the information which is specified are at the discretion of the user, and can be any valid coding values.
ABEND codes
STORAGE OBTAIN might issue the hexadecimal abend codes in the following list.
For detailed abend code information, see z/OS MVS System Codes.
v 178 v 278 v
378 v 478 v 778
Chapter 99. STORAGE — Obtain and release storage
975
STORAGE macro
v 878 v
978 v A78 v B78 v D78
Return and reason codes
When control returns from the STORAGE OBTAIN request and you specified a conditional request, bits 32-63 of GPR 15 (and rtcd addr, if you coded RTCD) contain one of the following hexadecimal return codes. The contents of bits 0-31 of
GPR 15 are unpredictable.
Table 56. Return Codes for STORAGE OBTAIN
Return Code
0
Meaning and Action
Meaning
: Successful completion. CHECKZERO=YES was not specified, or the system has not cleared the requested storage to zeros.
4
8
C
Action
: None.
If you did not specify EXPLICIT on the LOC parameter
: v Meaning : Environmental error. Virtual storage was not obtained because insufficient storage is available.
v Action : Consult the system programmer to see if you have exceeded an installation-determined private storage limit.
If you specified EXPLICIT on the LOC parameter
: v Meaning : Program error. Virtual storage was not obtained because part of the requested storage area is outside the bounds of the user region.
v Action : Determine why your program is mistakenly requesting storage outside the user region. If your region size is too small, consult the system programmer about increasing the region size.
Meaning
: System error. Virtual storage was not obtained because the system has insufficient central storage to back the request.
Action
: Report the problem to the system programmer so the cause of the problem can be determined and corrected.
Meaning
: System error. Virtual storage was not obtained because the system cannot page in the page table associated with the storage to be allocated.
Action
: Report the problem to the system programmer so the cause of the problem can be determined and corrected.
976
z/OS MVS Assembler Services Reference IAR-XCT
|
STORAGE macro
Table 56. Return Codes for STORAGE OBTAIN (continued)
Return Code
10
Meaning and Action
Meaning
: Program error. Virtual storage was not obtained for one of the reasons listed below. This reason code applies only to STORAGE requests with LOC=EXPLICIT specified.
v Part of the requested area is allocated already.
v Virtual storage was already allocated in the same page as this request, but one of the following characteristics of the storage was different:
– The subpool
– The key
– Central storage backing
14
18
1C
Action
: Determine why your program is attempting to obtain allocated storage or why your program is attempting to obtain virtual storage with different attributes from the same page of storage. Correct the coding error.
Meaning
: Successful completion. The system has cleared the requested storage to zeros. This return code occurs only when CHECKZERO=YES is specified.
Action
: None.
Meaning
: PAGEFRAMESIZE1MB was specified on the LOC=parameter on a STORAGE OBTAIN request for a subpool other than 0-127, 129 -
132, 240, 244 or 250-252.
Action
: None.
Meaning
: EXECUTABLE=NO was specified for a subpool that does not support non-executable memory.
Action
: Determine why your program is attempting to obtain non-executable memory form a subpool that does not support it and correct the coding error.
RELEASE option of STORAGE
The STORAGE macro with the RELEASE parameter requests that the system release an area of virtual storage or an entire virtual storage subpool, previously allocated through the STORAGE or GETMAIN macro. The system abends the active task if the specified virtual storage does not start on a doubleword boundary or, for an unconditional request, if the specified area or subpool is not allocated to the task identified as the owning task.
Input register information
Before issuing the STORAGE macro with the RELEASE parameter, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
Used as work registers by the system.
Chapter 99. STORAGE — Obtain and release storage
977
STORAGE macro
Syntax
2-13
14
15
Unchanged.
Used as a work register by the system.
For a conditional request, contains the return code. For an unconditional request, used as a work register by the system.
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the service returns control.
Syntax
The STORAGE macro with the RELEASE option is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede STORAGE.
STORAGE
� One or more blanks must follow STORAGE.
RELEASE
,LENGTH=length value,ADDR=stor addr
,LENGTH=length value,ADDR=stor addr,SP=subpool number
,KEY=key number
length value: Symbol, decimal number, or register
(0), (2) - (12).
stor addr: RX-type address or register (1) - (12).
subpool number: Symbol, decimal number 0-127,
131, 132, or register (2) - (12), (15).
Default
: SP=0.
key number: Decimal number 0-15 or register (2)
- (1 2).
Note
: KEY is valid only when SP is specified.
978
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,RTCD=rtcd addr
|
|
,COND=YES
,COND=NO
,EXECUTABLE=YES
,EXECUTABLE=NO
,RELATED=value
STORAGE macro
Description
rtcd addr: RX-type address, register (15), or register (2) - (12). Default: RTCD=(15).
Default
: COND=NO
Default:
EXECUTABLE=YES
value: Any valid macro parameter specification.
Parameters
The parameters are explained as follows:
RELEASE
Requests that the system release virtual storage.
,LENGTH=length value
Specifies the number of bytes of storage that the system is to release. If you specify LENGTH, you must also specify ADDR. To free an entire subpool, use
SP instead of LENGTH and ADDR. Do not specify a length value of 0 with an address of 0. This combination causes STORAGE RELEASE to free the subpool specified with the SP parameter, or subpool 0 if the SP parameter is omitted.
,ADDR=stor addr
Specifies the address of the storage to be released. If you specify ADDR, you must also specify LENGTH. To free an entire subpool, use SP instead of
LENGTH and ADDR.
,SP=subpool number
Specifies the subpool number for the storage to be released. The valid subpool numbers are 0-127, 131, and 132. If you specify the subpool in a register, the subpool number must be in bits 24-31 of the register, with bits 0-23 set to zero.
If you omit this parameter, the system uses subpool 0.
A request to release all the storage in a subpool is known as a subpool release.
To issue a subpool release, use SP to indicate the subpool and do not specify
LENGTH or ADDR. A caller in problem state can issue a subpool release for subpools 1-127, 131, and 132. A caller in problem state cannot issue a subpool release for subpool 0. See the description of subpool handling in z/OS MVS
Programming: Assembler Services Guide for information and requirements pertaining to specific subpools.
,KEY=key number
Indicates the storage key of the storage to be released. The valid storage keys are your program's storage key or key 9. If you pass the storage key in a register, it must be in bits 56-59 in that register. KEY is valid only when SP is specified and applies only to subpools 131 and 132. KEY allows you to release storage in the specified storage key. See the discussion of subpool handling in
z/OS MVS Programming: Assembler Services Guide for information on authorization requirements pertaining to specific subpools.
Chapter 99. STORAGE — Obtain and release storage
979
|
|
|
|
|
|
|
|
|
|
|
|
|
|
STORAGE macro
,RTCD=rtcd addr
Specifies the location where the system is to store the return code. This parameter is valid only for conditional requests. The return code is also in GPR
15.
,COND=NO
,COND=YES
Specifies whether the request is unconditional or conditional.
COND=YES specifies that the task should not abend if the system cannot release the storage. However, the system cannot prevent some abends. The
RTCD parameter specifies the location where the system is to store a return code.
COND=NO specifies that the system is to abend the active task if it cannot release the storage. COND=NO is the default.
,EXECUTABLE=YES
,EXECUTABLE=NO
Specifies if code can be executed from the obtained storage on a system that has implemented instruction-execution-protection. It is only valid when requesting storage from a private storage subpool.
,EXECUTABLE=YES
This parameter indicates that code is able to be executed from the obtained storage.
,EXECUTABLE=NO
This parameter indicates that code will not be able to be executed from the obtained storage on a system that has implemented instruction-executionprotection. The specification of NO will be ignored when executed on a system that has not implemented instruction-execution-protection or is not running an appropriate level of z/OS.
,RELATED=value
Specifies information used to self-document macro by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and can be any valid coding values.
ABEND codes
STORAGE RELEASE might issue the hexadecimal abend codes in the following list. For detailed abend code information, see z/OS MVS System Codes.
v 178 v 278 v 378 v 478 v 778 v 878 v 978 v A78 v B78 v D78
980
z/OS MVS Assembler Services Reference IAR-XCT
STORAGE macro
Return and reason codes
When the STORAGE macro returns control to your program and you specified a conditional request, GPR 15 (and rtcd addr, if you coded RTCD) contains one of the following hexadecimal return codes:
Table 57. Return Codes for the STORAGE RELEASE
Return Code
0
Meaning and Action
Meaning
: Successful completion.
4
8
Action
: None.
Meaning
: Program error. Not all requested virtual storage was freed.
Action
: Check your program for the following kinds of errors: v The address of the storage area to be freed is not correct.
v The subpool you have specified does not match the subpool of the storage to be freed.
v The key you have specified does not match the key of the storage to be freed.
Meaning
: Program error. No virtual storage was freed because part of the storage area to be freed is fixed.
Action
: Check for the following kinds of errors: v You passed an incorrect storage area address to the STORAGE macro.
v
You attempted to free storage that is fixed.
Examples of the OBTAIN and RELEASE options
Example 1
Request that the system obtain 1000 bytes of virtual storage from subpool 127 and return its address in register 3. If the request fails, the system is to abnormally end the caller.
LA 2,1000
STORAGE OBTAIN,LENGTH=(2),ADDR=(3),SP=127,LOC=ANY,COND=NO
.
* Release 1000 bytes from subpool 127 and abnormally end the
* caller if the request fails. Assume that the length of the storage
* is still in register 2 and the address of the storage is still in
* register 3.
.
STORAGE RELEASE,LENGTH=(2),ADDR=(3),SP=127,COND=NO
.
Example 2
Request that the system obtain 4096 bytes from subpool 101 and return the address at the location defined by the RX-type address STRGA. If the request fails, the system is to save a return code at MY_RC.
STORAGE OBTAIN,LENGTH=ONE_PAGE,ADDR=STRGA,SP=MY_SUBPOOL,
LOC=ANY,COND=YES,RTCD=MY_RC
.
* Release 4096 bytes from subpool 101.
.
STORAGE RELEASE,LENGTH=ONE_PAGE,ADDR=STRGA,SP=MY_SUBPOOL,
COND=YES,RTCD=MY_RC
.
X
X
Chapter 99. STORAGE — Obtain and release storage
981
STORAGE macro
MY_RC
STRGA
DS F
DS F
ONE_PAGE EQU 4096
MY_SUBPOOL EQU 101
Example 3
Request that the system obtain 4096 bytes from subpool 101. If that much is not available, settle for a minimum of 1024 bytes. The system is to return the address of the storage at the RX-type address STRGA. If the request fails, the system is to store a return code at MY_RC.
STORAGE OBTAIN,LENGTH=(ONE_PAGE,ONE_K),ADDR=STRGA,
SP=MY_SUBPOOL,LOC=ANY,COND=YES,RTCD=MY_RC
ST
.
0,STRG_LEN
* Release the storage in subpool 101. The address of the
* storage is at the RX-type address ’STRGA’.
Note that
* LENGTH=STRG_LEN is not valid.
.
L 3,STRG_LEN
STORAGE RELEASE,LENGTH=(3),ADDR=STRGA,SP=MY_SUBPOOL,
COND=YES,RTCD=MY_RC
MY_RC
.
DS F
STRG_LEN DS F
STRGA DS F
ONE_PAGE EQU 4096
ONE_K EQU 1024
MY_SUBPOOL EQU 101
X
X
Example 4
Code the instructions to set up an 18-word save area, such as one that a program in AR address space control (ASC) mode would obtain to call a program in primary mode. The program issuing the STORAGE macro is in 31-bit addressing mode, and the code is reentrant.
PGM CSECT
PGM AMODE 31
PGM RMODE ANY
*
BAKR
SAC
LAE
14,0
512
12,0(15,0)
SAVE CALLER’S ARS, GPRS AND RETURN
ADDRESS ON LINKAGE STACK
SWITCH TO AR ASC MODE
SET UP PROGRAM BASE REGISTER AND AR
USING PGM,12
STORAGE OBTAIN,LENGTH=72 GET REENTRANT SAVEAREA
LAE 13,0(1,0)
MVC 4(4,13),=C’F1SA’
PUT SAVEAREA ADDRESS IN AR/GPR 13
PUT ACRONYM INTO SAVEAREA TO
INDICATE STATUS SAVED ON LINKAGE STACK *
.
* BEGIN PROGRAM CODE HERE
To release this save area, issue the following instructions:
.
LAE 1,0(13,0) COPY SAVEAREA ADDRESS
STORAGE RELEASE,ADDR=(1),LENGTH=72 FREE SAVEAREA
.
SLR 15,15
PR
SET RETURN CODE OF ZERO
RETURN TO CALLER, RESTORE CALLERS STATUS
982
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 100. SYMRBLD — Building a symptom record
Description
The SYMRBLD macro generates code to build a symptom record. A symptom record is a data area that contains a description of a program failure combined with a description of the environment where the failure occurred. The symptom record consists of six sections. These sections are numbered 1 through 5, including an additional section that is numbered 2.1. The purpose of each section is as follows: v
Section 1 (Environmental Data) - This section is filled in by the SYMREC macro.
The environmental data the SYMREC macro stores in this section includes the processor model and serial numbers, data and time, name of the customer installation, and the product ID of the control program.
v Section 2 (Control Data) - This section contains the lengths and offsets of the remaining sections.
v Section 2.1 (Component Data) - This section identifies the application in which the error occurred.
v Section 3 (Primary SDB symptoms) - This section contains the primary string of problem symptoms. This data is used for duplicate problem recognition.
v Section 4 (Secondary SDB symptoms) - This section contains any additional diagnostic values saved at the time of the error.
v
Section 5 (Variable Data) - This section contains diagnostic data, such as portions of data areas or parameter lists pertinent to the error.
Input to the SYMRBLD macro is a storage area for the symptom record, and the diagnostic data for sections 2.1, 3, 4, and 5 of the symptom record. The SYMRBLD macro must be invoked several times to build a complete symptom record. The following describes the sequence:
1.
Invoke SYMRBLD with the INITIAL parameter to initialize sections 1 and 2, and provide application data for section 2.1.
2.
Invoke SYMRBLD with the PRIMARY parameter to store symptoms into section 3. You may invoke this parameter more than once for one error.
3.
Optionally invoke SYMRBLD with the SECONDARY parameter to store symptoms into section 4.
4.
Optionally invoke SYMRBLD with the VARIABLE parameter to store data into section 5.
5.
Invoke SYMRBLD with the COMPLETE parameter to set the lengths of sections
3, 4, and 5 in section 2.1 and optionally code SYMRBLD to invoke the SYMREC macro for recording to the logrec data set. If you do not code SYMRBLD to invoke the SYMREC macro, your records will not be recorded to the logrec data set.
6.
Invoke SYMRBLD with the RESET parameter to rebuild the symptom record using the same storage area and application information that was specified using the INITIAL parameter. The RESET parameter is useful when the primary, secondary, and variable sections of the symptom record are to be changed but the application information in section 2.1 remains the same.
The following description of the SYMRBLD macro is divided into six sections: v SYMRBLD with the INITIAL parameter
© Copyright IBM Corp. 1988, 2017
983
SYMRBLD macro
v SYMRBLD with the PRIMARY parameter v
SYMRBLD with the SECONDARY parameter v SYMRBLD with the VARIABLE parameter v SYMRBLD with the COMPLETE parameter v SYMRBLD with the RESET parameter
There is no list or execute form of the macro.
Environment
Requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state, and any PSW key.
Task or SRB
Any PASN, any HASN, any SASN
24- or 31-bit
Primary, secondary, or access register (AR)
Enabled or disabled for I/O and external interrupts
No locks held.
Must be in the primary address space or be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
Programming requirements
The maximum size of the symptom record is 1900 bytes. In addition to providing storage for the symptom record, 100 bytes must be provided for a work area; therefore, the maximum amount of storage needed is 2000 bytes.
The symptom record storage must reside in the primary address space.
Restrictions
None.
Input register information
When specifying SYMRBLD COMPLETE with INVOKE=YES (the default) the caller must ensure that register 13 points to a standard 72-byte save area.
Once you specify SR on SYMRBLD INITIAL and you plan to specify either
SYMRBLD PRIMARY, SYMRBLD SECONDARY, SYMRBLD VARIABLE, or
SYMRBLD COMPLETE without respecifying the SR parameter, you must put the address of the storage area into register 1.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0
Reason code from the SYMREC macro if you code SYMRBLD COMPLETE with INVOKE=YES; otherwise, used as a work register by the system.
1
2-13
Used as a work register by the system.
Unchanged.
984
z/OS MVS Assembler Services Reference IAR-XCT
�
Syntax
name
SYMRBLD macro
14
15
Used as a work register by the system.
Return code from the SYMREC macro if you code SYMRBLD COMPLETE with INVOKE=YES; otherwise, used as a work register by the system.
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the SYMRBLD macro with the INITIAL option is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede SYMRBLD.
SYMRBLD
� One or more blanks must follow SYMRBLD.
INITIAL
,SR=storage addr
,PRIMLEN=primary length
,SECLEN=secondary length
,VARLEN=variable length
storage addr: RX-type address or address in register (2)-(12).
primary length: Decimal digit, RX-type address, or address in register (2)-(12).
secondary length: Decimal digit, RX-type address, or address in register
(2)-(12).
Default
: 0
variable length: Decimal digit, RX-type address, or address in register (2)-(12).
Default
: 0
Chapter 100. SYMRBLD — Building a symptom record
985
SYMRBLD macro
Syntax
,ARCHLEV=10
,COMPDSC=comp desc
,PROBLEM=problem id
,SERVLEV=service level
,NOCONVERTS
,PROGRAM=progname
,PROGLEV=proglevel
Description
This is the architecture level of the symptom record.
comp desc: RX-type address or address in register (2)-(12).
problem id: RX-type address or address in register (2)-(12).
service level: RX-type address or address in register (2)-(12).
progname: RX-type address or address in register (2)-(12).
proglevel: RX-type address or address in register (2)-(12).
Parameters
The parameters for SYMRBLD INITIAL are explained as follows:
INITIAL
Sets sections 1, 2, and 2.1 of the symptom record to zero, and initializes the offsets of sections 3, 4, and 5 in section 2.1.
,SR=storage addr
Specifies the address of the storage area, on a doubleword boundary, used for the symptom record. The storage area must reside in the primary address space.
The maximum size of the symptom record is 1900 bytes. Sections 1, 2, and 2.1
use 212 bytes of the total 1900 bytes. Sections 3, 4, and 5 use the remaining
1688 bytes. In addition to providing storage for the symptom record, 100 bytes must be provided for a work area, therefore, the maximum amount of storage needed is 2000 bytes.
Use the PRIMLEN, SECLEN, and VARLEN parameters to specify the length of sections 3, 4, and 5, respectively.
,PRIMLEN=primary length
Specifies the address of a required halfword input variable that contains the maximum length in bytes of the primary symptom string. You can also directly specify a decimal digit for the length (for example, PRIMLEN=900). If you use register notation, the register contains the address of the length rather than the length itself.
The following formula calculates the length of the primary symptom string:
Lengths of all SDBKEYs + length of all data provided with the DATA keyword + the number of times SDBKEY is specified
+ the length of all data specified with the SDBSTRING keyword
+ the number of times the SDBSTRING keyword is provided.
Note that this field cannot be zero and the maximum size of the entire symptom record is 1900 bytes.
986
z/OS MVS Assembler Services Reference IAR-XCT
SYMRBLD macro
,SECLEN=secondary length
Specifies the address of an optional halfword input variable that contains the maximum length in bytes of the secondary symptom string. You can also directly specify a decimal digit for the length (for example, SECLEN=900). If you use register notation, the register contains the address of the length rather than the length itself.
The following formula calculates the length of the secondary symptom string:
Lengths of all SDBKEYs + length of all data provided with the DATA keyword + the number of times SDBKEY is specified
+ the length of all data specified with the SDBSTRING keyword
+ the number of times the SDBSTRING keyword is provided.
Note that the maximum size of the entire symptom record is 1900 bytes.
If a length of zero is specified, the secondary symptom string is ignored. If
SECLEN is not specified, the default is zero.
,VARLEN=variable length
Specifies the address of an optional halfword input variable that contains the maximum length in bytes of the variable data section. You can also directly specify a decimal digit for the length (for example, VARLEN=900). If you use register notation, the register contains the address of the length rather than the length itself.
The following formula calculates the length of the variable data section:
The length provided must be the total length of the variable data items
+ the number of items (x) 4.
(The 4 is for the 2 byte key + 2 bytes for the length.) Note that the maximum size of the entire symptom record is 1900 bytes.
If a length of zero is specified, section 5 is ignored. If VARLEN is not specified, the default is zero.
,ARCHLEV=10
Specifies the architecture level of the symptom record. The only valid value is
10.
,COMPDSC=comp desc
Specifies the address of an optional 32-character input text description of the failing module's subfunction; for example, IOS - IOSB Analysis Routine.
,PROBLEM=problem id
Specifies the address of an optional 8-character input problem identifier used to associate the symptom record with other symptom records or with other problem indicators.
,SERVLEV=service level
Specifies the address of an optional 8-character input service level. When a value is provided, the code is normally at a higher level than the release level.
The values of this field can be any information that is indicative of the service level; for example, PTF#, APAR#, or user modification number.
,NOCONVERTS
Indicates no data conversion from binary to hexadecimal EBCDIC is needed for this symptom record.
,PROGRAM=progname
Specifies the address of a required 8-character input variable that contains the name of the failing program. When this parameter is specified, the
PIDS/aaaaaaaa SDB symptom is automatically put into section 3 of the symptom record. aaaaaaaa indicates the progname.
Chapter 100. SYMRBLD — Building a symptom record
987
SYMRBLD macro
Syntax
,PROGLEV=proglevel
Specifies the address of a required 8-character input variable that contains the name of the program major level.
Syntax
The standard form of the SYMRBLD macro with the PRIMARY option is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede SYMRBLD.
SYMRBLD
�
PRIMARY
,SR=storage addr
,SDBSTRING=SDB string
,SDBKEY=SDB key
One or more blanks must follow SYMRBLD.
,SDBLEN=SDB length
,SDBLENVAR=SDB variable
,DATA=data
,LEN=data length
,LENVAR=data variable
,CONVERT=YES
,CONVERT=NO
storage addr: RX-type address or address in register (2)-(12).
SDB string: RX-type address or address in register (2)-(12).
SDB key: SDB key name, or SDB key literal in single quotation marks. See the parameter description for a list of valid SDB key names and literals.
Note:
You must code either SDBSTRING or SDBKEY or both.
SDB length: Decimal digit 1-256, or register (2)-(12).
SDB variable: RX-type address or address in register (2)-(12).
Note:
1.
If you use register notation for SDB length, the register contains the length itself rather than the address of the length.
2.
SDBLEN (or SDBLENVAR) is valid with SDBSTRING only.
data: RX-type address or address in register (2)-(12).
Note:
DATA is required with SDBKEY only.
data length: Decimal digit 1-13, or register (2)-(12).
data variable: RX-type address or address in register (2)-(12).
Note:
1.
If you use register notation for data length, the register contains the length itself rather than the address of the length.
2.
LEN (or LENVAR) is valid with DATA only.
Default
: CONVERT=NO
Note
: CONVERT is valid with DATA only.
988
z/OS MVS Assembler Services Reference IAR-XCT
SYMRBLD macro
Syntax
,TYPE=TEST
,TYPE=NOTEST
Description
Default
: TYPE=TEST
Parameters
The parameters for SYMRBLD PRIMARY are explained as follows:
PRIMARY
Indicates that the symptom data provided is concatenated to section 3, the primary symptom string. The primary symptom string is an EBCDIC character string of problem symptoms. The primary symptom string is used to eliminate reporting duplicate problems repeatedly.
You would use the primary symptom string because, in most cases, the
PIDS/aaaaaaaa symptom is in section 3 of the symptom record. When the symptom record is initialized by invoking SYMRBLD INITIAL, the symptom is created from the data supplied with the PROGRAM parameter and is placed as the first symptom in section 3.
The suggested minimum list of symptoms includes: v Return or reason codes - PRCS/aaaaaaaa v CSECT name - RIDS/aaaaaaaa v Load module name - RIDS/aaaaaaaa#L
Note:
The following restrictions apply to symptoms in the primary symptom string: v The symptom data cannot contain imbedded blanks. The ‘#’ is used to substitute for desired blanks.
v The total length of each symptom may not exceed 15 characters. The symptom length includes the SDB key, a slash, and the EBCDIC data.
Remember that hexadecimal data doubles in length when converted to hexadecimal representation in EBCDIC.
,SR=storage addr
Specifies the address of the storage area, on a doubleword boundary, used for the symptom record. This is the same storage area you specified on SYMRBLD
INITIAL. If you do not specify SR with SYMRBLD PRIMARY, the default is to use the storage area address you placed in register 1.
,SDBSTRING=SDB string
Specifies the address of an optional character input string to be added to the primary symptom string. The data is a list of symptoms separated by a blank.
A symptom is an SDB key followed by a slash and EBCDIC data.
You must code either SDBSTRING or SDBKEY or both. When you code both on the same macro, the data provided with the SDBSTRING parameter is put into the symptom string first.
,SDBKEY=SDB key
Specifies an optional name from the set of SDB keys. You can provide the SDB key name, or specify the SDB key literal in single quotation marks (for example, specify either SDBKEY=SDBAB_S, or SDBKEY=‘AB/S’).
Chapter 100. SYMRBLD — Building a symptom record
989
SYMRBLD macro
You must code either SDBSTRING or SDBKEY or both. When you code both on the same macro, the data provided with the SDBSTRING parameter is put into the symptom string first.
The following table contains the valid SDB key names and literals:
Table 58. Valid SDB Key Names and Literals
SDB Key Name
SDBAB_S
SDBAB_U
SDBADRS
SDBDEVS
SDBFLDS
SDBLVLS
SDBMS
SDBOPCS
SDBOVS
SDBPCSS
SDBPIDS
SDBPRCS
SDBPTFS
SDBPUBS
SDBREGS
SDBREGS_CR
SDBREGS_FP
SDB Key
Literal
AB/S
AB/U
ADRS/
DEVS/
FLDS/
LVLS/
MS/
OPCS/
OVS/
PCSS/
PIDS/
PRCS/
PTFS/
PUBS/
REGS/
REGS/CR
REGS/FP
Description
System abend or program check.
User abend code.
Any software routine, CSECT, or program address; displacement within a routine; or offset within a field or data area.
IBM device types.
A field, data area, or label involved with the problem. If a field name is longer than 10 characters, use two keys and split the name of the field.
The system release or program product/component level where the problem occurs.
Program- or device-issued message. If there is no identifier, enter the message as it appears and
MS/NOID to denote this.
Software program operation code, I/O read/write command codes, teleprocessing operation codes and request codes.
Overlaid storage.
Any software statement, JCL, operator or user commands, parameters, program language statements, data set names, library names, teleprocessing logical and physical unit names, program function keys or other operator keys, environments, process names, procedures or other symptoms which do not fit other key descriptions in this table.
Product identifier.
Any program-generated return, reason, step, condition, or device status code.
Program temporary fix (PTF) or Authorized
Program Analysis Report (APAR) associated with the problem.
Publication identifier.
A register number associated with the problem, followed by the offset from the PSW.
A control register associated with the problem.
This symptom is followed with a symptom containing the value in the register.
A floating point register associated with the problem. This symptom is followed with a symptom containing the value in the register.
990
z/OS MVS Assembler Services Reference IAR-XCT
SYMRBLD macro
Table 58. Valid SDB Key Names and Literals (continued)
SDB Key Name
SDBREGS_GR
SDBREGS_AR
SDBRIDS
SDBRIDSL
SDBRIDSR
SDBSIG
SDBVALU
SDBVALU_B
SDBVALU_C
SDBVALU_H
SDBWS_D
SDBWS_E
SDB Key
Literal
Description
REGS/GR A general purpose register associated with the problem. This symptom is followed with a symptom containing the value in the register.
REGS/AR An access register associated with the problem.
This symptom is followed with a symptom containing the value in the register.
RIDS/ Module CSECT name.
RIDS/
RIDS/
SIG/
VALU/
Load module name.
Recovery routine CSECT name.
System- or device-issued operator warning signal.
Contents of a register. This SDB keyword must be preceded with one of the following: REGS/CRhh,
REGS/FPhh, or REGS/GRhh.
VALU/B
VALU/C
VALU/H
WS/D
WS/E
Binary value of a field in error. This SDB key must be preceded by the name of the field. The most appropriate SDB key is FLDS/.
Character value of a field in error. This SDB key must be preceded by the name of the field. The most appropriate SDB key is FLDS/.
Hexadecimal value of a field in error. This SDB key must be preceded by the name of the field.
The most appropriate SDB key is FLDS/.
System- or device-issued disabled WAIT code.
System- or device-issued enabled WAIT code.
,SDBLEN=SDB length
Specifies an optional decimal value from 1 to 256 that is the length of the data provided. If you use register notation, the register contains the length itself rather than the address of the length. This parameter is mutually exclusive with the SDBLENVAR parameter, and is valid with SDBSTRING only.
,SDBLENVAR=SDB variable
Specifies the address of an optional halfword that contains the length of the data provided. The length of the data must be from 1 to 256 bytes. This parameter is mutually exclusive with the SDBLEN parameter, and is valid with
SDBSTRING only.
,DATA=data
Specifies the address of the area that contains the data associated with the key specified by the SDBKEY parameter. DATA is required with SDBKEY only.
,LEN=data length
Specifies an optional decimal value from 1 to 13 that is the length of the data provided. If you use register notation, the register contains the length itself rather than the address of the length. This parameter is mutually exclusive with the LENVAR parameter, and is valid with DATA only.
,LENVAR=data variable
Specifies the address of an optional halfword that contains the length of the
Chapter 100. SYMRBLD — Building a symptom record
991
SYMRBLD macro
Syntax
data provided. The length of the data must be from 1 to 13 bytes. This parameter is mutually exclusive with the LEN parameter, and is valid with
DATA only.
,CONVERT=YES
,CONVERT=NO
Indicates that one to four bytes of binary data specified by the DATA parameter should be converted to hexadecimal representation in EBCDIC. If the length of the binary data is greater than four bytes, the results of the conversion are unpredictable.
If CONVERT is specified with the user abend code SDB key, SDBAB_U, the binary data is converted to decimal EBCDIC.
The default is CONVERT=NO. CONVERT is valid with DATA only.
,TYPE=TEST
,TYPE=NOTEST
Specifies whether code is generated to test if the data fits in the symptom record before storing the data. TYPE=NOTEST indicates that the data and key are unconditionally moved into the symptom record.
The default is TYPE=TEST.
Syntax
The standard form of the SYMRBLD macro with the SECONDARY option is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede SYMRBLD.
SYMRBLD
� One or more blanks must follow SYMRBLD.
SECONDARY
,SR=storage addr
,SDBSTRING=SDB string
,SDBKEY=SDB key
,SDBLEN=SDB length
storage addr: RX-type address or address in register (2)-(12).
SDB string: RX-type address or address in register (2)-(12).
SDB key: SDB key name, or SDB key literal in single quotation marks. See the parameter description for a list of valid SDB key names and literals.
Note
: You must code either SDBSTRING or SDBKEY or both.
SDB length: Decimal digit 1-256, or register (2)-(12).
992
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,SDBLENVAR=SDB variable
,DATA=data
,LEN=data length
,LENVAR=data variable
,CONVERT=YES
,CONVERT=NO
,TYPE=TEST
,TYPE=NOTEST
SYMRBLD macro
Description
SDB variable: RX-type address or address in register (2)-(12).
Note:
1.
If you use register notation for SDB length, the register contains the length itself rather than the address of the length.
2.
SDBLEN (or SDBLENVAR) is valid with SDBSTRING only.
data: RX-type address or address in register (2)-(12).
Note
: DATA is required with SDBKEY only.
data length: Decimal digit 1-13, or register (2)-(12).
data variable: RX-type address or address in register (2)-(12).
Note:
1.
If you use register notation for data length, the register contains the length itself rather than the address of the length.
2.
LEN (or LENVAR) is valid with DATA only.
Default
: CONVERT=NO
Note
: CONVERT is valid with DATA only.
Default
: TYPE=TEST
Parameters
The parameters for SYMRBLD SECONDARY are explained as follows:
SECONDARY
Indicates that the symptom data provided is concatenated to section 4, the secondary symptom string. The secondary symptom string is an EBCDIC character string of problem symptoms, SDB key/data pairs. The purpose of the secondary symptom string is to save diagnostic data at the time of the error.
This data may not be duplicated for each instance of the problem.
The suggested minimum list of symptoms includes: v Module assembly level - LVLS/aaa v Field name related to the error and contents - FLDS/av10 VALU/Cav8
Binary and hex data can be provided with the VALU/B and VALU/H keys.
Note:
The following restrictions apply to symptoms in the secondary symptom string: v The symptom data cannot contain imbedded blanks. The ‘#’ is used to substitute for desired blanks.
v The total length of each symptom (key/data) may not exceed 15 characters.
The symptom length includes the SDB key, a slash, and the EBCDIC data.
Remember that hexadecimal data doubles in length when converted to hexadecimal representation in EBCDIC.
,SR=storage addr
Specifies the address of the storage area, on a doubleword boundary, used for
Chapter 100. SYMRBLD — Building a symptom record
993
SYMRBLD macro
the symptom record. This is the same storage area you specified on SYMRBLD
INITIAL. If you do not specify SR with SYMRBLD SECONDARY, the default is to use the storage area address you placed in register 1.
,SDBSTRING=SDB string
Specifies the address of an optional character input string to be added to the secondary symptom string. The data is a list of symptoms separated by a blank. A symptom is an SDB key followed by a slash and EBCDIC data.
You must code either SDBSTRING or SDBKEY or both. When you code both on the same macro, the data provided with the SDBSTRING parameter is put into the symptom string first.
,SDBKEY=SDB key
Specifies an optional name from the set of SDB keys. You can provide the SDB key name, or specify the SDB key literal in single quotation marks (for
You must code either SDBSTRING or SDBKEY or both. When you code both on the same macro, the data provided with the SDBSTRING parameter is put into the symptom string first.
,SDBLEN=SDB length
Specifies an optional decimal value from 1 to 256 that is the length of the data provided. If you use register notation, the register contains the length itself rather than the address of the length. This parameter is mutually exclusive with the SDBLENVAR parameter, and is valid with SDBSTRING only.
,SDBLENVAR=SDB variable
Specifies the address of an optional halfword that contains the length of the data provided. The length of the data must be from 1 to 256 bytes. This parameter is mutually exclusive with the SDBLEN parameter, and is valid with
SDBSTRING only.
,DATA=data
Specifies the address of the area that contains the data associated with the key specified by the SDBKEY parameter. DATA is required with SDBKEY only.
,LEN=data length
Specifies an optional decimal value from 1 to 13 that is the length of the data provided. If you use register notation, the register contains the length itself rather than the address of the length. This parameter is mutually exclusive with the LENVAR parameter, and is valid with DATA only.
,LENVAR=data variable
Specifies the address of an optional halfword that contains the length of the data provided. The length of the data must be from 1 to 13 bytes. This parameter is mutually exclusive with the LEN parameter, and is valid with
DATA only.
,CONVERT=YES
,CONVERT=NO
Indicates that one to four bytes of binary data specified by the DATA parameter should be converted to hexadecimal representation in EBCDIC. If the length of the binary data is greater than four bytes, the results of the conversion are unpredictable.
If CONVERT is specified with the user abend code SDB key, SDBAB_U, the binary data is converted to decimal EBCDIC.
The default is CONVERT=NO. CONVERT is valid with DATA only.
994
z/OS MVS Assembler Services Reference IAR-XCT
�
�
Syntax
name
SYMRBLD macro
,TYPE=TEST
,TYPE=NOTEST
Specifies whether code is generated to test if the data fits in the symptom record before storing the data. TYPE=NOTEST indicates that the data and key are unconditionally moved into the symptom record.
The default is TYPE=TEST.
Syntax
The standard form of the SYMRBLD macro with the VARIABLE option is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede SYMRBLD.
SYMRBLD
One or more blanks must follow SYMRBLD.
VARIABLE
,SR=storage addr
,S5KEY=5key
,DATA=data
,LEN=data length
,LENVAR=data variable
,TYPE=NOTEST
,TYPE=TEST
storage addr: RX-type address or address in register (2)-(12).
5key: Section 5 key name, or section 5 key literal in single quotation marks.
See the parameter description for valid section 5 key names and literals.
data: RX-type address or address in register (2)-(12).
data length: Decimal digit 1-256, or register (2)-(12).
data variable: RX-type address or address in register (2)-(12).
Note:
If you use register notation for data length, the register contains the length itself rather than the address of the length.
Default
: TYPE=TEST
Parameters
The parameters for SYMRBLD VARIABLE are explained as follows:
VARIABLE
Indicates that the symptom data provided is concatenated to section 5, the variable data section. The variable data section is in key/length/data format.
The purpose of the variable data section is to provide additional serviceability
Chapter 100. SYMRBLD — Building a symptom record
995
SYMRBLD macro
Syntax
data for debugging. Examples of serviceability data are a parameter list, a text description of the problem, or a portion of a data area.
The VARIABLE parameter must be specified once for each symptom provided in key/length/data format.
,SR=storage addr
Specifies the address of the storage area, on a doubleword boundary, used for the symptom record. This is the same storage area you specified on SYMRBLD
INITIAL. If you do not specify SR with SYMRBLD VARIABLE, the default is to use the storage area address you placed in register 1.
,S5KEY=5key
Specifies the key that describes the data in section 5 of the symptom record.
You can provide the section 5 key name, or specify the section 5 key literal in single quotation marks (for example, specify either S5KEY=S5EBCDIC, or
S5KEY=‘F000’).
The following table contains the two valid section 5 key names and literals:
Table 59. Valid Section 5 Key Names and Literals
Section 5 Key Name
S5EBCDIC
S5HEX
Section 5 Key Literal
F000
FF00
Description
EBCDIC printable data.
Hexadecimal data.
,DATA=data
Specifies the address of the area that contains the data associated with the key specified by the S5KEY parameter.
,LEN=data length
Specifies an optional decimal value from 1 to 256 that is the length of the data provided. If you use register notation, the register contains the length itself rather than the address of the length. This parameter is mutually exclusive with the LENVAR parameter.
,LENVAR=data variable
Specifies the address of an optional halfword that contains the length of the data provided. The length of the data must be from 1 to 256 bytes. This parameter is mutually exclusive with the LEN parameter.
,TYPE=TEST
,TYPE=NOTEST
Specifies whether code is generated to test if the data fits in the symptom record before storing the data. TYPE=NOTEST indicates that the data and key are unconditionally moved into the symptom record.
The default is TYPE=TEST.
Syntax
The standard form of the SYMRBLD macro with the COMPLETE option is written as follows:
Description
name
name: Symbol. Begin name in column 1.
�
One or more blanks must precede SYMRBLD.
996
z/OS MVS Assembler Services Reference IAR-XCT
SYMRBLD macro
Syntax
SYMRBLD
�
COMPLETE
,SR=storage addr
,INVOKE=YES
,INVOKE=NO
,RETCODE=return code
,RSNCODE=reason code
Description
One or more blanks must follow SYMRBLD.
storage addr: RX-type address or address in register (2)-(12).
Default
: INVOKE=YES
return code: RX-type address or address in register (2)-(12).
Note:
RETCODE is valid with INVOKE=YES only.
reason code: RX-type address or address in register (2)-(12).
Note:
RSNCODE is valid with INVOKE=YES only.
Parameters
The parameters for SYMRBLD COMPLETE are explained as follows:
COMPLETE
Indicates that the symptom record is complete, and is ready to be written to the logrec data set.
SYMRBLD COMPLETE is required before the symptom record can be successfully written to the logrec data set.
,SR=storage addr
Specifies the address of the storage area, on a doubleword boundary, used for the symptom record. This is the same storage area you specified on SYMRBLD
INITIAL. If you do not specify SR with SYMRBLD COMPLETE, the default is to use the storage area address you placed in register 1.
,INVOKE=NO
,INVOKE=YES
Indicates whether to invoke the SYMREC macro that writes the symptom records out to the logrec data set. For unauthorized programs, your installation controls which programs can write symptom records and whether to write the symptom record to the logrec data set, the job log, both or neither through an installation-written exit. This exit is called ASREXIT. For more information about ASREXIT, see z/OS MVS Installation Exits. Records written for authorized programs always go to the logrec data set.
The default is INVOKE=YES.
,RETCODE=return code
Specifies the location where the system is to store the return code from the
SYMREC macro. (The SYMRBLD macro does not itself generate any return codes.) RETCODE is valid with INVOKE=YES only. The return code is also in general purpose register (GPR) 15 if you code INVOKE=YES.
Chapter 100. SYMRBLD — Building a symptom record
997
SYMRBLD macro
Syntax
,RSNCODE=reason code
Specifies the location where the system is to store the reason code from the
SYMREC macro. (The SYMRBLD macro does not itself generate any reason codes.) RSNCODE is valid with INVOKE=YES only. The reason code is also in
GPR 0 if you code INVOKE=YES.
ABEND codes
None.
Return and reason codes (for SYMRBLD
COMPLETE,INVOKE=YES)
The SYMRBLD macro itself does not generate any return codes. However, if you specify INVOKE=YES on SYMRBLD COMPLETE (or take the default), you can receive return codes and reason codes from the SYMREC macro. The return code from SYMREC is in GPR 15 (and return code if you coded RETCODE); the reason code from SYMREC is in GPR 0 (and reason code if you coded RSNCODE). See
“Return and reason codes” on page 1005 for a list of return codes from the
SYMREC macro.
Syntax
The standard form of the SYMRBLD macro with the RESET option is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede SYMRBLD.
SYMRBLD
� One or more blanks must follow SYMRBLD.
RESET
,SR=storage addr
,PRIMLEN=primary length
,SECLEN=secondary length
,VARLEN=variable length
storage addr: RX-type address or address in register (2)-(12).
primary length: Decimal digit, RX-type address, or address in register (2)-(12).
secondary length: Decimal digit, RX-type address, or address in register
(2)-(12).
variable length: Decimal digit, RX-type address, or address in register (2)-(12).
Parameters
The parameters for SYMRBLD RESET are explained as follows:
998
z/OS MVS Assembler Services Reference IAR-XCT
SYMRBLD macro
RESET
Rebuilds the symptom record using the same storage area and application information that was specified using the INITIAL parameter. This is useful when the primary, secondary, and variable sections of the symptom record are to be changed but the application information in section 2.1 remains the same.
,SR=storage addr
Specifies the address of the storage area, on a doubleword boundary, used for the symptom record. This is the same storage area you specified on SYMRBLD
INITIAL. The storage area must reside in the primary address space.
The maximum size of the symptom record is 1900 bytes. Sections 1, 2, and 2.1
use 212 bytes of the total 1900 bytes. Sections 3, 4, and 5 use the remaining
1688 bytes. In addition to providing storage for the symptom record, 100 bytes must be provided for a work area; therefore, the maximum amount of storage needed is 2000 bytes.
Use the PRIMLEN, SECLEN, and VARLEN parameters to specify the length of sections 3, 4, and 5 respectively.
,PRIMLEN=primary length
Specifies the address of an optional halfword input variable that contains the maximum length in bytes of the primary symptom string. You can also directly specify a decimal digit for the length (for example, PRIMLEN=900). If you use register notation, the register contains the address of the length rather than the length itself.
The following formula calculates the length of the primary symptom string:
Lengths of all SDBKEYs + length of all data provided with the DATA keyword + the number of times SDBKEY is specified
+ the length of all data specified with the SDBSTRING keyword
+ the number of times the SDBSTRING keyword is provided.
Note that this field cannot be zero and the maximum size of the entire symptom record is 1900 bytes.
If you do not specify PRIMLEN, the length of the primary symptom string will not change from the length you specified on SYMRBLD INITIAL, or on a previous SYMRBLD RESET.
,SECLEN=secondary length
Specifies the address of an optional halfword input variable that contains the maximum length in bytes of the secondary symptom string. You can also directly specify a decimal digit for the length (for example, SECLEN=900). If you use register notation, the register contains the address of the length rather than the length itself.
The following formula calculates the length of the secondary symptom string:
Lengths of all SDBKEYs + length of all data provided with the DATA keyword + the number of times SDBKEY is specified
+ the length of all data specified with the SDBSTRING keyword
+ the number of times the SDBSTRING keyword is provided.
Note that the maximum size of the entire symptom record is 1900 bytes.
If you do not specify SECLEN, the length of the secondary symptom string will not change from the length you specified on SYMRBLD INITIAL, or on a previous SYMRBLD RESET.
,VARLEN=variable length
Specifies the address of an optional halfword input variable that contains the maximum length in bytes of the variable data section. You can also directly
Chapter 100. SYMRBLD — Building a symptom record
999
SYMRBLD macro
specify a decimal digit for the length (for example, VARLEN=900). If you use register notation, the register contains the address of the length rather than the length itself.
The following formula calculates the length of the variable data section:
The length provided must be the total length of the variable data items
+ the number of items (x) 4.
(The 4 is for the 2 byte key + 2 bytes for the length.) Note that the maximum size of the entire symptom record is 1900 bytes.
If you do not specify VARLEN, the length of the variable data section will not change from the length you specified on SYMRBLD INITIAL, or on a previous
SYMRBLD RESET.
Example
The following is an example of invoking SYMRBLD to build a symptom record: v SYMRBLD INITIAL initializes sections 1 and 2 of the symptom record and provides component data for section 2.1.
v SYMRBLD PRIMARY stores the following primary symptom string data:
– Program return code: PRCS/00028878
– CSECT name: RIDS/ABE5698J
– Load module name: RIDS/ABD5698J#L
Note:
The symptom PIDS/ABE5698J is automatically placed as the first symptom in the primary symptom string.
v SYMRBLD SECONDARY stores the following secondary symptom string data:
– Module assembly level: LVLS/C20
– Field name: FLDS/COUNTER
– Value: VALU/HFFFFFFFF v SYMRBLD VARIABLE stores additional data that can be used for debugging in section 5 of the symptom record.
v SYMRBLD COMPLETE indicates that the record is complete. INVOKE=YES indicates that the record is written to the logrec data set. by the SYMREC macro.
SYMRBLD INITIAL,SR=SREC,
PRIMLEN=100,SECLEN=50,VARLEN=50,
ARCHLEV=10,COMPDSC=MYCOMP,
PROGRAM=PROGNAME,PROGLEV=REL6,
PROBLEM=MYPROB,
SERVLEV=MYSERV
SYMRBLD PRIMARY,SDBSTRING=S1_DATA
SYMRBLD SECONDARY,SDBSTRING=S2_DATA,SDBKEY=SDBVALU_H,
DATA=COUNTER,CONVERT=YES
SYMRBLD VARIABLE,S5KEY=S5HEX,DATA=MYVARDAT
SYMRBLD COMPLETE,INVOKE=YES
SREC DS CL600
MYCOMP DC CL13’COMPONENT XXX’
MYPROB DC CL14’DATABASE ERROR’
MYSERV DC CL9’VERSION 1’
PROGNAME DC CL8’ABE5698J’
REL6 DC CL3’REL6’
1000
z/OS MVS Assembler Services Reference IAR-XCT
S1_DATA DC CL43’PRCS/00028878 RIDS/ABE5698J RIDS/ABD5698J#L’
S2_DATA DC CL22’LVLS/C20 FLDS/COUNTER’
MYVARDAT DC XL2’01E4’
COUNTER DC X’FFFFFFFF’
SYMRBLD macro
Chapter 100. SYMRBLD — Building a symptom record
1001
SYMRBLD macro
1002
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 101. SYMREC — Process a symptom record
Description
The SYMREC macro updates a symptom record with system environment information and then logs the symptom record in the logrec data set. The symptom record is a data area in the user's application that has been mapped by the ADSR mapping macro.
As an application detects errors during execution, it stores diagnostic information into the symptom record and issues the SYMREC macro to log the record. The diagnostic information consists of a description of a programming failure and a description of the environment in which the failure occurred.
When the SYMREC macro is invoked, it checks that all the required input fields of the ADSR symptom record are set by the caller. If the required input fields are not set, SYMREC issues appropriate return and reason codes.
The SYMREC macro can be used for authorized and unauthorized programs. Your installation controls which programs can write symptom records and whether to write the symptom record to the logrec data set, the job log, both or neither through an installation-written exit. This exit is called ASREXIT. For further information about ASREXIT, see z/OS MVS Installation Exits. SYMRBLD is a related macro. For more information see z/OS MVS Programming: Assembler Services Guide.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state, and any PSW key.
Task or SRB
Any PASN, any HASN, any SASN
24- or 31-bit
Primary
Enabled or disabled for I/O and external interrupts. If disabled, the input data to SYMREC must be in fixed storage or in disabled reference (DREF) storage.
The caller may hold locks, but is not required to hold any.
Must be in the primary address space.
Programming requirements
The caller must include the ADSR mapping macro to map the symptom record specified on the SR parameter. The caller must fill in this symptom record. For more information on the ADSR mapping macro, see z/OS MVS Data Areas in the z/OS Internet library (www.ibm.com/systems/z/os/zos/library/bkserv).
Restrictions
Although callers in 24-bit or 31-bit addressing mode can issue the SYMREC macro, the addresses passed to the SYMREC service must be 31-bit addresses.
© Copyright IBM Corp. 1988, 2017
1003
SYMREC macro
Syntax
Input register information
The SYMREC macro is sensitive to the SYSSTATE macro with the OSREL parameter v If the caller has issued the SYSSTATE macro with the OSREL=ZOSV1R6 parameter (Version 1 Release 6 of z/OS or later) before issuing the SYMREC macro, the caller does not have to place any information into any general purpose register (GPR) unless using it in register notation for a particular parameter, or using it as a base register.
v Otherwise, the caller must ensure that the following general purpose register contains the specified information:
Register
Contents
13
The address of an 18-word save area
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
0
1
Register
Contents
Reason code
Used as a work register by the system
2-13
14
15
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the SYMREC macro is written as follows:
Description
name
name: Symbol. Begin name in column 1.
1004
z/OS MVS Assembler Services Reference IAR-XCT
SYMREC macro
Syntax
�
SYMREC
�
SR=addr
Description
One or more blanks must precede SYMREC.
One or more blanks must follow SYMREC.
addr: A-type address or register 2-12.
Parameters
The parameters are explained as follows:
SR=addr
Specifies the address of the symptom record. The SR parameter is required.
ABEND codes
None.
Return and reason codes
When SYMREC returns control, registers 15 and 0 contain the following hexadecimal return codes and reason codes, respectively:
Meaning and Action Hexadecimal
Return Code
0000
Hexadecimal
Reason Code
0000
0004
0008
0164
0158
Meaning
: SYMREC completed successfully and the symptom record was recorded.
Action
: None.
Meaning
: Program error. An attempt to write section
1 information from the completed symptom record failed. The area was not accessible to a write request.
The entire input record was recorded.
Action
: Make sure that the storage containing the input symptom record is not released before the
SYMREC request completes.
Meaning
: Program error. The total length of the input symptom record exceeds the maximum. A partial symptom record was recorded.
Action
: Correct the length of the symptom record.
The maximum length of the symptom record is 1900 bytes. Sections 1, 2, and 2.1 of the symptom record are fixed in length. The length of sections 1, 2, and
2.1 combined is 212 bytes. Therefore, the combined length of sections 3, 4, and 5 must be less than or equal to 1688 bytes.
Chapter 101. SYMREC — Process a symptom record
1005
SYMREC macro
Hexadecimal
Return Code
0008
000C
000C
000C
000C
000C
000C
Hexadecimal
Reason Code
015C
0104
0108
010C
0114
0128
012C
Meaning and Action
Meaning
: Program error. Optional segments of the input symptom record were not accessible. The record includes the accessible entries of the input symptom record. A partial symptom record was recorded.
Action
: Verify that all optional sections (sections 4 and 5) of the symptom record are accessible.
Meaning
: Program error. The first 2 bytes of the input symptom record do not contain the SR operand. No symptom record was recorded.
Action
: Verify that the correct address for the input symptom record was provided to the SYMREC service and that the first 2 bytes of the symptom record contain 'SR'.
Meaning
: Program error. The input symptom record does not contain the required entries for section 2.
No symptom record was recorded.
Action
: Make sure the following fields have been supplied in section 2 of the symptom record: the length of section 2 and the length/offset of section
2.1 and 3.
Meaning
: Program error. The input symptom record does not contain the required entries for section 2.1.
No symptom record was recorded.
Action
: Make sure the following fields have been supplied in section 2.1 of the symptom record: section 2.1 identifier, architecture level of the symptom record, and the component release level or
PID release level. Also verify that the length of section 2.1 is correct in section2.
Meaning
: Program error. The input symptom record does not contain the required entries for section 3.
No symptom record was recorded.
Action
: Make sure that the primary symptom string contains at least one symptom.
Meaning
: Program error. This reason code is set when the input symptom record cannot be referenced. No symptom record was recorded.
Action
: Verify that the correct address for the symptom record was provided to the SYMREC macro and that this storage is accessible.
Meaning
: Program error. All required sections of the symptom record could not be referenced. No symptom record was recorded.
Action
: Verify that all required sections (sections 1,
2, 2.1 and 3) of the symptom record are accessible.
1006
z/OS MVS Assembler Services Reference IAR-XCT
Hexadecimal
Return Code
000C
000C
000C
0010
0010
0010
SYMREC macro
Hexadecimal
Reason Code
0134
0144
0F1C
0F04
0F08
0F0C
Meaning and Action
Meaning
: Program error. The input symptom record address is in non-accessible storage. No symptom record was recorded.
Action
: Verify the input parameter list provided to the SYMREC request.
Meaning
: Program error. No symptom record was recorded. One of the following occurred: v The caller is in cross memory mode and the home address space is not accessible because it is swapped out or going through address space termination.
Action
: Make sure that the home address space is non-swappable during the SYMREC request. An address space can be made non-swappable using the SYSEVENT macro.
v The caller is disabled, but it did not obtain
MVS-recognized (valid) disablement. Valid disablement is obtained through a SETLOCK
OBTAIN,TYPE=CPU request, available to supervisor state and key 0 callers only.
Action
: Use the SETLOCK OBTAIN, TYPE=CPU to disable normally.
Meaning
: Program error. The installation exit
ASREXIT prevented the unauthorized caller from writing the symptom record to the logrec data set.
No symptom record was recorded.
Action
: None. The installation has decided that unauthorized programs cannot write to the logrec data set.
Meaning
: Environmental error. There was insufficient space in the LOGREC buffer to accommodate the symptom record. No symptom record was recorded.
Action
: The request might be successful if retried. If the problem persists, record the return and reason code and supply it to the appropriate system support personnel.
Meaning
: System error. The SYMREC service could not acquire storage for a work area or a copy of the symptom record. No symptom record was recorded.
Action
: The request might be successful if retried. If the problem persists, record the return and reason code and supply it to the appropriate system support personnel.
Meaning
: System error. Failure occurred while the symptom record was being moved to the LOGREC buffer. No symptom record was recorded.
Action
: Record the return and reason code and supply it to the appropriate IBM support personnel.
Chapter 101. SYMREC — Process a symptom record
1007
SYMREC macro
Hexadecimal
Return Code
0010
0010
0010
0014
Hexadecimal
Reason Code
0F10
0F14
0F18
—
Meaning and Action
Meaning
: System error. The SYMREC service has a logic error. No symptom record was recorded.
Action
: Record the return and reason code and supply it to the appropriate IBM support personnel.
Meaning
: System error. The SYMREC service has shut itself down. It has exceeded the maximum allowable logic errors for the service routine. No symptom record was recorded.
Action
: Record the return and reason code and supply it to the appropriate IBM support personnel.
Meaning
: System error. The SYMREC service has shut itself down. It has exceeded the maximum allowable incomplete SYMREC requests for processing. No symptom record was recorded.
Action
: Record the return and reason code and supply it to the appropriate IBM support personnel.
Meaning
: System error. SYMREC is not operable.
Action
: Record the return and reason code and supply it to the appropriate IBM support personnel.
SYMREC—List form
Use the list form of the SYMREC macro together with the execute form of the macro for applications that require reentrant code. The list form of the macro defines an area of storage, which the execute form of the macro uses to store the parameters.
Syntax
Syntax
The list form of the SYMREC macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede SYMREC.
SYMREC
� One or more blanks must follow SYMREC.
addr: A-type address (31 bit).
SR=addr
,MF=(L)
1008
z/OS MVS Assembler Services Reference IAR-XCT
SYMREC macro
Parameters
The parameters are explained under the standard form of the SYMREC macro with the following exception:
,MF=L
Specifies the list form of the SYMREC macro.
SYMREC - Execute form
Use the execute form of the SYMREC macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Syntax
Syntax
The execute form of the SYMREC macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede SYMREC.
SYMREC
�
SR=addr
,MF=(E,list addr)
One or more blanks must follow SYMREC.
addr: A-type address (31 bit) or register 2-12.
addr: A-type address (31 bit) or register 2-12.
addr: A-type address (31 bit) or register 2-12.
list addr: RX-type address or register 2-12.
Parameters
The parameters are explained under the standard form of the SYMREC macro with the following exception:
,MF=(E,list addr)
Specifies the execute form of the SYMREC macro. This form uses a remote parameter list.
Chapter 101. SYMREC — Process a symptom record
1009
SYMREC macro
1010
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 102. SYNCH and SYNCHX — Take a synchronous exit to a processing program
Description
The SYNCH macro allows a program to take a synchronous exit to a processing program. After the processing program has finished, the program that issued the
SYNCH macro regains control. The SYNCH macro is intended for use by primary mode programs only. If your program is in access register (AR) mode, use
SYNCHX, which provides the same function as SYNCH.
Descriptions of the SYNCH and SYNCHX macro in this information are: v The standard form of the SYNCH macro, which includes general information about the SYNCH and SYNCHX macros with specific information about the
SYNCH macro. The syntax of the SYNCH macro and its parameters are explained.
v The standard form of the SYNCHX macro, which presents information specific to the SYNCHX macro. The topic explains the syntax of the SYNCHX macro and the parameters that are valid only on SYNCHX.
v The list form of the SYNCH and SYNCHX macros.
v The execute form of the SYNCH and SYNCHX macros.
If the caller is in AR mode, the system passes the following values, unchanged, to the processing program: v ARs 0-13 v Bits 16 and 17 of the current PSW indicating the ASC mode (primary or AR mode, where primary=secondary=home) v Extended authorization index (EAX)
Parameters for SYNCH and SYNCHX must be in the caller's primary address space. Callers in AR mode must initialize AR 1 to zero before issuing SYNCHX.
Note:
The SYNCH and SYNCHX macros have the same environment specifications, register information, programming requirements, restrictions and limitations, performance implications, and return and reason codes described below, except where noted in the explanation for SYNCHX.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt Status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
24- or 31-bit for SYNCH; 24- or 31- or 64-bit for SYNCHX.
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space.
© Copyright IBM Corp. 1988, 2017
1011
SYNCH and SYNCHX macros
Syntax
Programming requirements
None.
Restrictions
None.
Input register information
Before issuing the SYNCH(X) macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
Values the processing program placed there before it returned to the caller
If RESTORE=YES, unchanged; if RESTORE=NO, values the processing program placed there before it returned to the caller
14
15
Used as a work register by the system
Value the processing program placed there before it returned to the caller
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the SYNCH macro is written as follows:
Description
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede SYNCH.
SYNCH
�
One or more blanks must follow SYNCH.
entry point addr: RX-type address, or register (2) - (12) or (15).
entry point addr
,RESTORE=NO
,RESTORE=YES
Default
: RESTORE=NO
1012
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|
|
|
||
||
Syntax
,AMODE=24
,AMODE=31
,AMODE=DEFINED
,AMODE=CALLER
,RMODE64=NO
,RMODE64=YES
SYNCH and SYNCHX macros
Description
Default
: AMODE=CALLER.
Note
: AMODE=DEFINED can be specified only if the entry point address is provided in a register.
Default
: RMODE64=NO
Note
: RMODE64=YES can be specified only with SYNCHX.
Parameters
The parameters are explained as follows:
entry point addr
Specifies the address of the entry point of the processing program to receive control.
,RESTORE=NO
,RESTORE=YES
Specifies whether registers 2-13 are to be restored when control returns to the caller.
,AMODE=24
,AMODE=31
,AMODE=DEFINED
,AMODE=CALLER
Specifies the addressing mode in which the requested program is to receive control.
If AMODE=24 is specified, the requested program will receive control in 24-bit addressing mode.
If AMODE=31 is specified, the requested program will receive control in 31-bit addressing mode.
If AMODE=DEFINED is specified, the user must provide the entry point using a register and not an RX-type address. The requested program will receive control in the addressing mode indicated by the high order bit of the entry point address. If the bit is set to 0, the requested program will receive control in 24-bit addressing mode; if the bit is set to 1, the requested program will receive control in 31-bit addressing mode.
If AMODE=CALLER is specified, the requested program will receive control in the addressing mode of the caller.
,RMODE64=NO
,RMODE64=YES
Specifies whether the residency mode in which the requested program is to receive control is RMODE 64 or not.
When RMODE64=YES, the entry point address in a register is treated as an
8-byte address. An entry point address that is not in a register is treated as
8-bytes.
Chapter 102. SYNCH and SYNCHX — Take a synchronous exit to a processing program
1013
SYNCH and SYNCHX macros
Return and reason codes
None.
Example 1
Take a synchronous exit to PROGRAMA. Do not restore registers 2-13 when control returns.
LOAD EP=PROGRAMA,DCB=LIB1
LR R8,R0
SYNCH (R8),RESTORE=NO
Load desired program
Obtain the entry point
Example 2
Take a synchronous exit to a program labeled SUBRTN and restore registers 2-13 when control returns.
SYNCH SUBRTN,RESTORE=YES
Example 3
Take a synchronous exit to the program located at the address given in register 8 and restore registers 2-13 when control returns. Indicate that this program is to execute in 24-bit addressing mode.
SYNCH (8),RESTORE=YES,AMODE=24
Example 4
Take a synchronous exit to the program located at the address given in register 8 and restore registers 2-13 when control returns. Indicate that this program is to receive control in the addressing mode defined by the high-order bit of its entry point address.
SYNCH (8),RESTORE=YES,AMODE=DEFINED
Example 5
Take a synchronous exit to the program located at the address given in register 8 and restore registers 2-13 when control returns. Indicate that this program is to receive control in the addressing mode as the caller.
SYNCH (8),RESTORE=YES,AMODE=CALLER
SYNCHX - Take a synchronous exit to a processing program
The SYNCHX macro provides the same function as the SYNCH macro. All parameters on the SYNCH macro are valid for the SYNCHX macro.
SYNCHX is intended for use by programs running in AR mode.
Note:
The SYNCHX macro has the same environment specifications, register information, programming requirements, restrictions and limitations, performance implications, and return and reason codes as the SYNCH macro, except where noted below.
Environment
The SYNCHX macro can be used by callers in AR or primary ASC mode.
1014
z/OS MVS Assembler Services Reference IAR-XCT
�
Syntax
name
SYNCH and SYNCHX macros
Programming requirements
If your program is in AR mode, (1) issue the SYSSTATE ASCENV=AR macro before you issue SYNCHX, and (2) initialize AR 1 to zero.
Register information
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-13
Unchanged
14-15
Used as work registers by the system
Syntax
The SYNCHX macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede SYNCHX.
SYNCHX
�
entry point addr
One or more blanks must follow SYNCHX.
entry point addr: RX-type address, or register (2) - (12) or (15).
Default
: RESTORE=NO ,RESTORE=NO
,RESTORE=YES
,AMODE=24
,AMODE=31
,AMODE=64
,AMODE=DEFINED
Default
: AMODE=CALLER
Note:
AMODE=DEFINED can only be specified if the entry point is provided in a register. AMODE=DEFINED can only be used to SYNCHX to amode 24 and amode 31 programs.
,AMODE=CALLER
Parameters
The parameters are described under the syntax of the standard form of the SYNCH macro. If AMODE=64 is specified, the requested program will receive control in
64-bit addressing mode.
Chapter 102. SYNCH and SYNCHX — Take a synchronous exit to a processing program
1015
SYNCH and SYNCHX macros
SYNCH and SYNCHX—List form
The list form of the SYNCH or SYNCHX macro is used to construct a control parameter list.
Syntax
Syntax
The list form of the SYNCH or SYNCHX macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede SYNCH or SYNCHX.
name
�
SYNCH
SYNCHX
�
,RESTORE=NO
,RESTORE=YES
,AMODE=24
,AMODE=31
,AMODE=DEFINED
,AMODE=CALLER
,MF=L
One or more blanks must follow SYNCH or SYNCHX.
Default
: RESTORE=NO
Default
: AMODE=CALLER
Parameters
The parameters are explained under the standard form of the SYNCH macro, with the following exception:
,MF=L
Specifies the list form of the SYNCH or SYNCHX macro.
Example
Use the list form of the SYNCH macro to specify that registers 2-13 are to be restored when control returns from executing the SYNCH macro and that the addressing mode of the program is to be defined by the high-order bit of the entry point address. Assume that the execute form of the macro specifies the program address.
SYNCH ,RESTORE=YES,AMODE=DEFINED,MF=L
1016
z/OS MVS Assembler Services Reference IAR-XCT
SYNCH and SYNCHX macros
SYNCH and SYNCHX—Execute form
The execute form of the SYNCH or SYNCHX macro uses a remote control-program parameter list that can be generated by the list form of SYNCH or SYNCHX.
Syntax
Syntax
The execute form of the SYNCH or SYNCHX macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede SYNCH or SYNCHX.
name
�
SYNCH
SYNCHX
�
entry point addr
,RESTORE=NO
,RESTORE=YES
,AMODE=24
,AMODE=31
,AMODE=DEFINED
,AMODE=CALLER
,MF=(E,ctrl addr)
One or more blanks must follow SYNCH or SYNCHX.
entry point addr: RX-type address, or register (2) - (12) or (15).
Note
: AMODE=DEFINED can be specified only if the entry point address is provided in a register.
ctrl addr: RX-type address or register (1), (2) - (12).
Parameters
The parameters are explained under the standard form of the SYNCH macro, with the following exception:
,MF=(E,ctrl addr)
Specifies the execute form of the SYNCH or SYNCHX macro.
Example
Use the execute form of the SYNCH macro to take a synchronous exit to the program located at the address given in register 8 and restore registers 2-13 when control returns. Indicate that the program is to receive control in the same addressing mode as the caller and that the parameter list is located at SYNCHL2.
SYNCH (8),RESTORE=YES,AMODE=CALLER,MF=(E,SYNCHL2)
Chapter 102. SYNCH and SYNCHX — Take a synchronous exit to a processing program
1017
SYNCH and SYNCHX macros
1018
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 103. SYSEVENT — System event
Description
The SYSEVENT macro provides the interface to the system resource manager
(SRM). Using SYSEVENT mnemonics, you can notify SRM of an event or ask SRM to perform a specific function. Out of the many different SYSEVENTs, only the following ones are unauthorized: v FREEAUX v QVS v
REQFASD v REQLPDAT with ENTRY=UNAUTHPC option v QRYCONT with ENTRY=UNAUTHPC option
See z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO for more information on these unauthorized SYSEVENTs, as well as all of the authorized SYSEVENTs.
© Copyright IBM Corp. 1988, 2017
1019
1020
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 104. SYSSTATE — Identify system state
Description
Use the SYSSTATE macro to generate code that is correct for the environment in which the program will run. Some macros need to know one or more of the following characteristics about that environment: v The addressing mode (AMODE) at the time the macro is issued v The ASC mode of the program at the time the macro is issued v The Architectural level in which the program will run at the time the macro is issued v The earliest release level that the program will run on at the time the macro is issued
For those macros that are sensitive to their environment, SYSSTATE identifies the environment. During the assembly stage, SYSSTATE sets one or more of the following: v Global character symbol &SYSAM64, to identify the AMODE v Global character symbol &SYSASCE, to identify the ASC mode v Global arithmetic symbol &SYSALVL, to identify the Architectural level v Global character symbols &SYSOSREL and &SYSOSREL_NAME, to identify the release level
Later, when the program is assembled, the macros check the global symbol(s) and generate the correct code.
IBM recommends that you issue the SYSSTATE macro before issuing other macros.
Once a program has issued SYSSTATE, there is no need to reissue it unless the program switches from one ASC mode to another, or from one AMODE to another, or has code paths that are isolated according to architecture level or z/OS release.
If you switch AMODE or ASC mode or to a different architecture code path or a different z/OS release code path, you should issue SYSSTATE immediately after the switch to indicate the new state. Without this information, the system assumes the macro is issued: v
In AMODE other than 64-bit v In primary ASC mode v In ESA/390 architectural level v Prior to z/OS V1R6
Also, it is recommended that: v If you know that your program will run on or after a particular release of z/OS, use SYSSTATE with the OSREL parameter.
v If you know that your program will run on or after the release of z/OS that provided the SYSSTATE macro with which you are assembling, use SYSSTATE with OSREL=SYSSTATE.
v When using SYSSTATE with OSREL, use SYSSTATE ARCHLVL=OSREL, as that will set the ARCHLVL accordingly.
© Copyright IBM Corp. 1988, 2017
1021
SYSSTATE macro
Another way to use the SYSSTATE macro is within a macro you write yourself. For example, you can issue SYSSTATE with the TEST parameter to ensure that the
&SYSASCE global symbol has been set:
1.
Define the &SYSASCE global symbol within your macro.
2.
Issue SYSSTATE TEST, which sets &SYSASCE to the default if it has not yet been set.
3.
Define different logical paths within your macro to correspond to the ASC mode that is in effect based on the value of &SYSASCE.
A program need use SYSSTATE TEST only when it wants to query the value of one of the variables. When setting variables (i.e., not SYSSTATE TEST), you can specify one or more of the parameters available. The variables associated with not-specified variables remain unchanged.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state, and any PSW key.
Task or SRB
Any PASN, any HASN, any SASN
24- or 31- or 64-bit
Primary or AR
Enabled or disabled for I/O and external interrupts
The caller may hold locks, but is not required to hold any.
None.
Programming requirements
None.
Restrictions
None.
Input register information
Before issuing the SYSSTATE macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain the following information:
Register
Contents
0-15
Unchanged
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-15
Unchanged
1022
z/OS MVS Assembler Services Reference IAR-XCT
SYSSTATE macro
⌂
Syntax
name
Performance implications
None.
Syntax
The SYSSTATE macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede SYSSTATE.
SYSSTATE
⌂ One or more blanks must follow SYSSTATE.
TEST
ASCENV=P
ASCENV=AR
AMODE64=NO
AMODE64=YES
ARCHLVL=0
ARCHLVL=1
ARCHLVL=2
ARCHLVL=3
ARCHLVL=OSREL
OSREL=osrel
PUSH
POP
Default
: ASCENV=P
Default:
AMODE64=NO
Default:
ARCHLVL=0
Parameters
The parameters are explained as follows:
TEST
TEST checks each one of the global symbols &SYSASCE, &SYSAM64, and
&SYSALVL, and does the following for each as required: v Sets the global symbol to its default, if the global symbol does not contain a value indicating that it had been set by a prior SYSSTATE macro.
Chapter 104. SYSSTATE — Identify system state
1023
SYSSTATE macro
v Leaves the global symbol unchanged, if the global symbol does contain a value indicating that you issued a specific SYSSTATE during this assembly.
ASCENV=P
ASCENV=AR
Indicates your program's ASC mode by setting the global symbol &SYSASCE.
v ASCENV=P indicates that the program is in primary mode.
v ASCENV=AR indicates that the program is in AR mode.
AMODE64=NO
AMODE64=YES
Indicates whether your program is AMODE 64 at this point. It sets the global symbol &SYSAM64.
v AMODE64=YES should be specified for any part of your program that runs in AMODE 64. Some macros process differently according to this specification. For example, macros such as ATTACHX, CALL, LINKX,
LOAD, and XCTLX build prarmeter lists consisting of 8-byte entries when
SYSSTATE AMODE64=YES.
v AMODE64=NO should be specified for programs, or parts of programs, that do not run in AMODE 64.
ARCHLVL=0
ARCHLVL=1
ARCHLVL=2
ARCHLVL=3
ARCHLVL=OSREL
Indicates the architectural level of the system for which the subsequent section of your program is designed by setting the global symbol &SYSALVL.
0
Means that the architecture is ESA/390. When bit CVTOS390_R10 in byte
CVTOSLV2 of the CVT data area is off, your program should not assume that ARCHLVL=1 or ARCHLVL=2 capabilities are available.
1
Means that the architecture is ESA/390. When bit CVTOS390_R10 in byte
CVTOSLV2 of the CVT data area is on, ARCHLVL=1 capabilities are available.
2
Means that the architecture is z/Architecture. Macros that pay attention to
ARCHLVL will avoid generating z/Architecture instructions when
ARCHLVL < 2 is in effect. When byte FLCARCH in the PSA data area is not zero, ARCHLVL=1 and ARCHLVL=2 capabilities are available. If you set an ARCHLVL value less than the latest, your program can still run on more recent levels of the system, but it might not take advantage of all the new functions.
3
Means that the architecture is the architecture level required by z/OS
V2R1, which corresponds, roughly, to the IBM System z9 processor.
OSREL
Indicates to set the ARCHLVL according to the OSREL specification using the following rules: v When the OSREL release is at least z/OS V2R1, set &SYSALVL to 3.
v When the OSREL release is at least z/OS V1R6, set &SYSALVL to 2.
v Otherwise, set &SYSALVL to 1.
When an ARCHLVL greater than 0 is in effect, be aware of the following points: v
1024
z/OS MVS Assembler Services Reference IAR-XCT
SYSSTATE macro
v Macros may expect that there is addressability to the literal area of your assembly language program at the point where the macro is invoked.
v
You might still need to use the IEABRC or IEABRCX macro to have subsequent macros generate code that avoids the use of base-displacement branch instructions, since many macros are not sensitive to the value specified for SYSSTATE ARCHLVL. See z/OS MVS Programming: Assembler
Services Reference IAR-XCT for details about the IEABRC and IEABRCX macros.
that you still might
OSREL=osrel
Indicates the earliest operating system release that subsequent macros may assume the code is running on by setting the global symbol &SYSOSREL and
&SYSOSREL_NAME. Specify osrel by specifying the release name in the form
ZOSVnRm, where n is the version number and m is the release number. For example, specify OSREL=ZOSV1R6 for z/OS V1R6. For each new release, an analogous value will be added for osrel. The system also provides global character macro variables for each supported release which you can check within a macro. These macro variables are of the form &SYSOSREL_ZOSVnRm.
You can also specify OSREL=SYSSTATE, which indicates that the OSREL is to match the release of z/OS that provided the SYSSTATE macro with which you are assembling.
PUSH
Saves current SYSSTATE global symbol settings. You can nest PUSH/POP to a depth of 255.
POP
Restore SYSSTATE global symbol settings to the previously saved levels. You can nest PUSH/POP to a depth of 255.
ABEND codes
None.
Return and reason codes
None.
Example 1
Change to AR mode and set the global symbol.
SAC 512
SYSSTATE ASCENV=AR
Example 2
The following example shows how you would code the SYSSTATE macro to indicate that your code was in a section that knew that it was running on z/OS
V1R6 or later:
L 15,X’10’ Get CVT address
TM CVTOSLV3-CVT(15),CVTZOS_V1R6
JZ NOT_V1R6
SYSSTATE PUSH save SYSSTATE values
SYSSTATE OSREL=ZOSV1R6
LXRES ELXLIST=...
SYSSTATE POP restore SYSSTATE values
NOT_V1R6 DS 0H
Chapter 104. SYSSTATE — Identify system state
1025
SYSSTATE macro
Example 3
The following example shows how you would use SYSSTATE to temporarily indicate a program's ASC mode, and then change back to the prior setting. In this example, the program issues SYSSTATE PUSH to save the current mode, changes to AR mode issues SYSSTATE to indicate that the program is running in AR ASC mode, and then issues SYSSTATE POP to restore the program to whatever the prior mode was:
SAC 512
SYSSTATE PUSH
SYSSTATE ASCENV=AR
* code running in AR-mode
SYSSTATE POP
Example 4
The following example shows how you would code a macro to be sensitive to
SYSSTATE with the OSREL parameter, in this case for release z/OS V1R6:
MACRO
TESTMAC
GBLC &SYSOSREL
GBLC &SYSOSREL_ZOSV1R6
SYSSTATE TEST
AIF (&SYSOSREL GE &SYSOSREL_ZOSV1R6).GENV1R6
* produce code suitable for prior to z/OS v1 R6
AGO .MACEND
.GENV1R6
ANOP
* produce code suitable for z/OS v1 R6 or later
.MACEND
ANOP
MEND
1026
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 105. TCBTOKEN — Request or translate the TTOKEN
Description
The TTOKEN is the 16-byte identifier of a task. Unlike a TCB address, each
TTOKEN is unique within the IPL; the system does not reassign this same identifier to any other TCB.
The TCBTOKEN macro provides three mutually exclusive services depending on how you specify the TYPE parameter: v
TYPE=CURRENT gives you the TTOKEN for the current task.
v TYPE=PARENT gives you the TTOKEN for the task that attached the current task.
v TYPE=JOBSTEP gives you the TTOKEN for the current task's job step task.
z/OS MVS Programming: Extended Addressability Guide describes TTOKENs.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt Status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
Any
31-bit
Primary or AR
Enabled or disabled for I/O and external interrupts
The caller can hold locks, but is not a requirement.
Must reside in the primary address space or in an address or data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
Programming requirements
None.
Restrictions
None.
Input register information
Before issuing the TCBTOKEN macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0
Used as a work register by the system
© Copyright IBM Corp. 1988, 2017
1027
TCBTOKEN macro
Syntax
1
2-13
14
15
Address of the TCBTOKEN parameter list
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0
Used as a work register by the system
1
2-13
ALET used to address the TCBTOKEN parameter list
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the TCBTOKEN macro is written as follows:
Description
name
⌂
name: Symbol. Begin name in column 1.
One or more blanks must precede TCBTOKEN.
TCBTOKEN
⌂ One or more blanks must follow TCBTOKEN.
TYPE=CURRENT
TYPE=PARENT
TYPE=JOBSTEP
,TTOKEN=ttoken addr
,RELATED=value
ttoken addr: RX-type address.
value: Any valid macro parameter specification.
1028
z/OS MVS Assembler Services Reference IAR-XCT
TCBTOKEN macro
Parameters
The parameters are explained as follows:
TYPE=CURRENT
TYPE=PARENT
TYPE=JOBSTEP
Specifies the type of TCB information requested, as follows:
CURRENT
The system returns the TTOKEN of the currently active task. The
TTOKEN is returned at the address specified by the TTOKEN parameter. Instead of using the TCBTOKEN service, you may use the
STCBTTKN field of the STCB data area associated with the current task
(for which the TCB address is in the PSATOLD field).
PARENT
The system returns the TTOKEN of the task that attached the currently active task. The TTOKEN is returned at the address specified by the
TTOKEN parameter. Instead of using the TCBTOKEN service, you may use the STCBTTKN field of the STCB data area associated with the parent task (for which the TCB address is in the TCBOTC field of the
TCB for the current task, for which the TCB address is in the
PSATOLD field).
JOBSTEP
The system returns the TTOKEN of the job step task associated with the currently active task. The TTOKEN is returned at the address specified by the TTOKEN parameter. Instead of using the TCBTOKEN service, you may use the STCBTTKN field of the STCB data area associated with the jobstep task associated with the current task (for which the TCB address is in the TCBJSTCB field of the TCB for the current task, for which the TCB address is in the PSATOLD field).
,TTOKEN=ttoken addr
Specifies the address at which the 16-byte TTOKEN associated with the specified TCB is returned.
,RELATED=value
Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user and may be any valid coding values.
ABEND codes
None.
Return codes
When TCBTOKEN returns control, register 15 contains one of the following return codes:
Table 60. Return codes for the TCBTOKEN macro
Hexadecimal return code
00
Meaning and action
Meaning
: TCBTOKEN services completed successfully.
Action
: None.
Chapter 105. TCBTOKEN — Request or translate the TTOKEN
1029
TCBTOKEN macro
Table 60. Return codes for the TCBTOKEN macro (continued)
Hexadecimal return code
10
Meaning and action
Meaning
: The TCB could not be referenced.
14
18
20
Action
: Ensure that the input TCB address is valid.
Meaning
: The TCB did not pass the acronym check.
Action
: Ensure that the input TCB address is valid.
Meaning
: The TCB has terminated.
Action
: None required.
Meaning
: An unexpected error occurred.
24
28
30
34
Action
: Reissue TCBTOKEN.
Meaning
: The contents of access register 1, used to address the parameter list, were not valid.
Action
: Change your program to run in primary mode or set access register 1 to zero.
Meaning
: The parameter list is not valid.
Action
: Ensure that the parameter list address is valid and addressable in the calling program's key.
Meaning
: The task is scheduled for termination, but has not yet terminated.
Action
: None required.
Meaning
: The caller is not running in task mode.
Action
: Change your program to run in task mode.
Example
Obtain the TTOKEN for the currently active task and store it in
CURRENT_TTOKEN.
TCBTOKEN TYPE=CURRENT,TTOKEN=CURRENT_TTOKEN
TCBTOKEN—List form
The list form of the TCBTOKEN macro builds a nonexecutable parameter list that the execute form of the TCBTOKEN macro can refer to.
Syntax
Syntax
The list form of the TCBTOKEN macro is written as follows:
Description
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede TCBTOKEN.
TCBTOKEN
1030
z/OS MVS Assembler Services Reference IAR-XCT
TCBTOKEN macro
Syntax
�
,RELATED=value
,MF=L
Description
One or more blanks must follow TCBTOKEN.
value: Any valid macro parameter specification.
Parameters
The parameters are explained below:
,MF=L
Specifies the list form of the TCBTOKEN macro.
TCBTOKEN—Execute form
The execute form of the TCBTOKEN macro modifies and executes the parameter list that the list form of TCBTOKEN generated.
Syntax
Syntax
The execute form of the TCBTOKEN macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede TCBTOKEN.
TCBTOKEN
�
One or more blanks must follow TCBTOKEN.
TYPE=CURRENT
TYPE=PARENT
TYPE=JOBSTEP
,TTOKEN=ttoken addr
,RELATED=value
,MF=(E,cntl addr)
ttoken addr: RX-type address.
value: Any valid macro parameter specification.
cntl addr: RX-type address or register (1) - (12).
Chapter 105. TCBTOKEN — Request or translate the TTOKEN
1031
TCBTOKEN macro
Parameters
The parameters are the same as those for the standard form of the TCBTOKEN macro with the following addition:
,MF=(E,cntl addr)
Specifies the execute form of the TCBTOKEN macro. This form uses a remote parameter list. The cntl addr specifies the address of the remote parameter list that the list form of the macro generates.
1032
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 106. TESTART — Tests the validity of ALETs
Description
TESTART tests for conditions that lead to an access register translation (ART) program interruption. Use it to test: v The validity of an access list entry token (ALET) v The validity of the extended authorization index (EAX) authority of the program that passed the ALET v The value of an ALET v If a specified ALET points to an entry for a SCOPE=COMMON data space.
By testing for these conditions, your program can avoid using an ALET that would cause an ART program interruption.
For information about ALETs, EAXs, and EAX-authorization, see z/OS MVS
Programming: Extended Addressability Guide.
Environment
Requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks held
:
Control parameters
:
Requirement
Problem state.
Task or SRB
Any PASN, any HASN, any SASN
Any
Primary or AR
Enabled or disabled for I/O and external interrupts
The caller can be locked or unlocked.
Not applicable
Programming requirements
None.
Restrictions
None.
Input register information
The input to the macro is the ALET and the caller's EAX.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
14
Used as work registers by the system
Unchanged
Used as a work register by the system
© Copyright IBM Corp. 1988, 2017
1033
TESTART macro
Syntax
15
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Performance implications
None.
Syntax
The TESTART macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede TESTART.
TESTART
�
ALET=(access-reg)
,EAX=(eax)
,CADS=YES
,CADS=NO
One or more blanks must follow TESTART.
access-reg: Access register (0) - (15).
eax: Register (0) - (14).
Default
: CADS=NO
Parameters
The parameters are explained as follows:
ALET=(access-reg)
Specifies an access register 0 through 15 that contains the ALET to be tested.
,EAX=(eax)
Specifies a general purpose register 0 through 14 that contains the EAX to be used in the test, in bit positions 0-15. (The system ignores bits 16 - 31.)
,CADS=YES
,CADS=NO
Specifies if TESTART is to check the caller's PASN-AL to see if the specified
ALET points to an entry for a SCOPE=COMMON data space. If CADS=YES is specified, TESTART returns one of the following return codes:
1034
z/OS MVS Assembler Services Reference IAR-XCT
TESTART macro
v X'04' if the ALET does not represent a SCOPE=COMMON data space v
X'18' if the ALET is for a SCOPE=COMMON data space.
If CADS=NO is specified, TESTART does not indicate whether or not the specified ALET is for a SCOPE=COMMON data space.
ABEND codes
None.
Return codes
When TESTART macro returns control to your program, GPR 15 contains a return code.
Table 61. Return Codes for the TESTART Macro
Hexadecimal
Return Code
Meaning and Action
00
Meaning
: The specified ALET is 0.
04
08
0C
10
14
18
Action
: None.
Meaning
: The specified ALET represents a valid entry on the DU-AL. If
CADS=YES was specified on the call, the ALET does not point to an entry for a SCOPE=COMMON data space.
Action
: None required. However, you might take some action based upon your application.
Meaning
: The specified ALET represents a valid entry on the
PASN-AL.
Action
: None required. However, you might take some action based upon your application.
Meaning
: The specified ALET is 1.
Action
: None required. However, you might take some action based upon your application.
Meaning
: The specified ALET and/or EAX will cause an ART program interruption.
Action
: None required. However, you might take some action based upon your application.
Meaning
: A system error occurred in the TESTART service routine.
Action
: Retry the request.
Meaning
: The program specified CADS=YES on the call to TESTART.
The specified ALET points to an entry for a SCOPE=COMMON data space.
Action
: None required. However, you might take some action based upon your application.
Example 1
Request that TESTART verify the following two conditions: v The ALET in AR1 passed by the caller is zero or is a valid ALET on the caller's dispatchable unit access list. The caller's registers were saved in the linkage stack prior to this example.
Chapter 106. TESTART — Tests the validity of ALETs
1035
TESTART macro
v The caller is EAX-authorized to data being passed as a parameter that can be accessed by the called program that runs with an authorized EAX.
R1
AR1
R15
*
EQU 1
EQU 1
EQU 15
General register 1
Access register 1
General register 15
*
SLR R15,R15
EREG AR1,AR1
Set a zero code for the ESTA
Extract GPR/AR 1 from the linkage stack
ESTA R0,R15
BH ERROR
Place the caller’s EAX in R1 bits 0-15
TESTART ALET=(AR1),EAX=(R1) Test the ALET/EAX
CL R15,=X’00000004’ Test the TESTART return code
Branch to error routine when the return code is greater than 4
Example 2
Request that TESTART verify the following two conditions: v The ALET passed by the caller (on the linkage stack) points to an entry for a
SCOPE=COMMON data space v The caller is EAX-authorized to data being passed as a parameter that can be accessed by the called program that runs with an authorized EAX.
R1
AR1
R15
*
EQU 1
EQU 1
EQU 15
General register 1
Access register 1
General register 15
SLR R15,R15
EREG AR1,AR1
Set a zero code for the ESTA
Extract GPR/AR 1 from the linkage stack
ESTA R0,R15 Place the caller’s EAX in R1 bits 0-15
TESTART ALET=(AR1),EAX=(R1),CADS=YES Test the ALET/EAX
CL
BE
R15,=X’00000018’ Test the TESTART return code
CADS_ALET Branch to CADS ALET routine processing
1036
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 107. TIME — Obtain time and date
Description
The TIME macro returns the local time of day and date, the Coordinated Universal
Time (UTC) (or the Greenwich mean time) of day and date, or the contents of the time-of-day (TOD) clock. The time-of-day clock referenced can be either in the basic time-of-day format (TOD) or the extended time-of-day format (ETOD).
v TOD — Unsigned 64-bit binary number v ETOD — Unsigned 128-bit binary number
You can use the STCKCONV and CONVTOD macros to convert between
TOD-clock format and various time of day and date formats. The STCKCONV macro converts a TOD-clock value to a time of day and date value and the
CONVTOD macro converts a time of day and date value to a TOD clock value. See
z/OS MVS Programming: Assembler Services Guide and z/Architecture Principles of
Operation for information comparing the formats of the TOD and ETOD.
In a system using an external time reference (ETR
2
), the TOD clocks are set automatically at system initialization. However, in a system without an ETR, the time of day and date are only as accurate as the information entered by the operator. System response time also influences the accuracy of the values returned by the TIME macro.
There are two different linkage methods that can be specified. The TIME macro with LINKAGE=SYSTEM can be used by a program in primary or AR mode, in cross memory mode, and in either an enabled or disabled state. The
LINKAGE=SYSTEM parameter also permits a choice of formats for the date value returned, as well as list and execute forms of the macro. With LINKAGE=SVC, the caller cannot be in cross memory mode or AR mode, must be in an enabled state, and has no choice of the format for the returned date value.
IBM recommends
the use of the LINKAGE=SYSTEM parameter on the TIME macro. The LINKAGE=SVC parameter is provided solely for compatibility with existing programs.
The following description of the TIME macro is divided into two sections,
LINKAGE=SYSTEM and LINKAGE=SVC. There are list and execute forms of the macro for LINKAGE=SYSTEM, but not for LINKAGE=SVC.
LINKAGE=SYSTEM
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
Requirement
Problem state and any PSW key.
Task or SRB
PASN=HASN=SASN or PASN¬=HASN¬=SASN
2. External time reference (ETR) is the MVS generic name for the IBM Sysplex Timer.
© Copyright IBM Corp. 1988, 2017
1037
TIME macro
Environmental factor
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control Parameters
:
Requirement
24- or 31- or 64-bit
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
The caller may hold locks, but is not required to hold any.
Must be in the primary address space or be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
Programming requirements
If the program is in AR mode, issue the SYSSTATE ASCENV=AR macro before
TIME. SYSSTATE ASCENV=AR tells the system to generate code appropriate for
AR mode.
Restrictions
None.
Input register information
Before issuing the TIME macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14
15
Used as a work register by the system
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
1038
z/OS MVS Assembler Services Reference IAR-XCT
⌂
Syntax
name
TIME macro
Syntax
The standard form of the TIME macro with LINKAGE=SYSTEM is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede TIME.
TIME
⌂ One or more blanks must follow TIME.
Default
: DEC
stor addr: RX-type address or register (2) - (12).
DEC,stor addr
BIN,stor addr
MIC,stor addr
STCK,stor addr
STCKE,stor addr
,ZONE=LT
,ZONE=UTC|GMT
,LINKAGE=SYSTEM
,DATETYPE=YYYYDDD
,DATETYPE=MMDDYYYY
,DATETYPE=DDMMYYYY
,DATETYPE=YYYYMMDD
Default
: ZONE=LT
Note
: This parameter has no meaning if STCK or STCKE is specified.
Note
: LINKAGE=SVC is the default.
Default
: DATETYPE=YYYYDDD
Parameters
The parameters are explained as follows:
DEC,stor addr
BIN,stor addr
MIC,stor addr
STCK,stor addr
STCKE,stor addr
Specifies the format in which the time of day and date, or TOD clock contents, are returned. stor addr specifies the address of a 16-byte storage area in which
TIME will return the values. The first two words of this area contain the time of day, or TOD clock contents, in the requested format. The third word contains the date in the requested format. Set the fourth word to zero before issuing TIME.
DEC returns the time of day as 8 bytes of packed decimal digits (without a sign) of the form
Chapter 107. TIME — Obtain time and date
1039
TIME macro t h m i
HHMMSSthmiju0000, where:
HH
is hours, based on a 24-hour clock
MM
is minutes
SS
is seconds is tenths of seconds is hundredths of seconds is milliseconds is ten-thousandths of seconds
j u
is hundred-thousandths of seconds is microseconds
BIN returns the time of day as an unsigned 32-bit binary number with the low-order bit equivalent to 0.01 second. The second word of the time value returned is zero.
MIC returns the time of day since midnight in microseconds. The value is returned as 8 bytes of information where bit 51 is equivalent to one microsecond.
STCK returns the contents of the basic TOD clock as an unsigned 64-bit binary number where bit 51 is equivalent to one microsecond.
STCKE returns the contents of the extended TOD clock (ETOD) as an unsigned
128-bit binary number where bit 59 is equivalent to one microsecond.
Note:
The resolution of the time-of-day clock is model dependent. See
Principles of Operation for an explanation of the rate advancement.
,ZONE=LT
,ZONE=UTC|GMT
LT specifies that the local time and date are to be returned. UTC or GMT specifies that an externally-sourced time and date such as Coordinated
Universal Time (UTC) or Greenwich Mean Time (GMT) are to be returned.
Refer to the information on time in z/Architecture Principles of Operation,
SA22-7832 for a discussion of the differences between UTC and GMT.
ZONE is not meaningful if STCK or STCKE is specified.
,LINKAGE=SYSTEM
Specifies that non-SVC linkage is used to invoke the TIME service routine.
,DATETYPE=YYYYDDD
,DATETYPE=MMDDYYYY
,DATETYPE=DDMMYYYY
,DATETYPE=YYYYMMDD
Specifies the format in which the converted date is returned. For each parameter, the format of the returned date is as follows:
DATETYPE
Form of Returned Date
YYYYDDD
0YYYYDDD
MMDDYYYY
MMDDYYYY
1040
z/OS MVS Assembler Services Reference IAR-XCT
TIME macro
DDMMYYYY
DDMMYYYY
YYYYMMDD
YYYYMMDD
The date is returned as packed decimal digits without a sign, where:
YYYY
is the year
DDD
is the day of the year
MM
is the month of the year
DD
is the day of the month
For example, with DATETYPE=YYYYDDD, January 21, 2000 would be returned as a converted TOD value of 02000021.
ABEND codes
None.
Return codes
When TIME macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.
Table 62. Return Codes for the TIME Macro
Hexadecimal
Return Code
00
Meaning and Action
Meaning
: Successful completion.
04
08
0C
10
Action
: None.
Meaning
: Programming error. TOD clocks are not initialized.
Action
: Retry the request later in the IPL.
Meaning
: Environmental error. The TOD clock is not usable.
Action
: Retry the request.
Meaning
: System error.
Action
: Retry the request.
Meaning
: Programming error. The user's parameter list is not in addressable storage.
Action
: Ensure that the parameter list is in the caller's Primary address space. If in AR mode, the PASN access list must not be used for addressing the parameter list.
Example 1
Request the local time of day and date (in year/day of the year format) to be returned in decimal digits in a 16-byte area called TIMEDATE.
TIME DEC,TIMEDATE,ZONE=LT,LINKAGE=SYSTEM
TIMEDATE DS CL16 TIME AND DATE RETURNED
Chapter 107. TIME — Obtain time and date
1041
TIME macro
Example 2
Request the GMT time of day and date to be returned in a 16-byte area called
OUTVAL. The GMT time of day should be returned as microseconds and the date should be returned in a day/month/year format.
OUTVAL
TIME MIC,OUTVAL,ZONE=GMT,LINKAGE=SYSTEM,DATETYPE=DDMMYYYY
DS CL16 TIME AND DATE RETURNED
LINKAGE=SYSTEM - List form
Use the list form of the TIME macro (LINKAGE=SYSTEM) together with the execute form of the macro for applications that require reentrant code. The list form of the macro defines an area of storage that the execute form of the macro uses to store the parameters.
Syntax
Syntax
The list form of the TIME macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede TIME.
TIME
�
LINKAGE=SYSTEM
One or more blanks must follow TIME.
Note
: LINKAGE=SYSTEM must be specified in order to obtain the list form of the TIME macro.
,MF=L
Parameters
The parameters are explained under the standard form of the TIME macro with
LINKAGE=SYSTEM, with the following exception:
,MF=L
Specifies the list form of the TIME macro.
Example
Establish the correct amount of storage for the TIME parameter list.
LIST1 TIME LINKAGE=SYSTEM,MF=L
1042
z/OS MVS Assembler Services Reference IAR-XCT
TIME macro
LINKAGE=SYSTEM - Execute form
Use the execute form of the TIME macro (LINKAGE=SYSTEM) together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Syntax
Syntax
The execute form of the TIME macro is written as follows:
Description
⌂
name
name: Symbol. Begin name in column 1.
One or more blanks must precede TIME.
TIME
⌂ One or more blanks must follow TIME.
Default
: DEC
stor addr: RX-type address or register (2) - (12).
DEC,stor addr
BIN,stor addr
MIC,stor addr
STCK,stor addr
STCKE,stor addr
,ZONE=LT
,ZONE=UTC|GMT
,LINKAGE=SYSTEM
Default
: ZONE=LT
Note
: This parameter has no meaning if STCK is specified.
Note
: LINKAGE=SYSTEM must be specified in order to obtain the execute form of the TIME macro.
Default
: DATETYPE=YYYYDDD
Note
: This parameter has no meaning if STCK is specified.
,DATETYPE=YYYYDDD
,DATETYPE=MMDDYYYY
,DATETYPE=DDMMYYYY
,DATETYPE=YYYYMMDD
,MF=(E,list addr) list addr: RX-type address or register (2) - (12).
Parameters
The parameters are explained under the standard form of the TIME macro with
LINKAGE=SYSTEM, with the following exception:
Chapter 107. TIME — Obtain time and date
1043
TIME macro
,MF=(E,list addr)
Specifies the execute form of the TIME macro. list addr specifies the address of the parameter list created by the list form of the macro.
Example
Request the local time of day and date to be returned in a 16-byte area called
OUTAREA. The local time of day should be returned as decimal digits and the local date should be returned in year/month/day format. Specify the address of the appropriate parameter list in LIST1.
TIME DEC,OUTAREA,LINKAGE=SYSTEM,MF=(E,LIST1),DATETYPE=YYYYMMDD
OUTAREA DS CL16 TIME AND DATE RETURNED
LINKAGE=SVC
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control Parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
24- or 31-bit addressing mode
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space.
Programming requirements
None.
Restrictions
The caller cannot have any enabled, unlocked task (EUT) FRRs established.
Input register information
Before issuing the TIME macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter or using it as a base register.
Output register information
When control returns to the caller, the registers contain:
Register
Contents
0
The time of day if you specified DEC, BIN, or TU. If you did not specify any of these parameters, register 0 is used as a work register by the system.
1
2-13
Contains the date, if you specified DEC, BIN, TU, or MIC. If you did not specify any of these parameters, register 1 is used as a work register by the system.
Unchanged.
1044
z/OS MVS Assembler Services Reference IAR-XCT
�
�
Syntax
name
TIME macro
14
15
Used as a work register by the system.
Return code.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the TIME macro with LINKAGE=SVC is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede TIME.
TIME
One or more blanks must follow TIME.
Default
: DEC
stor addr: RX-type address or register (0) or (2) - (12).
DEC
BIN
TU
MIC,stor addr
STCK,stor addr
,ZONE=LT
,ZONE=UTC|GMT
,LINKAGE=SVC
Default
: ZONE=LT
Note
: This parameter has no meaning if STCK is specified.
Default
: LINKAGE=SVC
Note:
The ERRET parameter is obsolete and will be ignored by the system.
Therefore, the syntax and parameter descriptions for TIME no longer contain
ERRET. However, the system will still accept ERRET and it is not necessary to delete it from existing code.
Parameters
The parameters are explained as follows:
DEC
BIN
TU
Chapter 107. TIME — Obtain time and date
1045
TIME macro
MIC,stor addr
STCK,stor addr
Specifies the form in which the time of day and date, or TOD clock contents, is returned.
DEC returns the time of day in register 0 as packed decimal digits, without a sign, of the form
HHMMSSth, where:
HH
is hours (24-hour clock)
MM
is minutes
SS
is seconds
t h
is tenths of seconds is hundredths of seconds
BIN returns the time of day in register 0 as an unsigned 32-bit binary number.
The low-order bit is equivalent to 0.01 second.
TU returns the time of day in register 0 as an unsigned 32-bit binary number.
The low-order bit is approximately 26.04166 microseconds (one timer unit).
MIC returns the time of day in microseconds. The stor addr is the address of an
8-byte area in storage with bit 51 equivalent to one microsecond.
STCK returns the contents of the TOD clock as an unsigned 64-bit binary number where bit 51 is equivalent to one microsecond. The stor addr is the address of an 8-byte area in storage.
Note:
The resolution of the time-of-day clock is model dependent. See
Principles of Operation for an explanation of the rate advancement.
The date is returned in register 1 as packed decimal digits of the form
0CYYDDDF, where:
C
is a digit representing the century. In the years 1900 through 1999, the macro will return a value of C=0. In the years 2000 through 2099, the macro will return a value of C=1.
is the last two digits of the year.
YY
DDD
is the day of the year.
F
is a 4-bit sign character that allows the data to be unpacked and printed.
,ZONE=LT
,ZONE=UTC|GMT
Specifies that the local time and date (LT) or the Coordinated Universal Time
(UTC) or Greenwich mean time (GMT) and date are to be returned.
,LINKAGE=SVC
Specifies that the linkage used to invoke the TIME service routine is through an SVC instruction.
ABEND codes
10B
See z/OS MVS System Codes for an explanation and programmer responses for this code.
1046
z/OS MVS Assembler Services Reference IAR-XCT
TIME macro
Return and reason codes
The only return code from the TIME macro is a zero in register 15 indicating successful completion.
Example 1
Request the system to store the time-of-day clock in the address pointed to by register 2.
TIME STCK,(2)
Example 2
Request that the current local time and date be returned as packed decimal digits in registers 0 and 1.
TIME DEC,ZONE=LT,LINKAGE=SVC
Example 3
Request that the current time of day in microsecond format be returned in the location OUTAREA. Note that the default is taken for LINKAGE.
TIME MIC,OUTAREA
.
.
OUTAREA DS 2F
Chapter 107. TIME — Obtain time and date
1047
TIME macro
1048
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 108. TIMEUSED — Obtain accumulated CPU or vector time
Description
The TIMEUSED macro returns an 8-byte integer in a doubleword storage area that you specify. The number is the total CPU or vector time that is used by the current
TCB up until you issue the macro. The format of the number is time-of-day (TOD) clock or microseconds time format.
Note:
TIMEUSED returns normalized CPU time. Some servers are configured with
IBM zEnterprise
®
Application Assist Processors (zAAPs) or IBM z Integrated
Information Processor (zIIPs), which run at a faster speed than the normal CP processors. In this case, zAAP time and zIIP time are normalized to the equivalent time it would take to run on a normal CP when accumulated into total CPU time.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN or PASN¬=HASN¬=SASN
31- or 64-bit
Primary or access register (AR)
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space or be in an address space/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
Programming requirements
None.
Restrictions
None.
Input register information
For TIME_ON_CP=YES, register 13 contains the address of a 36-word save area in
F4SA format that resides below the 2-gigabyte bar.
Otherwise, before issuing the TIMEUSED macro, the caller does not have to place any information into any register unless they use it in register notation for a particular parameter, or use it as a base register.
Output register information
When control returns to the caller after the call to TIMEUSED, the general-purpose registers (GPR) contain:
© Copyright IBM Corp. 1988, 2017
1049
TIMEUSED macro
Register
0-1
2-13
14
15
Contents
Used as work registers by the system
Unchanged
Used as a work register by the system
Return code
||
|||
||
|
||
|
|
When control returns to the caller after the call to TIMEUSED, the AR contains:
Register
0-1
2-13
14-15
Contents
Used as work registers by the system
Unchanged
Used as work registers by the system
Syntax
name
Some callers depend on register contents to remain the same before and after they issue a service. If the system changes the contents of registers on which the caller depends, the caller must save them before they issue the service, and restore them after the system returns control.
Performance implications
When your application uses TIMEUSED LINKAGE=SYSTEM without the CPU and
VECTOR parameters (or can change to do so), consider use of the ECT parameter that gives access to the Extract-CPU-Time (ECT) facility that is available on IBM
System z9
® or later hardware.
v If your application might run on some systems that support the ECT facility and on some systems that do not, you can use the ECT=COND parameter to check for availability of this facility. The ECT=COND parameter adds a small extra overhead when run on a system that does not support the ECT facility, but results in a much faster path when run on a system, which does support the facility.
v If your application always runs on a system that supports the ECT facility, use
ECT=YES without specifying the LINKAGE parameter. This provides better performance than using LINKAGE=SYSTEM,ECT=COND.
The TIMEUSED support to use the Extract-CPU-Time facility is available on z/OS
V1R8 or later systems.
Syntax
The TIMEUSED macro is written as follows:
Description
name: Symbol. Begin name in column 1.
⌂
One or more blanks must precede TIMEUSED.
TIMEUSED
⌂
One or more blanks must follow TIMEUSED.
STORADR=addr addr: RX-type address or register (2)-(12).
1050
z/OS MVS Assembler Services Reference IAR-XCT
TIMEUSED macro
Syntax
,LINKAGE=SYSTEM
,RELATED=value
,CPU=TOD
,CPU=MIC
,VECTOR=TOD
,VECTOR=MIC
,ECT=SYSTEM
,ECT=COND
,ECT=YES
,TIME_ON_CP=YES
,OFFLOAD_TIME=YES
,OFFLOAD_ON_CP=YES
Description
Default
: See the parameter description.
value: Any valid macro parameter specification
Default
: CPU=TOD
Default
: ECT=SYSTEM
Parameters
The parameters are explained as follows:
STORADR=addr
When TIME_ON_CP, OFFLOAD_TIME, and OFFLOAD_ON_CP are not specified, STORADR=addr specifies the address of a doubleword area where the accumulated CPU or vector time is returned. When in AMODE 64 and invoking TIMEUSED with LINKAGE=SYSTEM or ECT=YES, the area can be in
64-bit storage; otherwise, it must be in 31-bit storage. The time interval is represented as an unsigned 64-bit binary number. If you specify CPU=TOD or
VECTOR=TOD, bit 51 is the low-order bit of the interval value and equivalent to 1 microsecond. If you specify CPU=MIC or VECTOR=MIC, bit 63 is the low-order bit of the interval value and equivalent to 1 microsecond.
When ECT=YES and one or more of TIME_ON_CP, OFFLOAD_TIME, and
OFFLOAD_ON_CP are specified, STORADR=addr specifies the address of an
8-word area in 31-bit storage of the primary address space where one or more accumulated time values are returned. It is recommended that the area is on a doubleword boundary. Each time interval is represented as an unsigned 64-bit binary number. Bit 51 is equivalent to 1 microsecond.
On output where the return code is 0: v Words 0-1 = Total time.
v Words 2-3 = Time on CP when TIME_ON_CP=YES.
v
Words 4-5 = Offload time (unnormalized) when OFFLOAD_TIME=YES.
v Words 6-7 = Offload on CP when OFFLOAD_ON_CP=YES. Any subfield that is not requested to be returned is unpredictable.
Chapter 108. TIMEUSED — Obtain accumulated CPU or vector time
1051
TIMEUSED macro
,LINKAGE=SYSTEM
Indicates that the linkage is by nonbranch entry. Do not specify LINKAGE with ECT=YES. You must specify LINKAGE=SYSTEM for all other unauthorized invocations.
,RELATED=value
Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information that is specified are at the discretion of the user and can be any valid coding values.
,CPU=TOD
,CPU=MIC
,VECTOR=TOD
,VECTOR=MIC
Specifies that TIMEUSED returns the total CPU or vector time in either TOD clock format (CPU=TOD or VECTOR=TOD) or in microseconds (CPU=MIC or
VECTOR=MIC).
,ECT=SYSTEM
,ECT=COND
,ECT=YES
Specifies which instruction service the system is to use.
SYSTEM
Specifies that the system determines which instruction service to use.
For LINKAGE=BRANCH, the system uses the Extract CPU Time instruction service when that service is available. For
LINKAGE=SYSTEM, it will not use the Extract CPU Time instruction service.
COND
Specifies that the system is conditionally to use the Extract CPU Time instruction service. If the service and instruction are available, the system uses that service. Otherwise, the system uses the regular
TIMEUSED service. Output is in TOD format. Use only with
LINKAGE=SYSTEM. Do not specify the CPU or VECTOR parameters.
You must include the CVT, IHAECVT, and IHAPSA mapping macros.
YES
Specifies that the system is unconditionally to use the Extract CPU
Time instruction service. You must verify that the service and instruction are available (running on z/OS V1R8 or later, with bit
FLCFECT on in byte FLCFACL3 in macro IHAPSA). Output is in TOD format. Do not specify the CPU, VECTOR, or LINKAGE parameters.
You must include the CVT, IHAECVT, and IHAPSA mapping macros.
,TIME_ON_CP=YES
The system is to return information about TIME_ON_CP for the task, which is adjusted for the time spent within the current dispatch. Requires the ECT=YES and STORADR parameters and can be specified along with either
OFFLOAD_TIME=YES or OFFLOAD_ON_CP=YES, or both. You must include
DSECTs CVT and IHAECVT. The function is available only if bit CVTECT1 in byte CVTOSLV8 of the CVT data area is on.
,OFFLOAD_TIME=YES
The system is to return information about time on offload engines for the task, which is adjusted for the time spent within the current dispatch. This time is unnormalized (it is in the units that apply to the offload processors). Requires the ECT=YES and STORADR parameters and can be specified along with
TIME_ON_CP=YES or OFFLOAD_ON_CP=YES, or both. You must include
1052
z/OS MVS Assembler Services Reference IAR-XCT
TIMEUSED macro
DSECTs CVT and IHAECVT. The function is available only if bit CVTECT1 in byte CVTOSLV8 of the CVT data area is on.
,OFFLOAD_ON_CP=YES
The system is to return information about time on a standard CP that was eligible for offload, which is adjusted for the time spent within the current dispatch. Requires the ECT=YES and STORADR parameters and can be specified along with either TIME_ON_CP=YES or OFFLOAD_TIME=YES, or both. You must include DSECTs CVT and IHAECVT. The function is available only if bit CVTECT1 in byte CVTOSLV8 of the CVT data area is on.
ABEND codes
The caller might encounter system completion code X'012'. See z/OS MVS System
Codes for an explanation and programmer response for this code.
Return codes
Register 15 contains one of the following hexadecimal return codes from
TIMEUSED:
Table 63. Return and Reason Codes for the TIMEUSED Macro
Hexadecimal
Return Code
0
Meaning and Action
Meaning
: The service completed successfully.
8
Action
: None.
Meaning
: Unexpected error.
Action
: Reissue the TIMEUSED macro.
Examples
Example 1
Request the total CPU time in TOD clock format to be stored at the address in register 2.
TIMEUSED STORADR=(2),LINKAGE=SYSTEM,CPU=TOD
Example 2
Request the total vector time in microseconds to be stored at the address in register
2.
TIMEUSED STORADR=(2),LINKAGE=SYSTEM,VECTOR=MIC
Chapter 108. TIMEUSED — Obtain accumulated CPU or vector time
1053
TIMEUSED macro
1054
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 109. TRANMSG — Translate messages
Description
The TRANMSG macro returns a translated message or messages in a requested language. TRANMSG translates any of the following forms of messages: v Self-defined text v A message text block (MTB) v A message parameter block (MPB) v A combination of the above
TRANMSG uses a message input/output block (MIO) as input. You can either create the MIO, or let TRANMSG create it for you. You must create the MIO if you are translating multi-line messages with continuation lines. If you create the MIO for multi-line messages, it must contain the following: v Code of the desired language v Addresses of the messages to be translated v Address of an output buffer in the calling program's address space into which
TRANMSG is to return the translated messages.
You must also set the MIOCONT flag on in the MIO for multi-line messages with continuation lines.
Otherwise, use parameters on TRANMSG to provide that information, so
TRANMSG can build the MIO correctly.
Upon return, each translated message is in the output buffer in the form of an
MTB, and the MIO contains the addresses of the MTBs. If the translated message has more than one line, the MTB will indicate multiple lines by showing more than one message entry area within the MTB associated with the translated message.
See z/OS MVS Programming: Assembler Services Guide for more information on using
TRANMSG.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt Status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task or SRB
PASN=HASN=SASN or PASN¬=HASN¬=SASN
24- or 31-bit
Primary
Enabled for I/O and external interrupts
No locks held
Not applicable
© Copyright IBM Corp. 1988, 2017
1055
TRANMSG macro
Programming requirements
Before invoking TRANMSG, you must obtain storage for: v The MIO v The output buffer where TRANMSG will return the translated messages.
The size of the storage you will need for the MIO and output buffer depends on the number and size of messages you are translating. See z/OS MVS Data Areas in the z/OS Internet library (www.ibm.com/systems/z/os/zos/library/bkserv) for a mapping of the MIO. Storage must be in the address space in which the calling program issued TRANMSG.
You must include the following mapping macros: v CNLMMIO v
CNLMMCA
Restrictions
If TRANMSG builds the MIO for your application: v Message translation starts at the first message in the message entry list (list addr in the INBUF parameter).
v The first message must contain a message identifier.
v You must supply all parameters on TRANMSG.
If you provide a formatted MIO, the only required parameter is MIO.
Input register information
Before issuing the TRANMSG macro, the caller must ensure that register 13 contains the address of an 18-word save area, which can be provided through the use of standard linkage conventions.
Output register information
When the TRANMSG macro returns control, the output registers contain the following values:
Register
Contents
0
The contents of the high-order halfword are not part of the intended programming interface. The low-order halfword contains a reason code.
1
2-13
14
15
Used as a work register by system
Unchanged
Used as a work register by system
Return code
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
Translating multiple messages on one invocation of TRANMSG is more efficient than invoking TRANMSG multiple times with one message for each invocation.
1056
z/OS MVS Assembler Services Reference IAR-XCT
�
Syntax
name
Syntax
If you build the MIO, code the TRANMSG macro as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede TRANMSG.
TRANMSG
�
MIO=msg block addr
One or more blanks must follow TRANMSG.
msg block addr: RX-type address or register (2) - (12).
TRANMSG macro
Syntax
name
�
TRANMSG
�
MIO=msg block addr
,MIOL=length of block addr
,INBUF=(list addr, num of
entries addr)
,OUTBUF=output buffer addr
,OUTBUFL=output buffer
length addr
,LANGCODE=lang code addr
If you want the TRANMSG macro to build the MIO, code TRANMSG as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede TRANMSG.
One or more blanks must follow TRANMSG.
msg block addr: RX-type address or register (2) - (12).
length of block addr: RX-type address or register (2) - (12).
list addr: RX-type address or register (2) - (12).
num of entries: RX-type address or register (2) - (12).
output buffer addr: RX-type address or register (2) - (12).
output buffer length addr: RX-type address or register (2) - (12).
lang code addr: RX-type address or register (2) - (12).
Chapter 109. TRANMSG — Translate messages
1057
TRANMSG macro
Parameters
The parameters are explained as follows:
MIO=msg block addr
Specifies the address, or a register, containing the address of an area containing the MIO or the address where TRANMSG is to build or find the MIO. If you have built the MIO, code only this parameter. Specify all other parameters only if TRANMSG is to build the MIO.
,MIOL=length of block addr
Specifies the address of a fullword or a register containing the length in bytes of the MIO. The length value is right-justified and padded with blanks. This parameter is required if TRANMSG is to build the MIO.
,INBUF=(list addr, num of entries addr)
Specifies the address of a register pointing to the list of addresses of the self-defined text, MPB, or MTB that TRANMSG is to use as input, and the number of entries in the list, respectively. This parameter is required if
TRANMSG is to build the MIO.
,OUTBUF=output buffer addr
Specifies the address of a register containing the address of the output buffer into which TRANMSG is to return translated messages in the form of MTBs.
This parameter is required if TRANMSG is to build the MIO.
,OUTBUFL=output buffer length addr
Specifies the address of a fullword or a register containing the length in bytes of the output buffer. This parameter is required if TRANMSG is to build the
MIO.
,LANGCODE=lang code addr
Specifies the address of, or a register pointing to, the 3-byte character field containing the code of the language into which you want the messages translated. z/OS MVS Programming: Assembler Services Guide contains a list of language codes. This parameter is required if TRANMSG is to build the MIO.
Return and reason codes
While TRANMSG provides return and reason codes in registers 15 and 0, respectively, you can determine exactly which message failed by looking at the reason code returned for each message in the MIOREAS field of the MIO variable data area. See z/OS MVS Data Areas in the z/OS Internet library
(www.ibm.com/systems/z/os/zos/library/bkserv) for a mapping of the MIO.
When TRANMSG completes, register 15 contains one of the following hexadecimal return codes:
Meaning Hexadecimal
Return Code
00
04
08
Processing completed successfully.
Processing complete. The output is complete, but TRANMSG might not have translated everything (for example, one variable in your message might not have translated).
Processing complete. The output is usable, but incomplete (for example, you might not have received all lines of a multiline message).
1058
z/OS MVS Assembler Services Reference IAR-XCT
Hexadecimal
Return Code
0C
TRANMSG macro
Meaning
Processing ended prematurely. The output is unusable. Possible causes are: v You have attempted to translate too many messages at one time.
v The MIO is not valid v The output buffer is too small for any messages.
Processing did not complete. The output is unpredictable.
10
When TRANMSG completes, the low-order halfword of register 0 contains one of the following hexadecimal reason codes:
Meaning Hexadecimal
Return Code
00
04
Hexadecimal
Reason Code
00
07
04
04
04
04
04
04
04
04
04
04
04
04
04
04
04
08
0B
0C
0D
1A
1B
1C
1D
1F
21
22
23
24
25
32
Successful processing.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
The passed storage address is not valid.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
TRANMSG returned a token value as text.
The translated message is not a valid mixed DBCS string.
A substitution token that is in the MPB is not in the message skeleton.
A substitution token that is in the message skeleton is not in the MPB.
The internal day code is not valid.
The required date format is not available.
TRANMSG used the default.
A date formatting failure occurred.
The required time format is not available.
TRANMSG used the default.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
Input for the date format is not numeric. TRANMSG returned the date without formatting it.
Chapter 109. TRANMSG — Translate messages
1059
TRANMSG macro
0C
0C
0C
0C
0C
0C
0C
0C
0C
0C
08
08
08
08
08
08
Hexadecimal
Return Code
08
08
08
08
0C
11
12
13
15
02
04
05
06
0A
10
18
19
1E
20
03
14
Hexadecimal
Reason Code
01
2B
33
34
17
Meaning
The language you requested is not available.
TRANMSG returned a U.S. English message.
The buffer space is insufficient for the output parameter blocks. The output was truncated.
The message identifier is longer than the text of the message continuation.
The input message length is not valid.
The input message does not match a message in the run-time message file.
TRANMSG did not find a match in the target language run-time message file.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
TRANMSG could not match the message ID in the message skeleton to those contained in the run-time message file.
TRANMSG attempted to match message text against an English message skeleton with translated line numbers. Input to TRANMSG must be an MPB when you use English message skeletons with translated line numbers.
TRANMSG did not copy the input parameter block from the caller's address space.
TRANMSG was unable to copy the MIO from the caller's address space.
The MIO acronym is not valid.
TRANMSG was unable to copy the MIO and output parameter blocks to the caller's address space.
TRANMSG could not obtain storage.
The length of the MIO is less than the minimum length for a valid MIO.
The length of the MTB is less than the minimum length for a valid MTB.
The length of the MPB is less than the minimum length for a valid MPB.
The MTB record count is not valid. The message record count must be one (1).
The input message has a length less than three. A valid input message must have at least one character each for the message identifier and the message text, separated by a blank character.
The MVS message service is unavailable.
1060
z/OS MVS Assembler Services Reference IAR-XCT
TRANMSG macro
0C
0C
0C
0C
10
0C
0C
0C
Hexadecimal
Return Code
0C
Hexadecimal
Reason Code
26
2A
31
39
3A
09
27
28
29
Meaning
The translation request terminated. The MMS user exit has set the processing indicator to a nonzero value.
The entry installation exit has failed.
The exit installation exit has failed.
The continuation ID in a multi-line message has zero length.
The MIO invocation type is not valid.
The MIOXLATE field in the MIO is not valid.
The MIO is too small.
The number in the list of entries is not a valid value.
This reason code is for internal diagnostic purposes only. Record it and supply it to the appropriate IBM support personnel.
If you translate multiple lines of message text
The return code and reason code you receive will reflect the most severe condition.
Multiple lines of message text can be either multi-line messages or multiple messages. You will need to check the MIOREASN field contained within the variable message entry areas of the MIO to determine processing status of each line. The MIOREASN field provides reasons for the errors.
If you received return codes 0 or 4, check field MIOTRUNC in the MIO to see if
TRANMSG processed all message input.
It is possible that the output buffer was not large enough to hold all the translated messages. A return code of 0 or 4 might indicate this situation. Check the
MIOTRUNC field of the MIO. If MIOTRUNC is 0, TRANMSG processed all messages. If MIOTRUNC is nonzero, it contains the number of the first message that did not fit into the input buffer.
If TRANMSG processing ended prematurely
You can increase the output buffer size, then reissue TRANMSG, or you can redrive message translation (that is, restart message translation at the point where it ended.) You can redrive message translation by using the same MIO and input and output data areas. Save the output of the failing message translation before redriving because TRANMSG reuses these fields on subsequent calls to translate the remaining messages. To redrive message translation, do the following:
1.
First, determine where processing stopped. The nonzero number in the
MIOTRUNC field is the number of the output message TRANMSG truncated because it did not fit into the output buffer. For example, if you issue
TRANMSG to return five translated messages, and the output buffer can hold only three messages, TRANMSG will not return the fourth and fifth message in the output buffer. When TRANMSG completes, the MIOTRUNC field would contain a value of 4.
2.
Set the MIOXLATE field of the MIO to the value of the MIOTRUNC field; in this case, 4.
Chapter 109. TRANMSG — Translate messages
1061
TRANMSG macro
3.
If the first message to be translated is a continuation message (contains no message ID), also set the MIOMID field to the message value, and the
MIOMIDL field to the message ID length of the associated continuation message.
4.
Issue TRANMSG again to translate the remaining messages, starting, in this case, with the fourth message.
Repeat this process until MIOTRUNC is 0, indicating that all input messages have been processed.
If you don't want to redrive using the same MIO, allocate a new, larger output buffer, change the MIO output buffer pointer, the length fields MIOBFPTR and
MIOBFSIZ, and the MIOXLATE field. Issue TRANMSG again until MIOTRUNC is
0.
Example 1
Translate U.S. English text to Japanese using self-defined text as input. TRANMSG will build the MIO.
TRANSSDT CSECT
TRANSSDT AMODE 31
TRANSSDT RMODE ANY
STM 14,12,12(13)
BALR 12,0
USING *,12
ST
LA
13,SAVE+4
15,SAVE
ST
LR
15,8(13)
13,15
***********************************************************************
* GETMAIN STORAGE AREA FOR THE MIO *
***********************************************************************
* *
GETMAIN RU,LV=STORLEN,SP=SP230
LR R4,R1 SAVE STORAGE ADDRESS
USING MIO,R4
L R2,MLENGTH
AR R2,R1
OBTAIN LENGTH OF MIO AREA
CALCULATE ADDRESS OF OUTPUT BUFFER
* *
***********************************************************************
* ISSUE TRANSLATE FOR MESSAGE *
***********************************************************************
*
TRANMSG MIO=MIO,MIOL=MLENGTH,INBUF=(SDTA,ONE),
OUTBUF=(R2),OUTBUFL=OUTAREAL,LANGCODE=LC
*
C
***********************************************************************
* FREE STORAGE AREA FOR THE MIO *
***********************************************************************
* *
FREEMAIN RU,LV=STORLEN,SP=SP230,A=(4)
* *
***********************************************************************
L 13,SAVE+4
LM
BR
14,12,12(13)
14
DROP
***********************************************************************
MLENGTH DC
OUTAREAL DC
SDT DC
DC
SDTA DC
A(MLEN)
A(STORLEN-MLEN)
H’37’
CL37’XXXX01 ENGLISH MESSAGE WITH ID XXXX01’
A(SDT)
1062
z/OS MVS Assembler Services Reference IAR-XCT
TRANMSG macro
LC
SP230
ONE
SAVE
R1
R2
R4
MLEN
DC CL3’JPN’
EQU 230
DC
DC
F’1’
18F’0’
EQU 1
EQU 2
EQU 4
EQU (MIOVDAT-MIO)+MIOMSGL
STORLEN EQU 512
***********************************************************************
DSECT
CNLMMCA
CNLMMIO
END TRANSSDT
Example 2
Translate U.S. English text to Japanese. Build your own MIO.
TRANS2A CSECT
TRANS2A AMODE 31
TRANS2A RMODE ANY
STM 14,12,12(13)
BALR 12,0
USING *,12
ST
LA
13,SAVE+4
15,SAVE
ST
LR
15,8(13)
13,15
* *
***********************************************************************
* GETMAIN STORAGE AREA *
***********************************************************************
* *
GETMAIN RU,LV=STORLEN,SP=SP230
LR R4,R1
XC 0(MIOVDAT-MIO,R4),0(R4) CLEAR MIO HEADER SECTION
MVC MIOACRN-MIO(L’MIOACRN,R4),=C’MIO ’ SET ACRONYM
MVI MIOVRSN-MIO(R4),$MIO_VERSION
MVC MIOSIZE-MIO(4,R4),MLENGTH
SET VERSION NUMBER
SAVE MIO SIZE
MVC MIOLANG-MIO(L’MIOLANG,R4),=C’JPN’ SET LANGUAGE NAME
L R3,MLENGTH CALCULATE OUTAREA ADD
LA
ST
AR
XC
AR
ST
R3,R4
R3,MIOBFPTR-MIO(,R4)
GET MIO ADDRESS
SET OUTAREA ADDRESS
MVC MIOBFSIZ-MIO(L’MIOBFSIZ,R4),OUTAREAL SET OUTAREA LENGTH
LA R3,1
ST R3,MIOXLATE-MIO(,R4)
MVI MIOMID-MIO(R4),C’ ’
ST
LA
R3,MIOVDATL-MIO(,R4)
R3,1
SET TO FIRST MSG
INIT MSGID TO SPACES
MVC MIOMID-MIO+1(L’MIOMID-1,R4),MIOMID-MIO(R4)
LA R3,MIOMSGL GET LENGTH OF MIO
SAVE VARIABLE AREA LENGTH
ST R3,MIOMSGNO-MIO(,R4)
R3,MIOVDAT-MIO
R3,MIOOFFST-MIO(,R4)
R3,R4
0(MIOMSGL,R3),0(R3)
SET NUMBER OF MSGS
TO TRANSLATE
C
GET OFFSET TO VAR. AREA
SAVE OFFSET TO 1ST MSG
POINT TO MIO VARIABLE AREA
CLEAR MSG ENTRY AREA
LA
ST
R2,SDT
R2,MIOINPTP-MIOMSG(,R3)
MVI MIOINFL-MIOMSG(R3),MIOXLATF
* *
***********************************************************************
* ISSUE TRANSLATE FOR MESSAGE *
***********************************************************************
* *
TRANMSG MIO=(R4)
OBTAIN INPUT AREA ADDRESS
SAVE INPUT AREA ADDRESS
INDICATE TRANSLATE
* *
Chapter 109. TRANMSG — Translate messages
1063
TRANMSG macro
***********************************************************************
* FREE STORAGE AREA *
***********************************************************************
* *
FREEMAIN RU,LV=STORLEN,SP=SP230,A=(4)
* *
***********************************************************************
L
LM
13,SAVE+4
14,12,12(13)
BR
DROP
14
***********************************************************************
DS 0F
MLENGTH DC
OUTAREAL DC
SDT DC
DC
A(MLEN)
A(STORLEN-MLEN)
H’37’
CL37’XXXX01 ENGLISH MESSAGE WITH ID XXXX01’
INAREA DC
LC DC
SP230
ONE
EQU
DC
A(SDT)
CL3’JPN’
230
F’1’
SAVE
R1
R2
R3
R4
MLEN
DC
EQU
EQU
EQU
EQU
EQU
18F’0’
1
2
3
4
(MIOVDAT-MIO)+MIOMSGL
STORLEN EQU 512
***********************************************************************
DSECT
CNLMMCA
CNLMMIO
END TRANS2A
Example 3
Translate three single-line U.S. English messages to Japanese using self-defined text as input.
TRANMULT CSECT
TRANMULT AMODE 31
TRANMULT RMODE ANY
STM 14,12,12(13)
BALR 12,0
USING *,12
ST
LA
13,SAVE+4
15,SAVE
ST
LR
15,8(13)
13,15
* *
***********************************************************************
* GETMAIN STORAGE AREA *
***********************************************************************
* *
GETMAIN RU,LV=STORLEN,SP=SP230
LR R4,R1 SAVE STORAGE ADDRESS
USING MIO,R4
L
AR
R2,MLENGTH
R2,R1
OBTAIN LENGTH OF MIO AREA
CALCULATE ADDRESS OF OUTPUT BUFFER
* *
***********************************************************************
* ISSUE TRANSLATE FOR MESSAGE *
***********************************************************************
*
TRANMSG MIO=MIO,MIOL=MLENGTH,INBUF=(SDT1A,THREE),
OUTBUF=(R2),OUTBUFL=OUTAREAL,LANGCODE=LC
*
C
***********************************************************************
1064
z/OS MVS Assembler Services Reference IAR-XCT
TRANMSG macro
* FREE STORAGE AREA *
***********************************************************************
* *
FREEMAIN RU,LV=STORLEN,SP=SP230,A=(4)
* *
***********************************************************************
L
LM
BR
DROP
13,SAVE+4
14,12,12(13)
14
***********************************************************************
MLENGTH DC A(MLEN)
OUTAREAL DC
SDT1 DC
A(STORLEN-MLEN)
H’33’
SDT2
SDT3
SDT1A
SDT2A
SDT3A
LC
SP230
THREE
SAVE
R1
DC
DC
DC
DC
DC
DC
DC
DC
CL33’XXXX0A THIS IS MESSAGE NUMBER ONE’
H’33’
CL33’XXXX0B THIS IS MESSAGE NUMBER TWO’
H’35’
CL35’XXXX0C THIS IS MESSAGE NUMBER THREE’
A(SDT1)
A(SDT2)
A(SDT3)
DC CL3’JPN’
EQU 230
DC F’3’
DC 18F’0’
EQU 1
R2
R4
EQU 2
EQU 4
MLEN EQU (MIOVDAT-MIO)+(3*MIOMSGL)
STORLEN EQU 512
***********************************************************************
DSECT
CNLMMCA
CNLMMIO
END TRANMULT
Example 4
Translate U.S. English text to Japanese using an MTB as input. Create the input
MTB.
TRANMTBA CSECT
TRANMTBA AMODE 31
TRANMTBA RMODE ANY
STM 14,12,12(13)
BALR 12,0
USING *,12
ST
LA
13,SAVE+4
15,SAVE
ST
LR
15,8(13)
13,15
* *
***********************************************************************
* GETMAIN STORAGE AREA *
***********************************************************************
* *
GETMAIN RU,LV=STORLEN,SP=SP230
LR R4,R1 SAVE STORAGE ADDRESS
USING MIO,R4
L R2,MLENGTH
AR R2,R4
USING MTB,R2
OBTAIN LENGTH OF MIO AREA
CALCULATE ADDRESS OF MTB
MVC MTBACRN,=C’MTB ’ SET ACRONYM
MVI MTBVRSN,$MTB_VERSION SET VERSION NUMBER
MVC MTBLNGCD,LC
LA R3,MTBLEN
SET LANGUAGE CODE
CALCULATE SIZE OF MTB
Chapter 109. TRANMSG — Translate messages
1065
TRANMSG macro
ST
LA
R3,MTBSIZE
R3,MTBVDAT-MTB
ST R3,MTBOFFST
MVC MTBCOUNT,ONE
SAVE MTB SIZE
OBTAIN LENGTH OF MTB HEADER
SAVE OFFSET TO MTB VARIABLE AREA
SAVE RECORD COUNT
MVC MTBVDATL,SDTLEN
AR R3,R2
SAVE MTB VARIABLE AREA SIZE
POINT TO MTB VARIABLE AREA
USING MTBMSG,R3
MVC
ST
LA
MTBMSG(39),SDT
R2,LIST
R3,39(,R3)
SET MESSAGE LENGTH
SAVE MTB ADDRESS LIST
SAVE ADDRESS OF OUTPUT BUFFER
***********************************************************************
* ISSUE TRANSLATE FOR MESSAGE *
***********************************************************************
*
TRANMSG MIO=MIO,MIOL=MLENGTH,INBUF=(LIST,ONE),
OUTBUF=(R3),OUTBUFL=OUTAREAL,LANGCODE=LC
*
C
***********************************************************************
* FREE STORAGE AREA *
***********************************************************************
* *
FREEMAIN RU,LV=STORLEN,SP=SP230,A=(4)
* *
***********************************************************************
L
LM
13,SAVE+4
14,12,12(13)
BR 14
***********************************************************************
MLENGTH DC
OUTAREAL DC
SDT DC
DC
A(MLEN)
A(STORLEN-(MLEN+MTBLEN))
H’37’
CL37’XXXX01 ENGLISH MESSAGE WITH ID XXXX01’
LC
SP230
ONE
ZERO
DC CL3’JPN’
EQU 230
DC
DC
F’1’
F’0’
SDTLEN DC
SAVE DC
LIST
R1
DC
F’39’
18F’0’
F’0’
EQU 1
R2
R3
EQU 2
EQU 3
R4 EQU 4
STORLEN EQU 512
MLEN EQU (MIOVDAT-MIO)+MIOMSGL
MTBLEN EQU (MTBVDAT-MTB)+39
***********************************************************************
DSECT
CNLMMCA
CNLMMIO
CNLMMTB
END TRANMTBA
Example 5
Translate a U.S. English multiline message into Japanese. Create the MIO.
TRANSMLA CSECT
TRANSMLA AMODE 31
TRANSMLA RMODE ANY
STM 14,12,12(13)
BALR 12,0
USING *,12
ST
LA
13,SAVE+4
15,SAVE
ST
LR
15,8(13)
13,15
* *
***********************************************************************
1066
z/OS MVS Assembler Services Reference IAR-XCT
TRANMSG macro
* GETMAIN STORAGE AREA *
***********************************************************************
* *
GETMAIN RU,LV=STORLEN,SP=SP230
LR R4,R1
XC 0(MIOVDAT-MIO,R4),0(R4) CLEAR MIO HEADER SECTION
MVC MIOACRN-MIO(L’MIOACRN,R4),=C’MIO ’ SET ACRONYM
MVI MIOVRSN-MIO(R4),$MIO_VERSION
MVC MIOSIZE-MIO(4,R4),MLENGTH
SET VERSION NUMBER
SAVE MIO SIZE
MVC MIOLANG-MIO(L’MIOLANG,R4),=C’JPN’ SET LANGUAGE NAME
L R3,MLENGTH CALCULATE OUTAREA ADD
AR
ST
R3,R4
R3,MIOBFPTR-MIO(,R4)
GET MIO ADDRESS
SET OUTAREA ADDRESS
MVC MIOBFSIZ-MIO(L’MIOBFSIZ,R4),OUTAREAL SET OUTAREA LENGTH
LA R3,1
LA
ST
AR
LA
ST R3,MIOXLATE-MIO(,R4)
MVI MIOMID-MIO(R4),C’ ’
ST
LA
R3,MIOVDATL-MIO(,R4)
R3,3
SET TO FIRST MSG
INIT MSGID TO SPACE
MVC MIOMID-MIO+1(L’MIOMID,R4),MIOMID-MIO(R4) CLEAR MSGID
LA R3,MSGLEN GET LENGTH OF MIO
SAVE VARIABLE AREA LENGTH
ST R3,MIOMSGNO-MIO(,R4)
R3,MIOVDAT-MIO
R3,MIOOFFST-MIO(,R4)
R3,R4
R15,MIOVDAT-MIO
SET NUMBER OF MSGS
TO TRANSLATE
GET OFFSET TO VAR. AREA
SAVE OFFSET TO 1ST MSG
POINT TO MIO VARIABLE AREA
GET LENGTH OF MIO HEADER
AR
LA
R15,R4
R3,SDT1A
XC 0(MIOMSGL,R15),0(R15)
MVC MIOINPTP-MIOMSG(4,R15),0(R3)
MVI MIOINFL-MIOMSG(R15),MIOXLATF
LA R3,4(,R3)
LA
L
R15,MIOMSGL(,R15)
0,TWO
GET ADDRESS OF MIO MSG ENTRY
GET MSG AREA LENGTH
CLEAR MSG ENTRY AREA
GET ADDRESS OF SDT
INDICATE TRANSLATE
POINT TO NEXT MESSAGE ADDR.
POINT TO NEXT MESSAGE ENTRY
SET NUMBER OF MESSAGES
LOOP
*
DS
XC
OI
OI
LA
LA
BCT
0H
0(MIOMSGL,R15),0(R15)
MVC MIOINPTP-MIOMSG(4,R15),0(R3)
MIOINFL-MIOMSG(R15),MIOXLATF
MIOINFL-MIOMSG(R15),MIOCONT
R3,4(,R3)
R15,MIOMSGL(,R15)
0,LOOP
CLEAR MSG ENTRY AREA
GET ADDRESS OF SDT
INDICATE TRANSLATE
INDICATE CONTINUATION
POINT TO NEXT MESSAGE ADDR.
POINT TO NEXT MESSAGE ENTRY
LOOP UNTIL ALL MSGS PROCESSED
*
***********************************************************************
* ISSUE TRANSLATE FOR MESSAGE *
***********************************************************************
* *
TRANMSG MIO=(R4)
* *
***********************************************************************
* FREE STORAGE AREA *
***********************************************************************
* *
FREEMAIN RU,LV=STORLEN,SP=SP230,A=(4)
* *
***********************************************************************
L
LM
13,SAVE+4
14,12,12(13)
BR 14
***********************************************************************
MLENGTH DC
OUTAREAL DC
TWO
SDT1
DC
DC
SDT2
DC
DC
A(MLEN)
A(STORLEN-MLEN)
F’2’
H’33’
CL33’MSGID1 ENGLISH MESSAGE - LINE ONE’
H’28’
C
Chapter 109. TRANMSG — Translate messages
1067
TRANMSG macro
SDT3
DC
DC
CL28’ENGLISH MESSAGE - LINE TWO ’
H’30’
SDT1A
SDT2A
SDT3A
LC
SAVE
SP230
R1
R2
R3
R4
R15
DC
DC
DC
DC
DC
DC
EQU
EQU
EQU
CL30’ENGLISH MESSAGE - LINE THREE
A(SDT1)
A(SDT2)
A(SDT3)
CL3’JPN’
18F’0’
EQU 230
1
EQU 2
3
EQU 4
15
MSGLEN EQU 3*MIOMSGL
’
MLEN EQU (MIOVDAT-MIO)+MSGLEN
STORLEN EQU 512
***********************************************************************
DSECT
CNLMMCA
CNLMMIO
END TRANSMLA
1068
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 110. TTIMER — Test interval timer
Description
The TTIMER macro tests the timer interval established by an STIMER macro. It also optionally cancels the remaining time interval.
If MIC is specified, the remaining time is returned to the doubleword area specified in the address. Bit 51 of the area is the low-order bit of the interval value and equivalent to one microsecond. If a time interval has not been set or has already expired, the area is set to zero.
Note:
The resolution of the timer is model dependent. See Principles of Operation for additional details concerning timing facilities.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
24- or 31- or 64-bit
Primary
Enabled or disabled for I/O and external interrupts
No locks held
Must be in the primary address space
Programming requirements
For information about programs in 64-bit addressing mode (AMODE 64), see z/OS
MVS Programming: Extended Addressability Guide.
Restrictions
Time intervals established via the STIMERM SET macro cannot be tested or cancelled with the TTIMER macro.
Input register information
Before issuing the TTIMER macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0
Used as a work register by the system if you do not specify TU. If you specify TU, register 0 contains the amount of time remaining in a timer interval.
© Copyright IBM Corp. 1988, 2017
1069
TTIMER macro
Syntax
1
2-13
14
15
Used as a work register by the system.
Unchanged.
Used as a work register by the system.
Return code.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service and restore them after the system returns control.
Performance implications
None.
Syntax
The TTIMER macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede TTIMER.
TTIMER
� One or more blanks must follow TTIMER.
CANCEL
,TU
,MIC,stor addr
Default
: TU
stor addr: RX-type address, or register (0) or (2) - (12).
The ERRET parameter is obsolete and is ignored by the system. Therefore, the syntax and parameter descriptions for TTIMER no longer contain ERRET.
However, the system still accepts ERRET and it is not necessary to delete it from existing code.
Parameters
The parameters are explained as follows:
CANCEL
Specifies that the remaining time interval and any exit routine are to be canceled. If the time interval has already expired, the CANCEL option has no effect and a value of zero time remaining is returned. In this case, a specified exit will still receive control. If a nonzero time remaining is returned when the
CANCEL option is specified, any exit routine is canceled. If CANCEL is not designated, the unexpired portion of the time interval remains in effect.
1070
z/OS MVS Assembler Services Reference IAR-XCT
TTIMER macro
If WAIT was coded in the STIMER macro that established the interval, the task is not taken out of the wait condition and CANCEL is ignored.
,TU
,MIC,stor addr
Specifies that the remaining time in the interval be returned.
For TU, the time is returned in register 0 as an unsigned 32-bit binary number.
The low-order bit is approximately 26.04166 microseconds (one timer unit). If the time remaining is too great to be expressed in four bytes, the remaining time interval is set to the maximum possible value (X'FFFFFFFF') and the return code is set to 4.
For MIC, the time is returned in microseconds. The stor addr is the doubleword area on a doubleword boundary where the remaining interval is to be stored.
ABEND codes
12E
See z/OS MVS System Codes for an explanation and programmer responses for this code.
Return codes
When TTIMER macro returns control to your program, GPR 15 contains a return code.
Table 64. Return Codes for the TTIMER Macro
Hexadecimal
Return Code
00
Meaning and Action
Meaning
: Successful completion.
04
Action
: None.
Meaning
: You specified the TU parameter, but the time remaining is greater than X'FFFFFFFF'.
Action
: None required. However, you might take some action based upon your application.
Example 1
Cancel the task's current time interval. The time remaining, if any, should be returned in timer units in register 0.
TTIMER CANCEL,TU
Example 2
Return the time remaining, in microseconds, to the storage location addressed by the label OUTAREA. Do not cancel the interval.
TTIMER ,MIC,OUTAREA
.
.
DS
OUTAREA DC
0D
2F
Chapter 110. TTIMER — Test interval timer
1071
TTIMER macro
1072
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 111. UCBDEVN — Return EBCDIC device number for a UCB
Description
Use the UCBDEVN macro to obtain the printable EBCDIC format for the device number of a given unit control block (UCB). When issuing UCBDEVN, an unauthorized caller must pass a copy of the UCB unless one of the following is true: v The caller received the UCB address from an authorized program that can guarantee that the UCB is pinned or cannot be deleted by a dynamic configuration change.
v The caller is running in an environment where dynamic configuration changes cannot occur.
v The caller can otherwise guarantee that the UCB will not be deleted.
The caller can obtain a copy of the UCB by using the UCBSCAN macro. See z/OS
MVS Programming: Assembler Services Guide for information about accessing UCBs.
Before issuing UCBDEVN, authorized callers must pin the UCB unless one of the following is true: v The caller is running in an environment where dynamic configuration changes cannot occur.
v The caller can otherwise guarantee that the UCB will not be deleted.
If you are coding an authorized program that must pin the UCB, see z/OS MVS
Programming: Authorized Assembler Services Guide for information about accessing
UCBs.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task or SRB
Any PASN, any HASN, any SASN.
24- or 31-bit
Primary
Enabled or disabled for I/O and external interrupts
No locks held
No requirement
Programming requirements
If you do not specify the UCBPTR parameter, you must include the IEFUCBOB mapping macro and establish addressability to the UCB common segment through a USING statement.
© Copyright IBM Corp. 1988, 2017
1073
UCBDEVN macro
Syntax
Restrictions
The caller of UCBDEVN cannot pass a copy of a UCB for a nonbase exposure of a multiple-exposure device.
When issuing UCBDEVN, the caller cannot pass a copy of an alias UCB of a parallel access volume.
UCBDEVN accepts above 16 megabyte UCBs, below 16 megabyte UCBs, and captured UCBs as input. To specify an above 16 megabyte UCB, the caller must run in AMODE 31. If the caller runs in AMODE 31 and passes a 24-bit UCB pointer, the pointer must have a clean high order byte.
Input register information
Before issuing the UCBDEVN macro, the caller must ensure that GPR 13 contains the address of an 18-word save area.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The UCBDEVN macro is written as follows:
Description
name
⌂
name: Symbol. Begin name in column 1.
One or more blanks must precede UCBDEVN.
UCBDEVN
⌂
DEVN=devnumber
XDEVN=xdevn
One or more blanks must follow UCBDEVN.
devnumber: RS-type address.
xdevn: Mutually exclusive with the DEVN keyword.
1074
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,UCBPTR=ucbptr
UCBDEVN macro
Description
ucbptr: RX-type address.
Note:
If you omit this parameter, the system assumes that you have established addressability to the UCB common segment.
Default
: NO ,NONBASE=NO
,NONBASE=YES
Parameters
The parameters are explained as follows:
DEVN=devnumber
Specifies the name of the fullword area in which the system returns the
EBCDIC device number.
XDEVN=xdevn
Ten character field containing the EBCDIC form of the UCB name. The first byte is the length of the returned UCB name text. The remainder of the field contains the returned UCB name text, left-justified and padded with blanks.
The string that is returned is a logical device number composed of 4 or more hex digits.
XDEVN is mutually exclusive with the DEVN keyword.
,UCBPTR=ucbptr
Specifies a fullword containing the address of the UCB common segment, which contains the device number you need. If you omit this parameter, you must do the following: v Include the IEFUCBOB mapping macro in your program to map the UCB.
v Establish addressability to the UCB common segment through a USING statement.
v Place the address of the UCB common segment in the register specified in the USING statement.
If the UCB common segment is for a multiple exposure device, the system returns printable EBCDIC for the base exposure device number.
,NONBASE=NO
,NONBASE=YES
Specifies which device number the caller should receive for a specified alias
UCB of a parallel access volume. NO specifies the base device number, and
YES specifies the alias device number.
Return and reason codes
UCBDEVN does not return any return codes.
Example
Use the UCBDEVN macro to obtain the printable EBCDIC form of the device number for the UCB whose address is in UCBVAL. The system is to return the value in the fullword named WORD1.
UCBDEVN DEVN=WORD1,UCBPTR=UCBVAL
Chapter 111. UCBDEVN — Return EBCDIC device number for a UCB
1075
UCBDEVN macro
1076
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 112. UCBINFO — Return information from a UCB
|
|
|
Description
Use the UCBINFO macro to obtain information from a unit control block (UCB) for a specified device. The UCBINFO macro provides the following options:
DEVCOUNT
Returns a count of the UCBs for a device class or device group.
DEVINFO
Returns information about a device, particularly, why the device is offline.
For the base UCB of a Parallel Access Volume (PAV), DEVINFO returns the number of alias UCBs that are defined, and the number that are usable.
Also, the DEVINFO can return an indicator in the IOSDDEVI mapping macro reflecting whether the device is a Hyper Parallel Access Volume
(HyperPAV) device.
GETCDR
Returns the Configuration Data Record (CDR) for a specific device-path from the Configuration Data Table (CDT).
HYPERPAVALIASES
Returns information for HyperPAV aliases that are configured in the same logical subsystem as the input device. The HYPERPAVALIASES function allows you to obtain selected information for each alias exposure of a
Parallel Access Volume (PAV) device in HyperPAV mode. All alias exposures contained in the logical subsystem are returned in the output
PAVAREA. The data returned by this function is mapped by the mapping macro IOSDPAVA and consists of a header and one or more entries.
PATHINFO
Returns information about the device path and type of channel path associated with the device.
PATHMAP
Returns information about the device path.
PRFXDATA
Obtains a copy of the UCB prefix extension segment.
PAVINFO
Returns information about the alias UCBs for a Parallel Access Volume
(PAV) or a Hyper Parallel Access Volume (HyperPAV).
The options of the UCBINFO macro have the same environmental specifications, programming requirements, restrictions, register information, and performance implications described below, except where noted in the explanations of each option.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Requirement
Problem state and any PSW key.
Task or SRB
© Copyright IBM Corp. 1988, 2017
1077
UCBINFO macro
Environmental factor
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Locks:
Control parameters:
Requirement
Any PASN, any HASN, any SASN
24- or 31-bit
Primary or access register (AR)
Enabled or disabled for I/O and external interrupts
The caller may hold locks, but is not required to hold any
Control parameters must be in the primary address space or, for AR-mode callers, must be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
Programming requirements
Before issuing the UCBINFO macro, you can issue the UCBSCAN macro to obtain the device number, which you must provide as input to UCBINFO. See z/OS MVS
Programming: Assembler Services Guide for information about accessing UCBs.
The caller must include the appropriate mapping macro for the UCBINFO option being used:
Option Mapping Macro
DEVCOUNT
None
DEVINFO
IOSDDEVI mapping macro
HYPERPAVALIASES
IOSDPAVA mapping macro
PATHINFO
IOSDPATH mapping macro
PATHMAP
IOSDMAP mapping macro
PAVINFO
IOSDPAVA mapping macro
PRFXDATA
IOSDUPI mapping macro
Restrictions
None.
Input register information
Before issuing the UCBINFO macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
A reason code; otherwise, used as a work register by the system
Used as a work register by the system
1078
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
2-13
14
15
Unchanged
Used as a work register by the system
A return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Performance implications
None.
UCBINFO DEVCOUNT
Use the UCBINFO DEVCOUNT macro to obtain a count of the UCBs for a device class.
Syntax
Syntax
The standard form of the DEVCOUNT option of the UCBINFO macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
UCBINFO
�
One or more blanks must follow UCBINFO.
DEVCOUNT
,COUNT=count addr
,GROUP=DEVICELASS
,DEVCLASS=ALL
,DEVCLASS=CHAR
,DEVCLASS=COMM
,DEVCLASS=CTC
,DEVCLASS=DASD
,DEVCLASS=DISP
count addr: RS-type address or register (2) - (12).
Default:
ALL
Chapter 112. UCBINFO — Return information from a UCB
1079
UCBINFO macro
Syntax
,DEVCLASS=TAPE
,DEVCLASS=UREC
,GROUP=OTHER
,DEVGROUP=PAVBASE
,DEVGROUP=PAVALIAS
Description
Default:
PAVBASE
,SUBCHANNELSET=ID
,SCHSET=schset addr
,SCHSET=0
,SUBCHANNELSET=ALL
,IOCTOKEN=ioctoken addr
schset addr: RS-type address or register (2) - (12).
Default:
0
ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
,RETCODE=retcode addr
,RSNCODE=rsncode addr
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
Parameters
The parameters are explained as follows:
DEVCOUNT
Specifies that the system is to return a count of the UCBs.
,COUNT=count addr
Specifies the address of the fullword field that is to receive the count.
,GROUP=DEVICECLASS
GROUP specifies the grouping upon which the UCB count is based.
DEVICECLASS indicates that the UCB count is based on device classes.
,DEVICECLASS=ALL|CHAR|COMM|CTC|DASD|DISP|TAPE|UREC
Specifies the device class for which the corresponding UCBs are to be counted:
ALL
Counts UCBs for all device classes
CHAR
Counts UCBs for character reader device class
COMM
Counts UCBs for communications device class
1080
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
CTC
Counts UCBs for channel to channel device class
DASD
Counts UCBs for direct access device class
DISP
Counts UCBs for display device class
TAPE
Counts UCBs for tape device class
UREC
Counts UCBs for unit record device class
,GROUP=OTHER
GROUP specifies the grouping upon which the UCB count is based.
OTHER indicates that the UCB count is not based on device classes.
,DEVGROUP=PAVBASE
,DEVGROUP=PAVALIAS
Specifies the device group for which the corresponding UCBs are to be counted.
v PAVBASE , counts UCBs for Parallel Access Volume (PAV) base UCBs.
v PAVALIAS , counts UCBs for Parallel Access Volume (PAV) alias UCBs.
,SUBCHANNELSET=ID
,SUBCHANNELSET=ALL
,SUBCHANNELSET=ID
Indicates the UCB count is based on one subchannel set. DEFAULT: ID
,SCHSET=schset addr
,SCHSET=0
Specifies the name (RS-type), or address in register (2)-(12), of an optional byte input that specifies a subchannel set for which the UCBINFO request is to be performed. DEFAULT: 0.
,SUBCHANNELSET=ALL
Indicates the UCB count is based on all subchannel sets. DEFAULT: ID
,IOCTOKEN=ioctoken addr
Specifies the address of a 48-character storage area that contains the MVS I/O configuration token. The caller can obtain this token by issuing the IOCINFO macro. z/OS MVS Programming: Assembler Services Reference ABE-HSP If the I/O configuration token that is current when UCBINFO is invoked does not match the token whose address is supplied here, the system issues a return code to the caller.
If you set the input IOCTOKEN (specified by ioctoken addr) to binary zeros,
UCBINFO sets IOCTOKEN to the current I/O configuration token.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
Chapter 112. UCBINFO — Return information from a UCB
1081
|
|
|
|
|
UCBINFO macro
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 2 , if you use the currently available parameters.
To code
, specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 2.
,RETCODE=retcode addr
Specifies the address of a fullword field into which the system copies the return code from GPR 15.
,RSNCODE=rsncode addr
Specifies the address of a fullword field into which the system copies the reason code from GPR 0.
Return and reason codes
When the UCBINFO DEVCOUNT macro returns control to your program, GPR 15
(or retcode addr, if you coded RETCODE) contains a return code, and GPR 0 (or
rsncode addr, if you coded RSNCODE) contains a reason code.
Hexadecimal
Return Code
00
Hexadecimal
Reason Code
None
08
08
08
08
01
02
05
0B
Meaning and Action
Meaning:
The DEVCOUNT function completed successfully.
Action:
None.
Meaning:
Program error. A caller in AR mode specified an
ALET that was not valid.
Action:
Correct the ALET and reissue the macro.
Meaning:
Program error. The system could not access the caller's parameter list. This might be due to using a keyword that requires authorization but the caller was not authorized, that is the Supervisor state or PSW key 0 - 7.
Action:
Ensure that you have met the environmental requirements for the macro and reissue the macro.
Meaning:
Program error. An error occurred when the system referenced the caller-supplied area specified in the
IOCTOKEN parameter. This reason code is valid only for callers using the IOCTOKEN parameter.
Action:
Correct the IOCTOKEN parameter.
Meaning:
The value specified on the SCHSET keyword is not valid.
Action:
Enter the correct value on the SCHSET keyword.
1082
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
Hexadecimal
Return Code
0C
20
Hexadecimal
Reason Code
None
None
Meaning and Action
Meaning:
Environmental error. The I/O configuration token supplied through the IOCTOKEN parameter is not current. This return code is valid only for callers using the
IOCTOKEN parameter.
Action:
Obtain the current I/O configuration token by issuing an IOCINFO macro or by setting the input
IOCTOKEN parameter in the UCBINFO macro to zero.
Meaning:
System error. An unexpected error occurred.
Action:
Supply the return code to the appropriate IBM support personnel.
Example
To invoke UCBINFO to return a count of all DASD devices, code:
.
.
UCBINFO DEVCOUNT,COUNT=CTAREA,DEVCLASS=DASD,
RETCODE=INFORTCD,RSNCODE=RSNCD
.
X
DS 0D
CTAREA DS F
INFORTCD DS F
RSNCD DS F
UCBINFO DEVCOUNT—List form
Use the list form of the DEVCOUNT option of the UCBINFO macro together with the execute form for applications that require reentrant code. The list form of the macro defines an area of storage that the execute form uses to contain the parameters.
Syntax
This macro is an alternative list form macro, and requires a different technique for using the list form as compared to the conventional list form macros. See
“Alternative list form macros” on page 13 for further information.
The list form of the DEVCOUNT option of the UCBINFO macro is written as follows:
Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
UCBINFO
�
One or more blanks must follow UCBINFO.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
Default:
IMPLIED_VERSION
Chapter 112. UCBINFO — Return information from a UCB
1083
UCBINFO macro
Syntax
,PLISTVER=plistver
MF=(L,list addr)
MF=(L,list addr, attr)
MF=(L,list addr,0D)
Description
plistver: 2
list addr: RX-type address
attr: 1- to 60-character input string
Default:
0D
Parameters
The parameters are explained under the standard form of UCBINFO DEVCOUNT with the following exceptions:
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
Specifies the list form of the UCBINFO DEVCOUNT macro.
list addr is the name of a storage area to contain the parameters.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
UCBINFO DEVCOUNT—Execute form
Use the execute form of the DEVCOUNT option of the UCBINFO macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Syntax
The execute form of the DEVCOUNT option of the UCBINFO macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
UCBINFO
� One or more blanks must follow UCBINFO.
DEVCOUNT
,COUNT=count addr count addr: RS-type address or register (2) - (12).
1084
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,GROUP=DEVICELASS
,DEVCLASS=ALL
,DEVCLASS=CHAR
,DEVCLASS=COMM
,DEVCLASS=CTC
,DEVCLASS=DASD
,DEVCLASS=DISP
,DEVCLASS=TAPE
,DEVCLASS=UREC
,GROUP=OTHER
,DEVGROUP=PAVBASE
Description
Default:
ALL
Default:
PAVBASE
,SUBCHANNELSET=ID
,SCHSET=schset addr
,SCHSET=0
,SUBCHANNELSET=ALL
,IOCTOKEN=ioctoken addr
schset addr: RS-type address or register (2) - (12).
Default:
0
ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
retcode addr: RX-type address or register (2) - (12).
,RETCODE=retcode addr
,RSNCODE=rsncode addr
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
rsncode addr: RX-type address or register (2) - (12).
list addr: RX-type address or address in register (2) - (12).
Default:
COMPLETE
UCBINFO macro
Parameters
The parameters are explained under the standard form of UCBINFO DEVCOUNT with the following exceptions:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Specifies the execute form of the UCBINFO DEVCOUNT macro.
list addr specifies the area that the system uses to contain the parameters.
Chapter 112. UCBINFO — Return information from a UCB
1085
UCBINFO macro
COMPLETE, which is the default, specifies that the macro is to check for required parameters and supply defaults for omitted optional parameters.
UCBINFO DEVINFO
Use the UCBINFO DEVINFO macro to obtain information about a device, specifically, reasons why the device is offline.
Syntax
Syntax
The standard form of the DEVINFO option of the UCBINFO macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
UCBINFO
� One or more blanks must follow UCBINFO.
DEVINFO
,DEVIAREA=deviarea addr
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
deviarea addr: RX-type address or register (2) - (12).
devn addr: RS-type address or register (2) - (12).
schset addr: RS-type address or register (2) - (12).
Default:
0
,IOCTOKEN=ioctoken addr ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
,RETCODE=retcode addr
,RSNCODE=rsncode addr
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
Parameters
The parameters are explained as follows:
1086
z/OS MVS Assembler Services Reference IAR-XCT
|
|
UCBINFO macro
DEVINFO
Specifies that the system is to return information about the specified device.
,DEVIAREA=deviarea addr
Specifies the address of a required 256-byte output field into which the system is to return information about the specified device. This field is mapped by the mapping macro IOSDDEVI.
,DEVN=devn addr
Specifies the address of a halfword that contains, in binary form, the device number of the device. The DEVN and UCBPTR parameters are mutually exclusive.
,SCHSET=schset addr
,SCHSET=0
Specifies the name (RS-type), or address in register (2)-(12), of an optional byte input that specifies a subchannel set for which the device information is to be obtained. DEFAULT: 0.
,IOCTOKEN=ioctoken addr
Specifies the address of a 48-character storage area that contains the MVS I/O configuration token. The caller can obtain this token by issuing the IOCINFO macro. If the I/O configuration token that is current when UCBINFO is invoked does not match the token whose address is supplied here, the system issues a return code to the caller.
If you set the input IOCTOKEN (specified by ioctoken addr) to binary zeros,
UCBINFO sets IOCTOKEN to the current I/O configuration token.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 2 , if you use the currently available parameters.
To code
, specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v
A decimal value of 2
,RETCODE=retcode addr
Specifies the address of a fullword field into which the system copies the return code from GPR 15.
Chapter 112. UCBINFO — Return information from a UCB
1087
|
|
|
|
UCBINFO macro
,RSNCODE=rsncode addr
Specifies the address of a fullword field into which the system copies the reason code from GPR 0.
Return and reason codes
When the UCBINFO DEVINFO macro returns control to your program, GPR 15 (or
retcode addr, if you coded RETCODE) contains a return code, and GPR 0 (or rsncode
addr, if you coded RSNCODE) contains a reason code.
Meaning and Action Hexadecimal Return
Code
00
Hexadecimal Reason
Code
None
04
08
08
08
08
08
08
0C
None
01
02
08
05
09
0B
None
Meaning:
The DEVINFO function completed successfully.
Action:
None.
Meaning:
Program error. No UCB exists for the device number specified in the DEVN parameter.
Action:
Correct the device number and reissue the macro.
Meaning:
Program error. A caller in AR mode specified an ALET that was not valid.
Action:
Correct the ALET and reissue the macro.
Meaning:
Program error. An error occurred when the system tried to access the caller's parameter list. This might be due to using a keyword that requires authorization but the caller was not authorized, that is the Supervisor state or PSW key 0 - 7.
Action:
Ensure that you have met the environmental requirements for the macro, and reissue the macro.
Meaning:
Program error.
Meaning:
Program error. An error occurred when the system referenced the caller-supplied area specified in the IOCTOKEN parameter. This reason code is valid only for callers using the
IOCTOKEN parameter.
Action:
Correct the IOCTOKEN parameter.
Meaning:
Program error. An error occurred when the system attempted to reference the area specified by the DEVIAREA parameter.
Action:
Correct the address specified on the
DEVIAREA parameter and reissue the macro.
Meaning:
The value specified on the SCHSET keyword is not valid.
Action:
Enter a valid value.
Meaning:
Environmental error. The I/O configuration token supplied through the
IOCTOKEN parameter is not current. This return code is valid only for callers using the
IOCTOKEN parameter.
Action:
Obtain the current I/O configuration token by issuing an IOCINFO macro or by setting the input IOCTOKEN parameter in the
UCBINFO macro to zero.
1088
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
Hexadecimal Return
Code
20
28
Hexadecimal Reason
Code
None
None
Meaning and Action
Meaning:
System error. An unexpected error occurred.
Action:
Supply the return code to the appropriate
IBM support personnel.
Meaning:
Program error. The device number provided by the caller is an alias device number of a parallel access volume. For information about a parallel access volume, the caller must specify the base device number.
Action:
Correct the DEVN parameter and reissue the macro.
Example
To invoke UCBINFO to return device information, code:
.
.
UCBINFO DEVINFO,DEVIAREA=INFOAREA,DEVN=DEVNUM,
RETCODE=INFORTCD
.
DS 0D
INFOAREA DS CL256
INFORTCD DS F
DEVNUM DS H
X
UCBINFO DEVINFO - List form
Use the list form of the DEVINFO option of the UCBINFO macro together with the execute form for applications that require reentrant code. The list form of the macro defines an area of storage that the execute form uses to contain the parameters.
Syntax
This macro is an alternative list form macro, and requires a different technique for using the list form as compared to the conventional list form macros. See
“Alternative list form macros” on page 13 for further information.
The list form of the DEVINFO option of the UCBINFO macro is written as follows:
Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
UCBINFO
� One or more blanks must follow UCBINFO.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
Default:
IMPLIED_VERSION
Chapter 112. UCBINFO — Return information from a UCB
1089
UCBINFO macro
Syntax
,PLISTVER=plistver
MF=(L,list addr)
MF=(L,list addr, attr)
MF=(L,list addr,0D)
Description
plistver: 2
list addr: RX-type address
attr: 1- to 60-character input string
Default:
0D
Parameters
The parameters are explained under the standard form of UCBINFO DEVINFO with the following exceptions:
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
Specifies the list form of the UCBINFO DEVINFO macro.
list addr is the name of a storage area to contain the parameters.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
UCBINFO DEVINFO - Execute form
Use the execute form of the DEVINFO option of the UCBINFO macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Syntax
The execute form of the DEVINFO option of the UCBINFO macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
UCBINFO
� One or more blanks must follow UCBINFO.
DEVINFO
,DEVIAREA=deviarea addr deviarea addr: RX-type address or register (2) - (12).
1090
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
,IOCTOKEN=ioctoken addr
Description
devn addr: RS-type address or register (2) - (12).
schset addr RS-type address or register (2) - (12).
Default:
0
ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
,RETCODE=retcode addr
retcode addr: RX-type address or register (2) - (12).
,RSNCODE=rsncode addr rsncode addr: RX-type address or register (2) - (12).
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
list addr: RX-type address or address in register (2) - (12).
Default:
COMPLETE
UCBINFO macro
Parameters
The parameters are explained under the standard form of UCBINFO DEVINFO with the following exceptions:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Specifies the execute form of the UCBINFO DEVINFO macro.
list addr specifies the area that the system uses to contain the parameters.
COMPLETE, which is the default, specifies that the macro is to check for required parameters and supply defaults for omitted optional parameters.
|
|
UCBINFO GETCDR
Use the UCBINFO GETCDR macro to **fill in the blank**
||
||
||
|||
||
||
|
|
|
Syntax
�
name
Syntax
The standard form of the GETCDR option of the UCBINFO macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
Chapter 112. UCBINFO — Return information from a UCB
1091
UCBINFO macro
|
|
|
|
|
|
|
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
|
||
||
||
||
||
||
|
|
Syntax
UCBINFO
�
DEVINFO
,DEVIAREA=deviarea addr
,DEVN=devn addr
,SCHSET=schset
,SCHSET=0
,IOCTOKEN=ioctoken addr
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
,RETCODE=retcode addr
,RSNCODE=rsncode addr
Description
One or more blanks must follow UCBINFO.
deviarea addr: RX-type address or register (2) - (12).
devn addr: RS-type address or register (2) - (12).
schset RS-type address or register (2) - (12).
Default:
0
ioctoken addr: RX-type address or register (2) - (12).
Default:
IMPLIED_VERSION
plistver: 2
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
UCBINFO GETCDR - List form
Use the list form of the GETCDR option of the UCBINFO macro together with the execute form for applications that require reentrant code. The list form of the macro defines an area of storage that the execute form uses to contain the parameters.
This macro is an alternative list form macro, and requires a different technique for using the list form as compared to the conventional list form macros. See
“Alternative list form macros” on page 13 for further information.
The list form of the GETCDR option of the UCBINFO macro is written as follows:
Description
||
||
||
|||
||
||
|
Syntax
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
1092
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
Syntax
UCBINFO
�
GETCDR
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
MF=(L,list addr)
MF=(L,list addr, attr)
MF=(L,list addr,0D)
Description
One or more blanks must follow UCBINFO.
Default:
IMPLIED_VERSION
plistver: 2
list addr: RX-type address
attr: 1- to 60-character input string
Default:
0D
Parameters
The parameters are explained under the standard form of UCBINFO GETCDR with the following exceptions:
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
Specifies the list form of the UCBINFO GETCDR macro.
list addr is the name of a storage area to contain the parameters.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
|
|
|
|
|
UCBINFO GETCDR - Execute form
Use the execute form of the GETCDR option of the UCBINFO macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
||
||
||
|||
||
||
|
|
Syntax
�
name
The execute form of the GETCDR option of the UCBINFO macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
Chapter 112. UCBINFO — Return information from a UCB
1093
UCBINFO macro
|
|
|
|
|
|
|
|
|
||
||
||
||
|
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
Syntax
UCBINFO
�
GETCDR
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
,PATHMASK=pathmask addr
,PATHMASK=0
,CDRAREA=cdrarea addr
,CDRLEN=cdrlen addr
,IOCTOKEN=ioctoken addr
,RETCODE=retcode addr
,RSNCODE=rsncode addr
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Description
One or more blanks must follow UCBINFO.
devn addr: RS-type address or register (2) - (12).
schset addr: RS-type address or register (2) - (12).
Default:
0
pathmask addr: RS-type address or register (2) - (12).
Default:
0
cdrarea addr: RS-type address or register (2) - (12).
cdrlen addr: RS-type address or register (2) - (12).
ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
list addr: RX-type address or address in register (2) - (12).
Default:
COMPLETE
Parameters
The parameters are explained under the standard form of UCBINFO GETCDR with the following exceptions:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Specifies the execute form of the UCBINFO GETCDR macro.
list addr specifies the area that the system uses to contain the parameters.
COMPLETE, which is the default, specifies that the macro is to check for required parameters and supply defaults for omitted optional parameters.
1094
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
|
|
|
|
|
|
|
UCBINFO HYPERPAVALIASES
Use the UCBINFO HYPERPAVALIASES macro to obtain information for each alias exposure of a Parallel Access Volume (PAV) in HyperPAV mode. All alias exposures contained in the logical subsystem for the input device are returned in the output PAVAREA. The data returned by this function is mapped by macro
IOSDPAVA and consists of a header and one or more entries.
If the input device is not a HyperPAV device, a non-zero return code is returned.
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
|||
||
||
|
|
|
Syntax
�
name
UCBINFO
�
Syntax
HYPERPAVALIASES
,PAVAREA=pavarea addr
,PAVLEN=pavlen addr
,SCHINFO=NO | YES
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
The standard form of the HYPERPAVALIASES option of the UCBINFO macro is written as follows:
,IOCTOKEN=ioctoken addr
,RETCODE=retcode addr
Description
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
One or more blanks must follow UCBINFO.
pavarea addr: RS-type address or register (2) - (12).
pavlen addr: RS-type address or register (2) - (12).
Default:
NO
devn addr: RS-type address or register (2) - (12).
schset addr: RS-type address or register (2) - (12).
Default:
0
ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
retcode addr: RX-type address or register (2) - (12).
Chapter 112. UCBINFO — Return information from a UCB
1095
UCBINFO macro
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
||
||
||
Syntax
,RSNCODE=rsncode addr
Description
rsncode addr: RX-type address or register (2) - (12).
Parameters
The parameters are explained as follows:
,PAVAREA=pavarea addr
This parameter is required and is the name (RS-type), or address in register (2)
- (12), of the work area which is to receive the PAV information. The caller must specify the PAVLEN keyword to indicate the length of the PAVAREA.
The area is mapped by macro IOSDPAVA.
,PAVLEN=pavlen addr
This parameter is the name (RS-type), or address in register (2) - (12), of a required fullword input variable which specifies the length of the PAVAREA.
,SCHINFO=NO| YES
This parameter is an optional keyword input that indicates whether to also retrieve model dependent subchannel data for the device.
Note:
Retrieving subchannel data can cause overhead since a Store Subchannel
(STSCH) instruction must be issued to retrieve the data. Users who do not need this information might want to bypass this overhead by indicating NO for the SCHINFO keyword. DEFAULT: NO.
,SCHINFO=NO
Do not include model dependent subchannel data.
,SCHINFO=YES
Include model dependent subchannel data.
,DEVN=devn addr
Specifies the address of a halfword that contains, in binary form, the device number of the device.
,SCHSET=schset addr
,SCHSET=0
Specifies the name (RS-type), or address in register (2)-(12), of an optional byte input that specifies a subchannel set for which the device information is to be obtained. DEFAULT: 0.
,IOCTOKEN=ioctoken addr
Specifies the address of a 48-character storage area that contains the MVS I/O configuration token. The caller can obtain this token by issuing the IOCINFO macro, which is described in z/OS MVS Programming: Assembler Services
Reference ABE-HSP. If the I/O configuration token that is current when
UCBINFO is invoked does not match the token whose address is supplied here, the system issues a return code to the caller.
If you set the input IOCTOKEN (specified by ioctoken addr) to binary zeros,
UCBINFO sets IOCTOKEN to the current I/O configuration token.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list
1096
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
|
||
|
| |
|
|||
|
|||
|
|
|||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
UCBINFO macro
the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 2 , if you use the currently available parameters.
To code
, specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 2
,RETCODE=retcode addr
Specifies the address of a fullword field into which the system copies the return code from GPR 15.
,RSNCODE=rsncode addr
Specifies the address of a fullword field into which the system copies the reason code from GPR 0.
Return and reason codes
When the UCBINFO HYPERPAVALIASES macro returns control to your program,
GPR 15 (or retcode addr, if you coded RETCODE) contains a return code, and GPR
0 (or rsncode addr, if you coded RSNCODE) contains a reason code.
Meaning and Action Hexadecimal Return
Code
00
Hexadecimal Reason
Code
None
04
08
None
01
Meaning:
The HYPERPAVALIASES function completed successfully.
Action:
None.
Meaning:
Program error. No UCB exists for the device number specified in the DEVN parameter.
Action:
Correct the device number and reissue the macro.
Meaning:
Program error. A caller in AR mode specified an ALET that was not valid.
Action:
Correct the ALET and reissue the macro.
Chapter 112. UCBINFO — Return information from a UCB
1097
|
|
|||
|
|
|
|
|
|
|||
|
|
|
|
|||
|
|
|
|||
|
|
|
|
|
|||
|
|
|
|
|
|
|
|||
|
|
|
|
|||
|
|
|
|
|||
|
|
|
|
|
|
|||
|
| | |
| |
UCBINFO macro
Hexadecimal Return
Code
08
08
08
08
0C
20
30
30
30
Hexadecimal Reason
Code
02
05
0A
0B
None
None
01
02
03
Meaning and Action
Meaning:
Program error. An error occurred when the system tried to access the caller's parameter list. This might be due to using a keyword that requires authorization but the caller was not authorized, that is Supervisor state or PSW key 0
- 7.
Action:
Ensure that you have met the environmental requirements for the macro, and reissue the macro.
Meaning:
Program error. An error occurred when the system referenced the caller-supplied area specified in the IOCTOKEN parameter. This reason code is valid only for callers using the
IOCTOKEN parameter.
Action:
Correct the IOCTOKEN parameter.
Meaning:
Program error. An error occurred when the system attempted to reference the area specified by the PAVAREA parameter.
Action:
Correct the address specified on the
PAVAREA parameter and reissue the macro.
Meaning:
The value specified on the SCHSET keyword is not valid.
Action:
Enter a valid value.
Meaning:
Environmental error. The I/O configuration token supplied through the
IOCTOKEN parameter is not current. This return code is valid only for callers using the
IOCTOKEN parameter.
Action:
Obtain the current I/O configuration token by issuing an IOCINFO macro or by setting the input IOCTOKEN parameter in the
UCBINFO macro to zero.
Meaning:
System error. An unexpected error occurred.
Action:
Supply the return code to the appropriate
IBM support personnel.
Meaning:
Program error. The device number provided by the caller is not a HyperPAV device.
Action:
Correct the DEVN parameter and reissue the macro.
Meaning:
Program error. The work area specified with the PAVAREA parameter is not large enough to contain the minimum amount of data.
No data is returned.
Action:
Increase the size of the specified work area and reissue the macro.
Meaning:
Program error. The work area specified with the PAVAREA parameter is not large enough to contain an entry for each alias device.
Action:
Increase the size of the specified work area and reissue the macro.
1098
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
|
|||
|
| | |
| |
|
|
Hexadecimal Return
Code
34
Hexadecimal Reason
Code
01
Meaning and Action
Meaning:
Environmental error. The input device is a HyperPAV device for which logical subsystem information does not currently exist.
Action:
Contact your system programmer.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example
To invoke UCBINFO to return information about HyperPAV alias UCBs for a base device number, code:
UCBINFO HYPERPAVALIASES,DEVN=DEVNUM,
PAVAREA=INFOAREA,PAVLEN=AREALEN,
RETCODE=INFORTCD
.
.
.
DS 0D
DEVNUM DS H
INFOAREA DS CL1024
AREALEN DS F
INFORTCD DS F
X
X
UCBINFO HYPERPAVALIASES - List form
Use the list form of the HYPERPAVALIASES option of the UCBINFO macro together with the execute form for applications that require reentrant code. The list form of the macro defines an area of storage that the execute form uses to contain the parameters.
This macro is an alternative list form macro, and requires a different technique for using the list form as compared to the conventional list form macros. See
“Alternative list form macros” on page 13 for further information.
||
||
||
||
||
||
||
||
||
|||
||
||
||
||
||
|
|
Syntax
�
name
UCBINFO
�
HYPERPAVALIASES
The list form of the HYPERPAVALIASES option of the UCBINFO macro is written as follows:
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Description
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
One or more blanks must follow UCBINFO.
Default:
IMPLIED_VERSION
plistver: 2
Chapter 112. UCBINFO — Return information from a UCB
1099
UCBINFO macro
|
|
|
|
|
|
|
|
|
|
|
|
|
||
||
||
||
|
||
||
Syntax
MF=(L,list addr)
MF=(L,list addr, attr)
MF=(L,list addr,0D)
Description
list addr: RX-type address
attr: 1- to 60-character input string
Default:
0D
Parameters
The parameters are explained under the standard form of UCBINFO
HYPERPAVALIASES with the following exceptions:
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
Specifies the list form of the UCBINFO HYPERPAVALIASES macro.
list addr is the name of a storage area to contain the parameters.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
|
|
|
|
|
UCBINFO HYPERPAVALIASES - Execute form
Use the execute form of the HYPERPAVALIASES option of the UCBINFO macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
||
||
||
||
||
||
||
||
||
||
||
||
||
||
|||
|
|
Syntax
�
name
UCBINFO
�
HYPERPAVALIASES
,PAVAREA=pavarea addr
,PAVLEN=pavlen addr
The execute form of the HYPERPAVALIASES option of the UCBINFO macro is written as follows:
Description
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
One or more blanks must follow UCBINFO.
pavarea addr: RS-type address or register (2) - (12).
pavlen addr: RS-type address or register (2) - (12).
1100
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
|
|
|
|
|
|
|
|
|
||
||
||
||
||
||
||
||
||
||
||
||
||
||
||
|
||
||
||
||
||
||
||
||
Syntax
,SCHINFO=NO | YES
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
,IOCTOKEN=ioctoken addr
,RETCODE=retcode addr
,RSNCODE=rsncode addr
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Description
Default:
NO
devn addr: RS-type address or register (2) - (12).
schset addr: RS-type address or register (2) - (12).
Default:
0
ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
list addr: RX-type address or address in register (2) - (12).
Default:
COMPLETE
Parameters
The parameters are explained under the standard form of UCBINFO
HYPERPAVALIASES with the following exceptions:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Specifies the execute form of the UCBINFO HYPERPAVALIASES macro.
list addr specifies the area that the system uses to contain the parameters.
COMPLETE, which is the default, specifies that the macro is to check for required parameters and supply defaults for omitted optional parameters.
UCBINFO PATHINFO
Use the UCBINFO PATHINFO macro to obtain information about the device path and type of channel path associated with the device.
Syntax
The standard form of the PATHINFO option of the UCBINFO macro is written as follows:
Chapter 112. UCBINFO — Return information from a UCB
1101
|
|
UCBINFO macro
Syntax
name
�
UCBINFO
�
PATHINFO
,PATHAREA=patharea addr
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
Description
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
One or more blanks must follow UCBINFO.
patharea addr: RX-type address or register (2) - (12).
devn addr: RS-type address or register (2) - (12).
schset addr RS-type address or register (2) - (12).
Default:
0
,IOCTOKEN=ioctoken addr ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
,RETCODE=retcode addr
,RSNCODE=rsncode addr
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
Parameters
The parameters are explained as follows:
PATHINFO
Specifies that the system is to return information about the device path and type of channel path for the specified device.
,PATHAREA=patharea addr
Specifies the address of the required 256-byte output field into which the system is to return information about the device path and type of channel path for the specified device. This field is mapped by the mapping macro
IOSDPATH.
1102
z/OS MVS Assembler Services Reference IAR-XCT
|
UCBINFO macro
,DEVN=devn addr
Specifies the address of a halfword that contains, in binary form, the device number of the device.
,SCHSET=schset addr
,SCHSET=0
Specifies the name (RS-type), or address in register (2)-(12), of an optional byte input that specifies a subchannel set for which the system is to return information about the device path and type of channel path. DEFAULT: 0.
,IOCTOKEN=ioctoken addr
Specifies the address of a 48-character storage area that contains the MVS I/O configuration token. The caller can obtain this token by issuing the IOCINFO macro. z/OS MVS Programming: Assembler Services Reference ABE-HSP If the I/O configuration token that is current when UCBINFO is invoked does not match the token whose address is supplied here, the system issues a return code to the caller.
If you set the input IOCTOKEN (specified by ioctoken addr) to binary zeros,
UCBINFO sets IOCTOKEN to the current I/O configuration token.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION
, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 2
, if you use the currently available parameters.
To code
, specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 2
,RETCODE=retcode addr
Specifies the address of a fullword field into which the system copies the return code from GPR 15.
,RSNCODE=rsncode addr
Specifies the address of a fullword field into which the system copies the reason code from GPR 0.
Chapter 112. UCBINFO — Return information from a UCB
1103
|
|
|
|
UCBINFO macro
Return and reason codes
When the UCBINFO PATHINFO macro returns control to your program, GPR 15
(or retcode addr, if you coded RETCODE) contains a return code, and GPR 0 (or
rsncode addr, if you coded RSNCODE) contains a reason code.
Meaning and Action Hexadecimal Return
Code
00
Hexadecimal Reason
Code
None
04
08
08
08
08
08
08
0C
None
01
02
03
05
08
0B
None
Meaning:
The PATHINFO function completed successfully.
Action:
None.
Meaning:
Program error. No UCB exists for the device number specified in the DEVN parameter.
Action:
Correct the device number and reissue the macro.
Meaning:
Program error. A caller in AR mode specified an ALET that was not valid.
Action:
Correct the ALET and reissue the macro.
Meaning:
Program error. An error occurred when the system tried to access the caller's parameter list. This might be due to using a keyword that requires authorization but the caller was not authorized, that is the Supervisor state or PSW key 0 - 7.
Action:
Ensure that you have met the environmental requirements for the macro, and reissue the macro.
Meaning:
Program error. An unauthorized caller specified the UCBPTR parameter.
Action:
Specify the DEVN parameter instead of the UCBPTR parameter to indicate the device for which the system is to obtain path information.
Meaning:
Program error. An error occurred when the system referenced the caller-supplied area specified in the IOCTOKEN parameter. This reason code is valid only for callers using the
IOCTOKEN parameter.
Action:
Correct the IOCTOKEN parameter.
Meaning:
Program error. An error occurred when the system attempted to reference the area specified by the PATHAREA parameter.
Action:
Correct the address specified on the
PATHAREA parameter and reissue the macro.
Meaning:
The value specified on the SCHSET keyword is not valid.
Action:
Enter a valid value.
Meaning:
Environmental error. The I/O configuration token supplied through the
IOCTOKEN parameter is not current. This return code is valid only for callers using the
IOCTOKEN parameter.
Action:
Obtain the current I/O configuration token by issuing an IOCINFO macro or by setting the input IOCTOKEN parameter in the
UCBINFO macro to zero.
1104
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
Hexadecimal Return
Code
18
18
20
Hexadecimal Reason
Code
04
08
None
Meaning and Action
Meaning:
System error. The subchannel is in permanent error and cannot be accessed.
Action:
Supply the return and reason codes to the appropriate IBM support personnel.
Meaning:
Environmental error. The UCB is not connected to a subchannel.
Action:
Verify that there is a device at the device number associated with the subchannel, and reissue the macro.
Meaning:
System error. An unexpected error occurred.
Action:
Supply the return code to the appropriate
IBM support personnel.
Example
To invoke UCBINFO to return device path and type of channel path information, code:
.
.
UCBINFO PATHINFO,PATHAREA=INFOAREA,DEVN=DEVNUM,
RETCODE=INFORTCD
.
X
DS 0D
INFOAREA DS CL256
INFORTCD DS F
DEVNUM DS H
UCBINFO PATHINFO - List form
Use the list form of the PATHINFO option of the UCBINFO macro together with the execute form for applications that require reentrant code. The list form of the macro defines an area of storage that the execute form uses to contain the parameters.
This macro is an alternative list form macro, and requires a different technique for using the list form as compared to the conventional list form macros. See
“Alternative list form macros” on page 13 for further information.
Syntax
The list form of the PATHINFO option of the UCBINFO macro is written as follows:
Description
name
�
UCBINFO
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
Chapter 112. UCBINFO — Return information from a UCB
1105
UCBINFO macro
Syntax
�
Description
One or more blanks must follow UCBINFO.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
MF=(L,list addr)
MF=(L,list addr, attr)
MF=(L,list addr,0D)
list addr: RX-type address
attr: 1- to 60-character input string
Default:
0D
Parameters
The parameters are explained under the standard form of UCBINFO PATHINFO with the following exceptions:
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
Specifies the list form of the UCBINFO PATHINFO macro.
list addr is the name of a storage area to contain the parameters.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
UCBINFO PATHINFO - Execute form
Use the execute form of the PATHINFO option of the UCBINFO macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Syntax
The execute form of the PATHINFO option of the UCBINFO macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
UCBINFO
� One or more blanks must follow UCBINFO.
1106
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
PATHINFO
,PATHAREA=patharea addr
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
Description
patharea addr: RX-type address or register (2) - (12).
devn addr: RS-type address or register (2) - (12).
schset addr RS-type address or register (2) - (12).
Default:
0
,IOCTOKEN=ioctoken addr ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
,RETCODE=retcode addr
,RSNCODE=rsncode addr
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
list addr: RX-type address or address in register (2) - (12).
Default:
COMPLETE
UCBINFO macro
Parameters
The parameters are explained under the standard form of UCBINFO PATHINFO with the following exceptions:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Specifies the execute form of the UCBINFO PATHINFO macro.
list addr specifies the area that the system uses to contain the parameters.
COMPLETE, which is the default, specifies that the macro is to check for required parameters and supply defaults for omitted optional parameters.
UCBINFO PATHMAP
Use the UCBINFO PATHMAP macro to obtain information about the device path.
Syntax
The standard form of the PATHMAP option of the UCBINFO macro is written as follows:
Chapter 112. UCBINFO — Return information from a UCB
1107
UCBINFO macro
Syntax Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
UCBINFO
� One or more blanks must follow UCBINFO.
PATHMAP
,MAPAREA=maparea addr
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
,IOCTOKEN=ioctoken addr
maparea addr: RX-type address or register (2) - (12).
devn addr: RS-type address or register (2) - (12).
schset addr: RS-type address or register (2) - (12).
Default:
0
ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
,RETCODE=retcode addr
,RSNCODE=rsncode addr
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
|
|
Parameters
The parameters are explained as follows:
PATHMAP
Specifies that the system is to return information about the device path for the specified device.
,MAPAREA=maparea addr
Specifies a required 40-byte field into which the system is to return information about the device path for the specified device. This field is mapped by the mapping macro IOSDMAP.
,DEVN=devn addr
Specifies the address of a halfword that contains, in binary form, the device number of the device.
,SCHSET=schset addr
1108
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
,SCHSET=0
Specifies the name (RS-type), or address in register (2)-(12), of an optional byte input that specifies a subchannel set for which the information about the device path is to be returned. DEFAULT: 0.
,IOCTOKEN=ioctoken addr
Specifies the address of a 48-character storage area that contains the MVS I/O configuration token. The caller can obtain this token by issuing the IOCINFO macro. z/OS MVS Programming: Assembler Services Reference ABE-HSP If the I/O configuration token that is current when UCBINFO is invoked does not match the token whose address is supplied here, the system issues a return code to the caller.
If you set the input IOCTOKEN (specified by ioctoken addr) to binary zeros,
UCBINFO sets IOCTOKEN to the current I/O configuration token.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 2 , if you use the currently available parameters.
To code
, specify in this input parameter one of the following: v IMPLIED_VERSION v
MAX v A decimal value of 2
,RETCODE=retcode addr
Specifies the address of a fullword field into which the system copies the return code from GPR 15.
,RSNCODE=rsncode addr
Specifies the address of a fullword field into which the system copies the reason code from GPR 0.
Return and reason codes
When the UCBINFO PATHMAP macro returns control to your program, GPR 15
(or retcode addr, if you coded RETCODE) contains a return code, and GPR 0 (or
rsncode addr, if you coded RSNCODE) contains a reason code.
Chapter 112. UCBINFO — Return information from a UCB
1109
UCBINFO macro
|
|
|
|
Hexadecimal Return
Code
00
04
08
08
08
08
08
0C
10
20
Hexadecimal Reason
Code
None
None
01
02
05
06
0B
None
04
None
Meaning and Action
Meaning:
The PATHMAP function completed successfully.
Action:
None.
Meaning:
Program error. No UCB exists for the device number specified in the DEVN parameter.
Action:
Correct the device number and reissue the macro.
Meaning:
Program error. A caller in AR mode specified an ALET that was not valid.
Action:
Correct the ALET and reissue the macro.
Meaning:
Program error. An error occurred when the system tried to access the caller's parameter list. This might be due to using a keyword that requires authorization but the caller was not authorized, that is the Supervisor state or PSW key 0 - 7.
Action:
Ensure that you have met the environmental requirements for the macro, and reissue the macro.
Meaning:
Program error. An error occurred when the system referenced the caller-supplied area specified in the IOCTOKEN parameter. This reason code is valid only for callers using the
IOCTOKEN parameter.
Action:
Correct the IOCTOKEN parameter.
Meaning:
Program error. An error occurred when the system attempted to reference the area specified by the MAPAREA parameter.
Action:
Correct the address specified for
MAPAREA and reissue the macro.
Meaning:
The value specified on the SCHSET keyword is not valid.
Action:
Enter a valid value.
Meaning:
Environmental error. The I/O configuration token supplied through the
IOCTOKEN parameter is not current. This return code is valid only for callers using the
IOCTOKEN parameter.
Action:
Obtain the current I/O configuration token by issuing an IOCINFO macro or by setting the input IOCTOKEN parameter in the
UCBINFO macro to zero.
Meaning:
System error. The subchannel is in permanent error and cannot be accessed.
Action:
Supply the return and reason code to the appropriate IBM support personnel.
Meaning:
System error. An unexpected error occurred.
Action:
Supply the return code to the appropriate
IBM support personnel.
1110
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
Example
To invoke UCBINFO to return device path information, code:
.
.
UCBINFO PATHMAP,MAPAREA=INFOAREA,DEVN=DEVNUM,
RETCODE=INFORTCD
.
DS 0D
INFOAREA DS CL256
INFORTCD DS F
DEVNUM DS H
X
UCBINFO PATHMAP - List form
Use the list form of the PATHMAP option of the UCBINFO macro together with the execute form for applications that require reentrant code. The list form of the macro defines an area of storage that the execute form uses to contain the parameters.
Syntax
This macro is an alternative list form macro, and requires a different technique for using the list form as compared to the conventional list form macros. See
“Alternative list form macros” on page 13 for further information.
The list form of the PATHMAP option of the UCBINFO macro is written as follows:
Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
UCBINFO
� One or more blanks must follow UCBINFO.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
MF=(L,list addr)
MF=(L,list addr, attr)
MF=(L,list addr,0D)
list addr: RX-type address
attr: 1- to 60-character input string
Default:
0D
Parameters
The parameters are explained under the standard form of UCBINFO PATHMAP with the following exceptions:
Chapter 112. UCBINFO — Return information from a UCB
1111
UCBINFO macro
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
Specifies the list form of the UCBINFO PATHMAP macro.
list addr is the name of a storage area to contain the parameters.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
UCBINFO PATHMAP - Execute form
Use the execute form of the PATHMAP option of the UCBINFO macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Syntax
The execute form of the PATHMAP option of the UCBINFO macro is written as follows:
Description
�
name
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
UCBINFO
�
One or more blanks must follow UCBINFO.
PATHMAP
,MAPAREA=maparea addr
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
,IOCTOKEN=ioctoken addr
maparea addr: RX-type address or register (2) - (12).
devn addr: RS-type address or register (2) - (12).
schset addr: RS-type address or register (2) - (12).
Default:
0
ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
1112
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,RETCODE=retcode addr
,RSNCODE=rsncode addr
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Description
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
list addr: RX-type address or address in register (2) - (12).
Default:
COMPLETE
UCBINFO macro
Parameters
The parameters are explained under the standard form of the UCBINFO
PATHMAP macro with the following exceptions:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Specifies the execute form of the UCBINFO PATHMAP macro.
list addr specifies the area that the system uses to contain the parameters.
COMPLETE, which is the default, specifies that the macro is to check for required parameters and supply defaults for omitted optional parameters.
UCBINFO PAVINFO
Use the UCBINFO PAVINFO macro to obtain selected information applicable to each exposure (base and alias) of a Parallel Access Volume (PAV).
Syntax
Syntax
The standard form of the PAVINFO option of the UCBINFO macro is written as follows:
Description
name
�
UCBINFO
�
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
One or more blanks must follow UCBINFO.
PAVINFO
PAVINFOSUM=NO
PAVINFOSUM=YES
,PAVAREA=pavarea addr
Default
: NO
pavarea addr: RX-type address or register (2) - (12).
Chapter 112. UCBINFO — Return information from a UCB
1113
UCBINFO macro
Syntax
,PAVLEN=pavarea addr
,SCHINFO=NO
,SCHINFO=YES
,EXTFORMAT=NO
,EXTFORMAT=YES
,OUTVERSION=outver
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
Description
pavarea addr: RX-type address or register (2) - (12).
Default
: NO
Default
: NO
Default
: 3
devn addr: RS-type address or register (2) - (12).
schset addr: RS-type address or register (2) - (12).
Default:
0
,IOCTOKEN=ioctoken addr ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
,RETCODE=retcode addr
,RSNCODE=rsncode addr
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
Parameters
The parameters are explained as follows:
PAVINFO
Obtain selected information that applies to each exposure of a Parallel Access
Volume (PAV) device. The data returned by this function is mapped by the mapping macro IOSDPAVA and consists of a header and one or more entries.
Depending on the input device, the following is returned: v When the input device is a PAV-base, the first entry represents the base and each subsequent entry represents each of the bound PAV-alias devices associated with the base. Note that if the base has no bound PAV-aliases, then only the first entry is filled in.
v When the input is a non-PAV DASD device, only the first entry is filled in.
v
When the input device is a PAV-alias or a non-DASD, a non-zero return code is returned.
PAVINFOSUM=NO
1114
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
PAVINFOSUM=YES
Specifies whether to retrieve only a sum of channel measurement data and model dependent subchannel data for the base device and all of its aliases.
Note:
The model dependent subchannel data is only retrieved if
SCHINFO=YES.
NO
Do not just retrieve a total of channel measurement data and model dependent subchannel data for the base device and all of its aliases.
This option causes a PAVA entry to be created for the base device and each of its aliases.
YES
Retrieve only a sum of channel measurement data and model dependent subchannel data for the base device and all of its aliases.
This option causes the first PAVA entry to contain information on the base device, however, the measurement-related fields (such as
PAVACMB, PAVASMDB, and PAVAECMB) will contain totals for the base and all of its aliases.
,PAVAREA=pavarea addr
Specifies the address of a required output field into which the system will return information about the alias UCBs for the specified base device number.
This field is mapped by the mapping macro IOSDPAVA.
,PAVLEN=pavarea addr
Specifies the address or a register containing the length of the area specified by the PAVAREA parameter.
,SCHINFO=NO
,SCHINFO=YES
This parameter specifies whether or not to retrieve model-dependent subchannel data (control unit busy time, switch busy time, and device busy time) for the device. If you issue this request from a system running on a z990 or higher processor, the system ignores the SCHINFO parameter, but still returns the device busy time.
NO
Do not retrieve model-dependent subchannel data for the device.
Note that even if you specify NO on a z990 or higher processor, the service will still return the device busy time.
YES
Retrieve model-dependent subchannel data for the device, which includes control unit busy time, switch busy time, and device busy time. If you specify YES on a z990 or higher processor, the service will still return the device busy time.
,EXTFORMAT=NO
,EXTFORMAT=YES
This parameter specifies whether an extended format PAV area should be created. An extended format PAV area contains a length field in each entry that defines the actual length of the entry. This allows the PAV entry to be extended compatibly to add new information. A non-extended format PAV area contains entries which are fixed in size (60 bytes) and cannot be extended to contain new data. See the mapping macro IOSDPAVA for more information.
Note:
The value specified for the EXTFORMAT keyword on the UCBINFO
PAVINFO macro must match the value specified on the IOSDPAVA macro.
Otherwise, your program may not work correctly.
NO
Create the non-extended format PAV area.
Chapter 112. UCBINFO — Return information from a UCB
1115
UCBINFO macro
YES
Create the extended format PAV area.
,OUTVERSION=outver
Specifies the output version to be used when creating an extended format PAV area. The output version controls the size of the PAV entries that are returned. This parameter is used only if
EXTFORMAT(YES) is specified; it is ignored for EXTFORMAT(NO) requests. If an output version that is less than 3 is specified, version 3 is used. If an output version that is higher than the currently supported version is specified, the highest supported version is used.
Note:
Currently, version 3 is the only supported value.
,DEVN=devn addr
Specifies the address of a halfword that contains the base device number in binary form.
,SCHSET=schset addr
,SCHSET=0
Specifies the name (RS-type), or address in register (2)-(12), of an optional byte input that specifies a subchannel set for which the information that applies to each exposure of a Parallel Access Volume (PAV) device is to be obtained.
DEFAULT: 0.
,IOCTOKEN=ioctoken addr
Specifies the address of a 48-character storage area that contains the MVS I/O configuration token. The caller can obtain this token by issuing the IOCINFO macro. z/OS MVS Programming: Assembler Services Reference ABE-HSP If the I/O configuration token that is current when UCBINFO is invoked does not match the token whose address is supplied here, the system issues a return code to the caller.
If you set the input IOCTOKEN (specified by ioctoken addr) to binary zeros,
UCBINFO sets IOCTOKEN to the current I/O configuration token.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 2 , if you use the currently available parameters.
To code
, specify in this input parameter one of the following: v IMPLIED_VERSION
1116
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
UCBINFO macro
v MAX v
A decimal value in the range of 1 - 3.
,RETCODE=retcode addr
Specifies the address of a fullword field into which the system copies the return code from GPR 15.
,RSNCODE=rsncode addr
Specifies the address of a fullword field into which the system copies the reason code from GPR 0.
Return and reason codes
When the UCBINFO PAVINFO macro returns control to your program, GPR 15 (or
retcode addr, if you coded RETCODE) contains a return code, and GPR 0 (or rsncode
addr, if you coded RSNCODE) contains a reason code.
Hexadecimal Return
Code
00
Hexadecimal Reason
Code
None
04
08
08
08
08
08
None
01
02
03
05
0A
Meaning and Action
Meaning:
The PAVINFO function completed successfully.
Action:
None.
Meaning:
Program error. No UCB exists for the device number specified in the DEVN parameter.
Action:
Correct the device number and reissue the macro.
Meaning:
Program error. A caller in AR mode specified an ALET that was not valid.
Action:
Correct the ALET and reissue the macro.
Meaning:
Program error. An error occurred when the system tried to access the caller's parameter list. This might be due to using a keyword that requires authorization but the caller was not authorized, that is the Supervisor state or PSW key 0 - 7.
Action:
Ensure that you have met the environmental requirements for the macro, and reissue the macro.
Meaning:
Program error. An unauthorized caller specified the UCBPTR parameter.
Action:
Specify the DEVN parameter instead of the UCBPTR parameter to indicate the device for which the system is to obtain information.
Meaning:
Program error. An error occurred when the system referenced the caller-supplied area specified in the IOCTOKEN parameter. This reason code is valid only for callers using the
IOCTOKEN parameter.
Action:
Correct the IOCTOKEN parameter and reissue the macro.
Meaning:
Program error. An error occurred when the system attempted to reference the area specified by the PAVAREA parameter.
Action:
Correct the address specified on the
PAVAREA parameter and reissue the macro.
Chapter 112. UCBINFO — Return information from a UCB
1117
UCBINFO macro
Hexadecimal Return
Code
08
0C
1C
1C
1C
20
28
Hexadecimal Reason
Code
0B
None
01
02
03
None
None
Meaning and Action
Meaning:
The value specified on the SCHSET keyword is not valid.
Action:
Enter a valid value.
Meaning:
Environmental error. The I/O configuration token supplied through the
IOCTOKEN parameter is not current. This return code is valid only for callers using the
IOCTOKEN parameter.
Action:
Obtain the current I/O configuration token by issuing an IOCINFO macro or by setting the input IOCTOKEN parameter in the
UCBINFO macro to zero.
Meaning:
Program error. The device number provided by the caller specifies a device that is not a DASD or is a PAV alias device.
Action:
Correct the DEVN parameter and reissue the macro.
Meaning:
Program error. The work area specified with the PAVAREA parameter is not large enough to contain the minimum amount of data.
No data is returned.
Action:
Increase the size of the specified work area and reissue the macro.
Meaning:
Program error. The work area specified with the PAVAREA parameter is not large enough to contain an entry for each alias device.
Action:
Increase the size of the specified work area and reissue the macro.
Meaning:
System error. An unexpected error occurred.
Action:
Supply the return code to the appropriate
IBM support personnel.
Meaning:
Program error. The device number provided by the caller is an alias device number of a parallel access volume. The caller must specify the base device number.
Action:
Correct the DEVN parameter and reissue the macro.
Example
To invoke UCBINFO to return information about alias UCBs for a base device number, code:
.
.
UCBINFO PAVINFO,DEVN=DEVNUM,PAVAREA=INFOAREA,PAVLEN=AREALEN, X
RETCODE=INFORTCD
.
DS 0D
DEVNUM DS H
INFOAREA DS CL256
AREALEN DS F
INFORTCD DS F
1118
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
UCBINFO PAVINFO - List form
Use the list form of the PAVINFO option of the UCBINFO macro together with the execute form for applications that require reentrant code. The list form of the macro defines an area of storage that the execute form uses to contain the parameters.
Syntax
The list form of the PAVINFO option of the UCBINFO macro is written as follows:
Description
name
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
�
UCBINFO
� One or more blanks must follow UCBINFO.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
MF=(L,list addr)
MF=(L,list addr, attr)
MF=(L,list addr,0D)
list addr: RX-type address
attr: 1- to 60-character input string
Default:
0D
Parameters
The parameters are explained under the standard form of UCBINFO PAVINFO with the following exceptions:
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
Specifies the list form of the UCBINFO PAVINFO macro.
list addr is the name of a storage area to contain the parameters.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of X'0D', which forces the parameter list to a doubleword boundary.
UCBINFO PAVINFO - Execute form
Use the execute form of the PAVINFO option of the UCBINFO macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Chapter 112. UCBINFO — Return information from a UCB
1119
UCBINFO macro
Syntax
The execute form of the PAVINFO option of the UCBINFO macro is written as follows:
Description
name
�
UCBINFO
�
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
One or more blanks must follow UCBINFO.
PAVINFO
PAVINFOSUM=NO
PAVINFOSUM=YES
Default
: NO
,PAVAREA=pavarea addr
,PAVLEN=pavlen addr
pavarea addr: RX-type address or register (2) - (12).
pavlen addr: RX-type address or register (2) - (12).
Default
: NO ,SCHINFO=NO
,SCHINFO=YES
,EXTFORMAT=NO
,EXTFORMAT=YES
,OUTVERSION=outver
Default
: NO
Default
: 3
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
devn addr: RX-type address or register (2) - (12).
schset addr: RS-type address or register (2) - (12).
Default:
0
ioctoken addr: RX-type address or register (2) - (12).
,IOCTOKEN=ioctoken addr
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
,RETCODE=retcode addr
,RSNCODE=rsncode addr
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
,MF=(E,list addr) list addr: RX-type address or address in register (2) - (12).
1120
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
Syntax
,MF=(E,list addr,COMPLETE)
Description
Default:
COMPLETE
Parameters
The parameters are explained under the standard form of UCBINFO PAVINFO with the following exceptions:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Specifies the execute form of the UCBINFO PAVINFO macro.
list addr specifies the area that the system uses to contain the parameters.
COMPLETE, which is the default, specifies that the macro is to check for required parameters and supply defaults for omitted optional parameters.
UCBINFO PRFXDATA
Use the UCBINFO PRFXDATA macro to obtain a copy of the UCB prefix extension segment.
Syntax
Syntax
The standard form of the PRFXDATA option of the UCBINFO macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
UCBINFO
�
One or more blanks must follow UCBINFO.
PRFXDATA
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
devn addr: RS-type address or register (2) - (12).
schset addr: RS-type address or register (2) - (12).
Default:
0
,UCBPAREA=ucbparea addr
,IOCTOKEN=ioctoken addr
ucbparea addr: RX-type address or register (2) - (12).
ioctoken addr: RX-type address or register (2) - (12).
Chapter 112. UCBINFO — Return information from a UCB
1121
UCBINFO macro
Syntax Description
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
,RETCODE=retcode addr
,RSNCODE=rsncode addr
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
|
Parameters
The parameters are explained as follows:
PRFXDATA
Specifies that the system is to obtain information from the UCB prefix extension segment.
,DEVN=devn addr
Specifies the address of a halfword that contains, in binary form, the device number of the device.
,SCHSET=schset addr
,SCHSET=0
Specifies the name (RS-type), or address in register (2)-(12), of an optional byte input that specifies a subchannel set for which the information from the UCB prefix extension segment is to be obtained. DEFAULT: 0.
,UCBPAREA=ucbparea addr
Specifies the address of a 48-character storage area into which the system copies the UCB prefix extension segment. The IOSDUPI mapping macro maps the area.
,IOCTOKEN=ioctoken addr
Specifies the address of a 48-character storage area that contains the MVS I/O configuration token. The caller can obtain this token by issuing the IOCINFO macro. z/OS MVS Programming: Assembler Services Reference ABE-HSP If the I/O configuration token that is current when UCBINFO is invoked does not match the token whose address is supplied here, the system issues a return code to the caller.
If you set the input IOCTOKEN (specified by ioctoken addr) to binary zeros,
UCBINFO sets IOCTOKEN to the current I/O configuration token.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
1122
z/OS MVS Assembler Services Reference IAR-XCT
|
|
|
|
UCBINFO macro
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 2 , if you use the currently available parameters.
To code
, specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 2
,RETCODE=retcode addr
Specifies the address of a fullword field into which the system copies the return code from GPR 15.
,RSNCODE=rsncode addr
Specifies the address of a fullword field into which the system copies the reason code from GPR 0.
Return and reason codes
When the UCBINFO PRFXDATA macro returns control to your program, GPR 15
(or retcode addr, if you coded RETCODE) contains a return code, and GPR 0 (or
rsncode addr, if you coded RSNCODE) contains a reason code.
Hexadecimal Return
Code
00
Hexadecimal Reason
Code
None
04
08
08
08
None
01
02
03
Meaning and Action
Meaning:
The PRFXDATA function completed successfully.
Action:
None.
Meaning:
Program error. No UCB exists for the device number specified in the DEVN parameter.
Action:
Correct the device number and reissue the macro.
Meaning:
Program error. A caller in AR mode specified an ALET that was not valid.
Action:
Correct the ALET and reissue the macro.
Meaning:
Program error. An error occurred when the system tried to access the caller's parameter list. This might be due to using a keyword that requires authorization but the caller was not authorized, that is the Supervisor state or PSW key 0 - 7.
Action:
Ensure that you have met the environmental requirements for the macro, and reissue the macro.
Meaning:
Program error. An unauthorized caller specified the UCBPTR parameter.
Action:
Specify the DEVN parameter instead of the UCBPTR parameter to indicate the device for which the system is to obtain information.
Chapter 112. UCBINFO — Return information from a UCB
1123
UCBINFO macro
Hexadecimal Return
Code
08
08
0C
20
Hexadecimal Reason
Code
05
0B
None
None
Meaning and Action
Meaning:
Program error. An error occurred when the system referenced the caller-supplied area specified in the IOCTOKEN parameter. This reason code is valid only for callers using the
IOCTOKEN parameter.
Action:
Correct the IOCTOKEN parameter.
Meaning:
The value specified on the SCHSET keyword is not valid.
Action:
Enter a valid value.
Meaning:
Environmental error. The I/O configuration token supplied through the
IOCTOKEN parameter is not current. This return code is valid only for callers using the
IOCTOKEN parameter.
Action:
Obtain the current I/O configuration token by issuing an IOCINFO macro or by setting the input IOCTOKEN parameter in the
UCBINFO macro to zero.
Meaning:
System error. An unexpected error occurred.
Action:
Supply the return code to the appropriate
IBM support personnel.
Example
To invoke UCBINFO to obtain a copy of the UCB prefix extension segment, code:
.
.
UCBINFO PRFXDATA,DEVN=DEVNUM,UCBPAREA=UAREA,
RETCODE=INFORTCD
.
X
DS 0D
DEVNUM DS H
UAREA DS CL48
INFORTCD DS F
UCBINFO PRFXDATA - List form
Use the list form of the PRFXDATA option of the UCBINFO macro together with the execute form for applications that require reentrant code. The list form of the macro defines an area of storage that the execute form uses to contain the parameters.
Syntax
This macro is an alternative list form macro, and requires a different technique for using the list form as compared to the conventional list form macros. See
“Alternative list form macros” on page 13 for further information.
The list form of the PRFXDATA option of the UCBINFO macro is written as follows:
Description
name
name: symbol. Begin name in column 1.
1124
z/OS MVS Assembler Services Reference IAR-XCT
UCBINFO macro
Syntax Description
� One or more blanks must precede UCBINFO.
UCBINFO
� One or more blanks must follow UCBINFO.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
MF=(L,list addr)
MF=(L,list addr, attr)
MF=(L,list addr,0D)
list addr: RX-type address
attr: 1- to 60-character input string
Default:
0D
Parameters
The parameters are explained under the standard form of UCBINFO PRFXDATA with the following exceptions:
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
Specifies the list form of the UCBINFO PRFXDATA macro.
list addr is the name of a storage area to contain the parameters.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
UCBINFO PRFXDATA - Execute form
Use the execute form of the PRFXDATA option of the UCBINFO macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
Syntax
The execute form of the PRFXDATA option of the UCBINFO macro is written as follows:
Description
name
�
name: symbol. Begin name in column 1.
One or more blanks must precede UCBINFO.
Chapter 112. UCBINFO — Return information from a UCB
1125
UCBINFO macro
Syntax Description
UCBINFO
� One or more blanks must follow UCBINFO.
PRFXDATA
,DEVN=devn addr
,SCHSET=schset addr
,SCHSET=0
,UCBPTR=ucbptr addr
devn addr: RS-type address or register (2) - (12).
schset addr: RS-type address or register (2) - (12).
Default:
0
ucbptr addr: RS-type address or register (2) - (12).
Note:
Specify either DEVN or UCBPTR, but not both.
,UCBPAREA=ucbparea addr
,IOCTOKEN=ioctoken addr
ucbparea addr: RX-type address or register (2) - (12).
ioctoken addr: RX-type address or register (2) - (12).
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 2
,RETCODE=retcode addr
,RSNCODE=rsncode addr
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
list addr: RX-type address or address in register (2) - (12).
Default:
COMPLETE
Parameters
The parameters are explained under the standard form of UCBINFO PRFXDATA with the following exceptions:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Specifies the execute form of the UCBINFO PRFXDATA macro.
list addr specifies the area that the system uses to contain the parameters.
COMPLETE, which is the default, specifies that the macro is to check for required parameters and supply defaults for omitted optional parameters.
1126
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 113. UCBSCAN — Scan UCBs
Description
Use the UCBSCAN macro to scan unit control blocks (UCBs) and return a copy of a UCB.
Two types of scans are available with UCBSCAN: A scan of all UCBs, and a scan of all UCBs within a particular device class. For each type of scan, the caller may optionally: v
Restrict the scan to UCBs defined as static or installation-static.
v Restrict the scan to UCBs with 3-digit device numbers.
v Request alias UCBs for a parallel access volume.
v Specify the device number with which the scan should begin.
UCBSCAN presents the UCBs in ascending device number order. On each invocation, UCBSCAN returns a copy of requested UCB segments and data in caller-supplied areas. See z/OS MVS Programming: Assembler Services Guide for information on accessing UCBs.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Requirement
Problem state with any PSW key.
Task or SRB
Any PASN, any HASN, any SASN.
24- or 31-bit.
Primary or access register (AR).
Enabled or disabled for I/O and external interrupts
Locks:
Control parameters:
The caller may hold locks, but is not required to hold any.
Must be in the primary address space or, for AR-mode callers, must be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).
Programming requirements
If in AR mode, issue SYSSTATE ASCENV=AR before issuing UCBSCAN.
Restrictions
None.
Input register information
Before issuing the UCBSCAN macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
© Copyright IBM Corp. 1988, 2017
1127
UCBSCAN macro
Syntax
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0
Reason code if GPR 15 contains a return code of 04 or 08; otherwise, used as a work register by the system
1
2-13
14
15
Used as a work register by the system
Unchanged
Used as a work register by the system
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Performance implications
None.
Syntax
The standard form of the UCBSCAN macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede UCBSCAN.
UCBSCAN
� One or more blanks must follow UCBSCAN.
COPY
,WORKAREA=workarea addr
,UCBAREA=ucbarea addr
,CMXTAREA= cmxtarea addr
,CMXTAREA=NONE
workarea addr: RX-type address or register (2) - (12).
ucbarea addr: RX-type address or register (2) - (12).
cmxtarea addr: RX-type address or register (2) - (12).
Default:
NONE
1128
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,UCBPAREA= ucbparea addr
,UCBPAREA=NONE
,DCEAREA= dcearea addr
,DCEAREA=NONE
,DCELEN=length addr
,VOLSER=volser addr
,VOLSER=NONE
,DEVNCHAR= devnchar addr
,DEVN=devn addr
,DEVN=0
,DYNAMIC=NO
,DYNAMIC=YES
,RANGE=3DIGIT
,RANGE=ALL
,UNBOUND_ALIAS=NO
,UNOUND_ALIAS=YES
SPECIAL=NO
SPECIAL=YES
SPECIAL=ONLY
,DEVCLASS=ALL
,DEVCLASS=CHAR
,DEVCLASS=COMM
,DEVCLASS=CTC
,DEVCLASS=DASD
,DEVCLASS=DISP
,DEVCLASS=TAPE
,DEVCLASS=UREC
,DEVCID=devcid addr
Default:
3DIGIT
Default:
NO
Default:
NO
Default:
ALL
devcid addr: RS-type address
UCBSCAN macro
Description
ucbparea addr: RX-type address or register (2) - (12).
Default:
NONE
dcearea addr: RX-type address or register (2) - (12).
Default:
NONE
length addr: RS-type address or register (2) - (12).
Note:
DCELEN is valid only with DCEAREA and is required with
DCEAREA.
volser addr: RS-type address or register (2) - (12).
Default:
NONE
devnchar addr: RS-type address or register (2) - (12).
devn addr: RS-type address or register (2) - (12).
Default:
0
Default:
NO
Chapter 113. UCBSCAN — Scan UCBs
1129
UCBSCAN macro
Syntax
,DEVCID=0
,IOCTOKEN=ioctoken addr
,IOCTOKEN=NONE
Description
Default:
0
ioctoken addr: RX-type address or register (2) - (12).
Default:
NONE
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
,RETCODE=retcode addr
,RSNCODE=rsncode addr
Default:
IMPLIED_VERSION
plistver: 1
retcode addr: RX-type address or register (2) - (12).
rsncode addr: RX-type address or register (2) - (12).
Parameters
The parameters are explained as follows:
COPY
Specifies that a copy of the UCB is to be obtained. See z/OS HCD Planning for a list of the MVS services that accept a UCB copy.
Note:
When you issue UCBSCAN to obtain a UCB copy, the UCBID field in the copy is set to x‘CC’.
,WORKAREA=workarea addr
Specifies the address of a 100-character work area used by the UCBSCAN service. The caller must initialize this work area to binary zeros before starting a UCB scan. On subsequent invocations of UCBSCAN within the same scan, the caller must leave the contents of this work area unchanged.
,UCBAREA=ucbarea addr
Specifies the address of a 48-character storage area that will receive a copy of the UCB common segment and the UCB device-dependent segment. See z/OS
HCD Planning for a list of the MVS services that accept a UCB copy.
The caller does not need to initialize this area. Use the IEFUCBOB mapping macro to map the area. The contents of certain fields in the copy are: v The UCBEXTP field contains either:
– The address of the CMXTAREA, if CMXTAREA is below 16 MB
– 0, if CMXTAREA is above 16 MB or if the CMXTAREA parameter is not specified v The UCBNXUCB field is 0, because this field is not valid in the UCB copy.
v Address fields in the copy might not contain valid addresses, so do not use these addresses to reference the data areas they point to.
,CMXTAREA=cmxtarea addr
,CMXTAREA=NONE
Specifies the address of a 32-character storage area that will receive a copy of
1130
z/OS MVS Assembler Services Reference IAR-XCT
UCBSCAN macro
the UCB common extension segment. See z/OS HCD Planning for a list of the
MVS services that accept a UCB copy and require this segment as part of a
UCB copy.
Use the UCBCMEXT DSECT in the IEFUCBOB mapping macro to map the area. If the CMXTAREA area is below 16 MB, the UCBEXTP field in the
UCBAREA area contains the address of the CMXTAREA area, If the
CMXTAREA area is above 16 MB, the caller must explicitly supply the address of the CMXTAREA area because the UCBEXTP field will contain 0.
The UCBIEXT field contains 0 because this field is not valid in the UCB copy.
The UCBCLEXT field contains the address of the DCEAREA if the UCB has a device class extension and the caller specified the DCEAREA parameter.
Otherwise, the field contains 0.
,UCBPAREA=ucbparea addr
,UCBPAREA=NONE
Specifies the address of a 48-character storage area that will receive a copy of the UCB prefix extension segment. This keyword is required if
SUBCHANNELSET=ALL is specified. The area can be mapped by the
IOSDUPI mapping macro.
,DCEAREA=dcearea addr
,DCEAREA=NONE
Specifies the address of a storage area that will receive a copy of the UCB device class extension segment. See z/OS HCD Planning for a list of the MVS services that accept a UCB copy and require this segment as part of a UCB copy.
Note:
If DCEAREA=NONE is coded, then DCELEN=0 must be coded. If
DCEAREA=NONE is defaulted, then DCELEN does not have to be coded.
,DCELEN=length addr
Specifies the address of a 2-byte field that contains the length of the area specified by DCEAREA. The length specified must be 1 through 256 bytes.
DCELEN is required with DCEAREA.
,VOLSER=volser addr
,VOLSER=NONE
Specifies the address of a 6-character field that indicates, in EBCDIC, the volume serial number of the device for which a UCB copy is to be obtained.
,DEVNCHAR=devnchar addr
Specifies the address of a 4-character field that is to receive the EBCDIC device number associated with the UCB copy.
,DEVN=devn addr
,DEVN=0
Specifies (DEVN=devn addr) an input halfword that contains, in binary form, the device number with which the scan is to begin. The default, DEVN=0, starts the scan with the first UCB.
,SUBCHANNELSET=ID
,SUBCHANNELSET=ALL
,SUBCHANNELSET=ID
Indicates the UCB scan is based on one subchannel set. DEFAULT: ID
,SCHSET=xschset
Chapter 113. UCBSCAN — Scan UCBs
1131
UCBSCAN macro
SCHSET=0
Specifies the name (RS-type), or address in register (2)-(12), of an optional byte input that specifies a subchannel set for which the UCB scan is to be performed. DEFAULT: 0.
,SUBCHANNELSET=ALL
Indicates the UCB scan is based on all subchannel sets. DEFAULT: ID
,LDEVNCHAR=xldevnchar
Indicates the name (RS-type), or address in register (2)-(12), of an optional 5 character output which is to contain the EBCDIC logical device number associated with the UCB copy.
Note:
A logical device number is represented by the 1-digit subchannel set id followed by a 4-digit device number, sdddd.
,DYNAMIC=NO
,DYNAMIC=YES
Specifies whether the scan should be restricted to static and installation-static
UCBs (DYNAMIC=NO) or should also include dynamic UCBs
(DYNAMIC=YES).
,RANGE=3DIGIT
,RANGE=ALL
Specifies whether the scan should be restricted to UCBs with 3-digit device numbers (3DIGIT) or should also include UCBs with 4-digit device numbers
(ALL).
,UNBOUND_ALIAS=NO
,UNBOUND_ALIAS=YES
,UNBOUND_ALIAS=ONLY
Specifies whether the scan should include unbound alias UCBs.
YES
Include unbound alias UCBs
NO
Do not include unbound alias UCBs
ONLY
Include only unbound alias UCBs
Note:
The UNBOUND_ALIAS function is intended for IOS use only.
SPECIAL=NO
SPECIAL=YES
SPECIAL=ONLY
Specifies whether the UCB is findable (SPECIAL=YES) or not (SPECIAL=NO).
SPECIAL=ONLY should be used to scan for only special devices. Special devices are those UCBs that represent devices that are not PAV-alias devices in the alternate subchannel set. The 3390S and 3390D device types are special devices.
,DEVCLASS=ALL
,DEVCLASS=CHAR
,DEVCLASS=COMM
,DEVCLASS=CTC
,DEVCLASS=DASD
,DEVCLASS=DISP
,DEVCLASS=TAPE
,DEVCLASS=UREC
Specifies the device class that is to be scanned:
ALL
Scans UCBs for all device classes
1132
z/OS MVS Assembler Services Reference IAR-XCT
UCBSCAN macro
CHAR
Scans UCBs for character reader device class
COMM
Scans UCBs for communications device class
CTC
Scans UCBs for channel to channel device class
DASD
Scans UCBs for direct access device class
DISP
Scans UCBs for display device class
TAPE
Scans UCBs for tape device class
UREC
Scans UCBs for unit record device class
,DEVCID=devcid addr
Specifies the address of an 8-bit input field that contains the device class ID of the device class to be scanned. The value in this byte represents the third byte in the UCBTYP field of each device in the class.
If you specify DEVCID, only UCBs of the particular device class specified will be presented, and the DEVCLASS parameter is ignored.
,IOCTOKEN=ioctoken addr
,IOCTOKEN=NONE
Specifies the address of a 48-character storage area that contains the MVS I/O configuration token. The caller can obtain this token by issuing the IOCINFO macro. If the I/O configuration token that is current when UCBSCAN is invoked does not match the token whose address is supplied as input by
ioctoken addr, the caller will be notified through a return code.
If the input IOCTOKEN (specified by ioctoken addr) is set to binary zeros,
UCBSCAN will set IOCTOKEN to the current I/O configuration token at the start of the scan.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are: v IMPLIED_VERSION , which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
v MAX , if you want the parameter list to be the largest size currently possible.
This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
v 1 , if you use the currently available parameters.
To code
, specify in this input parameter one of the following: v IMPLIED_VERSION
Chapter 113. UCBSCAN — Scan UCBs
1133
UCBSCAN macro
v MAX v
A decimal value of 1
,RETCODE=retcode addr
Specifies the fullword location where the system is to store the return code.
The return code is also in GPR 15.
,RSNCODE=rsncode addr
Specifies the fullword location where the system is to store the reason code.
The reason code is also in GPR 0.
Return and reason codes
When control returns from USBSCAN, GPR 15 (and retcode addr, if you coded
RETCODE) contains a return code and, for some return codes, GPR 0 (or rsncode
addr, if you coded RSNCODE) contains a reason code.
Hexadecimal Return
Code
00
Hexadecimal Reason
Code
None
04
08
08
08
08
08
01
01
02
03
04
05
Meaning and Action
Meaning:
UCBSCAN completed successfully.
Action:
None.
Meaning:
UCBSCAN processing ended. All UCBs that met the search criteria have been presented to the caller. The contents of UCBAREA are unchanged, and WORKAREA has been reset to binary zeros.
Action:
None.
Meaning:
Program error. A caller in AR mode specified an ALET that was not valid.
Action:
Correct the ALET and reissue the macro.
Possibly the caller wrote over an area in the parameter list; look for this error.
Meaning:
Program error. An error occurred when the system tried to access the caller's parameter list.
Action:
Ensure that you have met the environmental requirements for the macro, and reissue the macro.
Meaning:
Program error. An error occurred in referencing the caller-supplied area for the UCB copy; the area was specified in the UCBAREA parameter.
Action:
Correct the UCBAREA parameter.
Meaning:
Program error. An error occurred in referencing the caller-supplied area for the UCB prefix extension segment data. This reason code is valid only for callers using the UCBPAREA parameter.
Action:
Correct the UCBPAREA parameter.
Meaning:
Program error. An error occurred when the system referenced the caller-supplied area specified in the IOCTOKEN parameter. This reason code is valid only for callers using the
IOCTOKEN parameter.
Action:
Correct the IOCTOKEN parameter.
1134
z/OS MVS Assembler Services Reference IAR-XCT
UCBSCAN macro
Hexadecimal Return
Code
08
08
08
08
08
08
0C
20
Hexadecimal Reason
Code
08
09
0B
0C
0D
0E
None
None
Meaning and Action
Meaning:
Program error. An error occurred in referencing the caller-supplied work area specified in the WORKAREA parameter.
Action:
Correct the WORKAREA parameter.
Meaning:
Program error. An error occurred in referencing the caller-supplied CMXTAREA area.
This reason code is valid only for callers using the CMXTAREA parameter.
Action:
Correct the CMXTAREA parameter.
Meaning:
Program error. An error occurred in referencing the caller-supplied DCEAREA area.
This reason code is valid only for callers using the DCEAREA parameter.
Action:
Correct the DCEAREA parameter.
Meaning:
Program error. The caller specified a volume serial number that is not valid. (Note that binary zeros are not considered valid.) This reason code is valid only for callers using the
VOLSER parameter.
Action:
Correct the VOLSER parameter.
Meaning:
Program error. For the DCEAREA token, the caller specified a length that is negative, is zero, or exceeds 256 bytes. This reason code is valid only for callers using the
DCELEN parameter.
Action:
Correct the DCELEN parameter.
Meaning:
The value specified on the SCHSET keyword is not valid.
Action:
Correct the SCHSET value.
Meaning:
Environmental error. The I/O configuration has changed, so that the I/O configuration token supplied through the
IOCTOKEN parameter is not current. This return code is valid only for callers using the
IOCTOKEN parameter.
Action:
Obtain the current I/O configuration token by issuing an IOCINFO macro or by setting the input IOCTOKEN parameter in the
UCBINFO macro to zero. Start the scan from the beginning.
Meaning:
System error. An unexpected error occurred.
Action:
Supply the return code to the appropriate
IBM support personnel.
UCBSCAN COPY - List form
Use the list form of the UCBSCAN macro together with the execute form for applications that require reentrant code. The list form of the macro defines an area of storage that the execute form uses for storing the parameters.
Chapter 113. UCBSCAN — Scan UCBs
1135
UCBSCAN macro
Syntax
Syntax
This macro is an alternative list form macro, and requires a different technique for using the list form as compared to the conventional list form macros. See
“Alternative list form macros” on page 13 for further information.
The list form of the COPY function of the UCBSCAN macro is written as follows:
Description
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede UCBSCAN.
UCBSCAN
� One or more blanks must follow UCBSCAN.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 1
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
list addr: Symbol.
attr: 1- to 60-character input string.
Default:
0D
Parameters
The parameters are explained under that standard form of the UCBSCAN macro with the following exceptions:
MF=(L,list addr)
MF=(L,list addr,attr)
MF=(L,list addr,0D)
Specifies the list form of the UCBSCAN macro.
The list addr parameter specifies the address of the storage area for the parameter list.
attr is an optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
UCBSCAN COPY - Execute form
Use the execute form of the UCBSCAN macro together with the list form for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
1136
z/OS MVS Assembler Services Reference IAR-XCT
�
Syntax
name
UCBSCAN macro
Syntax
The execute form of the COPY function of the UCBSCAN macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede UCBSCAN.
UCBSCAN
� One or more blanks must follow UCBSCAN.
COPY
,WORKAREA=workarea addr
,UCBAREA=ucbarea addr
workarea addr: RX-type address or register (2) - (12).
ucbarea addr: RX-type address or register (2) - (12).
,CMXTAREA= cmxtarea addr
,CMXTAREA=NONE
,UCBPAREA=ucbparea addr
,UCBPAREA=NONE
,DCEAREA= dcearea addr
,DCEAREA=NONE
,DCELEN=length addr
,VOLSER=volser addr
,VOLSER=NONE
,DEVNCHAR=devnchar addr
,DEVN=devn addr
,DEVN=0
,SUBCHANNELSET=ID
cmxtarea addr: RX-type address or register (2) - (12).
Default:
NONE
ucbparea addr: RX-type address or register (2) - (12).
Default:
NONE
dcearea addr: RX-type address or register (2) - (12).
Default:
NONE
length addr: RS-type address or register (2) - (12).
Note:
DCELEN is valid only with DCEAREA and is required with
DCEAREA.
volser addr: RS-type address or register (2) - (12).
Default:
NONE
devnchar addr: RS-type address or register (2) - (12).
devn addr: RS-type address or register (2) - (12).
Default:
0
Chapter 113. UCBSCAN — Scan UCBs
1137
UCBSCAN macro
Syntax
,SCHSET=xschset
,SCHSET=0
,SUBCHANNELSET=ALL
,DYNAMIC=NO
,DYNAMIC=YES
,RANGE=3DIGIT
,RANGE=ALL
,UNBOUND_ALIAS=NO
,UNBOUND_ALIAS=YES
,UNBOUND_ALIAS=ONLY
,DEVCLASS=ALL
,DEVCLASS=CHAR
,DEVCLASS=COMM
,DEVCLASS=CTC
,DEVCLASS=DASD
,DEVCLASS=DISP
,DEVCLASS=TAPE
,DEVCLASS=UREC
Description
xschset RS-type address or register (2) - (12).
Default:
0
Default:
Default:
Default:
Default:
NO
3DIGIT
NO
ALL
,DEVCID=devcid addr
,DEVCID=0
,IOCTOKEN=ioctoken addr
,IOCTOKEN=NONE
devcid addr: RS-type address
Default:
0
ioctoken addr: RX-type address or register (2) - (12).
Default:
NONE
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Default:
IMPLIED_VERSION
plistver: 1
,RETCODE=retcode addr retcode addr: RX-type address or register (2) - (12).
,RSNCODE=rsncode addr
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
rsncode addr: RX-type address or register (2) - (12).
list addr: RX-type address or register (2) - (12).
Default:
COMPLETE
1138
z/OS MVS Assembler Services Reference IAR-XCT
UCBSCAN macro
Parameters
The parameters are explained under the standard form of the COPY function of the UCBSCAN macro with the following exceptions:
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
Specifies the execute form of the UCBSCAN macro.
The list addr parameter specifies the address of the storage area for the parameter list.
COMPLETE specifies that the system is to check for required parameters and supply defaults for optional parameters that were not specified.
Chapter 113. UCBSCAN — Scan UCBs
1139
UCBSCAN macro
1140
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 114. UPDTMPB — Update a message parameter block for substitution data
Description
To build a message parameter block (MPB), you must issue both BLDMPB and
UPDTMPB. BLDMPB initializes the MPB, and UPDTMPB adds one substitution token to the MPB each time you issue it. Issue UPDTMPB once for each substitution token in the message.
You can also use UPDTMPB to replace or change the value of a particular substitution token in an existing MPB. See z/OS MVS Programming: Assembler
Services Guide for more information on using UPDTMPB.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt Status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task or SRB
PASN=HASN=SASN or PASN¬=HASN¬=SASN
24- or 31-bit
Primary
Enabled for I/O and external interrupts
No locks held
Not applicable
Programming requirements
You must include the mapping macro CNLMMPB.
Restrictions
None.
Input register information
Before issuing the UPDTMPB macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
0
1
Register
Contents
Reason code
Used as a work register by system
2-13
14
15
Unchanged
Used as a work register by system
Return code
© Copyright IBM Corp. 1988, 2017
1141
UPDTMPB macro
Syntax
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The UPDTMPB macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede UPDTMPB.
name
�
UPDTMPB
�
MPBPTR=mpb addr
,MPBLEN=mpb length addr
,SUBOOFST=new/changed blk offset
addr
,SUBCOFST=existing blk
offset addr
,TOKEN=token name addr
,TOKLEN=token length addr
,TOKTYPE=token type addr
,SUBSDATA=sub data addr
,SUBSLEN=sub data length
addr
One or more blanks must follow UPDTMPB.
mpb addr: RX-type address or register (2) - (12).
mpb length addr: RX-type address or register (2) - (12).
new/changed blk offset addr: RX-type address or register (2) - (12).
existing blk offset addr: RX-type address or register (2) - 12).
token name addr: RX-type address or register (2) - (12).
token length addr: RX-type address or register (2) - (12).
token type addr: RX-type address or register (2) - (12).
sub data addr: RX-type address or register (2) - (12).
sub data length addr: RX-type address or register (2) - (12).
1142
z/OS MVS Assembler Services Reference IAR-XCT
UPDTMPB macro
Parameters
The parameters are explained as follows:
MPBPTR=mpb addr
specifies the address or a register containing the address of the MPB to be modified.
,MPBLEN=mpb len addr
specifies the address or a register containing the address of the length of the area addressed by MPBPTR.
,SUBOOFST=new/changed blk offset addr
specifies the address of the area or a register into which UPDTMPB returns the value of the offset from the start of the MPB to the new or changed substitution block. A substitution block contains all the information that you need to format substitution data. It consists of a token field, token length, substitution length, token type, and substitution data.
,SUBCOFST=existing blk offset addr
specifies the address of the offset or a register containing the offset from the start of the MPB to the existing substitution block that UPDTMPB is to update.
If you do not specify SUBCOFST, UPDTMBP will build a new substitution block.
,TOKEN=token name addr
specifies the address of the area or a register pointing to the area containing the substitution token name.
,TOKLEN=token length addr
specifies the address of the area or a register containing the length of the
TOKEN field. If you do not specify TOKLEN, UPDTMPB uses, as a default, the length of the TOKEN field in the DSECT mapping. You must specify TOKLEN if you use register notation for the TOKEN keyword.
,TOKTYPE=token type addr
specifies the address of the area or a register containing the 1-byte token type.
This field can have the following values and meanings:
Value
2
3
0
1
Meaning
text date time day of week
,SUBSDATA=sub data addr
specifies the address of the area or a register pointing to the area containing the substitution data.
If TOKTYPE is 0, SUBSDATA can contain any text with a length defined
SUBSLEN.
If TOKTYPE is 1, SUBSDATA must be eight bytes long and in the format
yyyymmdd, where: v
yyyy is the year number, expressed as a 4-digit EBCDIC string in the range
0000 to 9999.
v mm is the month number, expressed as a 2-digit EBCDIC string in the range
01 to 12.
Chapter 114. UPDTMPB — Update a message parameter block for substitution data
1143
UPDTMPB macro
v dd is the day number, expressed as a 2-digit EBCDIC string in the range 01 to 31.
If TOKTYPE is 2, SUBSDATA must be twelve bytes long in the format
hhmmssdddddd, where: v hh is the hours in a 24-hour clock, expressed as a 2-digit EBCDIC string in the range 00 to 23.
v mm is the minutes, expressed as a 2-digit EBCDIC string in the range 00 to
59.
v ss is the seconds, expressed as a 2-digit EBCDIC string in the range 00 to 59.
EBCDIC blanks are considered zeros.
v
dddddd is the decimal seconds, expressed as a 6-digit EBCDIC string in the range 000000 to 999999. EBCDIC blanks are considered zeros.
If TOKTYPE is 3, SUBSDATA must be one byte long in the format d, where d is the day number, expressed as a 1-digit EBCDIC string in the range 1 to 7. The days are defined in parmlib member CNLcccxx. Day 1 is Sunday, 2 is Monday, and so on.
,SUBSLEN=sub data length addr
specifies the address of the area or a register pointing to the area containing the length of the substitution data. If you do not specify SUBSLEN, UPDTMPB uses, as a default, the length of the SUBSDATA field in the DSECT mapping.
You must specify SUBSLEN if you use register notation for the SUBSDATA parameter.
Return and reason codes
When UPDTMPB completes, register 15 contains one of the following hexadecimal return codes:
Meaning Hexadecimal
Return Code
00
0C
Processing completed successfully.
Processing unsuccessful. See reason codes.
When UPDTMPB completes, register 0 contains one of the following hexadecimal reason codes:
Meaning Hexadecimal
Return Code
0C
0C
0C
0C
00
0C
0C
Hexadecimal
Reason Code
36
37
38
3B
00
33
35
Successful processing.
There is insufficient storage in the MPB.
The value for TOKLEN is either zero or negative.
The value for SUBSLEN is negative.
The TOKTYPE value is not valid.
SUBCOFST is not valid.
The MPB acronym is not valid.
Example
Build and update an MPB for a message that contains substitution data for the third day of the week.
1144
z/OS MVS Assembler Services Reference IAR-XCT
UPDTMPB macro
BLDMPBA CSECT
BLDMPBA AMODE 31
BLDMPBA RMODE ANY
STM 14,12,12(13)
BALR 12,0
USING *,12
ST
LA
13,SAVE+4
15,SAVE
ST
LR
15,8(13)
13,15
***********************************************************************
* OBTAIN WORKING STORAGE AREA *
***********************************************************************
GETMAIN RU,LV=STORLEN,SP=SP230
LR R4,R1
*
***********************************************************************
* CREATE MPB HEADER SECTION *
***********************************************************************
*
BLDMPB MPBPTR=(R4),MPBLEN=MPBL,MSGID=MSGID,
MSGIDLEN=MIDLEN
*
***********************************************************************
X
* ADD SUBSTITUTION DATA TO MPB *
***********************************************************************
*
LR
A
R2,R4
R2,MPBL
USING VARS,R2
*
UPDTMPB MPBPTR=(R4),MPBLEN=MPBL,SUBOOFST=VARS,
TOKEN=TOKN,TOKLEN=TOKL,TOKTYPE=TOKT,
SUBSDATA=SDATA,SUBSLEN=SDATAL
*
*
***********************************************************************
* FREE STORAGE AREA *
X
X
***********************************************************************
*
FREEMAIN RU,LV=STORLEN,SP=SP230,A=(4)
*
L
LM
13,SAVE+4
14,12,12(13)
BR 14
***********************************************************************
MPBL
MSGID
DC
DC
MIDLEN DC
TOKN DC
A(MPBLEN)
CL10’MSGID2’
A(MIDL)
CL3’DAY’
TOKL
TOKT
DC
DC
SDATA DC
SDATAL DC
F’3’
CL1’3’
CL1’3’
A(SDL)
SAVE DC 18F’0’
SP230 EQU 230
STORLEN EQU 256
SDL
MIDL
EQU 6
EQU 6
MPBLEN EQU (MPBVDAT-MPB)+(MPBMID-MPBMSG)+(MPBSUB-MPBSB)+MIDL+SDL
R1 EQU 1
R2
R4
EQU 2
EQU 4
***********************************************************************
DSECT
CNLMMPB
Chapter 114. UPDTMPB — Update a message parameter block for substitution data
1145
UPDTMPB macro
VARS DSECT
VARSAREA DS CL24
VARSLEN EQU *-VARS
END BLDMPBA
1146
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 115. VRADATA — Update variable recording area data
Description
The VRADATA macro copies service information into a variable recording area
(VRA), usually the system diagnostic work area (SDWAVRA). This information can later be recorded in the LOGREC data set if software errors occur. (See the SETRP macro, RECORD=YES parameter description, for more information on recording the SDWA data area.) The information copied into the VRA using this macro is in a key, length, data format defined by the IHAVRA mapping macro. The key and length are one-byte fields; the data can vary in length. The IHAVRA mapping macro is shown in z/OS MVS Data Areas in the z/OS Internet library
(www.ibm.com/systems/z/os/zos/library/bkserv) under VRAMAP.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task or SRB
Any PASN, any HASN, any SASN
24- or 31- or 64-bit
Primary, secondary, or access register (AR)
Enabled or disabled for I/O and external interrupts
The caller may hold locks, but is not required to hold any.
None
Programming requirements
v If your program is in AR mode, issue the SYSSTATE ASCENV=AR macro before issuing VRADATA. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.
v You must include the IHASDWA mapping macro as a DSECT in your program if you accept the default for VRAINIT, VRACLEN, VRAMLEN, or if you specify
VRAINIT=SDWAVRA. You must also place the address of the SDWA data area into the SDWAREG register (or default register 1) if you accept the default for any of these three parameters.
v You must include the IHAVRA mapping macro as a DSECT in your program. If you include the IHASDWA mapping macro, IHAVRA is automatically included.
v You can issue VRADATA more than once in a program, but you need to specify
VRAINIT, VRACLEN, and VRAMLEN only once for a particular series of updates to the VRA.
v If you specify a key on the KEY parameter, but no data on the DATA parameter, the length field for the VRA entry (LEN parameter) is zero. You must be running in the key the SDWA was obtained in. Refer to z/OS MVS Programming:
Assembler Services Guide for more information.
Restrictions
None.
© Copyright IBM Corp. 1988, 2017
1147
VRADATA macro
Input register information
Before issuing the VRADATA macro, the AR-mode caller must ensure that the following GPRs contain the specified information.
Register
Contents
1
Address of the SDWA if you do not specify the SDWAREG parameter on this invocation or any previous invocation of the VRADATA macro; otherwise, the caller does not have to place any information into this register.
14
Address of the next available field in the VRA if you do not specify the
VRAREG parameter on this invocation or any previous invocation of the
VRADATA macro; otherwise, the caller does not have to place any information into this register.
Before issuing the VRADATA macro, the caller must ensure that the following ARs contain the specified information.
Register
Contents
1
ALET of the SDWA whose address is in GPR 1, only if you do not specify the SDWAREG parameter on this invocation or any previous invocation of the VRADATA macro; otherwise, the caller does not have to place any information into this register.
14
ALET of the next available space in the VRA whose address is in GPR 14 only if you do not specify the VRAREG parameter on this invocation or any previous invocation of the VRADATA macro; otherwise, the caller does not have to place any information into this register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-13
14
Unchanged
Address of the next available space in the VRA for the next invocation of
VRADATA if you did not specify the VRAREG parameter on this invocation or any previous invocation; otherwise, unchanged.
15
Used as a work register if you did not specify the WORKREG parameter on this invocation or any previous invocation of the VRADATA macro; otherwise, unchanged.
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
1148
z/OS MVS Assembler Services Reference IAR-XCT
⌂
⌂
Syntax
name
VRADATA macro
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The VRADATA macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede VRADATA.
VRADATA
VRAINIT=vra addr
,VRACLEN=curr len addr or (curr len addr,0)
,VRAMLEN=max len addr
,KEY=key nmbr
,LENADDR=data len addr
,LEN=data len value
,DATA=data addr
,SDWAREG=reg
,VRAREG=(reg,descr)
One or more blanks must follow VRADATA.
vra addr: RX-type address, or the symbol SDWAVRA.
Default
: address of SDWAVRA
curr len addr: RX-type address.
Default
: address of SDWAURAL.
max len addr: RX-type address.
Default
: address of SDWAVRAL.
key nmbr: Symbol or decimal digit.
data len addr: RX-type address.
data len value: Symbol or decimal digit.
Default
: length of DATA storage.
data addr: RX-type address, or register (1) - (15).
reg: Symbol or decimal digits 1-15.
Default
: 1
reg: Symbol or decimal digits 1-15.
Default
: 14
descr: SET or NOTSET
Default
: NOTSET if VRAINIT is specified,
Chapter 115. VRADATA — Update variable recording area data
1149
VRADATA macro
Syntax
,WORKREG=reg
,TYPE=(LEN,TEST)
,TYPE=(LEN,NOTEST)
,TYPE=(LEN,NOT)
,TYPE=(NOLEN,TEST)
,TYPE=(NOLEN,NOTEST)
,TYPE=(NOLEN,NOT)
,TYPE=(NOL,TEST)
,TYPE=(NOL,NOTEST)
,TYPE=(NOL,NOT)
Description
otherwise SET.
reg: Symbol or decimal digits 1-15.
Default
: 15
Default
: LEN,TEST
Parameters
The parameters are explained as follows:
VRAINIT=vra addr
Specifies the address of the variable recording area to be initialized and updated. The value in the register specified by the VRAREG parameter is also initialized unless VRAREG=(,SET) is specified. If VRAINIT=SDWAVRA is specified, the SDWA data area is also updated to indicate that the VRA contains data in key-length-data format that is to be displayed in hexadecimal.
If VRAINIT is not specified, VRAINIT=SDWAVRA is assumed. All subsequent
VRADATA macros use the specified VRAINIT value until you specify another
VRAINIT value.
,VRACLEN=curr len addr
Specifies the address of a one-byte field that contains the length of the current
VRA. This value changes as information is added in the VRA. If you do not specify VRACLEN, you can obtain the current length of the VRA from the
SDWAURAL field of the SDWA.
,VRACLEN=(curr len addr, 0)
Specifies that the area containing the length is to be zeroed.
All subsequent VRADATA macros use the specified VRACLEN value until you specify another VRACLEN value.
,VRAMLEN=max len addr
Specifies the address of a two-byte field that contains the maximum length of the VRA. If you do not specify VRAMLEN, the maximum length is obtained from SDWAVRAL.
All subsequent VRADATA macros use the specified VRAMLEN value until you specify another VRAMLEN value.
,KEY=key number
Specifies the key value to be placed in the VRAKEY field of the current VRA entry. The IHAVRA mapping macro (VRAMAP) defines the valid key values.
,LENADDR=data len addr
,LEN=data len value
Specifies the length of the data for the VRA entry. The maximum length is 255
1150
z/OS MVS Assembler Services Reference IAR-XCT
VRADATA macro
bytes. Omit this parameter unless the DATA parameter is a register value or a displacement plus a register, or if the defined data length must be overridden because it is larger than 255 bytes. For bit string data, use this parameter to indicate how many bytes the bit string occupies. The data length field pointed to by LENADDR must be a two-byte area with the length right-justified in the area.
,DATA=data addr
Specifies the address of the data to be copied into the VRA. The data must correspond to the key specified by the KEY parameter. If you specify DATA, you must specify KEY. You must also specify LEN or LENADDR if DATA has a register value or if the data length is greater than 255 bytes.
,SDWAREG=reg
Specifies a register containing the address of the SDWA data area. You must place the address in this register before invoking VRADATA. The VRADATA macro preserves the contents of this register. If you do not specify SDWAREG, register 1 is the default.
,VRAREG=(reg,descr)
Specifies a register to contain the address of the next available field in the VRA and a description of whether or not the register value is already set (SET) or not set (NOTSET). If VRAINIT is specified, the default is NOTSET. If VRAINIT is not specified, the default is SET. If you specify NOTSET or default to it, the system program places the address of the VRA plus the current length in the register before updating the VRA.
After updating the VRA, the system updates the register to point to the next available field in the VRA. If you do not specify VRAREG, register 14 is the default.
,WORKREG=reg
Specifies a work register. Each time you invoke the VRADATA macro, the contents of this register are destroyed. If you do not specify WORKREG, register 15 is the default.
,TYPE=(LEN,TEST)
,TYPE=(LEN,NOTEST)
,TYPE=(LEN,NOT)
,TYPE=(NOLEN,TEST)
,TYPE=(NOLEN,NOTEST)
,TYPE=(NOLEN,NOT)
,TYPE=(NOL,TEST)
,TYPE=(NOL,NOTEST)
,TYPE=(NOL,NOT)
Specifies whether (LEN) or not (NOLEN) you want the current length of the
VRA stored in the VRALEN area and also specifies whether (TEST) or not
(NOTEST) you want the VRA tested to see if it is full before adding the new entry. If you specify TEST, the current length of the VRA must already be in the VRACLEN area.
If you do not need to store the length or test to see if the new entry fits, specify NOLEN and NOTEST. These specifications considerably reduce the amount of code generated by the VRADATA macro. If you do not specify
TYPE, the value LEN, TEST is the default.
ABEND codes
None.
Chapter 115. VRADATA — Update variable recording area data
1151
VRADATA macro
Return and reason codes
None.
Example 1
Initialize the SDWA data area to indicate that the VRA contains hexadecimal data, in key, length, data format. Also, move two pieces of data into the SDWAVRA, and indicate that no test of the length of the VRA is needed, (because the data fits in the VRA). The second request indicates that the length used is to be stored in the
VRA current length field. The pieces of data are the IHAVRA mapping macro name and the contents of a control block.
VRADATA VRAINIT=SDWAVRA,KEY=VRACBM,DATA=MYCBNAME,
TYPE=(NOLEN,NOTEST)
VRADATA KEY=VRACB,DATA=MYCB,TYPE=(LEN,NOTEST)
X
Example 2
Initialize a variable recording area that is not the SDWA. Move in a piece of data, specifying its length. (The piece of data is an ASID.)
VRADATA VRAINIT=LRBTUSR,VRACLEN=LRBTCLEN,
VRAMLEN=LBRTMLEN
VRADATA KEY=VRAAID,DATA=(REGA),LEN=ASIDLEN
X
1152
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 116. WAIT — Wait for one or more events
|
Description
The WAIT macro informs the system that performance of the active task cannot continue until one or more specific events, each represented by a different event control block (ECB), have occurred. Bit 0 and bit 1 of each ECB must be set to zero before it is used. The caller must be enabled, unlocked, and in primary address space control (ASC) mode.
The system takes the following action: v
For each event that has already occurred (each ECB is already posted), the count of the number of events is decreased by one.
v If the number of events is zero by the time the last event control block is checked, control is returned to the instruction following the WAIT macro.
v If the number of events is not zero by the time the last ECB is checked, control is not returned to the issuing program until sufficient ECBs are posted to bring the number to zero. Control is then returned to the instruction following the
WAIT macro.
For more information on how to use the WAIT macro to synchronize tasks, see
z/OS MVS Programming: Assembler Services Guide.
Environment
The requirements for callers of WAIT are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
RMODE:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
One of the following: v For LINKAGE=SVC: PASN=HASN=SASN, v For LINKAGE=SYSTEM: PASN=HASN=SASN or
PASN¬=HASN¬=SASN
24- or 31- or 64-bit
Includes 64-bit
Primary
Enabled for I/O and external interruptions
No locks held
ECB and ECBLIST must be in the home address space.
Programming requirements
None.
Restrictions
When using LINKAGE=SVC (the default), the caller cannot have an EUT FRR established.
© Copyright IBM Corp. 1988, 2017
1153
WAIT macro
Syntax
Input register information
Before issuing the WAIT macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system
When control returns to the caller, the access registers (AR) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The WAIT macro is written as follows:
Description
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede WAIT.
WAIT
�
event nmbr,
One or more blanks must follow WAIT.
event nmbr: Symbol, decimal digit, or register (0) or (2) - (12).
Default
: 1
Value range
: 0-255
ECB=ecb addr ecb addr: RX-type address, or register (1) or (2) - (12).
1154
z/OS MVS Assembler Services Reference IAR-XCT
WAIT macro
Syntax
ECBLIST=ecb list addr
,LONG=NO
,LONG=YES
,LINKAGE=SVC
,LINKAGE=SYSTEM
,RELATED=value
Description
ecb list addr: RX-type address, or register (1) or (2) - (12).
Default
: LONG=NO
Default
: LINKAGE=SVC
value: Any valid macro keyword specification.
Parameters
The parameters are explained as follows:
event nmbr,
Specifies the number of events waiting to occur.
ECB=ecb addr
ECBLIST=ecb list addr
Specifies the address of an ECB on a fullword boundary or the address of a virtual storage area containing one or more consecutive fullwords on a fullword boundary. Each fullword contains the address of an ECB; the high order bit in the last fullword must be set to one to indicate the end of the list.
The ECB parameter is valid only if the number of events is specified as one or is omitted. The number of ECBs in the list specified by the ECBLIST form must be equal to or greater than the specified number of events.
If you specify ECBLIST, ecb list addr and all ECBs on the list must be in the home address space.
,LONG=NO
,LONG=YES
Specifies whether the task is entering a long wait (YES) or a regular wait (NO).
,LINKAGE=SVC
,LINKAGE=SYSTEM
Specifies whether POST is to be called through an SVC (LINKAGE=SVC) or not (LINKAGE=SYSTEM).
When the caller is not in cross memory mode (the primary, secondary, and home address spaces are the same) and no EUT FRR is established, use
LINKAGE=SVC. With this parameter, linkage is through an SVC instruction.
When the caller is in cross memory mode (the primary, secondary, and home address spaces are not the same) or if an EUT FRR is established, use
LINKAGE=SYSTEM. With this parameter, linkage is through a PC instruction.
Note that the ECB must be in the home address space.
,RELATED=value
Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user and may be any valid coding values.
Chapter 116. WAIT — Wait for one or more events
1155
WAIT macro
The RELATED parameter is available on macros that provide opposite services
(for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and
LOAD/DELETE) and on macros that relate to previous occurrences of the same macros (for example, CHAP and ESTAE).
The RELATED parameter may be used, for example, as follows:
WAIT1 WAIT 1,ECB=ECB,RELATED=(RESUME1,
’WAIT FOR EVENT’)
.
.
.
RESUME1 POST ECB,0,RELATED=(WAIT1,
’RESUME WAITER’)
Note:
Each of these macros will fit on one line when coded, so there is no need for a continuation indicator.
CAUTION:
A job step with all of its tasks in a WAIT condition is terminated upon expiration of the time limits that apply to it.
Example
You have previously initiated one or more activities to be completed asynchronously to your processing. As each activity was initiated, you set up an
ECB in which bits 0 and 1 were set to zero. You now wish to suspend your task via the WAIT macro until a specified number of these activities have been completed.
Completion of each activity must be made known to the system via the POST macro. POST causes an addressed ECB to be marked complete. If completion of the event satisfies the requirements of an outstanding WAIT, the waiting task is marked ready and will be executed when its priority allows.
ABEND codes
WAIT might abnormally terminate with one of the following abend codes: v X'101' v X'201' v X'301' v
X'401'
These hexadecimal codes are described in z/OS MVS System Codes.
Return and reason codes
None.
Example 1
Wait for one event to occur (with a default count).
WAIT ECB=WAITECB
.
.
WAITECB DC F’0’
Example 2
Wait for 2 events to occur.
1156
z/OS MVS Assembler Services Reference IAR-XCT
WAIT 2,ECBLIST=LISTECBS
.
.
LISTECBS DC A(ECB1)
DC A(ECB2)
DC A(X’80000000’+ECB3)
Example 3
Enter a long wait for a task.
.
.
WAIT 1,ECBLIST=LISTECBS,LONG=YES
.
LISTECBS DC A(ECB1)
DC A(ECB2)
DC X’80’
DC AL3(ECB3)
WAIT macro
Chapter 116. WAIT — Wait for one or more events
1157
WAIT macro
1158
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 117. WTL — Write to log
Description
Note: IBM recommends
you use the WTO macro with the MCSFLAG=HRDCPY parameter instead of WTL, because WTO supplies more data than WTL.
The WTL macro causes a message to be written to the system log (SYSLOG) or the operations log (OPERLOG) log stream depending on which one of these logs, or both, is active.
Note:
When a message is recorded in SYSLOG, the exact format of the output of the WTL macro varies depending on the job entry subsystem (JES2 or JES3) that is being used, the output class that is assigned to the log at system initialization, and whether DLOG is in effect for JES3. See the following for information on the format of logged messages: v
z/OS MVS System Messages, Vol 1 (ABA-AOM)
v
z/OS MVS System Messages, Vol 2 (ARC-ASA)
v
z/OS MVS System Messages, Vol 3 (ASB-BPX)
v
z/OS MVS System Messages, Vol 4 (CBD-DMO)
v
z/OS MVS System Messages, Vol 5 (EDG-GFS)
v
z/OS MVS System Messages, Vol 6 (GOS-IEA)
v
z/OS MVS System Messages, Vol 7 (IEB-IEE)
v
z/OS MVS System Messages, Vol 8 (IEF-IGD)
v
z/OS MVS System Messages, Vol 9 (IGF-IWM)
v
z/OS MVS System Messages, Vol 10 (IXC-IZP)
z/OS JES3 Commands also contains information on the format of logged messages.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
24- or 31-bit
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space.
Programming requirements
None.
© Copyright IBM Corp. 1988, 2017
1159
WTL macro
Syntax
Restrictions
Message text cannot exceed 126 characters. If the message text exceeds 126 characters, truncation occurs at the last embedded blank before the 126th character; when there are no embedded blanks, truncation occurs after the 126th character.
Input register information
Before issuing the WTL macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
Register
Contents
0
Reason code
1-14
15
Unchanged
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the WTL macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede WTL.
WTL
� One or more blanks must follow WTL.
1160
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
‘msg’
WTL macro
Description
msg: Up to 126 characters.
Parameters
The parameter is explained as follows:
‘msg’
Specifies the message to be written to the system log and/or the operations log. The message must be enclosed in apostrophes, which will not appear in the system log. The message can include any character that can be used in a
C-type (character) DC statement, and is assembled as a variable-length record.
See “Timing and Communication” in z/OS MVS Programming: Assembler
Services Guide for a list of the printable EBCDIC characters passed to display devices or printers.
ABEND codes
None.
Return and reason codes
When the WTL macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code. WTL issues a return code (either 00 or 04), with multiple reason codes for each. The return codes indicate the following: v
00 - WTL wrote the message to the system log, the operations log, or both.
v 04 - WTL could not write the message to either the system log or the operations log.
Return Code
0
Reason Code
None
0 04
Meaning and Action
Meaning
: WTL processing completed successfully.
The system logged the message in SYSLOG, and, if
OPERLOG was requested, the system logged the message in OPERLOG.
Action
: None.
Meaning
: WTL processing completed successfully.
The message was logged in the operations log
(OPERLOG log stream). The system log was not active.
Action
: If you want the message logged in the system log, start the system log and rerun the program.
Chapter 117. WTL — Write to log
1161
WTL macro
Return Code
0
0
0
04
04
04
Reason Code
08
0C
10
04
08
0C
Meaning and Action
Meaning
: WTL processing completed, but the message was only logged in the operations log because the WTL system log buffers are full.
Action
: Do one of the following, if you want subsequent messages logged in the system log: v
Enter a CONTROL M,LOGLIM command to change the allocated number of WTL system log buffers dynamically.
v Change the LOGLIM value, specifying the number of WTL system log buffers on the INIT statement in the CONSOLxx parmlib member. This value will take effect at the next IPL.
Meaning
: WTL processing completed, but the message was only logged in the system log because the operations log was not active.
Action
: If you want the message logged in the operations log, start the operations log and rerun the program. This will also place the message in the system log.
Meaning
: WTL processing completed, but the message was only logged in the system log. The message was not logged in the OPERLOG log stream because of a storage problem.
Action
: If you want the message logged in the operations log, retry the request. This will also place the message in the system log. If the problem persists, contact the IBM Support Center. Provide the return and reason code.
Meaning
: System error. WTL processing was not successful. Recovery could not be established.
Action
: Retry the request. If the problem persists, record the return and reason code and supply them to the appropriate IBM support personnel.
Meaning
: Environmental error. The system log and the operations log are not active.
Action
: Start the logs and rerun your program.
Meaning
: Environmental error. The WTL limit has been reached.
Action
: Do one of the following:
1.
Retry the request when the shortage is relieved.
2.
Issue a CONTROL M,LOGLIM command to change the allocated number of WTL SYSLOG buffers.
3.
Change the LOGLIM value on the INIT statement in the CONSOLxx member of
SYS1.PARMLIB. This new value will take effect at the next IPL.
Note:
If the problem is persistent, you might want to perform step 2 first and step 3 at the next IPL.
1162
z/OS MVS Assembler Services Reference IAR-XCT
Return Code
04
04
04
04
WTL macro
Reason Code
10
14
18
1C
Meaning and Action
Meaning
: System error. An internal error occurred.
The system issues message IEE390I.
Action
: Contact the IBM Support Center. Provide the return and reason code.
Meaning
: System error. The system encountered a
(VSM) error. The system issues message IEE390I.
Action
: Contact the IBM Support Center. Provide the return and reason code.
Meaning
: Environmental error. The message was not logged in either the system log or the operations log, because neither log is active.
Action
: Do one of the following: v If you want to log the message in the operations log, start the operations log with the VARY
OPERLOG,HARDCPY command and rerun the program.
v If you want the message logged in the system log, start the system log (SYSLOG) with the VARY
SYSLOG,HARDCPY command and rerun the program.
Meaning
: Environmental error. The message was not logged in the system log, as requested, because the
WTL limit has been reached. The operation log was not active at the time, so the message was not logged there either.
Action
: To log the message in the system log, do the following: v Issue a CONTROL M,LOGLIM command to change the allocated number of WTL SYSLOG buffers.
v Change the LOGLIM value on the INIT statement in the CONSOLxx member of SYS1.PARMLIB.
This new value will take effect at the next initialization.
v Retry the request when the storage shortage has been relieved.
If the problem persists, issue the CONTROL
M,LOGLIM command first, and change the LOGLIM value in CONSOLxx at your next IPL.
To log the message in the operations log, start the operations log and rerun the program.
Chapter 117. WTL — Write to log
1163
WTL macro
Return Code
04
04
Reason Code
20
24
Meaning and Action
Meaning
: Environmental error. The message was not logged in the operations log, as requested, because of storage problems. The system log was not active.
Action
: To log the message in the operations log, retry the request. If the problem persists, contact the
IBM Support Center, providing the return and reason codes.
To log the message in the system log also, start the system log and rerun the program.
Meaning
: Environmental error. The message was not logged in the system log because the WTL limit has been reached, and was not logged in the operation log because of storage problems.
Action
: To log the message in the operations log, retry the request. If the problem persists, contact the
IBM Support Center, providing the return and reason codes.
Example 1
Write a message to the system log.
WTL ’THIS IS THE STANDARD FORMAT FOR THE WTL MACRO’
Example 2
Write a message constructed in the list form of WTL.
WTL MF=(E,(R2))
WTL - List form
The list form of the WTL macro is used to construct a control program parameter list. The message parameter must be provided in the list form of the macro.
Syntax
Syntax
The list form of the WTL macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede WTL.
WTL
�
‘msg’
One or more blanks must follow WTL.
msg: Up to 126 characters.
1164
z/OS MVS Assembler Services Reference IAR-XCT
WTL macro
Syntax
,MF=L
Description
Parameters
The parameters are explained under the standard form of the WTL macro with the following exception:
,MF=L
Specifies the list form of the WTL macro.
WTL - Execute form
The execute form of the WTL macro uses a remote control program parameter list.
The parameter list can be generated by the list form of WTL. You cannot modify the message in the execute form.
Syntax
Syntax
The execute form of the WTL macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede WTL.
WTL
�
MF=(E,list addr)
One or more blanks must follow WTL.
list addr: RX-type address, or register (1) or (2) - (12).
Parameters
The parameters are explained under the standard form of the WTL macro with the following exception:
MF=(E,list addr)
Specifies the execute form of the WTL macro.
list addr specifies the area that the system uses to store the parameters.
Chapter 117. WTL — Write to log
1165
WTL macro
1166
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 118. WTO- Write to operator
Description
The WTO macro allows you to write messages to one or more operator consoles.
See z/OS MVS Programming: Assembler Services Guide for more information on using
WTO.
Environment
Requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key.
Task
PASN=HASN=SASN
24- or 31- or 64-bit
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space.
Programming requirements
Be aware of the following when coding the WTO macro: v
MCSFLAG=REG0 is not supported on z/OS V1R7 and higher.
v You should clear register zero.
v If the list and execute forms of the WTO macro are in separate modules, both modules must be assembled or compiled with the same level of WTO.
v If the execute form of the macro specifies TEXT=(text addr), CART, KEY, TOKEN,
CONSID, or CONSNAME, then the list form, to ensure that the parameter list is generated correctly, must specify the same parameters without data. For example:
WTO ’USR001I FOR SPECIAL REQUESTS CONTACT SYSTEM SUPPORT’,CONSID=,MF=L
If you specify parameter values on the list form, the system issues an MNOTE and ignores the data.
v
For any WTO parameters that allow a register specification, the value must be right-justified in the register.
v If you specify the TEXT keyword for a multi-line WTO, you must code its parameters in the following way:
– On the list form, omit text addr for each line, but include line type. If you specify text addr, the system ignores the data and issues an MNOTE.
– On the execute form, omit line type for each line, but include text addr.
v When using any parameter with an address, the data being referenced must be accessible by the caller issuing the WTO.
v As of z/OS 1.4.2, to prevent parameter lists that are not valid from causing system errors, the WTO service records the errors as symptom records in
LOGREC. One example of an invalid parameter list is an invalid combination of
WTO parameters. The system may also issue a D23 abend for diagnostic purposes only; the program issuing the WTO will not be abended. Message processing will continue as far as possible using the invalid parameter list.
© Copyright IBM Corp. 1988, 2017
1167
WTO macro
Due to these invalid parameter list errors, you may notice that some messages that once were processed are no longer able to be processed; your program may also receive different return codes. However, in these cases, the symptom record will always be issued, and the diagnostic D23 abend will be issued if possible.
IBM recommends that you correct all WTO errors, regardless of whether or not the message is actually displayed. For an example LOGREC symptom record,
If a dump is needed along with the diagnostic D23 abend to debug the problem, the following SLIP can be set to cause dumps to be taken:
SLIP SET,ENABLE,COMP=D23,ACTION=SVCD,END
Restrictions
v You can issue a WTO of up to 10 lines. A WTO over 10 lines produces a return code of 04. The return code indicates that only 10 lines will be processed and the rest are ignored.
v The caller cannot have an EUT FRR established.
Input register information
Before issuing the WTO macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter or using it as a base register.
Output register information
When control returns to the caller, the output registers contain the following values:
Register
Contents
0
Used as a work register by the system unless WTO returns code X'20' in register 15. In that case, register 0 contains the number of active WTO buffers for the issuer's address space.
1
2-13
14
15
Message identification number if the WTO macro completed normally (you can use this number to delete the message when it is no longer needed); otherwise, used as a work register by the system.
Unchanged.
Used as a work register by the system.
Return code.
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
1168
z/OS MVS Assembler Services Reference IAR-XCT
WTO macro
⌂
Syntax
name
Performance implications
None.
Syntax
The standard form of the WTO macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede WTO.
WTO
⌂
‘msg’
(‘text’)
(‘text’,line type)
TEXT=text addr
TEXT=(text addr,line type)
TEXT=((text addr,line type),...(text
addr,line type))
One or more blanks must follow WTO.
msg: Up to 126 characters.
text: Up to 126 characters.
text addr: RX-type address or register (2) - (12).
Note:
If you code ‘msg’ or (‘text’...), it must be the first positional parameter.
The permissible line types, text lengths, and maximum numbers of each line type are shown below:
L
D line type
C
DE
E text
34 char
70 char
70 char
70 char or
None maximum number
1 C type
2 L type
10 D type
1 DE type
1 E type
,ROUTCDE=(routing code)
,MCSFLAG=(flag name)
,DESC=(descriptor code)
The maximum total number of lines that can be coded in one instruction is
10.
routing code: Decimal digit from 1 to 28. The routing code is one or more codes, separated by commas, or a hyphen to indicate a range.
flag name: Any combination of the following, separated by commas:
CMD
HRDCPY
RESP
REPLY
NOTIME
BRDCST
descriptor code: Decimal number from 1 to 13. The descriptor code is one or more codes, separated by commas.
Chapter 118. WTO- Write to operator
1169
WTO macro
Syntax
,CART=cmd/resp token
,KEY=key
,TOKEN=token
,CONSID=console id
,CONSNAME=console
name
Description
cmd/resp token: RX-type address or register (2) - (12).
key: RX-type address or register (2) - (12).
token: RX-type address or register (2) - (12).
console id: RX-type address or register (2) - (12).
console name: RX-type address or register (2) - (12).
Parameters
The parameters are explained as follows:
‘msg’
(‘text’)
(‘text’,line type)
TEXT=(text addr)
TEXT=(text addr,line type)
TEXT=((text addr,line type),...(text addr,line type))
Specifies the message or multiple-line message to be written to one or more operator consoles.
The parameter 'msg' is used to write a single-line message to the operator. In the format, the message must be enclosed in apostrophes, which do not appear on the console. To have apostrophes appear in the message text, use two apostrophes to get one to appear. For example, ''Message Off'' would appear on a display as 'Message Off'. The message text can include any character that can be used in a character (C-type) DC instruction. When a program issues a
WTO macro, the system translates the text; only standard printable EBCDIC characters are passed to MCS-managed display devices. The EBCDIC characters that can be displayed are listed in z/OS MVS Programming: Assembler
Services Guide. All other characters are replaced by blanks. Unless the console has dual-case capability, lowercase characters are displayed or printed as uppercase characters.
The message is assembled as a variable-length record. The parameters
TEXT=(text addr) and TEXT=(text addr,line type) represent a 4-byte address of a message to be displayed. The message consists of a 2-byte message length followed by the message text. The 2-byte message length describes the length of the message text only. There are no boundary requirements.
The parameters ('text') and (text addr,line type) are used to write a multiple-line message to the operator. The text is one line of the multiple-line message.
Inline text consists of a character string enclosed in apostrophes (which do not appear on the operator console). Any character valid in a C-type DC instruction can be coded. The maximum number of characters depends on which line type is specified. The message can be up to ten lines long; the system truncates the message at the end of the tenth line. The ten-line limit does not include the control line (message IEE9321I), as explained under line type C below.
1170
z/OS MVS Assembler Services Reference IAR-XCT
WTO macro
Note:
1.
If the parameter (‘text’) is coded without repetition, for example, (‘text’), the message appears as a single-line message.
2.
All lines of a multiple-line WTO must be consistently specified with the message text or the TEXT keyword. When coding the TEXT keyword for a multiple-line message: v You can specify a maximum of 10 lines.
v Do not exceed the 70-character limit for the macro parameter value.
3.
For a multiple-line message, you must clear the three high-order bytes of register 0.
The line type defines the type of information contained in the “text” field of each line of the message:
C
Indicates that the “text” parameter is the text to be contained in the control line of the message. The control line normally contains a message title. C may only be coded for the first line of a multiple-line message. If this parameter is omitted and descriptor code 9 is coded, the system generates a control line (message IEE932I) containing only a message identification number. The control line remains static while you scroll through all the lines of a multiple-line message displayed on an MCS console (provided that the message is displayed in an out-of-line display area). Control lines are optional.
L
Indicates that the “text” parameter is a label line. Label lines contain message heading information; they remain static while you scroll through all the lines of a multiple-line message displayed on an MCS console (provided that the message is displayed in an out-of-line display area). Label lines are optional. If coded, lines must either immediately follow the control line, or another label line or be the first line of the multiple-line message if there is no control line. Only two label lines may be coded per message.
D
DE
Indicates that the “text” parameter contains the information to be conveyed to the operator by the multiple-line message. While you scroll through all lines of a multiple-line message displayed on an MCS console, the data lines are paged.
Indicates that the “text” parameter contains the last line of information to be passed to the operator. Specify DE on the last line of text of the
WTO. If there is no text on the last line, specify E.
E
Indicates that the previous line of text was the last line of text to be passed to the operator. The “text” parameter, if any, coded with a line type of E is ignored. If the last line has text, specify DE.
,ROUTCDE=(routing code)
Specifies the routing code or codes to be assigned to the message.
The routing codes are:
The routing codes are:
Code Meaning
1 Operator Action
The message indicates a change in the system status. It demands action by the operator at the console with master authority.
2 Operator Information
Chapter 118. WTO- Write to operator
1171
WTO macro
3
4
5
6
7
8
9
10
The message indicates a change in system status. It does not demand action; rather, it alerts the operator at the console with master authority to a condition that might require action.
This routing code is used for any message that indicates job status when the status is not requested specifically by an operator inquiry. It is also used to route processor and problem program messages to the system operator.
Tape Pool
The message gives information about tape devices, such as the status of a tape unit or reel, the disposition of a tape reel, or a request to mount a tape.
Direct Access Pool
The message gives information about direct access storage devices
(DASD), such as the status of a direct access unit or volume, the disposition of a volume, or a request to mount a volume.
Tape Library
The message gives tape library information, such as a request by volume serial numbers for tapes for system or problem program use.
Disk Library
The message gives disk library information, such as a request by volume serial numbers for volumes for system or problem program use.
Unit Record Pool
The message gives information about unit record equipment, such as a request to mount a printer train.
Teleprocessing Control
The message gives the status or disposition of teleprocessing equipment, such as a message that describes line errors.
System Security
The message gives information about security checking, such as a request for a password.
System/Error Maintenance
The message gives problem information for the system programmer, such as a system error, an uncorrectable I/O error, or information about system maintenance.
11 Programmer Information
This is commonly referred to as write to programmer (WTP). The message is intended for the problem programmer. This routing code is used when the program issuing the message cannot route the message to the programmer through a system output (SYSOUT) data set. The message appears in the JESYSMSG data set.
12 Emulation
The message gives information about emulation. (These message identifiers are not included in this publication.)
13-20
For customer use only.
1172
z/OS MVS Assembler Services Reference IAR-XCT
WTO macro
21-28
For subsystem use only.
29
Disaster recovery.
30-40
For IBM use only.
41
The message gives information about JES3 job status.
42
The message gives general information about JES2 or JES3.
43-64
For JES use only.
65-96
Messages associated with particular processors.
97-128
Messages associated with particular devices.
If you omit the ROUTCDE, DESC, and CONSID or CONSNAME parameters, the system uses the routing code specified on the ROUTCODE parameter on the DEFAULT statement in the CONSOLxx member of SYS1.PARMLIB.
Note:
Routing codes 1, 2, 3, 4, 7, 8, and 10 cause hard copy of the message when display consoles are used, or more than one console is active. All other routing codes may go to hard copy as a PARMLIB option or as a result of a
VARY HARDCPY command.
,MCSFLAG=(flag name)
Specifies one or more flag names whose meanings are shown below:
Table 65. MCSFLAG Flag Names for WTO Macro
Flag Name
RESP
REPLY
BRDCST
HRDCPY
NOTIME
CMD
Meaning
The WTO is an immediate command response.
This WTO is a reply to a WTOR.
Broadcast the message to all active consoles.
Queue the message for hard copy only.
Do not append time to the message.
The WTO is a recording of a system command issued for hardcopy log purposes.
,DESC=(descriptor code)
Specifies the message descriptor code or codes to be assigned to the message.
Descriptor codes 1 through 6, 11 and descriptor code 12 are mutually exclusive.
Codes 7 through 10, and 13, can be assigned in combination with any other code.
The descriptor codes are:
Code Meaning
1
2
System Failure
The message indicates an error that disrupts system operations. To continue, the operator must reIPL the system or restart a major subsystem. This causes the audible alarm to be issued.
Immediate Action Required
The message indicates that the operator must perform an action immediately. The message issuer could be in a wait state until the action is performed or the system needs the action as soon as possible to improve performance. The task waits for the operator to complete the action. This causes the audible alarm to be issued.
Chapter 118. WTO- Write to operator
1173
WTO macro
3
4
5
6
7
8
9
10
11
Note:
When an authorized program issues a message with descriptor code 2, a DOM macro must be issued to delete the message after the requested action is performed.
Eventual Action Required
The message indicates that the operator must perform an action eventually. The task does not wait for the operator to complete the action.
If the task can determine when the operator has performed the action, the task should issue a DOM macro to delete the message when the action is complete.
System Status
The message indicates the status of a system task or of a hardware unit.
Immediate Command Response
The message is issued as an immediate response to a system command. The response does not depend on another system action or task.
Job Status
The message indicates the status of a job or job step.
Task-Related
The message is issued by an application or system program. Messages with this descriptor code are deleted when the job step that issued them ends.
Out-of-Line
The message, which is one line of a group of one or more lines, is to be displayed out-of-line. If a message cannot be displayed out-of-line because of the device being used, descriptor code 8 is ignored, and the message is displayed in-line with the other messages.
Note:
Both descriptor codes 8 and 9 must be specified to cause a message to be displayed out-of-line.
Operator's Request
The message is written in response to an operator's request for information by a DEVSERV, DISPLAY, TRACK, or MONITOR command.
Note:
Both descriptor codes 8 and 9 must be specified to cause a message to be displayed out-of-line.
Not defined
Descriptor code 10 is not currently in use.
Critical Eventual Action Required
The message indicates that the operator must perform an action eventually, and the action is important enough for the message to remain on the display screen until the action is completed. The task does not wait for the operator to complete the action. This causes the audible alarm to be issued.
1174
z/OS MVS Assembler Services Reference IAR-XCT
WTO macro
12
13
Avoid using this descriptor code for non-critical messages because the display screen could become filled.
If the task can determine when the operator has performed the action, the task should issue a DOM macro to delete the message when the action is complete.
Important Information
The message contains important information that must be displayed at a console, but does not require any action in response.
Automation Information
Indicates that this message was previously automated.
Action messages may have an * sign or @ sign displayed before the first character of the message. The * sign indicates that the WTO was issued by an authorized program. The @ sign indicates that the WTO was issued by an unauthorized program. These action messages will cause the audible alarm to sound on operator consoles so-equipped.
All WTO messages with descriptor codes of 1, 2, or 11 are action messages that have an @ sign printed before the first character. This indicates a need for operator action.
The system holds messages with descriptor codes 1, 2, 3, or 11 until you delete them. When you no longer need messages with descriptor codes 1, 2, 3, or 11, you should delete those messages using the DOM macro. If messages with descriptor codes 1, 2, 3, or 11 also have descriptor code 7, the system deletes them automatically at job step. The system adds descriptor code 7 to all messages with descriptor code 1 or 2.
On operator consoles that support color, descriptor codes determine the color in which a message should be displayed. The colors used are described in z/OS
MVS System Commands.
The message processing facility (MPF) can suppress messages. For MPF to suppress messages, the hardcopy log must be active. The suppressed messages do not appear on any console; they do appear on the hardcopy log.
,CART=cmd/resp token
Specifies an 8-character input field containing a command and response token to be associated with this message. The command and response token is used to associate user information with a command and its command response. You can supply any value as a command and response token. When you specify this parameter in the list form, code it as CART= with nothing after the equal sign.
,KEY=key
Specifies an input field containing an 8-byte key to be associated with this message. The key must be EBCDIC if used with the MVS DISPLAY R command for retrieval purposes, but it must not be ‘*’. If a register is used, it contains the address of the key. When you specify this parameter in the list form, code it as KEY= with nothing after the equal sign.
,TOKEN=token
Specifies an input field containing a 4-byte token to be associated with this message. This field is used to identify a group of messages that can be deleted by a DOM macro that includes TOKEN. The token must be unique within an address space and can be any value. When you specify this parameter in the list form, code it as TOKEN= with nothing after the equal sign.
Chapter 118. WTO- Write to operator
1175
WTO macro
Note:
When you code the TOKEN parameter using a register, the register must contain the token itself, rather than the address of the token.
,CONSID=console id
Specifies a 4-byte field containing the ID of the console to receive a message. If you specify a 4-byte console ID, or if you specify a console ID for an extended
MCS console, you must use CONSID. To view a list of valid console IDs, issue the DISPLAY CONSOLES command.
Note:
1.
If you code the CONSID parameter using a register, the register must contain the console ID itself, rather than the address of the console ID.
2.
When you code CONSID on the list form of WTO, code it as CONSID= with nothing after the equal sign.
3.
CONSID is mutually exclusive with the CONSNAME parameter.
,CONSNAME=console name
Specifies an 8-byte field containing a 2- through 8-character name, left-justified and padded with blanks, of the console to receive a message. When you specify this parameter in the list form, code it as CONSNAME= with nothing after the equal sign.
This parameter is mutually exclusive with the CONSID parameter. Do not use
CONSNAME to pass a console name, together with register 0 to pass a console
ID, because the results are unpredictable. Be sure to clear the low-order byte of register 0 if you add the CONSNAME parameter to an existing invocation of
WTO.
ABEND codes
WTO might abnormally terminate with abend code X'D23'. See z/OS MVS System
Codes for an explanation and programmer response for this code.
Return and reason codes
When the WTO macro returns control to your program, GPR 15 contains one of the following return codes:
Meaning and Action Hexadecimal
Return Code
00
02
Meaning
: Processing completed successfully.
Action
: None.
Meaning
: Processing was not completely successful. This could be due to inconsistent parameters given to WTO, or it could be an environmental problem.
Action
: A D23 abend has been issued for diagnostic purposes only. No dump has been taken; if a dump is needed, you must set a SLIP trap.
Correct any inconsistencies in the WTO invocation.
1176
z/OS MVS Assembler Services Reference IAR-XCT
Hexadecimal
Return Code
04
18
30
WTO macro
Meaning and Action
Meaning
: Program error. The length of text for a message line was not correct.
Action
: v Make sure your text is properly referenced. If you are using the
TEXT parameter, make sure it is pointing to valid data.
v Make sure your message text is defined correctly. If you are using the
TEXT parameter, make sure the first two bytes of data in the area pointed to by the TEXT parameter value contain the length of the message text.
In all cases, correct the problem and retry the request.
Meaning
: Program error. The WPL was invalid and a symptom record was written to LOGREC to describe the error. The message was not processed.
Action
: Correct the WPL.
Meaning
: Environmental error. For routing code 11, the required resource was not available and the request was ignored. For any other routing code, the request was processed.
Action
: Retry the request when the resource you need is available.
Example 1
Issue a WTO with routing codes 1 and 10, descriptor code 2.
WTO ’USR001I CRITICAL RESOURCE SHORTAGE DETECTED’,
ROUTCDE=(1,10),
DESC=(2)
X
X
Example 2
Issue a WTO using the TEXT parameter. The message is to be sent to a console whose ID is contained in register 5 as a command response. A command and response token is also defined for this message. This example assumes a console ID was stored in field SAVECNID and a cart in SAVECART prior to issuing the WTO.
R0
R4
R5
.
.
LA
L
EQU
EQU
EQU
.
XR
WTO
0
4
5
R4,MYMSG
R5,SAVECNID
R0,R0 CLEAR REGISTER 0
TEXT=(R4),CONSID=(R5),CART=SAVECART,
DESC=(5)
ADDRESS OF MESSAGE AREA
CONSOLE ID
X
.
.
.
MYMSG DC
CATTXT DC
SAVECART DS
SAVECNID DS
AL2(L’CATTXT)
C’USR100I PROCESSING COMPLETE, NO ERRORS.’
CL8
F
Chapter 118. WTO- Write to operator
1177
WTO macro
Example 3
Issue a multiline message using the TEXT parameter. This is an important information message which is not to be sent to the hardcopy log.
R0
.
.
EQU
.
XR
WTO
0
R0,R0 CLEAR REG0 BEFORE MULTILINE
TEXT=((MESSAG1,D),(MESSAG2,D),(MESSAG3,DE)),
DESC=(7,12)
.
.
.
MESSAG1 DC AL2(L’MSG1TXT)
X
MSG1TXT DC C’USR005I ALL JOBS REQUIRING MORE THAN 2 TAPES MUST BE RUNX
ON THIRD SHIFT’
MESSAG2 DC AL2(L’MSG2TXT)
MSG2TXT DC C’JOBS REQUIRING 2 TAPES MAY BE RUN ON SECOND SHIFT’
MESSAG3 DC AL2(L’MSG3TXT)
MSG3TXT DC C’OR ON FIRST SHIFT WITH THE OPERATORS PERMISSION.’
Example 4
To prevent parameter lists that are not valid from causing system errors, the WTO service records the errors as symptom records in LOGREC. Here is a sample symptom record:
THE SYMPTOM RECORD DOES NOT CONTAIN A SECONDARY SYMPTOM STRING.
FREE FORMAT COMPONENT INFORMATION:
KEY = F000
+000
LENGTH = 000024 (0018)
C9D5C3D6 D9D9C5C3 E340E6E3
+010 E5D6C3C1
KEY = F000
E3C9D6D5
LENGTH = 000010 (000A)
D640C9D5 |INCORRECT WTO IN|
|VOCATION |
|AUTHORIZED | +000 C1E4E3C8
KEY = F000
D6D9C9E9 C5C4
LENGTH = 000009 (0009)
+000 C1E2C9C4
KEY = F000
61F0F0F0 F1
LENGTH = 000016 (0010)
|ASID/0001 |
E3C5D95C |JOBNAME/*MASTER*| +000 D1D6C2D5
KEY = F000
C1D4C561 5CD4C1E2
LENGTH = 000025 (0019)
+000
+010
C9D5E5D6
4EF0F0F0
D2C5D961
F0F4C5C4
C9C5C5C3
F2
KEY = F000
+000
LENGTH = 000032 (0020)
C5D5C4D3 C9D5C540 C4C5E3C5
+010 40C2C5C6
KEY = F000
D6D9C540 E6D7D3D3
LENGTH = 000017 (0011)
+000
+010
C3E4D9D9
F2
C5D5E340 D3C9D5C5
C2F9F9F9
C3E3C5C4
C9D5C5E2
61F0F0F0
|INVOKER/IEECB999|
|+00004ED2 |
|ENDLINE DETECTED|
| BEFORE WPLLINES|
|CURRENT LINE/000|
|2 |
KEY = F000
+000 E6D7D3
LENGTH = 000003 (0003)
KEY = FF00
+000
+010
+020
+030
+040
+050
LENGTH = 000216 (00D8)
00480050
4040F0F0
F0F0F2F4
F2F540C5
40C5D5C1
00000000
F0F0F2F2
F2F340C5
40C5D5C1
D5C1C2D3
C2D3C5C4
00000000
40C5D5C1
D5C1C2D3
C2D3C5C4
C5C44040
0400007C
000004D2
C2D3C5C4
C5C44040
4040F0F0
F0F0F2F6
10000000
00000000
+060 LENGTH(0048) ==> ALL BYTES CONTAIN X’00’.
+090 00000000 40404040 40404040 00000000
+0A0 LENGTH(0032) ==> ALL BYTES CONTAIN X’00’.
+0C0
+0D0
00000000
40C5D5C1
2000C103
C2D3C5C4
00103000 F0F0F2F7
KEY = F000
+000
LENGTH = 000010 (000A)
D4C1D1D6 D940E3C5 E7E3
KEY = F000 LENGTH = 000034 (0022)
|WPL
|...&0022 ENABLED|
| 0023 ENABLED
|0024 ENABLED
|25 ENABLED
|
00|
0026|
| ENABLED...@....|
|...........K....|
|....
|
....|
|......A.....0027|
| ENABLED
|MAJOR TEXT
|
|
1178
z/OS MVS Assembler Services Reference IAR-XCT
WTO macro
+000
+010
+020
40C9C5C5
F940C4E4
F2F3F4
F7F3F5C9
D4D4E840
40F1F74B
C4C9E2D7
F2F74BF3
D3C1E840
| IEE000I 17.27.3|
|9 DUMMY DISPLAY |
|234 |
This symptom record indicates that this is a WTO error. It also indicates whether the WTO issuer was authorized. The symptom record also contains the following information: v The ASID, job name, program name, and an offset into the program that issued the WTO. You can use this information to help identify the issuer v A description of the error v The message line number where the error was detected v The text of the first line, if the message is a multi-line WTO
Once you diagnose the reason for the error, correct the WTO invocation to issue the message properly, or contact the owner of the application that is issuing the
WTO to have it corrected.
WTO - List form
Use the list form of the WTO macro together with the execute form of the macro for applications that require reentrant code. The list form of the macro defines an area of storage, which the execute form of the macro uses to store the parameters.
Syntax
Syntax
The list form of the WTO macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede WTO.
WTO
�
‘msg’
(‘text’)
(‘text’,line type)
TEXT=
TEXT=((,line type),(,line
type),...(,line type))
One or more blanks must follow WTO.
msg: Up to 126 characters.
text: Up to 126 characters.
Note:
1.
If you code ‘msg’ or (‘text’...), it must be the first parameter you code.
2.
For a single-line WTO, the parameter value is not required on TEXT for the list form. Code only TEXT=. Then code TEXT=(text addr) on the execute form.
Chapter 118. WTO- Write to operator
1179
WTO macro
Syntax
,ROUTCDE=(routing code)
,MCSFLAG=(flag name)
,DESC=(descriptor code)
,CART=
,KEY=
,TOKEN=
,CONSID=
,CONSNAME=
Description
The permissible line types, text lengths, and maximum numbers of each line type are shown below:
L
D line type
C
DE
E text
34 char
70 char
70 char
70 char or
None maximum number
1 C type
2 L type
10 D type
1 DE type
1 E type
The maximum total number of lines that can be coded in one instruction is
10.
routing code: Decimal digit from 1 to 28. The routing code is one or more codes, separated by commas, or a hyphen to indicate a range.
flag name: Any combination of the following, separated by commas:
CMD
HRDCPY
RESP
REPLY
NOTIME
BRDCST
descriptor code: Decimal digit from 1 to 13. The descriptor code is one or more codes, separated by commas.
Parameter value not required for list form. Code only CART=.
If you code CART on the list form of WTO, you must code CART on the execute form.
Parameter value not required for list form. Code only KEY=.
If you code KEY on the list form of WTO, you must code KEY on the execute form.
Parameter value not required for list form. Code only TOKEN=.
If you code TOKEN on the list form of WTO, you must code
TOKEN on the execute form.
Parameter value not required for list form. Code only CONSID= or CONSNAME=.
If you code CONSID (or CONSNAME) on the list form of WTO, you must code CONSID (or CONSNAME) on the execute form.
,MF=L
1180
z/OS MVS Assembler Services Reference IAR-XCT
WTO macro
Parameters
The parameters are explained under the standard form of the WTO macro, with the following exception:
,MF=L
Specifies the list form of the WTO macro.
Example
Set up the list form of a WTO, and send an immediate action message to the master console.
MYLIST WTO ’USR001I CRITICAL RESOURCE SHORTAGE DETECTED’,
ROUTCDE=(1,10),
DESC=(2),CONSID=,MF=L
X
X
WTO - Execute form
Use the execute form of the WTO macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
The message cannot be modified on the execute form of the macro if you code inline text (‘msg’ or (‘text’...)) on the list form.
Syntax
Syntax
The execute form of the WTO macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede WTO.
WTO
�
TEXT=(text addr)
TEXT=((text addr,),(text
addr,),...(text addr,))
,CART=cmd/resp token
,KEY=key
One or more blanks must follow WTO.
text addr: RX-type address or register (2) - (12).
Note:
1.
If you code TEXT=(text addr) on the execute form of WTO, you must code TEXT= on the list form.
2.
If you specify inline text on the list form (‘msg’ or (‘text’...)), do not code the TEXT keyword on the execute form.
cmd/resp token: RX-type address or register (2) - (12).
If you code CART on the execute form of WTO, you must code
CART on the list form.
key: RX-type address or register (2) - (12).
If you code KEY on the execute form of WTO, you must code KEY on the list form.
Chapter 118. WTO- Write to operator
1181
WTO macro
Syntax
,TOKEN=token
,CONSID=console id
,CONSNAME=console name
,MF=(E,list addr)
Description
token: RX-type address or register (2) - (12).
If you code TOKEN on the execute form of WTO, you must code TOKEN on the list form.
console id: RX-type address or register (2) - (12).
console name: RX-type address or register (2) - (12). If you code CONSID (or
CONSNAME) on the execute form of WTO, you must code CONSID (or
CONSNAME) on the list form.
list addr: RX-type address, or register (1) - (12).
Parameters
The parameters are explained under the standard form of the WTO macro, with the following exception:
,MF=(E,list addr)
Specifies the execute form of the WTO macro.
list addr specifies the area that the system uses to store the parameters.
Example 1
Write a message with a prebuilt parameter list pointed to by register 1.
WTO MF=(E,(1))
Example 2
Issue a WTO whose list form is defined at label MYLIST, and is pointed to by register 2. Send the WTO to the console with an ID of 1, pointed to by register 4.
R2
R4
.
.
EQU 2
EQU 4
.
.
.
LA
L
R2,MYLIST
R4,MYCONID
WTO MF=(E,(R2)),CONSID=R4
.
MYCONID DC F’1’
ADDRESS OF PARAMETER LIST
CONSOLE ID
1182
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 119. WTOR - Write to operator with reply
Description
The WTOR macro causes a message requiring a reply to be written to one or more operator consoles and the hardcopy log. The macro also provides the information required by the system to return the reply to the issuing program. See z/OS MVS
Programming: Assembler Services Guide for more information on using the WTOR macro.
For information about how to select the macro for an MVS/SP version other than
the current version, see “Compatibility of MVS macros” on page 1.
Environment
Requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
24- or 31- or 64-bit
Primary
Enabled for I/O and external interrupts
No locks held
Must be in the primary address space
Programming requirements
Be aware of the following when coding the WTOR macro: v MCSFLAG=REG0 is not supported on z/OS V1R7 and higher.
v If the list and execute forms of the WTOR macro are in separate modules, both modules must be assembled or compiled with the same level of WTOR.
v IBM recommends that you begin the parameter list for WTOR on a fullword boundary.
v
If the execute form of the macro specifies RPLYISUR, CART, CONSID,
CONSNAME, KEY, or TOKEN, the list form, to ensure that the parameter list is generated correctly, must specify the same parameters without data. If you specify parameter values on the list form, the system issues an MNOTE and ignores the data.
v For any WTOR parameters that allow a register specification, the value must be right-justified in the register.
v As of z/OS 1.4.2, to prevent parameter lists that are not valid from causing system errors, the WTOR service records the errors as symptom records in
LOGREC. One example of an invalid parameter list is an invalid combination of
WTOR parameters. The system may also issue a D23 abend for diagnostic purposes only; the program issuing the WTOR will not be abended. Message processing will continue as far as possible using the invalid parameter list.
Due to these invalid parameter list errors, you may notice that some messages that once were processed are no longer able to be processed; your program may also receive different return codes. However, in these cases, the symptom record will always be issued, and the diagnostic D23 abend will be issued if possible.
© Copyright IBM Corp. 1988, 2017
1183
WTOR macro
IBM recommends that you correct all WTOR errors, regardless of whether or not the message is actually displayed. For an example LOGREC symptom record,
see “Example 4” on page 1178 in the WTO description.
If a dump is needed along with the diagnostic D23 abend to debug the problem, the following SLIP can be set to cause dumps to be taken:
SLIP SET,ENABLE,COMP=D23,ACTION=SVCD,END
Restrictions
v The WTOR macro can issue only single-line messages.
v The caller cannot have an EUT FRR established.
Input register information
Before issuing the WTOR macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain:
0
1
Register
Contents
Used as a work register by the system.
Message identification number if the WTOR macro completed normally
(you can use this number to delete the message when it is no longer needed); otherwise, used as a work register by the system.
2-13
14
15
Unchanged.
Used as a work register by the system.
Return code.
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
2-13
Used as work registers by the system
Unchanged
14-15
Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
None.
1184
z/OS MVS Assembler Services Reference IAR-XCT
WTOR macro
�
Syntax
name
Syntax
The standard form of the WTOR macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede WTOR.
WTOR
�
‘msg’,reply addr,reply length,ecb addr
TEXT=(text addr,reply
addr,reply length,ecb addr)
,ROUTCDE=(routing code)
,MCSFLAG=(flag name)
One or more blanks must follow WTOR.
msg: Up to 122 characters.
text addr: RX-type address or register (2) - (12).
reply addr: A-type address, or register (2) - (12).
reply length: Symbol, decimal number, or register (2) - (12).
The minimum length is 1; the maximum length is 119.
ecb addr: A-type address, or register (2) - (12).
routing code: Decimal digit from 1 to 28. The routing code is one or more codes, separated by commas, or a hyphen to indicate a range.
flag name: Any combination of the following, separated by commas:
BRDCST
HRDCPY
RESP
REPLY
NOTIME
,DESC=(descriptor code)
,MSGTYP=(msg type)
,RPLYISUR=reply console
descriptor code: Decimal number 7 or 13. If you code both 7 and 13, separate them with commas.
msg type: Any of the following:
N
SESS,JOBNAMES
Y
SESS,STATUS
SESS
JOBNAMES,STATUS
JOBNAMES
SESS,JOBNAMES,STATUS
STATUS
Note:
IBM recommends that you do not use MSGTYP=Y. See the MSGTYP
explanation on page “,MSGTYP=(msg type)” on page 1189 for more
information.
reply console: RX-type address or register (2) - (12).
Chapter 119. WTOR - Write to operator with reply
1185
WTOR macro
Syntax
,CART=cmd/resp token
,CONSID=console id
,CONSNAME=console name
,KEY=key
,TOKEN=token
Description
cmd/resp token: RX-type address or register (2) - (12).
console id: RX-type address or register (2) - (12).
console name: RX-type address or register (2) - (12).
key: RX-type address or register (2) - (12).
token: RX-type address or register (2) - (12).
Parameters
The parameters are explained as follows:
‘msg’,reply addr,reply length,ecb addr
TEXT=(text addr,reply addr,reply length,ecb addr)
‘msg’ is used to write the message to the operator. The message must be enclosed in apostrophes, which do not appear on the console. It can include any character that can be used in a character (C-type) DC instruction. When a program issues a WTOR macro, the system translates the text; only standard printable EBCDIC characters are passed to the display devices. All other characters are replaced by blanks. A list of these EBCDIC characters is provided in z/OS MVS Programming: Assembler Services Guide. Unless the console has dual-case capability, lowercase characters are converted to uppercase by the display station or printer and displayed or printed as uppercase characters.
The message is assembled as a variable-length record. text addr contains an address that points to a message to be displayed. The message contains a
2-byte text field length followed by the text. The 2-byte message length describes the length of the message text only. There are no boundary requirements.
Note:
All WTOR messages are action messages. An indicator is printed before the first character of an action message to indicate a need for operator action.
Action messages will cause the audible alarm to sound on operator consoles so-equipped.
reply addr specifies the address in virtual storage of the area into which the system is to place the reply. The reply is left-justified at this address.
reply length specifies the length, in bytes, of the reply message.
ecb addr specifies the address of the event control block (ECB) to be used by the system to indicate the completion of the reply. The value of the ECB data must point to a fullword boundary. The ECB should be zeroed before the WTOR issued. After the system receives the reply, the ECB appears as follows:
Offset
0
Length(bytes)
1
Contents
Completion code
1186
z/OS MVS Assembler Services Reference IAR-XCT
WTOR macro
Note:
Use RPLYISUR to obtain the 4-byte console ID and console name of the console issuing the reply.
,ROUTCDE=(routing code)
Specifies the routing code or codes to be assigned to the message.
The routing codes are:
The routing codes are:
Code Meaning
1 Operator Action
2
The message indicates a change in the system status. It demands action by the operator at the console with master authority.
Operator Information
The message indicates a change in system status. It does not demand action; rather, it alerts the operator at the console with master authority to a condition that might require action.
3
4
This routing code is used for any message that indicates job status when the status is not requested specifically by an operator inquiry. It is also used to route processor and problem program messages to the system operator.
Tape Pool
The message gives information about tape devices, such as the status of a tape unit or reel, the disposition of a tape reel, or a request to mount a tape.
Direct Access Pool
5
6
7
8
9
10
The message gives information about direct access storage devices
(DASD), such as the status of a direct access unit or volume, the disposition of a volume, or a request to mount a volume.
Tape Library
The message gives tape library information, such as a request by volume serial numbers for tapes for system or problem program use.
Disk Library
The message gives disk library information, such as a request by volume serial numbers for volumes for system or problem program use.
Unit Record Pool
The message gives information about unit record equipment, such as a request to mount a printer train.
Teleprocessing Control
The message gives the status or disposition of teleprocessing equipment, such as a message that describes line errors.
System Security
The message gives information about security checking, such as a request for a password.
System/Error Maintenance
Chapter 119. WTOR - Write to operator with reply
1187
WTOR macro
11
The message gives problem information for the system programmer, such as a system error, an uncorrectable I/O error, or information about system maintenance.
Programmer Information
This is commonly referred to as write to programmer (WTP). The message is intended for the problem programmer. This routing code is used when the program issuing the message cannot route the message to the programmer through a system output (SYSOUT) data set. The message appears in the JESYSMSG data set.
Emulation 12
The message gives information about emulation. (These message identifiers are not included in this publication.)
13-20
For customer use only.
21-28
For subsystem use only.
29
Disaster recovery.
30-40
For IBM use only.
41
42
The message gives information about JES3 job status.
The message gives general information about JES2 or JES3.
43-64
For JES use only.
65-96
Messages associated with particular processors.
97-128
Messages associated with particular devices.
If you omit the ROUTCDE, and CONSID or CONSNAME parameters, the system uses the routing code specified on the ROUTCODE parameter on the
DEFAULT statement in the CONSOLxx member of SYS1.PARMLIB.
,MCSFLAG=(flag name)
Specifies one or more flag names whose meanings are shown below:
Table 66. MCSFLAG Flag Names for WTOR Macro
Flag Name
RESP
REPLY
BRDCST
HRDCPY
NOTIME
Meaning
The WTOR is an immediate command response.
This is a reply to a WTOR.
Broadcast the message to all active consoles.
Queue the message for hard copy only.
Do not append time to the message.
,DESC=(descriptor code)
Specifies the message descriptor code or codes to be assigned to the message.
Valid descriptor codes for the WTOR macro are:
7
13
Retain action message for life-of-task
Message previously automated
All WTOR messages are action messages that have an @ sign displayed before the first character. This indicates a need for operator action.
The system adds descriptor code 7 to all WTOR messages. The system holds all WTOR messages until one of the following events occurs:
1188
z/OS MVS Assembler Services Reference IAR-XCT
WTOR macro
v The system deletes the WTOR message when the reply is received.
v
You delete the WTOR message using the DOM macro. You should delete any unanswered WTOR messages that are no longer current.
v The system deletes the WTOR message at task termination.
The message processing facility (MPF) can suppress messages. For MPF to suppress messages, the hardcopy log must be active. The suppressed messages do not appear on any console; they do appear on the hardcopy log.
,MSGTYP=(msg type)
Specifies how the message is to be routed to consoles on which the MONITOR command is active. If you specify anything other than MSGTYP=N, which is the default, your message is routed according to your specification on
MSGTYP, and the ROUTCDE parameter is ignored.
For SESS, JOBNAMES, or STATUS, the message is to be routed to the console that issued the MONITOR SESS, MONITOR JOBNAMES, or MONITOR
STATUS command, respectively. When the message type is identified by the operating system, the message is routed to only those consoles that requested the information.
For Y or N, the message type describes what functions (MONITOR SESS,
MONITOR JOBNAMES, and MONITOR STATUS) are desired. N, or omission of the MSGTYP parameter, indicates that the message is to be routed as specified in the ROUTCDE parameter. Y creates an area in the WTO parameter list in which you can set message type information if you are coding a WTOR without any of the following parameters: v
KEY v TOKEN v CONSID v CONSNAME v TEXT v RPLYISUR v CART v LINKAGE v SYNCH
IBM recommends that you do not use MSGTYP=Y.
,RPLYISUR =reply console
Specifies a 12-byte field where the system will place the 8-byte console name and the 4-byte console ID of the console through which the operator replies to this message. When you specify this keyword in the list form, code it as
RPLYISUR= with nothing after the equal sign.
,CART=cmd/resp token
Specifies an 8-byte field containing a command and response token to be associated with this message. The command and response token is used to associate user information with a command and its command response. When you specify this keyword in the list form, code it as CART= with nothing after the equal sign.
,CONSID=console id
Specifies a 4-byte field containing the ID of the console to receive a message.
To view a list of valid console IDs, issue the DISPLAY CONSOLES command.
Use this ID in place of a console ID in register 0. If you specify a 4-byte console ID, or if you specify a console ID for an extended MCS console, you
Chapter 119. WTOR - Write to operator with reply
1189
WTOR macro
must use CONSID instead of register 0. If you specify a 1-byte console ID, you must right-justify it and pad to the left with zeros.
Note:
1.
If you code the CONSID parameter using a register, the register must contain the console ID itself, rather than the address of the console ID.
2.
When you code CONSID on the list form of WTOR, code it as CONSID= with nothing after the equal sign.
3.
Do not use both CONSID and register 0 to pass a console ID, because the results are unpredictable.
4.
CONSID is mutually exclusive with the CONSNAME parameter.
,CONSNAME=console name
Specifies an 8-byte field containing a 2- through 8- character name, left-justified and padded with blanks, of the console to receive a message. This parameter is mutually exclusive with the CONSID parameter. When you specify this keyword in the list form, code it as CONSNAME= with nothing after the equal sign. Do not use CONSNAME to pass a console name, together with register 0 to pass a console ID, because the results are unpredictable. Be sure to clear the low-order byte of register 0 if you add the CONSNAME parameter to an existing invocation of WTOR.
,KEY=key
Specifies a field containing an 8-byte key to be associated with this message.
The key must be EBCDIC if used with the MVS DISPLAY R command for retrieval purposes, but it must not be ‘*’. The key must be left-justified and padded on the right with blanks. If a register is used, it contains the address of the key. When this keyword is specified in the list form, it must be coded as
KEY= with nothing after the equal sign.
,TOKEN=token
Specifies a field containing a 4-byte token to be associated with this message.
This field is used to identify a group of messages that can be deleted by a
DOM macro that includes TOKEN. The token must be unique within an address space and can be any value. When you specify this keyword on the list form, code it as TOKEN= with nothing after the equal sign.
Note:
When you code the TOKEN parameter using a register, the register must contain the token itself, rather than the address of the token.
ABEND codes
WTOR might abnormally terminate with abend code X'D23'. See z/OS MVS System
Codes for an explanation and programmer response for this code.
Return and reason codes
When the WTOR macro returns control to your program, GPR 15 contains one of the following return codes.
Meaning and Action Hexadecimal
Return Code
00
Meaning
: Processing completed successfully.
Action
: None. Be sure to delete the request by issuing the DOM macro.
1190
z/OS MVS Assembler Services Reference IAR-XCT
Hexadecimal
Return Code
02
04
18
WTOR macro
Meaning and Action
Meaning
: Processing was not completely successful. This could be due to inconsistent parameters given to WTOR, or it could be an environmental problem.
Action
: A D23 abend has been issued for diagnostic purposes only. No dump has been taken; if a dump is needed, you must set a SLIP trap.
Correct any inconsistencies in the WTOR invocation.
Meaning
: Program error. The length of text for a message line was not correct.
Action
: v Make sure your text is properly referenced. If you are using the
TEXT parameter, make sure it is pointing to valid data.
v Make sure your message text is defined correctly. If you are using the
TEXT parameter, make sure the first two bytes of data in the area pointed to by the TEXT parameter value contain the length of the message text.
In all cases, correct the problem and retry the request.
Meaning
: Program error. The WPL was invalid and a symptom record was written to LOGREC to describe the error. The message was not processed.
Action
: Correct the WPL.
Example 1
Issue a WTOR to a console whose ID is in register 4.
.
.
.
WTOR ’USR902A REPLY YES OR NO TO CONTINUE.’,REPLY,L8,REPECB, X
CONSID=(R4),RPLYISUR=CONINFO
R4
L8
EQU 4
EQU 8
REPLY DS
REPECB DS
CONINFO DS
CL8
F
CL12
Example 2
Issue a WTOR with the TEXT parameter. The message is to go to a specific console whose name is in field TOCON.
R4 EQU 4
LENG72 EQU 72
.
.
.
LA R4,CATMSG
WTOR TEXT=(CATMSG,REPAREA,LENG72,IDSECB),
CONSNAME=TOCON,
RPLYISUR=IDSAREA
.
.
.
CATMSG DC
REP99 DC
AL2(L’REP99)
C’USR999A ENTER LIST OF USERIDS.’
X
X
Chapter 119. WTOR - Write to operator with reply
1191
WTOR macro
TOCON DC
REPAREA DS
IDSECB DS
IDSAREA DS
CL8’ALTCON ’
CL72
F
CL12
Example 3
Issue a WTOR using the TEXT parameter with the list and execute forms of the macro. The console ID to which the message is to be queued is assumed to be in field MYCONID. On the TEXT parameter for the execute form, commas mark the positions of reply addr and ecb addr; for the list form, a comma marks the position of reply length.
R12
C50
EQU 12
EQU 50
USING *,R12
.
LENGTH OF REPLY AREA
.
.
WTOR MF=(E,M2,EXTENDED),TEXT=(MESSAGE,,C50,),CONSID=MYCONID, X
RPLYISUR=MYCONAR
.
.
M2
.
DS 0H
WTOR TEXT=(,RAREA,,MYECB),CONSID=,ROUTCDE=(2),RPLYISUR=,MF=L
MYCONID DS F
RAREA
MYECB
DS
DS
MYCONAR DS
MESSAGE DC
MTEXT DC
END
CL50
F
CL12
AL2(L’MTEXT)
C’USR930A REQUEST IS AMBIGUOUS. RESPECIFY DEVICE.’
WTOR - List form
Use the list form of the WTOR macro together with the execute form of the macro for applications that require reentrant code. The list form of the macro defines an area of storage, which the execute form of the macro uses to store the parameters.
Syntax
The message parameter must be provided in the list form.
Syntax
The list form of the WTOR macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede WTOR.
WTOR
�
One or more blanks must follow WTOR.
1192
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
‘msg’,reply addr,reply length,ecb addr
TEXT=(,reply addr,reply
length,ecb addr)
,ROUTCDE=(routing code)
,MCSFLAG=(flag name)
,DESC=(descriptor code)
,RPLYISUR=
,CART=
,CONSID=
,CONSNAME=
,KEY=
,TOKEN=
WTOR macro
Description
msg: Up to 122 characters.
reply addr: A-type address.
reply length: Symbol or decimal number.
The minimum length is 1; the maximum length is 119.
ecb addr: A-type address.
Note:
1.
If you code ‘msg’,reply addr,reply length,ecb addr, it must be the first parameter you code.
2.
If you do not code reply addr on the list form of WTOR, mark its position with a comma, and code reply addr on the execute form. The same is true for reply length and ecb addr.
routing code: Decimal digit from 1 to 28. The routing code is one or more codes, separated by commas, or a hyphen to indicate a range.
flag name: Any combination of the following, separated by commas:
RESP
REPLY
NOTIME
BRDCST
descriptor code: Decimal number 7 or 13. If you code both 7 and 13, separate them with commas.
Parameter value not required for list form. Code only RPLYISUR=.
If you code RPLYISUR on the list form of WTOR, you must code
RPLYISUR on the execute form.
Parameter value not required for list form. Code only CART=.
If you code CART on the list form of WTOR, you must code CART on the execute form.
Parameter value not required for list form. Code only CONSID= or
CONSNAME=.
If you code CONSID (or CONSNAME) on the list form of WTOR, you must code CONSID (or CONSNAME) on the execute form.
Parameter value not required for list form. Code only KEY=.
If you code KEY on the list form of WTOR, you must code KEY on the execute form.
Parameter value not required for list form. Code only TOKEN=.
If you code TOKEN on the list form of WTOR, you must code
TOKEN on the execute form.
,MF=L
Chapter 119. WTOR - Write to operator with reply
1193
WTOR macro
Parameters
The parameters are explained under the standard form of the WTOR macro, with the following exception:
,MF=L
Specifies the list form of the WTOR macro.
WTOR - Execute form
Use the execute form of the WTOR macro together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form.
The message cannot be modified on the execute form of the macro if you code inline text (‘msg’...) on the list form.
Syntax
Syntax
The execute form of the WTOR macro is written as follows:
Description
name
�
name: Symbol. Begin name in column 1.
One or more blanks must precede WTOR.
WTOR
�
,reply addr,reply length,ecb addr
TEXT=(text addr,reply addr,reply
length,ecb addr)
,RPLYISUR=reply console
,CART=cmd/resp token
One or more blanks must follow WTOR.
reply addr: RX-type address, or register (2) - (12).
reply length: Symbol, decimal number, or register 2-12.
The minimum length is 1; the maximum length is 119.
ecb addr: RX-type address, or register (2) - (12).
text addr: RX-type address or register (2) - (12).
Note:
1.
If you code reply addr,reply length,ecb addr, it must be the first parameter you code and must be preceded by a comma.
2.
If you specify inline text on the list form (‘msg’...), do not code the TEXT keyword on the execute form.
3.
If you do not code reply addr on the execute form of WTOR, mark its position with a comma, and code reply addr on the list form. The same is true for reply length and ecb addr.
reply console: RX-type address or register (2) - (12).
If you code RPLYISUR on the execute form of WTOR, you must code RPLYISUR on the list form.
cmd/resp token: RX-type address or register (2) - (12).
If you code CART on the execute form of WTOR, you must code
CART on the list form.
1194
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,CONSID=console id
,CONSNAME=console name
,KEY=key
,TOKEN=token
,MF=(E,list addr)
,MF=(E,list addr,EXTENDED)
WTOR macro
Description
console id: RX-type address or register (2) - (12).
console name: RX-type address or register (2) - (12). If you code CONSID (or
CONSNAME) on the execute form of WTOR, you must code CONSID (or
CONSNAME) on the list form.
key: RX-type address or register (2) - (12).
If you code KEY on the execute form of WTOR, you must code
KEY on the list form.
token: RX-type address or register (2) - (12).
If you code TOKEN on the execute form of WTOR, you must code
TOKEN on the list form.
list addr: RX-type address, or register (1) - (12).
Parameters
The parameters are explained under the standard form of the WTOR macro, with the following exception:
,reply addr,reply length,ecb addr
If you code reply addr,reply length,ecb addr, it must be the first parameter you code and must be preceded by a comma.
,MF=(E,list addr)
,MF=(E,list addr,EXTENDED)
Specifies the execute form of the WTOR macro.
list addr specifies the area that the system uses to store the parameters.
If you specify reply addr, reply length, or ecb addr, on the execute form of WTOR, and any of the following parameters are specified on the list and/or execute form, you must specify EXTENDED for the system to generate the parameter list correctly: v
KEY v TOKEN v CONSID v CONSNAME v TEXT v RPLYISUR v CART v SYNCH v Any value of ROUTCDE higher than 16
Chapter 119. WTOR - Write to operator with reply
1195
WTOR macro
1196
z/OS MVS Assembler Services Reference IAR-XCT
Chapter 120. XCTL and XCTLX - Pass control to a program in another load module
XCTL and XCTLX description
The XCTL macro passes control to a specified entry name in a load module; the entry name must be a member name, an alias in a directory of a partitioned data set, or have been specified in an IDENTIFY macro. The system brings the load module (called the target module) containing the entry name into storage if a usable copy is not already available. Control passes from the program that issues the XCTL or XCTLX (called the XCTL issuer) to the target module; control does not return to the XCTL issuer. Rather, control returns to the program that caused the XCTL issuer to run. The use count for the XCTL issuer's load module is decremented by 1. If the use count becomes zero, the system deletes the XCTLX issuer's module and reassigns that storage.
Descriptions of the XCTL and XCTLX macro in this information are: v The standard form of the XCTL macro, which includes general information about the XCTL and XCTLX macros with specific information about the XCTL macro. The syntax of the XCTL macro and all XCTL parameters are described.
v The standard form of the XCTLX macro, which presents information specific to the XCTLX macro. The topic explains the syntax of the XCTLX macro and the parameters that are valid only on XCTLX.
v The list form of the XCTL and XCTLX macros.
v The execute form of the XCTL and XCTLX macros.
The XCTL or XCTLX issuer can pass data to the target module in register 1 in several ways: v Using XCTL without LSEARCH and PARAM, placing the data directly in register 1. This choice is not available to the caller in AR mode.
v Using the execute form of the macro, placing the address of the data on the MF parameter. For this choice, the issuer might have used the CALL macro to build a user parameter list.
v Using the execute form of XCTL or XCTLX, specifying the location or locations of the data on the PARAM parameter. XCTL or XCTLX builds a list of the addresses (a user parameter list) at the location you specify on the MF parameter.
The data passed to the target module must not reside within the XCTL issuer's module; if the system deletes the XCTL issuer's module, any data in that module is not available. For more help in understanding passing parameters with XCTL and
XCTLX, see “Examples of passing data to the target module” on page 1207.
The target module gets control in the residency mode and addressing mode established by the link-edit. If XCTL=YES was specified on the ESTAE or ESTAEX macro that set up recovery for the XCTL issuer, then the ESTAE-type recovery routine covers the target module also.
The target module must return to the program that caused the XCTL issuer to run.
According to linkage conventions, the target module is responsible for restoring the status of the program that originally caused the XCTL issuer to run. The status
© Copyright IBM Corp. 1988, 2017
1197
XCTL and XCTLX macros
includes the contents of registers 2 through 14, as well as other information that is expected by the program that caused the XCTL issuer to run, such as: v
The program interruption control area (PICA) v The program mask.
The system abnormally terminates the task under either of the following conditions: v The system cannot locate the entry point that is to receive control v The XCTL issuer added entries to the linkage stack, and did not remove those entries prior to issuing the XCTL.
Environment
The requirements for the caller are:
Environmental factor
Minimum authorization
:
Dispatchable unit mode
:
Cross memory mode
:
AMODE
:
ASC mode
:
Interrupt status
:
Locks
:
Control parameters
:
User parameters
:
Requirement
Problem state and any PSW key
Task
PASN=HASN=SASN
24-bit or 31-bit for XCTL; 24- or 31- or 64-bit for XCTLX
Primary or access register
Enabled for I/O and external interrupts
No locks held
Must reside in the primary address space
Must reside in the primary address space
⌂
Syntax
name
Syntax
The standard form of the XCTL macro is written as follows:
Description
name: Symbol. Begin name in column 1.
One or more blanks must precede XCTL.
XCTL
⌂ One or more blanks must follow XCTL.
reg1 and reg2: Decimal digits in the order 2 through 12.
(reg1),
(reg1,reg2),
EP=entry name
EPLOC=entry name addr
DE=list entry addr
,DCB=dcb addr
entry name: Symbol.
entry name addr: A-type address or register (2) - (12).
list entry addr: A-type address, or register (2) - (12).
dcb addr: A-type address, or register (2) - (12).
1198
z/OS MVS Assembler Services Reference IAR-XCT
XCTL and XCTLX macros
Syntax
,LSEARCH=NO
,LSEARCH=YES
Description
Default
: LSEARCH=NO
Parameters
The parameters are explained as follows:
(reg1),
(reg1,reg2),
Specifies the register or range of registers to be restored before the target routine gets control from the save area at the address contained in register 13.
Note that the registers must be specified as decimal numbers; forms like
“(R2,R12)” are not accepted.
EP=entry name
EPLOC=entry name addr
DE=list entry addr
Specifies the entry name, the address of the entry name, or the address of a
62-byte list entry for the entry name that was constructed using the BLDL macro. If EPLOC is coded, the name must be padded to eight bytes, if necessary.
The system ignores the information you specify on the DE parameter if the parameter does one or both of the following: v
Specifies an entry in an authorized library (that is, defined in IEAAPFxx member of parmlib) v Requests access to a program or library that is controlled by the system authorization facility (SAF)
Instead, the system uses the BLDL macro to construct a new list entry containing the DE information.
Note
: When you use the DE parameter with the XCTL macro, DE specifies the address of a list that was created by a BLDL macro. BLDL and XCTL must be issued from the same task; otherwise, the system might terminate the program with an abend code of 106 and a return code of 15. Therefore, do not issue an
ATTACH or a DETACH macro between issuances of the BLDL and the XCTL macros.
,DCB=dcb addr
Specifies the address of the opened data control block for the partitioned data set containing the entry name described above. This parameter must indicate the same DCB used in the BLDL mentioned above. The DCB must not be defined in the XCTL issuer.
If the DCB parameter is omitted or if DCB=0 is specified when the XCTL macro is issued by the job step task, the data sets referred to by either the
STEPLIB or JOBLIB DD statement are first searched for the entry name. If the entry name is not found, the link library is searched.
If the DCB parameter is omitted or if DCB=0 is specified when the XCTL macro is issued by a subtask, the data sets associated with one or more data control blocks referred to by the TASKLIB operand of previous ATTACH macros in the subtasking chain are first searched for the entry point name. If the entry point name is not found, the search is continued as if the XCTL had been issued by the job step task.
Chapter 120. XCTL and XCTLX - Pass control to a program in another load module
1199
XCTL and XCTLX macros
Note:
The DCB must reside in 24-bit addressable storage.
,LSEARCH=NO
,LSEARCH=YES
Specifies whether (YES) or not (NO) you want the search limited to the job pack area and the first library in the normal search sequence.
Note:
When you use LSEARCH on XCTL, the system does not pass the contents of register 1 to the target module, unless you specify MF=(E,(1)) on the execute form.
Return and reason codes
None.
Example
Pass control through the address of the entry name (XCTLEP), and have registers 2 through 12 restored.
XCTL (2,12),EPLOC=XCTLEP
XCTLX - Pass control to a program in another load module
The XCTLX macro performs the same function as XCTL: it causes control to pass to a specified entry name in another load module, the target module. XCTLX is intended for use by programs running in access register (AR) mode. Programs running in primary mode can also use XCTLX.
If your program runs in AR mode, before you issue the XCTLX macro, issue the
SYSSTATE ASCENV=AR macro to tell the XCTLX macro to generate code appropriate for AR mode.
Syntax
Syntax
The XCTLX macro is written as follows:
Description
name
�
XCTLX
�
name: Symbol. Begin name in column 1.
One or more blanks must precede XCTLX.
One or more blanks must follow XCTLX.
reg1 and reg2: Decimal digits in the order 2 through 12.
(reg1),
(reg1,reg2),
EP=entry name
EPLOC=entry name addr
DE=list entry addr
entry name: Symbol.
entry name addr: A-type address or register (2) - (12).
list entry addr: A-type address, or register (2) - (12).
1200
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,DCB=dcb addr
,LSEARCH=NO
,LSEARCH=YES
Description
dcb addr: A-type address, or register (2) - (12).
Default
: LSEARCH=NO
XCTL and XCTLX macros
Parameters
The parameters are described under the syntax of the standard form of the XCTL macro.
XCTL and XCTLX - List form
Two parameter lists are used on XCTL or XCTLX: a control parameter list and an optional user parameter list. The list form uses only the control parameter list. The execute form builds a user parameter list and passes it to the target module.
Syntax
Syntax
The list form of the XCTL or XCTLX macro is written as follows:
Description
name
�
XCTL
XCTLX
�
name: Symbol. Begin name in column 1.
One or more blanks must precede XCTL or XCTLX.
EP=entry name,
EPLOC=entry name addr,
DE=list entry addr,
,DCB=dcb addr,
,LSEARCH=NO,
,LSEARCH=YES,
,SF=L
One or more blanks must follow XCTL or XCTLX.
entry name: Symbol.
entry name addr: A-type addresses.
list entry addr: A-type address.
dcb addr: A-type address.
Default
: LSEARCH=NO
Chapter 120. XCTL and XCTLX - Pass control to a program in another load module
1201
XCTL and XCTLX macros
Parameters
The parameters are explained under the standard form of the XCTL macro, with the following exception:
,SF=L
Specifies the list form of the XCTL or XCTLX macro.
Note:
If you code LSEARCH in either the list or execute form of the macro, you must code it in both.
XCTL - Execute form
Two parameter lists are available in the XCTL macro: a control parameter list and an optional user parameter list. The control parameter list can be either inline or remote (that is, in an area you specifically obtained); the user parameter list must be remote.
Syntax
Syntax
The execute form of the XCTL macro is written as follows:
Description
�
name
name: Symbol. Begin name in column 1.
One or more blanks must precede XCTL.
XCTL
�
(reg1),
(reg1,reg2),
EP=entry name,
EPLOC=entry name addr,
DE=list entry addr,
,DCB=dcb addr,
,PARAM=(parm),
,PARAM=(parm),VL=1,
One or more blanks must follow XCTL.
reg1 and reg2: Decimal digits or RX-type addresses, and in the order 2 through 12.
entry name: Symbol.
entry name addr: RX-type address or register (2) - (12).
list entry addr: RX-type address, or register (2) - (12).
dcb addr: RX-type address, or register (2) - (12).
parm: RX-type address, or register (2) - (12).
parm is one or more addresses, separated by commas. For example,
PARAM=(parm,parm,parm)
Default
: LSEARCH=NO ,LSEARCH=NO,
,LSEARCH=YES,
,MF=(E,user area)
user area: RX-type address, or register (1) or (2) - (12).
1202
z/OS MVS Assembler Services Reference IAR-XCT
Syntax
,SF=(E,ctrl area)
,MF=(E,user area),SF=(E,ctrl
area)
XCTL and XCTLX macros
Description
ctrl area: RX-type address, or register (2) - (12) or (15).
Parameters
The parameters are explained under the standard form of the XCTL macro, with the following exceptions:
PARAM=(parm)
PARAM=(parm),VL=1
Specifies one or more parameters to be passed to the target module. XCTL builds the user parameter list consisting of a fullword address for each parameter in the order specified, placed at the location designated by
MF=(E,user area). When the target module gets control, register 1 contains the address of the location designated by user area.
Use VL=1 if you are passing the target module a variable number of parameters. VL=1 causes the high-order bit of the last address parameter to be set to 1; the target module can check the last bit to find the end of the list.
LSEARCH=NO
LSEARCH=YES
Specifies whether (YES) or not (NO) you want the search limited to the job pack area and to the first library in the normal search sequence.
Note:
1.
Do not use register 1 to pass parameters to the target module unless you use XCTL and omit both LSEARCH and PARAM.
2.
If you code LSEARCH in either the list or execute form of the macro, you must code it in both.
,MF=(E,user area)
,SF=(E,ctrl area)
,MF=(E,user area),SF=(E,ctrl area)
Specifies the execute form of the XCTL macro.
Use MF=(E,user area) to specify the address of data you want the target module to receive in register 1. If you specify PARAM, MF=(E,user area) is required and identifies the remote location where you want XCTL to build the parameter list.
Use SF=(E,ctrl area) to point to a remote control parameter list. If you do not specify SF, XCTL builds the control parameter list inline.
XCTLX - Execute form
Two parameter lists are available in the XCTLX macro: a control parameter list and an optional user parameter list. The control parameter list can be either inline or remote (that is, in an area you specifically obtained); the user parameter list must be remote.
Chapter 120. XCTL and XCTLX - Pass control to a program in another load module
1203
XCTL and XCTLX macros
Syntax
Syntax
The execute form of the XCTLX macro is written as follows:
Description
⌂
name
name: Symbol. Begin name in column 1.
One or more blanks must precede XCTLX.
XCTLX
⌂
(reg1),
(reg1,reg2),
EP=entry name,
EPLOC=entry name addr,
DE=list entry addr,
,DCB=dcb addr,
,PARAM=(parm),
,PARAM=(parm),VL=1,
One or more blanks must follow XCTLX.
reg1 and reg2: Decimal digits or RX-type addresses, and in the order 2 through 12.
entry name: Symbol.
entry name addr: RX-type address or register (2) - (12).
list entry addr: RX-type address, or register (2) - (12).
dcb addr: RX-type address, or register (2) - (12).
parm: RX-type address, or register (2) - (12).
parm is one or more addresses, separated by commas. For example,
PARAM=(parm,parm,parm)
Default
: LSEARCH=NO ,LSEARCH=NO,
,LSEARCH=YES,
,PLIST4=YES
,PLIST4=NO
,PLIST8=YES
,PLIST8=NO
,PLISTARALETS=SYSTEM
,PLISTARALETS=NO
,PLIST8ARALETS=NO
,PLIST8ARALETS=YES
Default
: None.
Default
: None.
Default
: ,PLISTARALETS=SYSTEM
Note
: ,PLISTARALETS is valid only with XCTLX.
Default
: PLIST8ARALETS=NO
Note
: PLIST8ARALETS is valid only with XCTLX.
,MF=(E,user area)
,SF=(E,ctrl area)
user area: RX-type address, or register (1) or (2) - (12).
ctrl area: RX-type address, or register (2) - (12) or (15).
1204
z/OS MVS Assembler Services Reference IAR-XCT
XCTL and XCTLX macros
Syntax
,MF=(E,user area),SF=(E,ctrl
area)
Description
Parameters
The parameters are explained under the standard form of the XCTL macro, with the following exceptions:
PARAM=(parm)
PARAM=(parm),VL=1
Specifies an address or addresses to be passed to the target module. XCTLX expands each address inline to a fullword boundary and builds a parameter list with the addresses in the order specified, placed at the location designated by MF=(E,user area). When the target module receives control, GPR1 contains the address of the location designated by 'user area'. When PARAM is not specified, XCTLX passes GPR1 and AR1 unchanged to the target module.
When an AR mode caller uses either: v a parameter list with 4 bytes per entry without specifying
PLISTARALETS=NO; or v a parameter list with 8 bytes per entry and specifies PLIST8ARALETS=YES,
The addresses passed to the subtask are in the first part of the parameter list and their associated ALETs are in the second part. For a non-AR mode caller, or for an AR mode caller using a parameter list with 4 bytes per entry with
PLISTARALETS=NO, or for an AR mode caller using a parameter list with 8 bytes per entry without PLIST8ARALETS=YES, ALETs are not passed in the parameter list. When ALETs are passed in the parameter list, the ALETs occupy consecutive 4-byte fields, whether the parameter list is 4 or 8 bytes per entry.
See the description of the PLIST4 and PLIST8 keywords below for more information about controlling the bytes-per-entry in the parameter list. See the description of the PLISTARALETS and PLIST8ARALETS keyword below for
When using a 4-bytes-per-entry parameter list, specify VL=1 when you pass a variable number of parameters. VL=1 results in setting the high-order bit of the last address to 1. The 1 in the high-order bit identifies the last address parameter (which is not the last word in the list when the ALETs are also saved). When using an 8-bytes-per-entry parameter list, VL=1 is not valid.
Note:
If you specify only one address for PARAM= and you are not using register notation, you do not need to enter the parentheses.
LSEARCH=NO
LSEARCH=YES
Specifies whether (YES) or not (NO) you want the search limited to the job pack area and to the first library in the normal search sequence.
Note:
If you code LSEARCH in either the list or execute form of the macro, you must code it in both.
,PLIST4=YES
,PLIST4=NO
Chapter 120. XCTL and XCTLX - Pass control to a program in another load module
1205
XCTL and XCTLX macros
,PLIST8=YES
,PLIST8=NO
Defines the size of the parameter list entries for a parameter list to be built by
XCTLX based on the PARAM keyword.
PLIST4 and PLIST8 cannot be specified together. If neither is specified, the default is: v If running AMODE 64, PLIST8=YES v If not running AMODE 64, PLIST4=YES
If running AMODE 64 and PLIST4=YES is specified, the system builds a
4-bytes-per-entry parameter list just as it would if the program were running
AMODE 24 or AMODE 31 and did not specify PLIST4 or PLIST8.
If running AMODE 24 or AMODE 31 and PLIST8 is specified, the system builds an 8-bytes-per-entry parameter list just as it would if the program were running AMODE 64 and did not specify PLIST4 or PLIST8.
,PLISTARALETS=SYSTEM
,PLISTARALETS=NO
If the invoker is in AR mode, indicates whether the parameter list is also to contain the ALETs associated with the addresses. If the invoker is not in AR mode, this parameter is ignored.
,PLISTARALETS=SYSTEM
Indicates to follow the default system rules that for an AR mode invoker: v For AMODE 24/31, the parameter list is also to contain the ALETs.
v For AMODE 64 with PLIST8ARALETS=YES, the parameter list is also to contain the ALETs.
v For other cases, the parameter list is not to contain the ALETs.
,PLISTARALETS=NO
Indicates that the parameter list is not also to contain the ALETs. Do not specify this parameter with PLIST8ARALETS=YES.
,PLIST8ARALETS=NO
,PLIST8ARALETS=YES
If there is to be an 8-byte-per-entry parameter list and the invoker is in AR mode, indicates if the parameter list is also to contain the ALETs associated with the addresses. Otherwise, this parameter is ignored.
,PLIST8ARALETS=NO
Indicates that the 8-byte-per-entry parameter list is to consist of just the
8-byte addresses.
,PLIST8ARALETS=YES
Indicates that the 8-byte-per-entry parameter list is to consist of the following two parts: v All the 8-byte addresses, v All the associated ALETs in consecutive 4-byte fields.
,MF=(E,user area)
,SF=(E,ctrl area)
,MF=(E,user area),SF=(E,ctrl area)
Specifies the execute form of the XCTL macro.
1206
z/OS MVS Assembler Services Reference IAR-XCT
XCTL and XCTLX macros
Use MF=(E,user area) to specify the address of data you want the target module to receive in register 1. If you specify PARAM, MF=(E,user area) is required and identifies the remote location where you want XCTLX to build the parameter list.
Use SF=(E,ctrl area) to point to a remote control parameter list. If you do not specify SF, XCTLX builds the control parameter list inline.
Examples of passing data to the target module
These examples all perform the following function: pass control using the address of the entry name (XCTLEP), have registers 2 through 12 restored, and have the target module receive data in register 1. The control parameter list is inline.
Example 1
An XCTL issuer (not in AR mode) wants to pass a 6-byte token to the target module. The issuer puts the token into register 1 and issues the macro.
XCTL (2,12),EPLOC=XCTLEP
When the target module receives control, register 1 contains the token.
Example 2
An XCTL issuer (not in AR mode) wants to pass data that resides at the location
ADDRDATA.
XCTL (2,12),EPLOC=XCTLEP,MF=(E,ADDRDATA)
When the target module receives control, register 1 contains the address of
ADDRDATA.
Example 3
An XCTLX issuer (in primary or AR mode) wants to pass an address of a parameter list that was built by the CALL macro. The parameter list resides at the location PARM1. Additionally, the issuer wants to limit the search for the target module.
XCTLX (2,12),EPLOC=XCTLEP,LSEARCH=YES,MF=(E,PARM1)
When the target module receives control, register 1 contains the address of PARM1.
Example 4
An XCTLX issuer (in primary or AR mode) wants to pass a parameter list consisting of the addresses of three parameters. The issuer wants XCTLX to build a user parameter list at the address contained in register 3, and then pass this address to the target module. The three parameters are DATA1, DATA2, and
DATA3.
XCTLX (2,12),EPLOC=XCTLEP,PARAM=(DATA1,DATA2,DATA3),MF=(E,(3))
When the target module receives control, register 1 contains the address of the user parameter list that contains the fullword addresses of DATA1, DATA2, and DATA3, in that order.
Chapter 120. XCTL and XCTLX - Pass control to a program in another load module
1207
1208
z/OS MVS Assembler Services Reference IAR-XCT
Appendix. Accessibility
Accessible publications for this product are offered through IBM Knowledge
Center (www.ibm.com/support/knowledgecenter/SSLTBW/welcome).
If you experience difficulty with the accessibility of any z/OS information, send a detailed message to the Contact z/OS web page (www.ibm.com/systems/z/os/ zos/webqs.html) or use the following mailing address.
IBM Corporation
Attention: MHVRCFS Reader Comments
Department H6MA, Building 707
2455 South Road
Poughkeepsie, NY 12601-5400
United States
Accessibility features
Accessibility features help users who have physical disabilities such as restricted mobility or limited vision use software products successfully. The accessibility features in z/OS can help users do the following tasks: v Run assistive technology such as screen readers and screen magnifier software.
v Operate specific or equivalent features by using the keyboard.
v
Customize display attributes such as color, contrast, and font size.
Consult assistive technologies
Assistive technology products such as screen readers function with the user interfaces found in z/OS. Consult the product information for the specific assistive technology product that is used to access z/OS interfaces.
Keyboard navigation of the user interface
You can access z/OS user interfaces with TSO/E or ISPF. The following information describes how to use TSO/E and ISPF, including the use of keyboard shortcuts and function keys (PF keys). Each guide includes the default settings for the PF keys.
v
z/OS TSO/E Primer
v
z/OS TSO/E User's Guide
v
z/OS ISPF User's Guide Vol I
Dotted decimal syntax diagrams
Syntax diagrams are provided in dotted decimal format for users who access IBM
Knowledge Center with a screen reader. In dotted decimal format, each syntax element is written on a separate line. If two or more syntax elements are always present together (or always absent together), they can appear on the same line because they are considered a single compound syntax element.
Each line starts with a dotted decimal number; for example, 3 or 3.1 or 3.1.1. To hear these numbers correctly, make sure that the screen reader is set to read out
© Copyright IBM Corp. 1988, 2017
1209
punctuation. All the syntax elements that have the same dotted decimal number
(for example, all the syntax elements that have the number 3.1) are mutually exclusive alternatives. If you hear the lines 3.1 USERID and 3.1 SYSTEMID, your syntax can include either USERID or SYSTEMID, but not both.
The dotted decimal numbering level denotes the level of nesting. For example, if a syntax element with dotted decimal number 3 is followed by a series of syntax elements with dotted decimal number 3.1, all the syntax elements numbered 3.1
are subordinate to the syntax element numbered 3.
Certain words and symbols are used next to the dotted decimal numbers to add information about the syntax elements. Occasionally, these words and symbols might occur at the beginning of the element itself. For ease of identification, if the word or symbol is a part of the syntax element, it is preceded by the backslash (\) character. The * symbol is placed next to a dotted decimal number to indicate that the syntax element repeats. For example, syntax element *FILE with dotted decimal number 3 is given the format 3 \* FILE. Format 3* FILE indicates that syntax element FILE repeats. Format 3* \* FILE indicates that syntax element * FILE repeats.
Characters such as commas, which are used to separate a string of syntax elements, are shown in the syntax just before the items they separate. These characters can appear on the same line as each item, or on a separate line with the same dotted decimal number as the relevant items. The line can also show another symbol to provide information about the syntax elements. For example, the lines
5.1*, 5.1 LASTRUN, and 5.1 DELETE mean that if you use more than one of the
LASTRUN and DELETE syntax elements, the elements must be separated by a comma.
If no separator is given, assume that you use a blank to separate each syntax element.
If a syntax element is preceded by the % symbol, it indicates a reference that is defined elsewhere. The string that follows the % symbol is the name of a syntax fragment rather than a literal. For example, the line 2.1 %OP1 means that you must refer to separate syntax fragment OP1.
The following symbols are used next to the dotted decimal numbers.
? indicates an optional syntax element
The question mark (?) symbol indicates an optional syntax element. A dotted decimal number followed by the question mark symbol (?) indicates that all the syntax elements with a corresponding dotted decimal number, and any subordinate syntax elements, are optional. If there is only one syntax element with a dotted decimal number, the ? symbol is displayed on the same line as the syntax element, (for example 5? NOTIFY). If there is more than one syntax element with a dotted decimal number, the ? symbol is displayed on a line by itself, followed by the syntax elements that are optional. For example, if you hear the lines 5 ?, 5 NOTIFY, and 5 UPDATE, you know that the syntax elements
NOTIFY and UPDATE are optional. That is, you can choose one or none of them.
The ? symbol is equivalent to a bypass line in a railroad diagram.
! indicates a default syntax element
The exclamation mark (!) symbol indicates a default syntax element. A dotted decimal number followed by the ! symbol and a syntax element indicate that the syntax element is the default option for all syntax elements that share the same dotted decimal number. Only one of the syntax elements that share the dotted decimal number can specify the ! symbol. For example, if you hear the lines 2? FILE, 2.1! (KEEP), and 2.1 (DELETE), you know that (KEEP) is the
1210
z/OS MVS Assembler Services Reference IAR-XCT
default option for the FILE keyword. In the example, if you include the FILE keyword, but do not specify an option, the default option KEEP is applied. A default option also applies to the next higher dotted decimal number. In this example, if the FILE keyword is omitted, the default FILE(KEEP) is used.
However, if you hear the lines 2? FILE, 2.1, 2.1.1! (KEEP), and 2.1.1
(DELETE) , the default option KEEP applies only to the next higher dotted decimal number, 2.1 (which does not have an associated keyword), and does not apply to 2? FILE. Nothing is used if the keyword FILE is omitted.
* indicates an optional syntax element that is repeatable
The asterisk or glyph (*) symbol indicates a syntax element that can be repeated zero or more times. A dotted decimal number followed by the * symbol indicates that this syntax element can be used zero or more times; that is, it is optional and can be repeated. For example, if you hear the line 5.1* data area
, you know that you can include one data area, more than one data area, or no data area. If you hear the lines 3* , 3 HOST, 3 STATE, you know that you can include HOST, STATE, both together, or nothing.
Notes:
1.
If a dotted decimal number has an asterisk (*) next to it and there is only one item with that dotted decimal number, you can repeat that same item more than once.
2.
If a dotted decimal number has an asterisk next to it and several items have that dotted decimal number, you can use more than one item from the list, but you cannot use the items more than once each. In the previous example, you can write HOST STATE, but you cannot write HOST HOST.
3.
The * symbol is equivalent to a loopback line in a railroad syntax diagram.
+ indicates a syntax element that must be included
The plus (+) symbol indicates a syntax element that must be included at least once. A dotted decimal number followed by the + symbol indicates that the syntax element must be included one or more times. That is, it must be included at least once and can be repeated. For example, if you hear the line
6.1+ data area
, you must include at least one data area. If you hear the lines
2+, 2 HOST, and 2 STATE
, you know that you must include HOST, STATE, or both. Similar to the * symbol, the + symbol can repeat a particular item if it is the only item with that dotted decimal number. The + symbol, like the * symbol, is equivalent to a loopback line in a railroad syntax diagram.
Appendix. Accessibility
1211
1212
z/OS MVS Assembler Services Reference IAR-XCT
Notices
This information was developed for products and services that are offered in the
USA or elsewhere.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
United States of America
For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
© Copyright IBM Corp. 1988, 2017
1213
This information could include missing, incorrect, or broken hyperlinks.
Hyperlinks are maintained in only the HTML plug-in output for the Knowledge
Centers. Use of hyperlinks in other output formats of this information is at your own risk.
Any references in this information to non-IBM websites are provided for convenience only and do not in any manner serve as an endorsement of those websites. The materials at those websites are not part of the materials for this IBM product and use of those websites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
IBM Corporation
Site Counsel
2455 South Road
Poughkeepsie, NY 12601-5400
USA
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
1214
z/OS MVS Assembler Services Reference IAR-XCT
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs.
Terms and conditions for product documentation
Permissions for the use of these publications are granted subject to the following terms and conditions.
Applicability
These terms and conditions are in addition to any terms of use for the IBM website.
Personal use
You may reproduce these publications for your personal, noncommercial use provided that all proprietary notices are preserved. You may not distribute, display or make derivative work of these publications, or any portion thereof, without the express consent of IBM.
Commercial use
You may reproduce, distribute and display these publications solely within your enterprise provided that all proprietary notices are preserved. You may not make derivative works of these publications, or reproduce, distribute or display these publications or any portion thereof outside your enterprise, without the express consent of IBM.
Rights
Except as expressly granted in this permission, no other permissions, licenses or rights are granted, either express or implied, to the publications or any information, data, software or other intellectual property contained therein.
IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use of the publications is detrimental to its interest or, as determined by IBM, the above instructions are not being properly followed.
You may not download, export or re-export this information except in full compliance with all applicable laws and regulations, including all United States export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE
PUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" AND WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING
BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY,
Notices
1215
NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
IBM Online Privacy Statement
IBM Software products, including software as a service solutions, (“Software
Offerings”) may use cookies or other technologies to collect product usage information, to help improve the end user experience, to tailor interactions with the end user, or for other purposes. In many cases no personally identifiable information is collected by the Software Offerings. Some of our Software Offerings can help enable you to collect personally identifiable information. If this Software
Offering uses cookies to collect personally identifiable information, specific information about this offering’s use of cookies is set forth below.
Depending upon the configurations deployed, this Software Offering may use session cookies that collect each user’s name, email address, phone number, or other personally identifiable information for purposes of enhanced user usability and single sign-on configuration. These cookies can be disabled, but disabling them will also eliminate the functionality they enable.
If the configurations deployed for this Software Offering provide you as customer the ability to collect personally identifiable information from end users via cookies and other technologies, you should seek your own legal advice about any laws applicable to such data collection, including any requirements for notice and consent.
For more information about the use of various technologies, including cookies, for these purposes, see IBM’s Privacy Policy at ibm.com/privacy and IBM’s Online
Privacy Statement at ibm.com/privacy/details in the section entitled “Cookies,
Web Beacons and Other Technologies,” and the “IBM Software Products and
Software-as-a-Service Privacy Statement” at ibm.com/software/info/productprivacy.
Policy for unsupported hardware
Various z/OS elements, such as DFSMS, JES2, JES3, and MVS, contain code that supports specific hardware servers or devices. In some cases, this device-related element support remains in the product even after the hardware devices pass their announced End of Service date. z/OS may continue to service element code; however, it will not provide service related to unsupported hardware devices.
Software problems related to these devices will not be accepted for service, and current service activity will cease if a problem is determined to be associated with out-of-support devices. In such cases, fixes will not be issued.
Minimum supported hardware
The minimum supported hardware for z/OS releases identified in z/OS announcements can subsequently change when service for particular servers or devices is withdrawn. Likewise, the levels of other software products supported on a particular release of z/OS are subject to the service support lifecycle of those products. Therefore, z/OS and its product publications (for example, panels, samples, messages, and product documentation) can include references to hardware and software that is no longer supported.
v For information about software support lifecycle, see: IBM Lifecycle Support for z/OS (www.ibm.com/software/support/systemsz/lifecycle)
1216
z/OS MVS Assembler Services Reference IAR-XCT
v For information about currently-supported IBM hardware, contact your IBM representative.
Programming interface information
This information is intended to help the customer to code macros that are available to all assembler language programs. This information documents intended programming interfaces that allow the customer to write programs to obtain services of z/OS.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the Web at Copyright and
Trademark information (www.ibm.com/legal/copytrade.shtml).
UNIX is a registered trademark of The Open Group in the United States and other countries.
Notices
1217
1218
z/OS MVS Assembler Services Reference IAR-XCT
Index
Numerics
31-bit addressing mode macros requiring expansion
A
accessibility 1209 contact IBM 1209 features 1209
addressing mode and the services 2
ALET qualification
AMODE (addressing mode) changing
AR () mode
ASC (address space control) mode
B
branch macro
converting to relative branch 125,
C
callable service
central storage
coding the callable services 16
completion of an event
contact
control
passing to another load module 811
D
data sharing with IARVSERV macro 63
device measurement block index
E
ECB (event control block)
© Copyright IBM Corp. 1988, 2017
ETR (external time reference)
event
I
I/O configuration token
IARVSERV macro
incident token
IOS (input/output supervisor)
building control unit entry 445
K
keyboard
PF keys 1209 shortcut keys 1209
L
linkage stack
load module
bringing into virtual storage 823
Logrec Data Set
M
macro
level
X-macros
1219
multiple timer
N
navigation
P
paging service
program object
bringing into virtual storage 823
T
time interval
timer
TOD (time-of-day) clock
checking for synchronization with
Q
R
S
service
services
ASC mode
shared DASD
sharing storage with IARVSERV macro 63
specify program interruption exit 911
subtask
U
UCB (unit control block)
user interface
user parameter
V
virtual storage
bringing in a load module 823 bringing in a program object 823
Virtual storage
sharing with IARVSERV macro 63
VRA (variable recording area)
W
1220
z/OS MVS Assembler Services Reference IAR-XCT
X
X-macros
IBM®
Product Number: 5650-ZOS
Printed in USA
SA23-1370-30
advertisement
Key Features
- Assembler Services
- Addressing Modes
- Macro Versions
- Register Usage
- Error Handling
- Callable Services
- Examples
- Detailed Descriptions
Frequently Answers and Questions
What is the purpose of this manual?
What topics are covered in this manual?
What kind of information is provided for each Assembler Service?
advertisement
Table of contents
- 165 Guarded-Storage Facility services
- 173 incident token
- 177 stack query
- 181 external time reference status
- 185 name/token pair
- 195 token from a name/token pair
- 201 name/token pair
- 211 token from a name/token pair
- 215 dump request
- 235 execution diagnostic controls
- 251 Deallocate_Pause_Element
- 259 multiple elements service
- 273 service
- 279 Chapter 31. IEAVRLS — Release
- 285 Chapter 32. IEAVRLS2 — Release
- 291 service
- 303 Test_Pause_Element service
- 307 service
- 313 service
- 329 Deallocate_Pause_Element
- 337 multiple elements service
- 351 service
- 357 Chapter 45. IEA4RLS — Release
- 451 query a subsystem
- 467 description service
- 475 unit entry build service
- 479 memory information
- 485 resource serialization ENQ service
- 549 external CTRACE recording
- 557 group of CTRACE entries
- 571 trace query
- 577 Browse/read a log stream
- 623 Connect/disconnect to log stream
- 841 module
- 853 module into virtual storage
- 865 storage areas into central storage
- 869 storage
- 873 virtual storage contents
- 883 completion
- 887 translation
- 893 end a reference pattern
- 901 device (shared DASD)
- 913 control
- 917 parameters
- 925 Dump virtual storage and continue
- 941 interruption exit
- 947 level
- 951 abnormal exit
- 957 a subtask
- 963 conversion routine
- 1041 processing program
- 1049 event
- 1051 system state
- 1057 or translate the TTOKEN
- 1063 validity of ALETs
- 1067 and date