z/OS MVS Assembler Services Reference IAR-XCT

IBM z/OS

MVS Programming: Assembler Services

Reference, Volume 2 (IAR-XCT)

Version 2 Release 3

SA23-1370-30

Note

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

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.

.

.

.

.

.

. xxv

How to use this information .

.

.

.

.

.

.

. xxv z/OS information .

.

.

.

.

.

.

.

.

.

.

. xxv

How to send your comments to IBM xxvii

If you have a technical problem.

.

.

.

.

.

. xxvii

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 .

.

.

.

.

. xxix

Summary of changes for z/OS Version 2 Release 2 xxx z/OS Version 2 Release 1 summary of changes .

. xxx

||

Chapter 1. Using the services . . . . . 1

Compatibility of MVS macros.

.

.

.

.

.

.

.

. 1

Addressing mode (AMODE) .

.

.

.

.

.

.

.

. 2

Address space control (ASC) mode .

.

.

.

.

.

. 3

ALET qualification .

.

.

.

.

.

.

.

.

.

. 4

User parameters .

.

.

.

.

.

.

.

.

.

.

. 4

Telling the system about the execution environment 6

Specifying a macro version number.

.

.

.

.

.

. 7

How to request a macro version using PLISTVER 7

Register use .

.

.

.

.

.

.

.

.

.

.

.

.

. 8

Handling return codes and reason codes .

.

.

.

. 9

Handling program errors .

.

.

.

.

.

.

.

. 9

Handling environmental and system errors .

.

. 10

Using X-macros .

.

.

.

.

.

.

.

.

.

.

.

. 11

Macro forms .

.

.

.

.

.

.

.

.

.

.

.

.

. 12

Conventional list form macros .

.

.

.

.

.

. 12

Alternative list form macros .

.

.

.

.

.

.

. 13

Coding the macros .

.

.

.

.

.

.

.

.

.

.

. 13

Continuation lines .

.

.

.

.

.

.

.

.

.

. 16

Coding the callable services .

.

.

.

.

.

.

.

. 16

Including equate (EQU) statements .

.

.

.

. 17

Link-editing linkage-assist routines .

.

.

.

. 17

Service summary .

.

.

.

.

.

.

.

.

.

.

. 18

Chapter 2. IARCP64 — 64-bit cell pool services . . . . . . . . . . . . . . 25

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 25

Environment .

.

.

.

.

.

.

.

.

.

.

.

. 25

Programming requirements .

.

.

.

.

.

.

. 26

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 26

Input register information .

.

.

.

.

.

.

. 26

Output register information .

.

.

.

.

.

.

. 26

Performance implications .

.

.

.

.

.

.

.

. 27

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

.

. 27

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 29

© Copyright IBM Corp. 1988, 2017

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 36

Return and reason codes .

.

.

.

.

.

.

.

. 36

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 38

Chapter 3. IARR2V — Convert a central storage address to a virtual storage address . . . . . . . . . . . . . . 41

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 41

Environment .

.

.

.

.

.

.

.

.

.

.

.

. 41


.

.

.

.

.

.

. 41

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 41


.

.

.

.

.

.

. 41


.

.

.

.

.

.

. 41


.

.

.

.

.

.

.

. 42

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

.

. 42

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 43

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 44


.

.

.

.

.

.

.

. 44

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

.

. 45

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

.

. 46

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

.

. 46

Example 4 .

.

.

.

.

.

.

.

.

.

.

.

.

. 46

Chapter 4. IARST64 — 64-bit storage services . . . . . . . . . . . . . . 47

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 47

Environment .

.

.

.

.

.

.

.

.

.

.

.

. 47


.

.

.

.

.

.

. 48

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 48


.

.

.

.

.

.

. 48


.

.

.

.

.

.

. 48


.

.

.

.

.

.

.

. 49

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

.

. 49

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 51

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 56


.

.

.

.

.

.

.

. 60

Chapter 5. IARVSERV — Request to share virtual storage . . . . . . . . . 63

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 63

Environment .

.

.

.

.

.

.

.

.

.

.

.

. 63


.

.

.

.

.

.

. 63

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 64


.

.

.

.

.

.

. 64


.

.

.

.

.

.

. 64


.

.

.

.

.

.

.

. 64

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

.

. 65

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 66

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 68


.

.

.

.

.

.

.

. 68

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

.

. 71

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

.

. 71

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

.

. 71

Example 4 .

.

.

.

.

.

.

.

.

.

.

.

.

. 71

iii

Example 5 .

.

.

.

.

.

.

.

.

.

.

.

.

. 71

Example 6 .

.

.

.

.

.

.

.

.

.

.

.

.

. 71

IARVSERV—List form .

.

.

.

.

.

.

.

.

.

. 73

IARVSERV - Execute form .

.

.

.

.

.

.

.

. 74

Chapter 6. IARV64 — 64–bit virtual storage allocation . . . . . . . . . . 77

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 77

Abend and abend reason codes.

.

.

.

.

.

. 78


.

.

.

.

.

.

.

. 78

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 79

REQUEST=GETSTOR option of IARV64 .

.

.

.

. 80

Environment .

.

.

.

.

.

.

.

.

.

.

.

. 80


.

.

.

.

.

.

. 80

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 80


.

.

.

.

.

.

. 80


.

.

.

.

.

.

. 80


.

.

.

.

.

.

.

. 81

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

.

. 81

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 83

REQUEST=PAGEOUT option of IARV64 .

.

.

. 89

Environment .

.

.

.

.

.

.

.

.

.

.

.

. 89


.

.

.

.

.

.

. 89

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 89


.

.

.

.

.

.

. 89


.

.

.

.

.

.

. 89


.

.

.

.

.

.

.

. 90

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

.

. 90

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 91

REQUEST=PAGEIN option of IARV64 .

.

.

.

. 93

Environment .

.

.

.

.

.

.

.

.

.

.

.

. 93


.

.

.

.

.

.

. 93

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 93


.

.

.

.

.

.

. 93


.

.

.

.

.

.

. 93


.

.

.

.

.

.

.

. 94

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

.

. 94

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 95

REQUEST=DISCARDDATA option of IARV64 .

.

. 97

Environment .

.

.

.

.

.

.

.

.

.

.

.

. 97


.

.

.

.

.

.

. 97

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 97


.

.

.

.

.

.

. 98


.

.

.

.

.

.

. 98


.

.

.

.

.

.

.

. 98

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

.

. 98

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 99

REQUEST=CHANGEGUARD option of IARV64 102

Environment .

.

.

.

.

.

.

.

.

.

.

. 102

Programming requirements.

.

.

.

.

.

.

. 102

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 102


.

.

.

.

.

.

. 102


.

.

.

.

.

. 103


.

.

.

.

.

.

. 103

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 103

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 104

REQUEST=DETACH option of IARV64.

.

.

.

. 108

Environment .

.

.

.

.

.

.

.

.

.

.

. 108


.

.

.

.

.

.

. 108

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 108


.

.

.

.

.

.

. 108

iv

z/OS MVS Assembler Services Reference IAR-XCT


.

.

.

.

.

. 109


.

.

.

.

.

.

. 109

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 109

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 110

Chapter 7. IDENTIFY — Add an entry name . . . . . . . . . . . . . . . 115

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 115

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

.

. 115

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 116

Return codes .

.

.

.

.

.

.

.

.

.

.

. 116

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 117

Chapter 8. IEAARR — Establish an associated recovery routine (ARR) . . 119

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 119

Environment .

.

.

.

.

.

.

.

.

.

.

. 119


.

.

.

.

.

.

. 119

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 119


.

.

.

.

.

.

. 119


.

.

.

.

.

. 119


.

.

.

.

.

.

. 120

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 120

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 121

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 124

Return codes .

.

.

.

.

.

.

.

.

.

.

. 124

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 124

Chapter 9. IEABRC — Relative branch macro . . . . . . . . . . . . . . 125

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 125

Environment .

.

.

.

.

.

.

.

.

.

.

. 125


.

.

.

.

.

.

. 125

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 125

Register information .

.

.

.

.

.

.

.

.

. 125


.

.

.

.

.

.

. 125

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 125

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 126

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 126

Chapter 10. IEABRCX — Relative branch macro extension. . . . . . . 127

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 127

Environment .

.

.

.

.

.

.

.

.

.

.

. 127


.

.

.

.

.

.

. 127

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 127


.

.

.

.

.

.

.

.

. 127


.

.

.

.

.

.

. 127

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 128

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 128

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 128

Chapter 11. IEAFP — Floating point services. . . . . . . . . . . . . . 131

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 131

Environment .

.

.

.

.

.

.

.

.

.

.

. 131


.

.

.

.

.

.

. 131

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 131


.

.

.

.

.

.

. 131


.

.

.

.

.

. 131


.

.

.

.

.

.

. 132

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 132

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 132

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 133


.

.

.

.

.

.

. 133

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 134

||

|

Chapter 12. IEAGSF —

Guarded-Storage Facility services . . 135

Chapter 13. IEAINTKN — Build incident token . . . . . . . . . . . 143

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 143

Environment .

.

.

.

.

.

.

.

.

.

.

. 143


.

.

.

.

.

.

. 143

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 143


.

.

.

.

.

.

. 143


.

.

.

.

.

. 143


.

.

.

.

.

.

. 144

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 144

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 144

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 144


.

.

.

.

.

.

. 144

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 144

Chapter 14. IEALSQRY — Linkage stack query . . . . . . . . . . . . 147

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 147

Environment .

.

.

.

.

.

.

.

.

.

.

. 147


.

.

.

.

.

.

. 147

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 148


.

.

.

.

.

.

. 148


.

.

.

.

.

. 148


.

.

.

.

.

.

. 148

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 148

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 149

Return codes .

.

.

.

.

.

.

.

.

.

.

. 149

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 150

Chapter 15. IEAMETR — Query external time reference status . . . . 151

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 151

Environment .

.

.

.

.

.

.

.

.

.

.

. 151


.

.

.

.

.

.

. 151

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 151


.

.

.

.

.

.

. 151


.

.

.

.

.

. 151


.

.

.

.

.

.

. 152

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 152

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 152

Return codes .

.

.

.

.

.

.

.

.

.

.

. 153

Chapter 16. IEANTCR — Create a name/token pair . . . . . . . . . . 155

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 155

Environment .

.

.

.

.

.

.

.

.

.

.

. 155


.

.

.

.

.

.

. 155

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 156


.

.

.

.

.

.

. 156


.

.

.

.

.

. 156


.

.

.

.

.

.

. 156

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 156

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 157

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 158


.

.

.

.

.

.

. 158

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 159

Chapter 17. IEANTDL — Delete a name/token pair . . . . . . . . . . 161

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 161

Environment .

.

.

.

.

.

.

.

.

.

.

. 161


.

.

.

.

.

.

. 161

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 162


.

.

.

.

.

.

. 162


.

.

.

.

.

. 162


.

.

.

.

.

.

. 162

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 162

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 163

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 163


.

.

.

.

.

.

. 163

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 164

Chapter 18. IEANTRT — Retrieve the token from a name/token pair . . . . 165

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 165

Environment .

.

.

.

.

.

.

.

.

.

.

. 165


.

.

.

.

.

.

. 165

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 166


.

.

.

.

.

.

. 166


.

.

.

.

.

. 166


.

.

.

.

.

.

. 166

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 166

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 167

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 167


.

.

.

.

.

.

. 167

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 168

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 168

Chapter 19. IEAN4CR — Create a name/token pair . . . . . . . . . . 171

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 171

Environment .

.

.

.

.

.

.

.

.

.

.

. 171


.

.

.

.

.

.

. 171

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 172


.

.

.

.

.

.

. 172


.

.

.

.

.

. 172


.

.

.

.

.

.

. 172

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 172

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 173

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 174


.

.

.

.

.

.

. 174

Chapter 20. IEAN4DL — Delete a name/token pair . . . . . . . . . . 177

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 177

Environment .

.

.

.

.

.

.

.

.

.

.

. 177


.

.

.

.

.

.

. 177

Contents

v

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 178


.

.

.

.

.

.

. 178


.

.

.

.

.

. 178


.

.

.

.

.

.

. 178

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 178

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 179

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 179


.

.

.

.

.

.

. 179

Chapter 21. IEAN4RT — Retrieve the token from a name/token pair . . . . 181

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 181

Environment .

.

.

.

.

.

.

.

.

.

.

. 181


.

.

.

.

.

.

. 181

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 182


.

.

.

.

.

.

. 182


.

.

.

.

.

. 182


.

.

.

.

.

.

. 182

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 182

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 183

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 183


.

.

.

.

.

.

. 183

Chapter 22. IEATDUMP — Transaction dump request . . . . . . . . . . . 185

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 185

Environment .

.

.

.

.

.

.

.

.

.

.

. 185


.

.

.

.

.

.

. 186

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 186


.

.

.

.

.

.

. 186


.

.

.

.

.

. 186


.

.

.

.

.

.

. 186

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 187

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 189

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 196


.

.

.

.

.

.

. 196

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 203

Chapter 23. IEATXDC — Transactional execution diagnostic controls . . . . 205

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 205

Environment .

.

.

.

.

.

.

.

.

.

.

. 205


.

.

.

.

.

.

. 205

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 205


.

.

.

.

.

.

. 205


.

.

.

.

.

. 205


.

.

.

.

.

.

. 206

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 206

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 206

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 207

Return codes .

.

.

.

.

.

.

.

.

.

.

. 207

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 208

Chapter 24. IEAVAPE —

Allocate_Pause_Element . . . . . . 209

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 209

Environment .

.

.

.

.

.

.

.

.

.

.

. 209


.

.

.

.

.

.

. 209

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 209

vi



.

.

.

.

.

.

. 209


.

.

.

.

.

. 210


.

.

.

.

.

.

. 210

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 210

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 210

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 211

Return codes .

.

.

.

.

.

.

.

.

.

.

. 211

Chapter 25. IEAVAPE2 —


Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 213

Environment .

.

.

.

.

.

.

.

.

.

.

. 213


.

.

.

.

.

.

. 213

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 213


.

.

.

.

.

.

. 214


.

.

.

.

.

. 214


.

.

.

.

.

.

. 214

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 214

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 214

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 218

Return codes .

.

.

.

.

.

.

.

.

.

.

. 218

Chapter 26. IEAVDPE —

Deallocate_Pause_Element . . . . . 221

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 221

Environment .

.

.

.

.

.

.

.

.

.

.

. 221


.

.

.

.

.

.

. 221

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 221


.

.

.

.

.

.

. 221


.

.

.

.

.

. 221


.

.

.

.

.

.

. 222

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 222

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 222

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 223

Return codes .

.

.

.

.

.

.

.

.

.

.

. 223

Chapter 27. IEAVDPE2 —


Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 225

Environment .

.

.

.

.

.

.

.

.

.

.

. 225


.

.

.

.

.

.

. 225

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 225


.

.

.

.

.

.

. 225


.

.

.

.

.

. 225


.

.

.

.

.

.

. 226

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 226

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 226

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 227

Return codes .

.

.

.

.

.

.

.

.

.

.

. 227

Chapter 28. IEAVPME2 — pause multiple elements service . . . . . . 229

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 229

Environment .

.

.

.

.

.

.

.

.

.

.

. 229


.

.

.

.

.

.

. 229

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 229


.

.

.

.

.

.

. 230


.

.

.

.

.

. 230


.

.

.

.

.

.

. 230

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 231

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 231

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 233

Return codes .

.

.

.

.

.

.

.

.

.

.

. 233

Chapter 29. IEAVPSE — Pause service 237

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 237

Environment .

.

.

.

.

.

.

.

.

.

.

. 237


.

.

.

.

.

.

. 237

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 237


.

.

.

.

.

.

. 237


.

.

.

.

.

. 238


.

.

.

.

.

.

. 238

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 238

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 238

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 239

Return codes .

.

.

.

.

.

.

.

.

.

.

. 240

Chapter 30. IEAVPSE2 — Pause service . . . . . . . . . . . . . . 243

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 243

Environment .

.

.

.

.

.

.

.

.

.

.

. 243


.

.

.

.

.

.

. 243

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 243


.

.

.

.

.

.

. 244


.

.

.

.

.

. 244


.

.

.

.

.

.

. 244

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 244

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 244

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 246

Return codes .

.

.

.

.

.

.

.

.

.

.

. 246

Chapter 31. IEAVRLS — Release . . . 249

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 249

Environment .

.

.

.

.

.

.

.

.

.

.

. 249


.

.

.

.

.

.

. 249

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 249


.

.

.

.

.

.

. 249


.

.

.

.

.

. 250


.

.

.

.

.

.

. 250

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 250

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 250

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 251

Return codes .

.

.

.

.

.

.

.

.

.

.

. 251

Chapter 32. IEAVRLS2 — Release. . . 255

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 255

Environment .

.

.

.

.

.

.

.

.

.

.

. 255


.

.

.

.

.

.

. 255

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 255


.

.

.

.

.

.

. 255


.

.

.

.

.

. 256


.

.

.

.

.

.

. 256

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 256

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 256

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 257

Return codes .

.

.

.

.

.

.

.

.

.

.

. 257

Chapter 33. IEAVRPI —

Retrieve_Pause_Element_Information service . . . . . . . . . . . . . . 261

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 261

Environment .

.

.

.

.

.

.

.

.

.

.

. 261


.

.

.

.

.

.

. 261

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 261


.

.

.

.

.

.

. 261


.

.

.

.

.

. 262


.

.

.

.

.

.

. 262

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 262

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 262

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 264

Return codes .

.

.

.

.

.

.

.

.

.

.

. 264

Chapter 34. IEAVRPI2 —


Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 267

Environment .

.

.

.

.

.

.

.

.

.

.

. 267


.

.

.

.

.

.

. 267

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 268


.

.

.

.

.

.

. 268


.

.

.

.

.

. 268


.

.

.

.

.

.

. 268

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 269

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 269

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 271

Return codes .

.

.

.

.

.

.

.

.

.

.

. 271

Chapter 35. IEAVTPE —

Test_Pause_Element service . . . . . 273

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 273

Environment .

.

.

.

.

.

.

.

.

.

.

. 273


.

.

.

.

.

.

. 273

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 273


.

.

.

.

.

.

. 273


.

.

.

.

.

. 273


.

.

.

.

.

.

. 274

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 274

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 274

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 275

Return codes .

.

.

.

.

.

.

.

.

.

.

. 275

Chapter 36. IEAVXFR — Transfer service . . . . . . . . . . . . . . 277

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 277

Environment .

.

.

.

.

.

.

.

.

.

.

. 277


.

.

.

.

.

.

. 277

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 277


.

.

.

.

.

.

. 277


.

.

.

.

.

. 278


.

.

.

.

.

.

. 278

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 278

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 278

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 280

Return codes .

.

.

.

.

.

.

.

.

.

.

. 280

Contents

vii

Chapter 37. IEAVXFR2 — Transfer service . . . . . . . . . . . . . . 283

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 283

Environment .

.

.

.

.

.

.

.

.

.

.

. 283


.

.

.

.

.

.

. 283

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 283


.

.

.

.

.

.

. 283


.

.

.

.

.

. 284


.

.

.

.

.

.

. 284

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 284

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 284

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 286

Return codes .

.

.

.

.

.

.

.

.

.

.

. 286

Chapter 38. IEA4APE —


Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 289

Environment .

.

.

.

.

.

.

.

.

.

.

. 289


.

.

.

.

.

.

. 289

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 289


.

.

.

.

.

.

. 289


.

.

.

.

.

. 290


.

.

.

.

.

.

. 290

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 290

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 290

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 291

Return codes .

.

.

.

.

.

.

.

.

.

.

. 292

Chapter 39. IEA4APE2 —


Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 293

Environment .

.

.

.

.

.

.

.

.

.

.

. 293


.

.

.

.

.

.

. 293

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 293


.

.

.

.

.

.

. 294


.

.

.

.

.

. 294


.

.

.

.

.

.

. 294

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 294

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 294

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 297

Return codes .

.

.

.

.

.

.

.

.

.

.

. 297

Chapter 40. IEA4DPE -


Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 299

Environment .

.

.

.

.

.

.

.

.

.

.

. 299


.

.

.

.

.

.

. 299

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 299


.

.

.

.

.

.

. 299


.

.

.

.

.

. 299


.

.

.

.

.

.

. 300

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 300

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 300

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 301

Return codes .

.

.

.

.

.

.

.

.

.

.

. 301

Chapter 41. IEA4DPE2 —


Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 303

viii


Environment .

.

.

.

.

.

.

.

.

.

.

. 303


.

.

.

.

.

.

. 303

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 303


.

.

.

.

.

.

. 303


.

.

.

.

.

. 303


.

.

.

.

.

.

. 304

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 304

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 304

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 305

Return codes .

.

.

.

.

.

.

.

.

.

.

. 305

Chapter 42. IEA4PME2 — 64-bit pause multiple elements service . . . . . . 307

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 307

Environment .

.

.

.

.

.

.

.

.

.

.

. 307


.

.

.

.

.

.

. 307

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 307


.

.

.

.

.

.

. 308


.

.

.

.

.

. 308


.

.

.

.

.

.

. 308

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 309

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 309

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 311

Return codes .

.

.

.

.

.

.

.

.

.

.

. 311

Chapter 43. IEA4PSE — Pause service 315

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 315

Environment .

.

.

.

.

.

.

.

.

.

.

. 315


.

.

.

.

.

.

. 315

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 315


.

.

.

.

.

.

. 315


.

.

.

.

.

. 316


.

.

.

.

.

.

. 316

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 316

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 316

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 318

Return codes .

.

.

.

.

.

.

.

.

.

.

. 318

Chapter 44. IEA4PSE2 — Pause service . . . . . . . . . . . . . . 321

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 321

Environment .

.

.

.

.

.

.

.

.

.

.

. 321


.

.

.

.

.

.

. 321

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 321


.

.

.

.

.

.

. 322


.

.

.

.

.

. 322


.

.

.

.

.

.

. 322

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 322

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 322

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 324

Return codes .

.

.

.

.

.

.

.

.

.

.

. 324

Chapter 45. IEA4RLS — Release . . . 327

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 327

Environment .

.

.

.

.

.

.

.

.

.

.

. 327


.

.

.

.

.

.

. 327

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 327


.

.

.

.

.

.

. 327


.

.

.

.

.

. 328


.

.

.

.

.

.

. 328

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 328

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 328

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 329

Return codes .

.

.

.

.

.

.

.

.

.

.

. 329

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 351

Return codes .

.

.

.

.

.

.

.

.

.

.

. 351

Chapter 46. IEA4RLS2 — Release. . . 331

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 331

Environment .

.

.

.

.

.

.

.

.

.

.

. 331


.

.

.

.

.

.

. 331

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 331


.

.

.

.

.

.

. 331


.

.

.

.

.

. 332


.

.

.

.

.

.

. 332

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 332

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 332

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 333

Return codes .

.

.

.

.

.

.

.

.

.

.

. 333

Chapter 50. IEA4XFR — Transfer service . . . . . . . . . . . . . . 353

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 353

Environment .

.

.

.

.

.

.

.

.

.

.

. 353


.

.

.

.

.

.

. 353

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 353


.

.

.

.

.

.

. 353


.

.

.

.

.

. 354


.

.

.

.

.

.

. 354

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 354

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 354

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 356

Return codes .

.

.

.

.

.

.

.

.

.

.

. 356

Chapter 47. IEA4RPI —


Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 337

Environment .

.

.

.

.

.

.

.

.

.

.

. 337


.

.

.

.

.

.

. 337

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 337


.

.

.

.

.

.

. 338


.

.

.

.

.

. 338


.

.

.

.

.

.

. 338

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 338

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 338

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 340

Return codes .

.

.

.

.

.

.

.

.

.

.

. 341

Chapter 51. IEA4XFR2 — Transfer service . . . . . . . . . . . . . . 359

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 359

Environment .

.

.

.

.

.

.

.

.

.

.

. 359


.

.

.

.

.

.

. 359

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 359


.

.

.

.

.

.

. 359


.

.

.

.

.

. 360


.

.

.

.

.

.

. 360

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 360

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 360

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 362

Return codes .

.

.

.

.

.

.

.

.

.

.

. 362

Chapter 48. IEA4RPI2 —


Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 343

Environment .

.

.

.

.

.

.

.

.

.

.

. 343


.

.

.

.

.

.

. 343

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 343


.

.

.

.

.

.

. 344


.

.

.

.

.

. 344


.

.

.

.

.

.

. 344

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 344

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 344

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 347

Return codes .

.

.

.

.

.

.

.

.

.

.

. 347

Chapter 52. IEFDDSRV — DD service 365

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 365

Environment .

.

.

.

.

.

.

.

.

.

.

. 365


.

.

.

.

.

.

. 365

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 366


.

.

.

.

.

.

. 367


.

.

.

.

.

. 367


.

.

.

.

.

.

. 367

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 367

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 369

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 376


.

.

.

.

.

.

. 376

||

|

Chapter 53. IEFOPZQ — Query the

IEFOPZ configuration . . . . . . . . 379

Chapter 49. IEA4TPE —

Test_Pause_Element service . . . . . 349

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 349

Environment .

.

.

.

.

.

.

.

.

.

.

. 349


.

.

.

.

.

.

. 349

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 349


.

.

.

.

.

.

. 349


.

.

.

.

.

. 349


.

.

.

.

.

.

. 350

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 350

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 350

Chapter 54. IEFPRMLB — Logical parmlib support . . . . . . . . . . 391

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 391

Environment .

.

.

.

.

.

.

.

.

.

.

. 391


.

.

.

.

.

.

. 391

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 392


.

.

.

.

.

.

. 392


.

.

.

.

.

. 392


.

.

.

.

.

.

. 392

REQUEST=ALLOCATE option of IEFPRMLB.

.

. 392

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 392

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 394

Contents

ix

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 401


.

.

.

.

.

.

. 401

REQUEST=FREE option of IEFPRMLB .

.

.

.

. 405

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 405

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 406

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 409


.

.

.

.

.

.

. 409

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 409

REQUEST=LIST option of IEFPRMLB .

.

.

.

. 409

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 410

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 410

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 413


.

.

.

.

.

.

. 413

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 413

REQUEST=READMEMBER option of IEFPRMLB 413

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 413

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 415

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 419


.

.

.

.

.

.

. 419

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 419

Chapter 55. IEFSSI — Dynamically query a subsystem . . . . . . . . . 421

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 421

Environment .

.

.

.

.

.

.

.

.

.

.

. 421


.

.

.

.

.

.

. 421

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 422


.

.

.

.

.

.

. 422


.

.

.

.

.

. 422


.

.

.

.

.

.

. 422

REQUEST=QUERY parameter of IEFSSI .

.

. 422

Syntax for REQUEST=QUERY .

.

.

.

.

.

. 422

Parameters for REQUEST=QUERY .

.

.

.

. 423

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 426


.

.

.

.

.

.

. 426

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 427

Chapter 56. IOCINFO — Obtain MVS

I/O configuration information . . . . 429

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 429

Environment .

.

.

.

.

.

.

.

.

.

.

. 429


.

.

.

.

.

.

. 429

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 429


.

.

.

.

.

.

. 429


.

.

.

.

.

. 429


.

.

.

.

.

.

. 430

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 430

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 431

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 432


.

.

.

.

.

.

. 432

IOCINFO—List form .

.

.

.

.

.

.

.

.

.

. 433

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 433

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 433

IOCINFO - Execute form .

.

.

.

.

.

.

.

. 434

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 434

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 435

Chapter 57. IOSCHPD — IOS CHPID description service . . . . . . . . . 437

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 437

x


Environment .

.

.

.

.

.

.

.

.

.

.

. 437


.

.

.

.

.

.

. 437

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 437


.

.

.

.

.

.

. 437


.

.

.

.

.

. 437


.

.

.

.

.

.

. 438

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 438

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 439

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 442


.

.

.

.

.

.

. 442

Chapter 58. IOSCUMOD — IOS control unit entry build service . . . . . . . 445

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 445


.

.

.

.

.

.

. 445

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 445


.

.

.

.

.

.

. 445

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 445

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 446

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 447


.

.

.

.

.

.

. 447

Chapter 59. IOSSCM — Storage class memory information . . . . . . . . 449

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 449

Environment .

.

.

.

.

.

.

.

.

.

.

. 449


.

.

.

.

.

.

. 449

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 449


.

.

.

.

.

.

. 449


.

.

.

.

.

. 449


.

.

.

.

.

.

. 450

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 450

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 450

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 453


.

.

.

.

.

.

. 453

Chapter 60. ISGENQ — Global resource serialization ENQ service . . 455

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 455

Environment .

.

.

.

.

.

.

.

.

.

.

. 455


.

.

.

.

.

.

. 456

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 456


.

.

.

.

.

.

. 456


.

.

.

.

.

. 456


.

.

.

.

.

.

. 457

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 458

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 460

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 475


.

.

.

.

.

.

. 475

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 487

Chapter 61. ISGQUERY — Global resource serialization query service . 489

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 489

Environment .

.

.

.

.

.

.

.

.

.

.

. 489


.

.

.

.

.

.

. 489

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 490


.

.

.

.

.

.

. 490


.

.

.

.

.

. 490


.

.

.

.

.

.

. 491

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 492

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 494

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 507


.

.

.

.

.

.

. 507

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 515

Chapter 62. ITTUINIT — Activate external CTRACE recording . . . . . 519

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 519

Environment .

.

.

.

.

.

.

.

.

.

.

. 519


.

.

.

.

.

.

. 519

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 520


.

.

.

.

.

.

. 520


.

.

.

.

.

. 520


.

.

.

.

.

.

. 520

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 521

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 521


.

.

.

.

.

.

. 521

Chapter 63. ITTUTERM — End external CTRACE recording . . . . . 523

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 523

Environment .

.

.

.

.

.

.

.

.

.

.

. 523


.

.

.

.

.

.

. 523

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 523


.

.

.

.

.

.

. 523


.

.

.

.

.

. 523


.

.

.

.

.

.

. 524

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 524

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 524


.

.

.

.

.

.

. 525

Chapter 64. ITTUWRIT — Queue a group of CTRACE entries . . . . . . 527

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 527

Environment .

.

.

.

.

.

.

.

.

.

.

. 527


.

.

.

.

.

.

. 527

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 527


.

.

.

.

.

.

. 527


.

.

.

.

.

. 528


.

.

.

.

.

.

. 528

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 528

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 529


.

.

.

.

.

.

. 529

Chapter 65. ITZEVENT — Transaction trace EVENT record . . . . . . . . 531

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 531

Environment .

.

.

.

.

.

.

.

.

.

.

. 531


.

.

.

.

.

.

. 531

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 531


.

.

.

.

.

.

. 531


.

.

.

.

.

. 531


.

.

.

.

.

.

. 532

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 532

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 534

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 538


.

.

.

.

.

.

. 538

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 539

Chapter 66. ITZQUERY — Transaction trace query . . . . . . . . . . . . 541

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 541

Environment .

.

.

.

.

.

.

.

.

.

.

. 541


.

.

.

.

.

.

. 541

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 541


.

.

.

.

.

.

. 541


.

.

.

.

.

. 541


.

.

.

.

.

.

. 542

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 542

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 543

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 545


.

.

.

.

.

.

. 545

Chapter 67. IXGBRWSE —

Browse/read a log stream . . . . . . 547

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 547

Environment .

.

.

.

.

.

.

.

.

.

.

. 547


.

.

.

.

.

.

. 548

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 549


.

.

.

.

.

.

. 549


.

.

.

.

.

. 549


.

.

.

.

.

.

. 550

REQUEST=START option of IXGBRWSE .

.

. 550

Syntax for REQUEST=START .

.

.

.

.

.

. 550

Parameters for REQUEST=START .

.

.

.

. 551

REQUEST=READCURSOR option of

IXGBRWSE .

.

.

.

.

.

.

.

.

.

.

.

. 556

Syntax for REQUEST=READCURSOR .

.

.

. 556

Parameters for REQUEST=READCURSOR.

.

. 558

REQUEST=READBLOCK option of IXGBRWSE 562

Syntax for REQUEST=READBLOCK.

.

.

.

. 562

Parameters for REQUEST=READBLOCK .

.

. 564

REQUEST=RESET option of IXGBRWSE .

.

. 568

Syntax for REQUEST=RESET .

.

.

.

.

.

. 568

Parameters for REQUEST=RESET .

.

.

.

. 570

REQUEST=END option of IXGBRWSE .

.

.

. 573

Syntax for REQUEST=END.

.

.

.

.

.

.

. 573

Parameters for REQUEST=END .

.

.

.

.

. 574

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 577


.

.

.

.

.

.

. 577

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 589

Chapter 68. IXGCONN —

Connect/disconnect to log stream . . 593

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 593

Environment .

.

.

.

.

.

.

.

.

.

.

. 593


.

.

.

.

.

.

. 594

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 594


.

.

.

.

.

.

. 595


.

.

.

.

.

. 595


.

.

.

.

.

.

. 595

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 595

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 597

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 602


.

.

.

.

.

.

. 602

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 614

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 615

Contents

xi

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 615

Example 4 .

.

.

.

.

.

.

.

.

.

.

.

. 615

Chapter 69. IXGDELET — Deleting log data from a log stream . . . . . . . 617

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 617

Environment .

.

.

.

.

.

.

.

.

.

.

. 617


.

.

.

.

.

.

. 617

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 618


.

.

.

.

.

.

. 618


.

.

.

.

.

. 618


.

.

.

.

.

.

. 618

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 619

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 620

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 624


.

.

.

.

.

.

. 624

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 632

Chapter 70. IXGIMPRT — Import log blocks . . . . . . . . . . . . . . 635

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 635

Environment .

.

.

.

.

.

.

.

.

.

.

. 635


.

.

.

.

.

.

. 635

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 635


.

.

.

.

.

.

. 635


.

.

.

.

.

. 636


.

.

.

.

.

.

. 636

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 636

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 638

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 641


.

.

.

.

.

.

. 641

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 650

Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set . 653

IXGINVNT description .

.

.

.

.

.

.

.

.

. 653

Environment .

.

.

.

.

.

.

.

.

.

.

. 653


.

.

.

.

.

.

. 654

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 654


.

.

.

.

.

.

. 655


.

.

.

.

.

. 655


.

.

.

.

.

.

. 656

REQUEST=DEFINE TYPE=LOGSTREAM option of IXGINVNT .

.

.

.

.

.

.

.

.

.

.

. 656

Syntax for REQUEST=DEFINE

TYPE=LOGSTREAM .

.

.

.

.

.

.

.

.

. 656

Parameters for

REQUEST=DEFINE,TYPE=LOGSTREAM .

.

. 659

REQUEST=DEFINE TYPE=STRUCTURE option of IXGINVNT .

.

.

.

.

.

.

.

.

.

.

. 677

Syntax for REQUEST=DEFINE

TYPE=STRUCTURE .

.

.

.

.

.

.

.

.

. 677

Parameters for

REQUEST=DEFINE,TYPE=STRUCTURE .

.

. 678

REQUEST=UPDATE option of IXGINVNT .

. 681

Syntax for REQUEST=UPDATE .

.

.

.

.

. 681

Parameters for REQUEST=UPDATE .

.

.

.

. 684

REQUEST=CHECKDEF option of IXGINVNT 702

Syntax for REQUEST=CHECKDEF .

.

.

.

. 702

Parameters for REQUEST=CHECKDEF .

.

.

. 703

xii


ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 706


.

.

.

.

.

.

. 706

REQUEST=DELETE option of IXGINVNT .

.

. 728

Syntax for REQUEST=DELETE .

.

.

.

.

. 729

Parameters for REQUEST=DELETE .

.

.

.

. 730

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 732


.

.

.

.

.

.

. 733

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 753

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 754

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 754

Example 4 .

.

.

.

.

.

.

.

.

.

.

.

. 755

Example 5 .

.

.

.

.

.

.

.

.

.

.

.

. 755

Example 6 .

.

.

.

.

.

.

.

.

.

.

.

. 756

Example 7 .

.

.

.

.

.

.

.

.

.

.

.

. 756

Example 8 .

.

.

.

.

.

.

.

.

.

.

.

. 756

Example 9 .

.

.

.

.

.

.

.

.

.

.

.

. 757

Example 10 .

.

.

.

.

.

.

.

.

.

.

.

. 757

Example 11 .

.

.

.

.

.

.

.

.

.

.

.

. 757

Chapter 72. IXGOFFLD — Initiate offload to DASD log data sets . . . . 759

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 759

Environment .

.

.

.

.

.

.

.

.

.

.

. 759


.

.

.

.

.

.

. 759

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 759


.

.

.

.

.

.

. 759


.

.

.

.

.

. 760


.

.

.

.

.

.

. 760

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 760

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 761

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 763


.

.

.

.

.

.

. 764

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 768

Chapter 73. IXGQUERY — Query a log stream for information . . . . . . . 769

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 769

Environment .

.

.

.

.

.

.

.

.

.

.

. 769


.

.

.

.

.

.

. 769

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 769


.

.

.

.

.

.

. 770


.

.

.

.

.

. 770


.

.

.

.

.

.

. 770

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 770

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 772

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 775


.

.

.

.

.

.

. 775

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 780

Chapter 74. IXGUPDAT — Update log stream control information . . . . . 781

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 781

Environment .

.

.

.

.

.

.

.

.

.

.

. 781


.

.

.

.

.

.

. 781

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 781


.

.

.

.

.

.

. 781


.

.

.

.

.

. 781


.

.

.

.

.

.

. 782

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 782

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 783

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 786


.

.

.

.

.

.

. 786

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 790

Chapter 75. IXGWRITE — Write log data to a log stream . . . . . . . . 791

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 791

Environment .

.

.

.

.

.

.

.

.

.

.

. 791


.

.

.

.

.

.

. 792

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 792


.

.

.

.

.

.

. 792


.

.

.

.

.

. 792


.

.

.

.

.

.

. 793

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 793

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 794

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 797


.

.

.

.

.

.

. 798

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 809

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 809

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 810

Chapter 76. LINK and LINKX — Pass control to a program in another load module . . . . . . . . . . . . . . 811

LINK and LINKX description .

.

.

.

.

.

.

. 811

Environment .

.

.

.

.

.

.

.

.

.

.

. 811


.

.

.

.

.

.

. 812

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 812


.

.

.

.

.

.

.

.

. 812


.

.

.

.

.

.

. 813

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 813

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 814


.

.

.

.

.

.

. 815

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 815

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 815

LINKX — Pass control to a program in another load module.

.

.

.

.

.

.

.

.

.

.

.

.

. 815

Environment .

.

.

.

.

.

.

.

.

.

.

. 815


.

.

.

.

.

.

. 816


.

.

.

.

.

.

.

.

. 816

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 816

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 817

LINK and LINKX—List form .

.

.

.

.

.

.

. 819

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 819

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 820

LINK and LINKX—Execute form .

.

.

.

.

.

. 820

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 820

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 821

Chapter 77. LOAD — Bring a load module into virtual storage . . . . . 823

LOAD description .

.

.

.

.

.

.

.

.

.

.

. 823

Environment .

.

.

.

.

.

.

.

.

.

.

. 823


.

.

.

.

.

.

. 823

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 823


.

.

.

.

.

.

. 824


.

.

.

.

.

. 824


.

.

.

.

.

.

. 825

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 825

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 826


.

.

.

.

.

.

. 828

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 828

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 828

LOAD—List form .

.

.

.

.

.

.

.

.

.

.

. 828

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 828

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 829

LOAD - Execute form .

.

.

.

.

.

.

.

.

. 829

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 829

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 830

Chapter 78. LSEXPAND — Expand the linkage stack capacity . . . . . . . 831

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 831

Environment .

.

.

.

.

.

.

.

.

.

.

. 831


.

.

.

.

.

.

. 831

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 831


.

.

.

.

.

.

. 831


.

.

.

.

.

. 831


.

.

.

.

.

.

. 832

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 832

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 832

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 833

Return codes .

.

.

.

.

.

.

.

.

.

.

. 833

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 833

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 834

Chapter 79. PGLOAD — Load virtual storage areas into central storage . . 835

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 835

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 835

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 836

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 836

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 837

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 837

PGLOAD—List form .

.

.

.

.

.

.

.

.

.

. 837

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 837

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 837

Chapter 80. PGOUT — Page out virtual storage areas from central storage . . . . . . . . . . . . . . 839

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 839

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 839

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 840

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 840

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 840

PGOUT—List form .

.

.

.

.

.

.

.

.

.

. 840

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 840

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 841

Chapter 81. PGRLSE — Release virtual storage contents . . . . . . . 843

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 843

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 843

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 844

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 844

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 844

PGRLSE - List form .

.

.

.

.

.

.

.

.

.

. 844

Contents

xiii

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 844

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 845

PGRLSE - Execute form .

.

.

.

.

.

.

.

.

. 845

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 845

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 846

Chapter 82. PGSER — Page services 847

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 847

Environment .

.

.

.

.

.

.

.

.

.

.

. 847


.

.

.

.

.

.

. 847

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 847


.

.

.

.

.

.

. 847


.

.

.

.

.

. 848


.

.

.

.

.

.

. 848

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 848

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 849

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 851


.

.

.

.

.

.

. 851

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 852

Chapter 83. POST — Signal event completion . . . . . . . . . . . . 853

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 853

Environment .

.

.

.

.

.

.

.

.

.

.

. 853


.

.

.

.

.

.

. 853

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 853


.

.

.

.

.

.

. 854


.

.

.

.

.

. 854


.

.

.

.

.

.

. 854

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 854

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 855


.

.

.

.

.

.

. 855

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 856

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 856

Chapter 84. QRYLANG — Determine languages available for message translation. . . . . . . . . . . . . 857

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 857

Environment .

.

.

.

.

.

.

.

.

.

.

. 857


.

.

.

.

.

.

. 857

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 857


.

.

.

.

.

.

. 857


.

.

.

.

.

. 858


.

.

.

.

.

.

. 858

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 858

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 859


.

.

.

.

.

.

. 859

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 860

Chapter 85. REFPAT — Define and end a reference pattern . . . . . . . 863

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 863

Environment .

.

.

.

.

.

.

.

.

.

.

. 863


.

.

.

.

.

.

. 864

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 864


.

.

.

.

.

.

. 864


.

.

.

.

.

. 864


.

.

.

.

.

.

. 864

xiv


Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 865

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 865


.

.

.

.

.

.

. 867

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 867

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 867

REFPAT—List form .

.

.

.

.

.

.

.

.

.

. 867

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 867

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 868

REFPAT—Execute form .

.

.

.

.

.

.

.

.

. 868

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 868

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 869

Chapter 86. RESERVE — Reserve a device (shared DASD). . . . . . . . 871

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 871

Environment .

.

.

.

.

.

.

.

.

.

.

. 871


.

.

.

.

.

.

. 871

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 871


.

.

.

.

.

.

. 872


.

.

.

.

.

. 872

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 872

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 873

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 875


.

.

.

.

.

.

. 875

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 878

RESERVE—List form .

.

.

.

.

.

.

.

.

.

. 878

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 879

RESERVE - Execute form .

.

.

.

.

.

.

.

. 879

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 880

Chapter 87. RETURN — Return control . . . . . . . . . . . . . . 883

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 883

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 883

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 883

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 884

Chapter 88. SAVE — Save register contents . . . . . . . . . . . . . 885

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 885

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 885

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 885

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 886

Chapter 89. SETRP — Set return parameters . . . . . . . . . . . . 887

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 887

Environment .

.

.

.

.

.

.

.

.

.

.

. 887


.

.

.

.

.

.

. 887

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 887


.

.

.

.

.

.

. 887


.

.

.

.

.

. 888


.

.

.

.

.

.

. 888

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 889

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 890

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 893


.

.

.

.

.

.

. 893

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 893

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 893

Chapter 90. SNAP and SNAPX —

Dump virtual storage and continue . . 895

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 895

Environment .

.

.

.

.

.

.

.

.

.

.

. 895


.

.

.

.

.

.

. 896


.

.

.

.

.

. 896


.

.

.

.

.

.

. 896

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 897


.

.

.

.

.

.

. 897

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 897

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 899


.

.

.

.

.

.

. 902

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 903

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 903

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 903

Example 4 .

.

.

.

.

.

.

.

.

.

.

.

. 903

Example 5 .

.

.

.

.

.

.

.

.

.

.

.

. 903

SNAPX — Dump virtual storage and continue .

. 904

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 904

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 905

SNAP and SNAPX—List form .

.

.

.

.

.

.

. 906

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 906

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 907

SNAP and SNAPX—Execute form .

.

.

.

.

. 907

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 907

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 909

Chapter 91. SPIE — Specify program interruption exit . . . . . . . . . . 911

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 911

Environment .

.

.

.

.

.

.

.

.

.

.

. 912


.

.

.

.

.

.

. 912

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 912


.

.

.

.

.

.

. 912


.

.

.

.

.

. 912


.

.

.

.

.

.

. 913

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 913

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 913

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 914


.

.

.

.

.

.

. 914

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 914

SPIE—List form .

.

.

.

.

.

.

.

.

.

.

. 914

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 915

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 915

SPIE - Execute form .

.

.

.

.

.

.

.

.

.

. 915

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 915

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 916

Chapter 92. SPLEVEL — Set macro level . . . . . . . . . . . . . . . 917

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 917

Environment .

.

.

.

.

.

.

.

.

.

.

. 918


.

.

.

.

.

.

. 918

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 918


.

.

.

.

.

.

. 918


.

.

.

.

.

. 918


.

.

.

.

.

.

. 918

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 918

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 919

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 919


.

.

.

.

.

.

. 919

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 919

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 919

Chapter 93. STAE — Specify task abnormal exit . . . . . . . . . . . 921

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 921

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 921

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 922

Return codes .

.

.

.

.

.

.

.

.

.

.

. 923

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 923

STAE - List form .

.

.

.

.

.

.

.

.

.

.

. 924

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 924

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 924

STAE - Execute form .

.

.

.

.

.

.

.

.

.

. 924

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 925

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 925

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 926

Chapter 94. STATUS — Start and stop a subtask . . . . . . . . . . . . . 927

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 927

Environment .

.

.

.

.

.

.

.

.

.

.

. 927


.

.

.

.

.

.

. 927

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 927


.

.

.

.

.

.

. 927


.

.

.

.

.

. 927


.

.

.

.

.

.

. 928

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 928

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 928

Return codes .

.

.

.

.

.

.

.

.

.

.

. 929

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 929

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 929

Chapter 95. STCKCONV — Store clock conversion routine . . . . . . . . . 933

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 933

Environment .

.

.

.

.

.

.

.

.

.

.

. 933


.

.

.

.

.

.

. 933

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 933


.

.

.

.

.

.

. 933


.

.

.

.

.

. 934


.

.

.

.

.

.

. 934

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 934

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 935

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 936

Return codes .

.

.

.

.

.

.

.

.

.

.

. 936

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 937

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 937

STCKCONV—List form .

.

.

.

.

.

.

.

.

. 937

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 937

Parameter .

.

.

.

.

.

.

.

.

.

.

.

. 937

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 938

STCKCONV - Execute form .

.

.

.

.

.

.

. 938

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 938

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 938

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 939

Contents

xv

Chapter 96. STCKSYNC — Store clock synchronous service . . . . . . . . 941

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 941

Environment .

.

.

.

.

.

.

.

.

.

.

. 941


.

.

.

.

.

.

. 941

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 941


.

.

.

.

.

.

. 942


.

.

.

.

.

. 942


.

.

.

.

.

.

. 942

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 942

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 943

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 943

Return codes .

.

.

.

.

.

.

.

.

.

.

. 943

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 944

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 944

Chapter 97. STIMER — Set interval timer . . . . . . . . . . . . . . . 945

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 945

Environment .

.

.

.

.

.

.

.

.

.

.

. 945


.

.

.

.

.

.

. 945

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 945


.

.

.

.

.

.

. 946


.

.

.

.

.

. 946


.

.

.

.

.

.

. 947

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 947

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 948

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 950


.

.

.

.

.

.

. 950

Examples .

.

.

.

.

.

.

.

.

.

.

.

.

. 950

Chapter 98. STIMERM — Set, test, cancel multiple interval timer . . . . 951

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 951

Environment .

.

.

.

.

.

.

.

.

.

.

. 952


.

.

.

.

.

.

. 952

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 952


.

.

.

.

.

.

. 953


.

.

.

.

.

. 953


.

.

.

.

.

.

. 953

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 953

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 954

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 958

Return codes .

.

.

.

.

.

.

.

.

.

.

. 958

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 959

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 959

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 960

Example 4 .

.

.

.

.

.

.

.

.

.

.

.

. 960

Example 5 .

.

.

.

.

.

.

.

.

.

.

.

. 960

Example 6 .

.

.

.

.

.

.

.

.

.

.

.

. 960

Example 7 .

.

.

.

.

.

.

.

.

.

.

.

. 960

Example 8 .

.

.

.

.

.

.

.

.

.

.

.

. 961

STIMERM—List form .

.

.

.

.

.

.

.

.

. 961

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 961

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 961

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 961

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 962

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 962

STIMERM - Execute form .

.

.

.

.

.

.

.

. 962

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 962

xvi


Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 963

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 963

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 963

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 964

Chapter 99. STORAGE — Obtain and release storage . . . . . . . . . . 965

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 965

Environment .

.

.

.

.

.

.

.

.

.

.

. 965


.

.

.

.

.

.

. 965

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 965


.

.

.

.

.

.

.

.

. 965


.

.

.

.

.

.

. 965

OBTAIN option of STORAGE .

.

.

.

.

.

.

. 966

Input register information for

LINKAGE=SYSTEM .

.

.

.

.

.

.

.

.

. 966

Output register information for

LINKAGE=SYSTEM .

.

.

.

.

.

.

.

.

. 966

Input register information for LINKAGE=SVC 967

Output register information for LINKAGE=SVC 967

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 968

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 970

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 975


.

.

.

.

.

.

. 976

RELEASE option of STORAGE .

.

.

.

.

.

. 977


.

.

.

.

.

.

. 977


.

.

.

.

.

. 977

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 978

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 979

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 980


.

.

.

.

.

.

. 981

Examples of the OBTAIN and RELEASE options 981

Chapter 100. SYMRBLD — Building a symptom record . . . . . . . . . . 983

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 983

Environment .

.

.

.

.

.

.

.

.

.

.

. 984


.

.

.

.

.

.

. 984

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 984


.

.

.

.

.

.

. 984


.

.

.

.

.

. 984


.

.

.

.

.

.

. 985

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 985

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 986

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 988

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 989

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 992

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 993

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 995

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 995

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 996

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 997

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 998

Return and reason codes (for SYMRBLD

COMPLETE,INVOKE=YES) .

.

.

.

.

.

. 998

Syntax.

.

.

.

.

.

.

.

.

.

.

.

.

.

. 998

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 998

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1000

Chapter 101. SYMREC — Process a symptom record . . . . . . . . . 1003

Description.

.

.

.

.

.

.

.

.

.

.

.

.

. 1003

Environment .

.

.

.

.

.

.

.

.

.

.

. 1003


.

.

.

.

.

. 1003

Restrictions.

.

.

.

.

.

.

.

.

.

.

.

. 1003


.

.

.

.

.

.

. 1004


.

.

.

.

.

. 1004


.

.

.

.

.

.

. 1004

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1004

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1005

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1005


.

.

.

.

.

.

. 1005

SYMREC—List form .

.

.

.

.

.

.

.

.

. 1008

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1008

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1009

SYMREC - Execute form .

.

.

.

.

.

.

.

. 1009

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1009

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1009

Chapter 102. SYNCH and SYNCHX —

Take a synchronous exit to a processing program . . . . . . . . 1011

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 1011

Environment .

.

.

.

.

.

.

.

.

.

.

. 1011


.

.

.

.

.

. 1012

Restrictions.

.

.

.

.

.

.

.

.

.

.

.

. 1012


.

.

.

.

.

.

. 1012


.

.

.

.

.

. 1012


.

.

.

.

.

.

. 1012

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1012

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1013


.

.

.

.

.

.

. 1014

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1014

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1014

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 1014

Example 4 .

.

.

.

.

.

.

.

.

.

.

.

. 1014

Example 5 .

.

.

.

.

.

.

.

.

.

.

.

. 1014

SYNCHX - Take a synchronous exit to a processing program .

.

.

.

.

.

.

.

.

.

. 1014

Environment .

.

.

.

.

.

.

.

.

.

.

. 1014


.

.

.

.

.

. 1015

Register information.

.

.

.

.

.

.

.

.

. 1015

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1015

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1015

SYNCH and SYNCHX—List form .

.

.

.

.

. 1016

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1016

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1016

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1016

SYNCH and SYNCHX—Execute form .

.

.

.

. 1017

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1017

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1017

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1017

Chapter 103. SYSEVENT — System event . . . . . . . . . . . . . . 1019

Description.

.

.

.

.

.

.

.

.

.

.

.

.

. 1019

Chapter 104. SYSSTATE — Identify system state . . . . . . . . . . . 1021

Description.

.

.

.

.

.

.

.

.

.

.

.

.

. 1021

Environment .

.

.

.

.

.

.

.

.

.

.

. 1022


.

.

.

.

.

. 1022

Restrictions.

.

.

.

.

.

.

.

.

.

.

.

. 1022


.

.

.

.

.

.

. 1022


.

.

.

.

.

. 1022


.

.

.

.

.

.

. 1023

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1023

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1023

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1025


.

.

.

.

.

.

. 1025

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1025

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1025

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 1026

Example 4 .

.

.

.

.

.

.

.

.

.

.

.

. 1026

Chapter 105. TCBTOKEN — Request or translate the TTOKEN . . . . . . 1027

Description.

.

.

.

.

.

.

.

.

.

.

.

.

. 1027

Environment .

.

.

.

.

.

.

.

.

.

.

. 1027


.

.

.

.

.

. 1027

Restrictions.

.

.

.

.

.

.

.

.

.

.

.

. 1027


.

.

.

.

.

.

. 1027


.

.

.

.

.

. 1027


.

.

.

.

.

.

. 1028

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1028

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1029

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1029

Return codes .

.

.

.

.

.

.

.

.

.

.

. 1029

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1030

TCBTOKEN—List form .

.

.

.

.

.

.

.

. 1030

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1030

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1031

TCBTOKEN—Execute form .

.

.

.

.

.

.

. 1031

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1031

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1032

Chapter 106. TESTART — Tests the validity of ALETs . . . . . . . . . 1033

Description.

.

.

.

.

.

.

.

.

.

.

.

.

. 1033

Environment .

.

.

.

.

.

.

.

.

.

.

. 1033


.

.

.

.

.

. 1033

Restrictions.

.

.

.

.

.

.

.

.

.

.

.

. 1033


.

.

.

.

.

.

. 1033


.

.

.

.

.

. 1033


.

.

.

.

.

.

. 1034

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1034

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1034

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1035

Return codes .

.

.

.

.

.

.

.

.

.

.

. 1035

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1035

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1036

Chapter 107. TIME — Obtain time and date . . . . . . . . . . . . . 1037

Description.

.

.

.

.

.

.

.

.

.

.

.

.

. 1037

LINKAGE=SYSTEM .

.

.

.

.

.

.

.

.

.

. 1037

Contents

xvii

Environment .

.

.

.

.

.

.

.

.

.

.

. 1037


.

.

.

.

.

. 1038

Restrictions.

.

.

.

.

.

.

.

.

.

.

.

. 1038


.

.

.

.

.

.

. 1038


.

.

.

.

.

. 1038


.

.

.

.

.

.

. 1038

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1039

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1039

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1041

Return codes .

.

.

.

.

.

.

.

.

.

.

. 1041

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1041

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1042

LINKAGE=SYSTEM - List form .

.

.

.

.

.

. 1042

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1042

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1042

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1042

LINKAGE=SYSTEM - Execute form .

.

.

.

. 1043

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1043

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1043

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1044

LINKAGE=SVC .

.

.

.

.

.

.

.

.

.

.

. 1044

Environment .

.

.

.

.

.

.

.

.

.

.

. 1044


.

.

.

.

.

. 1044

Restrictions.

.

.

.

.

.

.

.

.

.

.

.

. 1044


.

.

.

.

.

.

. 1044


.

.

.

.

.

. 1044


.

.

.

.

.

.

. 1045

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1045

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1045

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1046


.

.

.

.

.

.

. 1047

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1047

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1047

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 1047

Chapter 108. TIMEUSED — Obtain accumulated CPU or vector time . . 1049

Description.

.

.

.

.

.

.

.

.

.

.

.

.

. 1049

Environment .

.

.

.

.

.

.

.

.

.

.

. 1049


.

.

.

.

.

. 1049

Restrictions.

.

.

.

.

.

.

.

.

.

.

.

. 1049


.

.

.

.

.

.

. 1049


.

.

.

.

.

. 1049


.

.

.

.

.

.

. 1050

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1050

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1051

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1053

Return codes .

.

.

.

.

.

.

.

.

.

.

. 1053

Examples .

.

.

.

.

.

.

.

.

.

.

.

. 1053

Chapter 109. TRANMSG — Translate messages . . . . . . . . . . . . 1055

Description.

.

.

.

.

.

.

.

.

.

.

.

.

. 1055

Environment .

.

.

.

.

.

.

.

.

.

.

. 1055


.

.

.

.

.

. 1056

Restrictions.

.

.

.

.

.

.

.

.

.

.

.

. 1056


.

.

.

.

.

.

. 1056


.

.

.

.

.

. 1056


.

.

.

.

.

.

. 1056

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1057

xviii


Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1058


.

.

.

.

.

.

. 1058

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1062

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1063

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 1064

Example 4 .

.

.

.

.

.

.

.

.

.

.

.

. 1065

Example 5 .

.

.

.

.

.

.

.

.

.

.

.

. 1066

Chapter 110. TTIMER — Test interval timer . . . . . . . . . . . . . . 1069

Description.

.

.

.

.

.

.

.

.

.

.

.

.

. 1069

Environment .

.

.

.

.

.

.

.

.

.

.

. 1069


.

.

.

.

.

. 1069

Restrictions.

.

.

.

.

.

.

.

.

.

.

.

. 1069


.

.

.

.

.

.

. 1069


.

.

.

.

.

. 1069


.

.

.

.

.

.

. 1070

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1070

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1070

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1071

Return codes .

.

.

.

.

.

.

.

.

.

.

. 1071

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1071

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1071

Chapter 111. UCBDEVN — Return

EBCDIC device number for a UCB . . 1073

Description.

.

.

.

.

.

.

.

.

.

.

.

.

. 1073

Environment .

.

.

.

.

.

.

.

.

.

.

. 1073


.

.

.

.

.

. 1073

Restrictions.

.

.

.

.

.

.

.

.

.

.

.

. 1074


.

.

.

.

.

.

. 1074


.

.

.

.

.

. 1074


.

.

.

.

.

.

. 1074

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1074

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1075


.

.

.

.

.

.

. 1075

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1075

Chapter 112. UCBINFO — Return information from a UCB . . . . . . 1077

Description.

.

.

.

.

.

.

.

.

.

.

.

.

. 1077

Environment .

.

.

.

.

.

.

.

.

.

.

. 1077


.

.

.

.

.

. 1078

Restrictions.

.

.

.

.

.

.

.

.

.

.

.

. 1078


.

.

.

.

.

.

. 1078


.

.

.

.

.

. 1078


.

.

.

.

.

.

. 1079

UCBINFO DEVCOUNT .

.

.

.

.

.

.

.

. 1079

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1079

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1080


.

.

.

.

.

.

. 1082

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1083

UCBINFO DEVCOUNT—List form.

.

.

.

.

. 1083

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1084

UCBINFO DEVCOUNT—Execute form .

.

.

. 1084

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1085

UCBINFO DEVINFO .

.

.

.

.

.

.

.

.

. 1086

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1086

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1086


.

.

.

.

.

.

. 1088

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1089

UCBINFO DEVINFO - List form .

.

.

.

.

. 1089

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1090

UCBINFO DEVINFO - Execute form .

.

.

.

. 1090

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1091

UCBINFO GETCDR .

.

.

.

.

.

.

.

.

.

. 1091

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1091

UCBINFO GETCDR - List form .

.

.

.

.

.

. 1092

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1093

UCBINFO GETCDR - Execute form .

.

.

.

. 1093

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1094

UCBINFO HYPERPAVALIASES .

.

.

.

.

.

. 1095

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1095

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1096


.

.

.

.

.

.

. 1097

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1099

UCBINFO HYPERPAVALIASES - List form .

.

. 1099

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1100

UCBINFO HYPERPAVALIASES - Execute form 1100

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1101

UCBINFO PATHINFO .

.

.

.

.

.

.

.

.

. 1101

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1101

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1102


.

.

.

.

.

.

. 1104

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1105

UCBINFO PATHINFO - List form .

.

.

.

.

. 1105

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1106

UCBINFO PATHINFO - Execute form .

.

.

.

. 1106

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1107

UCBINFO PATHMAP .

.

.

.

.

.

.

.

.

. 1107

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1107

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1108


.

.

.

.

.

.

. 1109

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 1111

UCBINFO PATHMAP - List form .

.

.

.

.

. 1111

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1111

UCBINFO PATHMAP - Execute form .

.

.

.

. 1112

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1113

UCBINFO PAVINFO.

.

.

.

.

.

.

.

.

.

. 1113

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1113

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1114


.

.

.

.

.

.

. 1117

Example .

.

.

.

.

.

.

.

.

.

.

.

.

. 1118

UCBINFO PAVINFO - List form .

.

.

.

.

.

. 1119

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1119

UCBINFO PAVINFO - Execute form .

.

.

.

. 1119

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1121

UCBINFO PRFXDATA .

.

.

.

.

.

.

.

.

. 1121

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1121

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1122


.

.

.

.

.

.

. 1123

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1124

UCBINFO PRFXDATA - List form .

.

.

.

.

. 1124

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1125

UCBINFO PRFXDATA - Execute form .

.

.

.

. 1125

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1126

Chapter 113. UCBSCAN — Scan

UCBs . . . . . . . . . . . . . . 1127

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 1127

Environment .

.

.

.

.

.

.

.

.

.

.

. 1127


.

.

.

.

.

. 1127

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 1127


.

.

.

.

.

.

. 1127


.

.

.

.

.

. 1128


.

.

.

.

.

.

. 1128

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1128

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1130


.

.

.

.

.

.

. 1134

UCBSCAN COPY - List form .

.

.

.

.

.

.

. 1135

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1136

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1136

UCBSCAN COPY - Execute form .

.

.

.

.

. 1136

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1137

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1139

Chapter 114. UPDTMPB — Update a message parameter block for substitution data . . . . . . . . . 1141

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 1141

Environment .

.

.

.

.

.

.

.

.

.

.

. 1141


.

.

.

.

.

. 1141

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 1141


.

.

.

.

.

.

. 1141


.

.

.

.

.

. 1141


.

.

.

.

.

.

. 1142

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1142

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1143


.

.

.

.

.

.

. 1144

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1144

Chapter 115. VRADATA — Update variable recording area data . . . . 1147

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 1147

Environment .

.

.

.

.

.

.

.

.

.

.

. 1147


.

.

.

.

.

. 1147

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 1147


.

.

.

.

.

.

. 1148


.

.

.

.

.

. 1148


.

.

.

.

.

.

. 1149

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1149

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1150

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1151


.

.

.

.

.

.

. 1152

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1152

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1152

Chapter 116. WAIT — Wait for one or more events . . . . . . . . . . . 1153

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 1153

Environment .

.

.

.

.

.

.

.

.

.

.

. 1153


.

.

.

.

.

. 1153

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 1153


.

.

.

.

.

.

. 1154


.

.

.

.

.

. 1154


.

.

.

.

.

.

. 1154

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1154

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1155

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1156

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1156

Contents

xix


.

.

.

.

.

.

. 1156

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1156

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1156

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 1157

Chapter 117. WTL — Write to log 1159

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 1159

Environment .

.

.

.

.

.

.

.

.

.

.

. 1159


.

.

.

.

.

. 1159

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 1160


.

.

.

.

.

.

. 1160


.

.

.

.

.

. 1160


.

.

.

.

.

.

. 1160

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1160

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1161

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1161


.

.

.

.

.

.

. 1161

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1164

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1164

WTL - List form .

.

.

.

.

.

.

.

.

.

.

. 1164

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1164

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1165

WTL - Execute form .

.

.

.

.

.

.

.

.

.

. 1165

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1165

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1165

Chapter 118. WTO- Write to operator 1167

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 1167

Environment .

.

.

.

.

.

.

.

.

.

.

. 1167


.

.

.

.

.

. 1167

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 1168


.

.

.

.

.

.

. 1168


.

.

.

.

.

. 1168


.

.

.

.

.

.

. 1169

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1169

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1170

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1176


.

.

.

.

.

.

. 1176

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1177

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1177

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 1178

Example 4 .

.

.

.

.

.

.

.

.

.

.

.

. 1178

WTO - List form .

.

.

.

.

.

.

.

.

.

.

. 1179

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1179

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1181

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1181

WTO - Execute form .

.

.

.

.

.

.

.

.

. 1181

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1181

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1182

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1182

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1182

Chapter 119. WTOR - Write to operator with reply . . . . . . . . 1183

Description .

.

.

.

.

.

.

.

.

.

.

.

.

. 1183

Environment .

.

.

.

.

.

.

.

.

.

.

. 1183


.

.

.

.

.

. 1183

Restrictions .

.

.

.

.

.

.

.

.

.

.

.

. 1184


.

.

.

.

.

.

. 1184


.

.

.

.

.

. 1184

xx



.

.

.

.

.

.

. 1184

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1185

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1186

ABEND codes .

.

.

.

.

.

.

.

.

.

.

. 1190


.

.

.

.

.

.

. 1190

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1191

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1191

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 1192

WTOR - List form .

.

.

.

.

.

.

.

.

.

. 1192

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1192

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1194

WTOR - Execute form .

.

.

.

.

.

.

.

.

. 1194

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1194

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1195

Chapter 120. XCTL and XCTLX - Pass control to a program in another load module . . . . . . . . . . . . . 1197

XCTL and XCTLX description .

.

.

.

.

.

. 1197

Environment .

.

.

.

.

.

.

.

.

.

.

. 1198

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1198

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1199


.

.

.

.

.

.

. 1200

Example.

.

.

.

.

.

.

.

.

.

.

.

.

. 1200

XCTLX - Pass control to a program in another load module .

.

.

.

.

.

.

.

.

.

.

.

. 1200

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1200

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1201

XCTL and XCTLX - List form .

.

.

.

.

.

. 1201

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1201

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1202

XCTL - Execute form .

.

.

.

.

.

.

.

.

. 1202

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1202

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1203

XCTLX - Execute form .

.

.

.

.

.

.

.

.

. 1203

Syntax .

.

.

.

.

.

.

.

.

.

.

.

.

. 1204

Parameters .

.

.

.

.

.

.

.

.

.

.

.

. 1205

Examples of passing data to the target module 1207

Example 1 .

.

.

.

.

.

.

.

.

.

.

.

. 1207

Example 2 .

.

.

.

.

.

.

.

.

.

.

.

. 1207

Example 3 .

.

.

.

.

.

.

.

.

.

.

.

. 1207

Example 4 .

.

.

.

.

.

.

.

.

.

.

.

. 1207

Appendix. Accessibility . . . . . . 1209

Accessibility features .

.

.

.

.

.

.

.

.

. 1209

Consult assistive technologies .

.

.

.

.

.

. 1209

Keyboard navigation of the user interface .

.

. 1209

Dotted decimal syntax diagrams .

.

.

.

.

. 1209

Notices . . . . . . . . . . . . . 1213

Terms and conditions for product documentation 1215

IBM Online Privacy Statement .

.

.

.

.

.

. 1216

Policy for unsupported hardware .

.

.

.

.

. 1216

Minimum supported hardware .

.

.

.

.

.

. 1216

Programming interface information .

.

.

.

. 1217

Trademarks .

.

.

.

.

.

.

.

.

.

.

.

. 1217

Index . . . . . . . . . . . . . . 1219

Figures

1.

Sample User Parameter List for Callers in AR

Mode .

.

.

.

.

.

.

.

.

.

.

.

.

.

. 5

2.

Sample tabular syntax diagram for the TEST macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 14

3.

Continuation Coding .

.

.

.

.

.

.

.

. 16

4.

Return Code Area Used by RESERVE 876


xxi

xxii


Tables

||

|

||

|

1.

Passing User Parameters in AR Mode .

.

.

. 5

2.

Execution environment characteristics and corresponding SYSSTATE parameters and global symbols .

.

.

.

.

.

.

.

.

.

.

.

.

. 6

3.

Service Summary .

.

.

.

.

.

.

.

.

. 18

4.

Return and Reason Codes for the IARCP64

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 37

5.

Return and Reason Codes for the IARR2V

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 45

6.

Return and Reason Codes for the IARST64

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 60

7.

Return and Reason Codes for the IARVSERV

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 68

8.

Return and Reason Codes for the IARV64

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 78

9.

Return and reason codes for the IEAFP macro 133

10.

Return and reason codes for the IEAGSF macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 141

11.

Return Codes for IEALSQRY .

.

.

.

.

. 149

12.

Return Codes for the IEAMETR Macro

13.

Return and Reason Codes for the IEATDUMP

153

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 196

14.

Return codes for the IEATXDC Macro 207

15.

Authorization .

.

.

.

.

.

.

.

.

.

. 211

16.

Checkpoint/Restart Toleration - only available when the CVTPAUS4 bit is set in the CVT. .

. 211

17.

Authorization .

.

.

.

.

.

.

.

.

.

. 215

18.


.

.

.

.

.

.

.

.

.

.

.

. 215

19.

Linkage option .

.

.

.

.

.

.

.

.

.

. 218

20.

Linkages .

.

.

.

.

.

.

.

.

.

.

.

. 233

21.

Authorization .

.

.

.

.

.

.

.

.

.

. 291

22.


.

.

.

.

.

.

.

.

.

.

.

. 291

23.

Linkage option .

.

.

.

.

.

.

.

.

.

. 297

24.

Linkages .

.

.

.

.

.

.

.

.

.

.

.

. 311

25.

Return and reason codes for the IEFDDSRV macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 376

26.

Return and reason codes for the IEFOPZQ macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 387

27.

Return and Reason Codes for the IEFPRMLB

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 401

28.

Return and Reason Codes for the IEFSSI

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 426

29.

Return and reason codes for the IOSCHPD macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 442

30.

Return and reason codes for the IOSSCM macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 453

31.

Return and Reason Codes for the ISGENQ

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 475

32.

Return and Reason Codes for the ISGQUERY

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 507

33.

Return and Reason Codes for the ITZEVENT

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 539

34.

Return and Reason Codes for the ITZQUERY

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 546

35.

Return and Reason Codes for the IXGBRWSE

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 577

36.

Return and reason codes for the IXGCONN macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 602

37.

Return and Reason Codes for the IXGDELET

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 624

38.

Return and Reason Codes for the IXGIMPRT

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 641

39.

Valid special (graphical) characters: .

.

.

. 674

40.

Valid special (graphical) characters: .

.

.

. 699

41.

Return and Reason Codes for the IXGINVNT

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 707

42.

Return and Reason Codes for the IXGINVNT

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 733

43.

Return and Reason Codes for the IXGOFFLD

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 764

44.

Return and Reason Codes for the IXGQUERY

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 776

45.

Return and Reason Codes for the IXGUPDAT

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 786

46.

Return and reason codes for the IXGWRITE macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 798

47.

Return and Reason Codes for the LSEXPAND

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 833

48.

Return Codes for the RESERVE Macro with the RET=TEST Parameter .

.

.

.

.

.

. 876

49.

Return Codes for the RESERVE Macro with the RET=USE Parameter .

.

.

.

.

.

.

. 876

50.

Return Codes for the RESERVE Macro with the RET=HAVE Parameter .

.

.

.

.

.

. 877

51.

Return and Reason Codes for the STAE

Macro .

.

.

.

.

.

.

.

.

.

.

.

.

. 923

52.

Return Codes for the STATUS Macro

53.

Return Codes for the STCKCONV Macro

54.

Return Codes for the STCKSYNC Macro

55.

Return Codes for the STIMERM Macro

56.

Return Codes for STORAGE OBTAIN

929

936

943

958

976

57.

Return Codes for the STORAGE RELEASE 981

58.

Valid SDB Key Names and Literals .

.

.

. 990

59.

Valid Section 5 Key Names and Literals

60.

Return codes for the TCBTOKEN macro

996

1029

61.

Return Codes for the TESTART Macro

62.

Return Codes for the TIME Macro

1035

1041

63.

Return and Reason Codes for the

TIMEUSED Macro .

.

.

.

.

.

.

.

. 1053

64.

Return Codes for the TTIMER Macro

65.

MCSFLAG Flag Names for WTO Macro

66.

MCSFLAG Flag Names for WTOR Macro

1071

1173

1188


xxiii

xxiv


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


xxv

xxvi


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.


xxvii

xxviii


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

Added new EXECUTABLE parameter for API STORAGE to the “OBTAIN option of STORAGE” on page 966 section.

Changed

v

The DUPLEXMODE(DRXRC) is removed from “Parameters for

REQUEST=DEFINE,TYPE=LOGSTREAM” on page 659 and “Parameters for

REQUEST=UPDATE” on page 684.

v

The STG_SIZE is updated in “Parameters for

REQUEST=DEFINE,TYPE=LOGSTREAM” on page 659 and “Parameters for

REQUEST=UPDATE” on page 684.

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

307.

v

The IEFOPZQ macro has been added in Chapter 53, “IEFOPZQ — Query the

IEFOPZ configuration,” on page 379.


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

A new IOSSCM service has been added in Chapter 59, “IOSSCM — Storage class memory information,” on page 449.

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


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

“Compatibility of MVS macros”

“Addressing mode (AMODE)” on page 2

“Address space control (ASC) mode” on page 3

“ALET qualification” on page 4

“User parameters” on page 4

“Telling the system about the execution environment” on page 6

“Specifying a macro version number” on page 7

“Register use” on page 8

“Handling return codes and reason codes” on page 9

“Handling program errors” on page 9

“Handling environmental and system errors” on page 10

“Using X-macros” on page 11

“Macro forms” on page 12

“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 summary” on page 18

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


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


|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

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


v


v


v


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


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.


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


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.


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


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.


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


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.


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

techniques are required and refers you to the information under “Alternative list form macros” on page 13.

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


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.


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


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)


Register (15)


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.


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


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.


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 (See note 1 on page 23)

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


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


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


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


19

CSVINFO

CSVQUERY

DELETE

DEQ

DETACH

DIV

DOM

DSPSERV

EDTINFO

ENQ

ESPIE

ESTAE (See note

2 on page 23)

ESTAEX

EVENTS

FREEMAIN


Service

CSRPRGT1

CSRREFR

CSRSAVE

CSRSCOT

CSRSI

CSRUNIC

CSRVIEW

CSVAPF


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 (See note 3 on page 23)

No (See note 3 on page 23)

No

Yes

No

No

No

Yes

No

Yes

No

No

Yes

No

No

No


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

(See note 5 on page 24)

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


AMODE

No

No

No

No

No

No

No

No

20



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


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


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


21


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


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


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


No

No

No

Yes

No

No

No

No

Yes

Yes

No


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


Service

SYMREC

SYNCH

SYNCHX

SYSSTATE

TCBTOKEN

TESTART

TIME



Yes

Yes

Yes

Yes

Yes

Yes

No

No

No Yes

Yes (See note 1)

No

Yes

Yes

No

Yes

Yes

Yes


Yes

Yes


Yes

Yes

No

No

Yes

Yes

Yes

Yes

No

No

No

No

Yes (See note 1)

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.


23

Yes

No

Yes

Yes

Yes

No

No

No

No

No

Yes

No

Yes

No


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


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.


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.


Return code in the low 32 bits.

13

14

15

For REQUEST=GET:

Register

Contents

0


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.



For REQUEST=FREE:

Register

Contents

0-1

2-12


Unchanged if ReGS=SAVE was specified, used as work registers by the system if ReGS=USE was specified.

13

Unchanged.

14-15


26


⌂

Syntax

name

IARCP64 macro

For REQUEST=DELETE:

Register

Contents

0-1

2-13


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


Unchanged.

14-15



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


IARCP64 macro

Syntax Description

,CELLNAME=cellname


,REGS=SAVE

,REGS=USE

cellname: RS-type address or address in register (2) - (12)

celladdr: RS-type address or address in register (2) - (12)


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


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


IARCP64 macro


The current task is to be the owner. Do not specify this unless the program is in task mode.


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.


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.


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:


1-byte field.


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.


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


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:


A required input parameter that contains the cell pool ID returned on the successful BUILD request.

To code:


8-character field.


An optional output parameter of the obtained cell. If CELLADDR is not specified, the cell address is left in register 1.

To code:


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.


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:



A required input parameter that identifies the cell to free.


The name of the cell to free.

To code:

Specify the RS-type address, or address in register (2) - (12), of a character field.


The address of the cell to free.

To code:




An optional input parameter that contains the cell pool ID returned on the

BUILD request.

To code:


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:


A required input parameter that contains the cell pool ID returned on the

BUILD request.

To code:


8-character field.

34


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.


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


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:


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.


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


IARCP64 REQUEST=GET,INPUT_CPID=theCPID,

CELLADDR=theCellAddr,

EXPAND=NO,

FAILMODE=RC,

REGS=SAVE,


(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



v Save and restore registers


IARCP64 REQUEST=FREE,

CELLADDR=theCellAddr,

REGS=SAVE

IAXSERVC

DYNAREA DSECT theCPID DS D theCellAddr DS D


4.

Delete the pool.


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


39

IARCP64 macro

40


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


Environment



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


24-, 31- or 64-bit.


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.


None.

Restrictions

None.


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.


When control returns to the caller, the GPRs contain:

Register

Contents


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.


Return code.


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.



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


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


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.


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


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


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


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


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


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






AMODE:

ASC mode:


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


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.


47

IARST64 macro


Locks:


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.



None.

Restrictions

None.


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.


When control returns to the caller, the 64-bit GPRs contain:

For REQUEST=GET

13

14

15

Register

Contents

0


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.



For REQUEST=FREE

48


⌂

Syntax

name

IARST64 macro

Register

Contents

0-1

2-12


v Unchanged, if REGS=SAVE was specified.

v Used as work registers by the system, if REGS=USE was specified.

13

Unchanged.

14-15



Register

Contents

0-1

2-13


Unchanged.

14-15


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.


None.

Syntax

The IARST64 macro is written as follows:

Description


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


,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


|

|

IARST64 macro

Syntax

,AREANAME=areaname


,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


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.


51

IARST64 macro


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


,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=IPT



,OWNINGTASK=RCT

When COMMON=NO and REQUEST=GET are specified, a required parameter that indicates the task that is to be considered the owner.


This parameter indicates that the current task is to be the owner. Do not specify this parameter unless the program is in task mode.


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.


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.


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


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.


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


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


|

|

|

|

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.



When REQUEST=FREE is specified, a required input parameter.


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.


A parameter that contains the address of the area to free.

To code:



,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


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


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.


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.


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:

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:


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



xx041Axx xx041Bxx xx041Cxx xx0420xx xx0425xx xx0426xx

IARST64 macro


Equate Symbol:

IARST64AbendRsnCellNotInUse

Meaning:


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:


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.


57

IARST64 macro


xx0427xx xx0428xx xx0511xx xx0512xx xx0514xx xx0515xx xx0516xx


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:


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



xx0517xx xx0518xx xx0529xx xx052Axx xx052Bxx xx052Cxx xx052Dxx

IARST64 macro


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:


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.


59

|

IARST64 macro


xx052Exx


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.


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


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:

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:


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


IARST64 macro

Table 6. Return and Reason Codes for the IARST64 Macro (continued)

Hexadecimal

Return Code

08

Hexadecimal

Reason Code

xx0403xx


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,


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



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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

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.



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


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


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.



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.


Unchanged.


Return code.


Register

Contents

0-1

2-13


Unchanged.

14-15




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


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


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.


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.


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.


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


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:


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=MAX


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.



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.


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.


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

: The IARVSERV request completed successfully.

Action

: None required.

68


IARVSERV macro

Table 7. Return and Reason Codes for the IARVSERV Macro (continued)

Hexadecimal

Return Code

04

Hexadecimal

Reason Code

xx0101xx


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.


69

IARVSERV macro


Hexadecimal

Return Code

04

Hexadecimal

Reason Code

xx0301xx


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


70


IARVSERV macro


Hexadecimal

Return Code

0C

Hexadecimal

Reason Code

xx030Bxx


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


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


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


Load Target address


*

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


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



IARVSERV

� One or more blanks must follow IARVSERV.


,PLISTVER=MAX


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


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



IARVSERV

�

One or more blanks must follow IARVSERV.

SHARE

UNSHARE

CHANGEACCESS



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


IARVSERV macro


,COPYNOW

,RETAIN=NO

,RETAIN=YES

Default

: RETAIN=NO


,PLISTVER=MAX


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


75

IARVSERV macro

76


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

IARV64” on page 93)

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

IARV64” on page 108)

For guidance information on the use of 64–bit virtual storage allocation, see z/OS

MVS Programming: Assembler Services Guide.


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.


When the IARV64 macro returns control to your program: v

GPR 15 (and retcode, when you code RETCODE) contains a return 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

: 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


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


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


IARV64 macro

Table 8. Return and Reason Codes for the IARV64 Macro (continued)

Hexadecimal

Return Code

08

Hexadecimal

Reason Code

—


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,


MF=(E,V64L)

*

*

*

* Place code to check return/reason codes here

*

*************************************************************

* Free the storage *

*************************************************************

IARV64 REQUEST=DETACH,MEMOBJSTART=O,


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






AMODE:

ASC mode:


Locks:


Requirement

Problem state and PSW key 8-15.

Task or SRB


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


Enabled for I/O and external interrupts

No locks may be held.



None.

Restrictions

No data space ALETs can be specified.


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.



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


Return code


Register

Contents

80


Syntax

name

IARV64 macro

0-1

2-13

Used as work registers by the system

Unchanged

14-15




None

Syntax

The REQUEST=GETSTOR option of the IARV64 macro is written as follows:

Description


⌂

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


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=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:


,MF=S

,MF=(L,list addr)



,MF=(E,list addr)


Default:

MF=S


82


Syntax

IARV64 macro

Description

Parameters


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.


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:


,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


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:


,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


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


|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

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


This parameter indicates that code will obey the current system default.

,EXECUTABLE=YES


,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


GPR 15.

To code:

Specify the RS-type address of a fullword field, or register (2)-(12).

,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX

,PLISTVER=0, 1


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.


87

IARV64 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 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 , 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








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.


,list addr



,attr


,COMPLETE

Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

88


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






AMODE:

ASC mode:


Locks:


Requirement


Task or SRB


31- or 64-bit




Control parameters must be in the primary address space and can reside both below and above the bar.


None.

Restrictions






0

1

Register

Contents



2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15



89

IARV64 macro

Syntax



None

Syntax

The REQUEST=PAGEOUT option of the IARV64 macro is written as follows:

Description

�

name



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




Default:


,PLISTVER=MAX

,PLISTVER=0, 1

Default:

MF=S


,MF=S

,MF=(L,list addr)



,MF=(E,list addr)


90


IARV64 macro

Parameters


name


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.


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.


To code:



,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:


,RETCODE=retcode


GPR 15.

To code:


,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX


91

IARV64 macro

,PLISTVER=0, 1








– 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










,list addr



92


IARV64 macro

,attr


,COMPLETE


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






AMODE:

ASC mode:


Locks:


Requirement


Task or SRB


31- or 64-bit






None.

Restrictions






0

1

Register

Contents



2-13

14

15

Unchanged


Return code



93

IARV64 macro

Syntax

Register

Contents

0-1

2-13


Unchanged

14-15




None

Syntax

The REQUEST=PAGEIN option of the IARV64 macro is written as follows:

Description

�

name



IARV64

� One or more blanks must follow IARV64.

REQUEST=PAGEIN

,RANGLIST=ranglist ranglist: RS-type address or address in register (2) - (12).


,NUMRANGE=1


Default:

NUMRANGE=1


,RETCODE=retcode

,RSNCODE=rsncode rsncode: RS-type address or register (2) - (12).


Default:


,PLISTVER=MAX

,PLISTVER=0, 1

,MF=S

,MF=(L,list addr)

Default:

MF=S

list addr: RS-type address or register (1) - (12).

94


IARV64 macro

Syntax



,MF=(E,list addr)


Description

Parameters


name


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.


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.


NUMPAGES


The number of pages specified starting with the specified VSA must lie within a single memory object.


To code:



,NUMRANGE=1



To code:



95

IARV64 macro

,RETCODE=retcode


GPR 15.

To code:


,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX

,PLISTVER=0, 1








– 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








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


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.


,list addr



,attr


,COMPLETE


REQUEST=DISCARDDATA option of IARV64

REQUEST=DISCARDDATA allows you to discard data within physical pages of one or more memory objects.

Environment






AMODE:

ASC mode:


Locks:


Requirement


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


31- or 64-bit




Control parameters must be in the primary address space and can reside both below and above the bar.


None.

Restrictions



97

IARV64 macro

Syntax





0

1

Register

Contents


2-13

14

15


Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None

Syntax

The REQUEST=DISCARDDATA option of the IARV64 macro is written as follows:

Description

name

�



IARV64

�


REQUEST=DISCARDDATA

98


Syntax

,KEEPREAL=YES

,KEEPREAL=NO

,CLEAR=YES

,CLEAR=NO


Description

Default:

Default:

KEEPREAL=YES

CLEAR=YES

ranglist: RS-type address or address in register (2) - (12).


,NUMRANGE=1


Default:

NUMRANGE=1


,RETCODE=retcode

,RSNCODE=rsncode rsncode: RS-type address or register (2) - (12).


Default:


,PLISTVER=MAX

,PLISTVER=0, 1

Default:

MF=S


,MF=S

,MF=(L,list addr)



,MF=(E,list addr)


IARV64 macro

Parameters


name


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.


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.


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.


NUMPAGES


The number of pages specified starting with the specified VSA must lie within the memory object.


To code:



,NUMRANGE=1



To code:


,RETCODE=retcode


GPR 15.

100


IARV64 macro

To code:


,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX

,PLISTVER=0, 1








– CONVERTSIZE64

– CONVERTSTART

– GUARDSIZE64

To code:


,MF=S










101

IARV64 macro


,list addr



,attr


,COMPLETE


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






AMODE:

ASC mode:


Locks:


Requirement


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






None.

Restrictions




102


�

Syntax

name

IARV64 macro



0

1

Register

Contents



2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None

Syntax

The REQUEST=CHANGEGUARD option of the IARV64 macro is written as follows:

Description



IARV64

�


REQUEST=CHANGEGUARD

,CONVERT=TOGUARD

,CONVERT=FROMGUARD


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=(E,list addr)


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=rsncode


Default:


,PLISTVER=MAX

,PLISTVER=0, 1

Default:

MF=S


Parameters


name


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


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


,COND=YES

The request is conditional. The request will not be abnormally ended when a MEMLIMIT violation would occur.


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.


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:


,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:


,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:


106


IARV64 macro

,RETCODE=retcode


GPR 15.

To code:


,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX

,PLISTVER=0, 1








– 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










107

IARV64 macro



,list addr



,attr


,COMPLETE


REQUEST=DETACH option of IARV64

REQUEST=DETACH allows you to free one or more memory objects.

Environment






AMODE:

ASC mode:


Locks:


Requirement


Task or SRB


Note:

that problem state caller running in PSW key 8-15 can use GETSTOR/DETACH only when primary = home.

31- or 64-bit






None.

Restrictions




108


�

Syntax

name

IARV64 macro



0

1

Register

Contents



2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None

Syntax

The REQUEST=DETACH option of the IARV64 macro is written as follows:

Description



IARV64

�


REQUEST=DETACH

,MATCH=SINGLE

,MATCH=USERTOKEN


Default:

MATCH=SINGLE

memobjstart: RS-type address or address in register (2) - (12).


109

IARV64 macro


,USERTKN=usertkn

,USERTKN=NO_USERTKN

,USERTKN=usertkn

,OWNER=YES


Default:

USERTKN=NO_USERTKN


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


Default:


,PLISTVER=MAX

,PLISTVER=0, 1

Default:

MF=S


,MF=S

,MF=(L,list addr)



,MF=(E,list addr)




Parameters


name


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


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.


When MATCH=SINGLE is specified, a required input parameter that contains the address of the first byte in the memory object.

To code:


,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:


,USERTKN=usertkn

When MATCH=USERTOKEN is specified, a required input parameter that identifies the user token.

To code:


,OWNER=YES

An optional parameter that specifies whether the owning task still exists. The default is OWNER=YES.


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:


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


,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


GPR 15.

To code:


,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX

,PLISTVER=0, 1


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


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 1

, supports both the following parameters and parameters from version 0:

– CONVERTSIZE64

– CONVERTSTART

– GUARDSIZE64

To code:


,MF=S










,list addr



,attr



113

IARV64 macro

,COMPLETE


114


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


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


EP=entry name


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


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


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






AMODE:

ASC mode:


Locks:


Requirement

Problem state and PSW key 8-15

Task


31-bit or 64-bit



The caller is not required to hold any locks on entry. The caller may hold the local, CMS, or CPU lock.

None.


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.


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.



Register

Contents

0

The value placed in register 0 by the target routine prior to its returning to the system.


119

IEAARR macro

Syntax

1

2-13

14

15


Unchanged




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


Unchanged





None.

Syntax

The IEAARR macro is written as follows:

Description

name

⌂


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


IEAARR macro


,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


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:


,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:


,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


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


2-13

Unchanged from the IEAARR caller

14

15



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:


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


IEAARR TARGETPTR=TP,ARRPTR=AP,PARAMPTR=PP,

ARRPARAMPTR=APP,TARGETSTATE=PROB

...

124


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.


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


Register information

Because IEABRC is not an executable macro, there is no need to save and restore register contents.


None.

Syntax

The IEABRC macro is written prior to any base/displacement branch that needs to be converted to a relative branch as follows:


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


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.


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)


B X+Y



IEABRCX changes no registers, so there is no need to save and restore register contents.


None.


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


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


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task or SRB


31-bit



The caller is not required to hold any locks on entry. The caller may hold the local, CMS, or CPU lock.

None


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.


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.



Register

Contents


131

⌂

Syntax

name

0

1

Reason code, when GPR 15 is non-zero


2-13

Unchanged

14-15


15

Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

The IEAFP macro is written as follows:

Description


One or more blanks must precede IEAFP.

IEAFP

⌂ One or more blanks must follow IEAFP.

STOP

STOPVECTOR

,RETCODE=retcode

,RSNCODE=rsncode



Parameters


132


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


GPR 15.

To code:


,RSNCODE=rsncode


GPR 0.

To code:


ABEND codes

None.


When the IEAFP macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return 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


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.


IEAFP STOP

134


|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

||

||

|

||

||

||

||

||

|

||

||

|||

|

|

|

|

|

|

|

Chapter 12. IEAGSF — Guarded-Storage Facility services

Environment


Environmental Factor Requirement




AMODE:

ASC mode:


Locks:



Task

For START and STOP: Any PASN, any HASN, any SASN.

For UPDATE: PASN=HASN

31- or 64-bit



The caller is not required to hold any locks on entry, but may hold the LOCAL lock.


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


Register

Contents


135

|

|

|

|

|

||

||

||

|

|

|

|

|

|

|

||

||

||

||

||

|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

| |

|

||||||||||||||||

||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

| |

|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

|

0

1

Reason code, when GPR 15 is non-zero


2-13

Unchanged

14-15


15

Return code


Register

Contents

0-1

2-13


Unchanged

14-15



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


|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

Parameters


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:


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)





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


,COMPLETE


,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=MAX

,PLISTVER=0







To code:

Specify one of the following: v IMPLIED_VERSION v MAX v A decimal value of 0

,RETCODE=retcode


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


|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

,RSNCODE=rsncode


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:


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:


32-character field.

,UPDATEMASK=0001













139

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|




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.


specifies that only the fourth doubleword is to be updated.


specifies that only the third doubleword is to be updated.


specifies that only the third and fourth doubleword are to be updated.


specifies that only the second doubleword is to be updated.


specifies that only the second and fourth doubleword are to be updated.


specifies that only the second and third doublewords are to be updated.


specifies that only the second, third, and fourth doublewords are to be updated.


specifies that only the first doubleword is to be updated.


specifies that only the first and fourth doublewords are to be updated.


specifies that only the first and third doublewords are to be updated.


specifies that only the first and third and fourth doublewords are to be updated.


specifies that only the first and second doublewords are to be updated.


specifies that only the first and second and fourth doublewords are to be updated.


specifies that only the first and second and third doublewords are to be updated.


specifies that all four doublewords are to be updated.

ABEND Codes

None.

140


|

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.



Macro IHAGSRET provides equate symbols for the return and reason codes.

|||

|

|

|||

|

|

|

|

|||

|

|

| ||

|

||

|||

|

|

|

|||

|

|

|

|

|

|||

|

|||

|

|


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


Equate symbol

: IeaGsfRsnBadFunction

Meaning

: Incorrect value passed to target routine.

Action


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


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.


141

|

|

|

|

|

|

|

|||

|

|

|

|||

|

|

|

|

|

|

|||

|

|

|

|||

|

|

| ||

|

|

|||

|||

|

|

|

Table 10. Return and reason codes for the IEAGSF macro (continued)

Return code

C

Reason code

xxxx0C03


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:


IEAGSF START,INITIALCONTROLS=MYGSCB

142


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




:


:


:

AMODE

:

ASC mode

:

Interrupt Status

:

Locks

:

Requirement

Problem state with PSW key 8-15

Task or SRB


24- or 31- bit



The caller may hold locks, but is not required to hold any.


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.


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.


When control returns to the caller, the general purpose registers (GPRs) contain:

Register

Contents

0-1

2-13


Unchanged

14-15


When control returns to the caller, the access registers (ARs) contain:


143

IEAINTKN macro

Syntax

Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

The standard form of the IEAINTKN macro is written as follows:

Description

name

�

IEAINTKN

�

,TOKEN=inctoken addr


One or more blanks must precede IEAINTKN.

One or more blanks must follow IEAINTKN.

inctoken addr: RX-type address or register (2) - (12).

Parameters


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.


None.

Example

Provide an incident token in the area named MYTOKEN.

IEAINTKN TOKEN=MYTOKEN

.

.

144


.

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


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:


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




:


:


:

Amode

:

ASC mode

:


:

Locks

:


:

Requirement

Problem state, PSW key 8-15

Task


24- or 31-bit



No locks are required.



None.


147

IEALSQRY macro

Syntax

Restrictions

None.


Before issuing the IEALSQRY macro, the caller does not have to place any information into a general purpose register (GPR) or access register (AR).


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


Unchanged.


Return code.

When control returns to the caller from IEALSQRY, the access registers (ARs) contain:

Register

Contents

0-1

2-13


Unchanged.

14 and 15



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

�


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


IEALSQRY macro

Syntax

,RETCODE=retcode

Description

retcode: RS-type address, or register (2) - (12).

Default

: No retcode processing.


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

: 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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement

Any state or key

Task mode


31-bit

Primary or access register


None

Must be in the primary address space


None.

Restrictions

None.


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.



Register

Contents

0-1

2-13


Unchanged

14

15


Return code



151

IEAMETR macro

Syntax

Register

Contents

0-1

2-13


Unchanged

14-15



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


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


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


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


Chapter 16. IEANTCR — Create a name/token pair

Description

Call the IEANTCR service to create a name/token pair.

Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement

Problem state, with any PSW key

Task


31-bit



No locks held

The parameter list and all parameters must reside in the caller's primary address space.


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


155

IEANTCR callable service

Syntax

Restrictions

None.


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.



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




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



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


(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


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


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


Hexadecimal

Return Code

40


Decimal Return

Code

64


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


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


Chapter 17. IEANTDL — Delete a name/token pair

Description

Call the IEANTDL service to delete a name/token pair.

Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

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


31-bit



No locks held





*

IEANT_TASK_LEVEL

IEANT_HOME_LEVEL

IEANT_PRIMARY_LEVEL

IEANT_SYSTEM_LEVEL



EQU

EQU

EQU

EQU

EQU

EQU


*


*

IEANT_NOPERSIST

IEANT_PERSIST

EQU

EQU

*


*

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_AR_INVALID


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


161

IEANTDL callable service

Syntax

Restrictions

None.


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.



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax


Description

CALL IEANTDL

,(level

,user_name

,return_code)



CALL IEANTDL:

162



1.

LOAD EP=IEANTDL


...


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


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


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


4

8

Meaning


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


Action


Chapter 17. IEANTDL — Delete a name/token pair

163


Hexadecimal

Return Code

10

18

1C

20

28

40

Decimal Return

Code

16


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


Action

: Release all locks before issuing IEANTDL.

Meaning


Action


2, or 3.

Meaning


Action


Meaning


Action


Meaning


Action


Example

For a complete example of creating, retrieving, and deleting a task-level name/token pair, see the IEANTCR callable service.

164


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task


31-bit



The caller can hold a local, CML, or CMS lock; however, no locks are required.



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:


*

IEANT_TASK_LEVEL

IEANT_HOME_LEVEL

IEANT_PRIMARY_LEVEL

IEANT_SYSTEM_LEVEL



EQU

EQU

EQU

EQU

EQU

EQU


*


*

IEANT_NOPERSIST

IEANT_PERSIST

EQU

EQU

*


*

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


165

IEANTRT callable service

IEANT_NAME_INVALID


IEANT_AR_INVALID


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.


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.



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax


166



Syntax

CALL IEANTRT

Description

,(level

,user_name

,user_token

,return_code)



CALL IEANTRT:

1.

LOAD EP=IEANTRT


...


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


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


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


Hexadecimal

Return Code

00

04

08

1C

40

Decimal Return

Code

0


4

8

28

64

Meaning


Action

: None.

Meaning


Action


Meaning


Action


Meaning


Action


2, 3, or 4.

Meaning


Action


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



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


*********************************************************************

* 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


Chapter 19. IEAN4CR — Create a name/token pair

Description

Call the IEAN4CR service to create a name/token pair.

Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement

Problem state, with any PSW key

Task


64-bit



No locks held





*

IEANT_TASK_LEVEL

IEANT_HOME_LEVEL

IEANT_PRIMARY_LEVEL

IEANT_SYSTEM_LEVEL



EQU

EQU

EQU

EQU

EQU

EQU


*


*

IEANT_NOPERSIST

IEANT_PERSIST

IEANT_NOCHECKPOINT

IEANT_CHECKPOINTOK

EQU

EQU

EQU

EQU

*


*

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_AR_INVALID


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


171

IEAN4CR callable service

Restrictions

None.


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.



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax


Syntax


Description

CALL IEAN4CR

,(level

,user_name

,user_token

,persist_option

,return_code)

172





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


(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


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.


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


4

8

16

24

28

32

36

Meaning


Action

: None.

Meaning

: The user_name specified already exists.

Action

: Choose a different user_name.

Meaning


Action


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


Action

: Release all locks before issuing IEAN4CR.

Meaning


Action


2, or 3.

Meaning


Action


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


Hexadecimal

Return Code

28

40


Decimal Return

Code

40


64

Meaning


Action


Meaning


Action


Chapter 19. IEAN4CR — Create a name/token pair

175


176


Chapter 20. IEAN4DL — Delete a name/token pair

Description

Call the IEAN4DL service to delete a name/token pair.

Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


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


64-bit



No locks held





*

IEANT_TASK_LEVEL

IEANT_HOME_LEVEL

IEANT_PRIMARY_LEVEL

IEANT_SYSTEM_LEVEL



EQU

EQU

EQU

EQU

EQU

EQU


*


*

IEANT_NOPERSIST

IEANT_PERSIST

EQU

EQU

*


*

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_AR_INVALID


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


177

IEAN4DL callable service

Restrictions

None.


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.



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax


Syntax


Description

CALL IEAN4DL

,(level

,user_name

,return_code)



CALL IEAN4DL:

178



1.

LOAD EP=IEAN4DL


...


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


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


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


4

8

Meaning


Action

: None.

Meaning


Action


Meaning


Action


Chapter 20. IEAN4DL — Delete a name/token pair

179


Hexadecimal

Return Code

10

18

1C

20

28

40

Decimal Return

Code

16


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


Action

: Release all locks before issuing IEAN4DL.

Meaning


Action


2, or 3.

Meaning


Action


Meaning


Action


Meaning


Action


180


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task


64-bit



The caller can hold a local, CML, or CMS lock; however, no locks are required.



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:


*

IEANT_TASK_LEVEL

IEANT_HOME_LEVEL

IEANT_PRIMARY_LEVEL

IEANT_SYSTEM_LEVEL



EQU

EQU

EQU

EQU

EQU

EQU


*


*

IEANT_NOPERSIST

IEANT_PERSIST

EQU

EQU

*


*

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


181

IEAN4RT callable service

IEANT_NAME_INVALID


IEANT_AR_INVALID


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.


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.



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax


Syntax


Description

182



Syntax

CALL IEAN4RT

Description

,(level

,user_name

,user_token

,return_code)



CALL IEAN4RT:

1.

LOAD EP=IEAN4RT


...


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


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


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


Hexadecimal

Return Code

00

04

08

1C

40

Decimal Return

Code

0


4

8

28

64

Meaning


Action

: None.

Meaning


Action


Meaning


Action


Meaning


Action


2, 3, or 4.

Meaning


Action


184


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






AMODE:

ASC mode:


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



The caller must not hold any locks.


185

IEATDUMP transaction dump



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.


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.


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.



0

1

Register

Contents

Reason code


2-14

15

Unchanged

Return code


Register

Contents

0-1

2-13


Unchanged

14-15



None.

186


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


Syntax

The parameters DCB, DCBAD, and ASYNC=YES are no longer supported.

The IEATDUMP macro is written as follows:

Description


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


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


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=(E,list addr)



,MF=(M,list addr)

,MF=(M,list addr,COMPLETE)

,MF=(M,list addr,NOCHECK)

188



Parameters

The parameters DCB, DCBAD, and ASYNC=YES are no longer supported, and are removed from this information.


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.


189


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


,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



,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


,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




,SYMREC=symrec



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


190



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


,INTOKEN=intoken



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


,INTOKEN=intoken

A parameter of a 32-byte area that contains an incident token previously built by the IEAINTKN macro.

To code


32-character field.





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



A parameter of an area that contains information describing the problem.

This area has a maximum length of 1024 bytes.

To code


,LISTAD=listad

,LIST=list


,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


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


191


To code



,SUBPLST=subplst



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


,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



,DSPLIST=dsplist



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


,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


,SDATA=DEFS

,SDATA=ALLNUC

,SDATA=CSA

,SDATA=GRSQ

,SDATA=LPA

,SDATA=LSQA

,SDATA=NUC

,SDATA=RGN

,SDATA=SQA

,SDATA=SUM

,SDATA=SWA

192



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


193


,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


,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


,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


4-character field.

,RETCODE=retcode


GPR 15.

To code

: Specify the RS-type address of a fullword field, or register (2) - (12).

,RSNCODE=rsncode


GPR 0.

To code

: Specify the RS-type address of a fullword field, or register (2) - (12).


,PLISTVER=MAX

,PLISTVER=1





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



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=(M,list addr)

,MF=(M,list addr,COMPLETE)

,MF=(M,list addr,NOCHECK)






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


195


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


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


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


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

: 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



Table 13. Return and Reason Codes for the IEATDUMP Macro (continued)

Return Code

00000004

Reason Code

00000006


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.


197



Return Code

00000008

Reason Code

00000008


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


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


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




Return Code

00000008

Reason Code

00000015


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


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


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


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


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


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.


199



Return Code

00000008

Reason Code

00000020


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


PROBDESC(AD) has a valid ALET when the transaction dump is requested. Reissue IEATDUMP.

200




Return Code

00000008

Reason Code

0000002A


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


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


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


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


Reissue IEATDUMP.

Meaning

: The specified ECB(AD) was not valid. The ECB was not on a fullword boundary.

Action

: Reissue IEATDUMP with an ECB.


201

|



Return Code

00000008

Reason Code

00000035


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


IEATDUMP.

Meaning


Action


IEATDUMP.

Meaning


Action


IEATDUMP.

Meaning


Action


IEATDUMP.

202


|

|

|

|

|||

|

|||

|

|



Return Code

0000000C

Reason Code

00000007


Meaning


0000000C

0000000C

0000000C

0000000C

0000000C

0000000C

0000000C

00000010

00000008

00000009

0000000A

0000000B

0000000C

0000000D

000000FF xxxxxxxx

Action


IEATDUMP.

Meaning


Action


IEATDUMP.

Meaning


Action


IEATDUMP.

Meaning

: Unable to obtain storage for transaction dump from subpool 230 below the line.

Action


IEATDUMP.

Meaning


Action


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


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


203


E2 EQU *

DUMPTTL2 DC AL1(E3-S3)

S3

E3

DC

EQU

C’IEADUMP TO AUTOMATICALLY ALLOCATED DATA SET’

*

204


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






AMODE:

ASC mode:


Locks:


Requirement

Problem state with PSW key 8-15.

Task


31- or 64-bit



None.

None.


None.

Restrictions

None.


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



Register

Contents

0-1

2-13

14


Unchanged



205

IEATXDC macro

Syntax

15

Return code


Register

Contents

0-1

2-13


Unchanged

14-15



None.

Syntax

The IEATXDC macro is written as follows:

Description

name

�


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


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


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



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

: 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


Chapter 23. IEATXDC — Transactional execution diagnostic controls

207

IEATXDC macro

Table 14. Return codes for the IEATXDC Macro (continued)

Return Code

12


Meaning

: Service called in SRB mode.

Action

: Avoid using IEATXDC in SRB mode.

Examples

None.

208


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement

Problem state and any PSW key.

Task

PASN=HASN=SASN

31-bit

Primary


No locks held.

Must be in the primary address space and addressable by the caller.


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.


Before calling Allocate_Pause_Element, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:

Register

Contents


209

IEAVAPE callable service

Syntax

1

13

Address of the parameter address list.

Address of a 72-byte register save area.



Register

Contents

0-1

2-13


Unchanged

14

15


Return Code


Register

Contents

0-1

2-13


Unchanged

14-15



None.

Syntax


Description

CALL IEAVAPE

(return_code

,auth_level

,pause_element_token)

Parameters


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



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.


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

: Successful completion.

Action

: None.

IEA_SUCCESS

Chapter 24. IEAVAPE — Allocate_Pause_Element

211


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:

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


Meaning

: Program error. The calling program is not in primary ASC mode, which this service requires. The system rejects the service call.

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

: Retry the request later.

Meaning

: This service routine encountered an unexpected error. The system rejects this service request.

Action

: Contact IBM support.

212


Chapter 25. IEAVAPE2 — Allocate_Pause_Element

Description


Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

31-bit

Primary


No locks held



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



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.


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.


213

IEAVAPE2 callable service

Syntax



Register

Contents

1

13





Register

Contents

0-1


2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

Description

CALL IEAVAPE2

,(return_code

,pause_element_auth_level

,pause_element_token

,pause_element_owner_stoken

,owner_termination_release_code

,linkage)

Parameters


214


IEAVAPE2 callable service return_code


Type: Integer v Character Set: N/A v Length: 4 bytes


,pause_element_auth_level

Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes


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.




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.



IEA_CHECKPOINTOK 2

Meaning

The application can tolerate the pause elements' not being restored upon a restart after a checkpoint.

Note:



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


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




IEAVAPE2


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.



PURGEDQ.


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


Specifies how the Allocate_Pause_Element service routine is to be invoked. The following options are supported:


217


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


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_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:


Meaning:

Program error. The calling program is not in primary ASC mode, which this service requires.


Action:


218



Return code in: Decimal

(Hex)

48 (30)

Equate Symbol

56 (38)

4095 (FFF)

84 (54)

88 (58)

96 (60)

100 (64)


IEA_OUT_OF_STORAGE



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:


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:



219


220


Chapter 26. IEAVDPE — Deallocate_Pause_Element

Description

Deallocate_Pause_Element frees a pause element that is no longer needed.

Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

31-bit addressing mode.

Primary mode.


No locks held.




HLL Definition

IEAASM

IEAC

Description



Restrictions




Before calling Deallocate_Pause_Element, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:

Register

Contents

1

13





Register

Contents


221

IEAVDPE callable service

Syntax

0-1

2-13

14

15


Unchanged


Return code


Register

Contents

0-1


2-13

Unchanged

14-15




None.

Syntax


Description

CALL IEAVDPE

,(return_code

,auth_level


Parameters


return_code


Contains the return code from the Deallocate_Pause_Element service.

,auth_level


222



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.


Supplied parameter v Type: Character string v


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



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



Meaning

: Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.

Action



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



Chapter 26. IEAVDPE — Deallocate_Pause_Element

223


Return code in:

Decimal (Hex)

Equate symbol

36 (24)


40 (28)


44 (2C)

IEA_INVALID_MODE

60 (3C)

IEA_AUTH_TOKEN

64 (40)

IEA_PE_NOT_HOME

4095 (FFF)



Meaning


Action


Meaning

: Program error. The auth_level value specified in the call is not valid. The system rejects the service call.

Action



Meaning


Action



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


Meaning

: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was for a pause element allocated to another address.

Action



Meaning


Action


224


Chapter 27. IEAVDPE2 — Deallocate_Pause_Element

Description


Environment






AMODE:

ASC mode:


Locks:


Requirement


Task

PASN=HASN=SASN


Primary mode.


No locks held.



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



Restrictions


Key 1-15 or problem state callers must specify linkage as IEA_LINKAGE_SVC.



Register

Contents

1

13






225

IEAVDPE2 callable service

Syntax

Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax


Description

CALL IEAVDPE2

,(return_code


,linkage)

Parameters


return_code






226




linkage


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


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:


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:


Meaning:

Program error. One or more locks other than the local lock are held. The system rejects the service call.

Action:


Chapter 27. IEAVDPE2 — Deallocate_Pause_Element

227



(Hex)

32 (20)

Equate symbol

IEA_PE_BAD_STATE

36 (24)

44 (2C)


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:



Meaning:


Action:


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:


Meaning:

Program error. The pause element token was for an unauthorized pause element allocated to another address space.

Action:


Meaning:

Program error. The linkage value specified is not valid. The system rejects the service call.

4095 (FFF) IEA_UNEXPECTED_ERROR

Action:


Meaning:

This service routine encountered an unexpected error. The system rejects this service request.

Action:


228


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

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


Primary mode.


No locks held.




HLL Definition

IEAASM

IEAC

Description



Restrictions



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


229

IEAVPME2 callable service


Before calling the Pause service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:

Register

Contents

1

13


Note that register 13 is not required to contain any particular value. See the

workarea

parameter description.



Register

Contents

0-1


2-13

14

15

Unchanged


Return code.

Note that this service saves and restores full 64-bit GPRs.


Register

Contents

0-1

2-13


Unchanged

14-15




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



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


CALL IEAVPME2:

1.

LOAD EP=IEAVPME2

Save the entry point address...


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


return_code


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


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


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.


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


232



v Type: Integer v


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


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


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.


233



(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:


Action:

None.

Meaning:


Action:


Meaning:


Action:


Meaning:

The work unit has already been paused using the specified pause element token. The system rejects the service call.

Action:


Meaning:

Program error. The caller is holding one or more locks; no locks may be held. The system rejects the service call.

Action:


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.


Meaning:


Action:


Meaning:


Action:


234




(Hex)

53 (35)

Equate Symbol

IEA_ALREADY_SUSPENDED

61 (3D)

65 (41)

76 (4C)

80 (50)

84 (54)

104(68)

108(6C)


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:


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:


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:


Action:


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:


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:



235



(Hex)

4094(FFE)

Equate Symbol

IEA_ERROR_PETS_INVALIDATED

4095(FFF) IEA_UNEXPECTED_ERROR


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:


Action:


236


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






AMODE:

ASC mode:


Locks:


Requirement


Task or SRB

PASN=HASN=SASN


Primary mode.


No locks held.




HLL Definition

IEAASM

IEAC

Description



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.



Before calling the Pause service, the caller must ensure that the following general-purpose registers (GPRs) contain the specified information:

Register

Contents


237

IEAVPSE callable service

Syntax

1

13





Register

Contents

0-1

2-13


Unchanged

14

15


Return code.


Register

Contents

0-1

2-13


Unchanged

14-15



None.

Syntax


Description

CALL IEAVPSE

,(return_code

,auth_level


,updated_pause_element_token

,release_code)

Parameters


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



,auth_level

Supplied parameter: v


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.


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


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


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)


40 (28)


44 (2C)

IEA_INVALID_MODE

Meaning:


Action:

None

Meaning:


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:


Meaning:


Action:


Meaning:

Program error. The caller is holding one or more locks; no locks must be held. The system rejects the service call.

Action:


Meaning:


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:


Action:


Meaning:

Program error. The auth_level value specified in the call is not valid. The system rejects the service call.

Action:


Meaning:


Action:


240


Return code in:

Decimal (Hex)

Equate symbol

52 (34)


60 (3C)

IEA_AUTH_TOKEN

64 (40)

IEA_PE_NOT_HOME

4095 (FFF)




Meaning:


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:


Meaning:

Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was for a pause element allocated to another address.

Action:


Meaning:


Action:


Chapter 29. IEAVPSE — Pause service

241


242


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






AMODE:

ASC mode:


Locks:


Requirement


Task

PASN=HASN=SASN


Primary mode.


No locks held.





HLL Definition

IEAASM

IEAC

Description



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.


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


243

IEAVPSE2 callable service

Syntax



Register

Contents

1

13





Register

Contents

0-1


2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

Description

CALL IEAVPSE2

,(return_code



,release_code

,linkage)

Parameters


return_code

Returned parameter

244



v Type: Integer v





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.



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


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



Chapter 30. IEAVPSE2 — Pause service

245


Variable

IEA_LINKAGE_SVC

IEA_LINKAGE_BRANCH


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.


ABEND codes

Abend Code

AC7

Reason Code

001A0001

Description

This is an internal error.


Return code in:

Decimal (Hex)

00 (00)

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:


Action:

None

Meaning:


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:


Meaning:


Action:


Meaning:


Action:


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


Return code in:

Decimal (Hex)

36 (24)

Equate symbol


44 (2C) IEA_INVALID_MODE

52 (34)

60 (3C)


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




Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


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:


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:


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:


IEAVPSE2 from a suspend exit.

Meaning:


Action:


Meaning:


Action:


Chapter 30. IEAVPSE2 — Pause service

247


248


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN


Primary mode.


No locks held.




HLL Definition

IEAASM

IEAC

Description



Restrictions




Before calling the Release service, the caller must ensure that the following general purpose (GPRs) contain the specified information:

Register

Contents

1

13




249

IEAVRLS callable service

Syntax



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1


2-13

Unchanged

14-15




None.

Syntax

Description

CALL IEAVRLS

,(return_code

,auth_level

,target_du_pause_element_token

,target_du_release_code)

Parameters


return_code


Contains the return from the Release service.

,auth_level

Supplied Parameter v Type: Integer v Character Set: N/A

250



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


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


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



Decimal (Hex)

Equate symbol

00 (00)

IEA_SUCCESS

04 (04)

IEA_PE_TOKEN_BAD

Meaning


Action

: None.

Meaning

: The specified pause element token is not valid.


Action


Chapter 31. IEAVRLS — Release

251


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)


40 (28)


44 (2C)

IEA_INVALID_MODE

60 (3C)

IEA_AUTH_TOKEN

64 (40)

IEA_PE_NOT_HOME

4095 (FFF)



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


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


Meaning

: Program error. The pause element associated with the pause element token specified is invalid or has already been prereleased.

Action


Meaning


Action


Meaning


Action


Meaning


Action


Meaning


Action


Meaning


Action


Meaning


Action


252



Chapter 31. IEAVRLS — Release

253


254


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






AMODE:

ASC mode:


Locks:


Requirement


Task

PASN=HASN=SASN


Primary mode.


No locks held.





HLL Definition

IEAASM

IEAC

Description



Restrictions



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




255

IEAVRLS2 callable service

Syntax

Register

Contents

1

13





Register

Contents

0-1

2-13

14

15


Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

Description

CALL IEAVRLS2

,(return_code

,,target_du_pause_element_token

,target_du_release_code

,linkage)

Parameters


return_code

Returned parameter v Type: Integer v


256






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.



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


Specifies how the Release service routine is to be invoked. The following options are supported:

Variable

IEA_LINKAGE_SVC

IEA_LINKAGE_BRANCH


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


Chapter 32. IEAVRLS2 — Release

257


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_LOCK_HELD

36 (24) IEA_UNSUPPORTED_MVS_RELEASE


60 (3C)

64 (40)

IEA_PE_BAD_STATE

IEA_AUTH_TOKEN

IEA_PE_NOT_HOME


Meaning:


Action:

None.

Meaning:

The specified pause element token is not valid.


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:


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:


Meaning:

Program error. The pause element associated with the pause element token specified is invalid or has already been prereleased.

Action:


Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


258


Return code:

Decimal (Hex)

84 (54)

Equate symbol

IEA_INVALID_LINKAGE




Meaning:


Action:


Meaning:


Action:


Chapter 32. IEAVRLS2 — Release

259


260


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

31-bit addressing mode

Primary mode


No locks held.





HLL Definition

IEAASM

IEAC

Description



Restrictions

None.


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.


261

IEAVRPI callable service

Syntax



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1


2-13

Unchanged

14-15




None.

Syntax

Description

CALL IEAVRPI

,(return_code

,auth_level


,authorization

,owner

,state

,release_code)

Parameters


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



,auth_level

Supplied parameter v


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


0

1

The caller is not key 0 and supervisor state.

The caller is both key 0 and supervisor state.



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


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


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



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


,state



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


Note:

The returned value is random if the state parameter is not

IEAV_PET_RELEASED or IEAV_PET_PRERELEASED.

ABEND codes

None.

Return codes


264




(Hex)

00 (00)

Equate symbol

IEA_SUCCESS

04 (04)

08 (08)

24 (18)

36 (24)

44 (2C)

60 (3C)

64 (40)


IEA_PE_TOKEN_BAD

IEA_PE_TOKEN_STALE

IEA_LOCK_HELD


IEA_INVALID_MODE

IEA_AUTH_TOKEN

IEA_PE_NOT_HOME

Meaning


Action

: None

Meaning


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


Meaning


Action


Meaning


Action


Meaning


Action


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


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


Chapter 33. IEAVRPI — Retrieve_Pause_Element_Information service

265



(Hex)

4095 (FFF)

Equate symbol



Meaning


Action


266


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN


Primary mode.


No locks held.





HLL Definition

IEAASM

IEAC

Description





267

IEAVRPI2 callable service

Restrictions



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



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

268



Syntax

Syntax

CALL IEAVRPI2

Description

,(return_code

,pause_element_auth_level


,linkage

,owner_stoken

,current_stoken

,state

,release_code)

Parameters


return_code



,pause_element_auth_level


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.




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


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


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



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


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


Length: 4 bytes


Note:


270



State Constant

Hexadecimal

(Decimal)


1

(1)

IEAV_PET_RESET

2

(2)

IEAV_PET_RELEASED

40

(64)

Meaning

IEAV_PET_PAUSED

80

(128)






,release_code




Note:



ABEND codes

None.

Return code:

Decimal (Hex)

00 (00)

Return codes



IEA_SUCCESS


Meaning


Action

: None

Meaning


Action


Chapter 34. IEAVRPI2 — Retrieve_Pause_Element_Information service

271


Return code:

Decimal (Hex)

08 (08)

Equate symbol

IEA_PE_TOKEN_STALE

24 (18) IEA_LOCK_HELD


40 (28) IEA_INVALID_AUTHCODE

44 (2C)

60 (3C)

84 (54)

4095 (FFF)

IEA_INVALID_MODE


IEA_INVALID_LINKAGE



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


Meaning


Action


Meaning


Action


Meaning:


Action:


Meaning


Action


Meaning:


Action


Meaning

: Program error. The linkage value specified is not valid. The system rejects the service call.

Action


Meaning


Action


272


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN


Primary mode.


No locks held.





HLL Definition

IEAASM

IEAC

Description



Restrictions

None.


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.



Register

Contents

0-1



273

IEAVTPE callable service

Syntax

2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

Description

CALL IEAVTPE

,(return_code


,state

,release_code)

Parameters


return_code



Contains the return code from the Test_Pause_Element service.



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



v Character Set: N/A v

Length: 4 bytes


Note:



Hexadecimal

(Decimal)


1

(1)

IEAV_PET_RESET

2

(2)


IEAV_PET_RELEASED

40

(64)

IEAV_PET_PAUSED

80

(128)





,release_code



Note:



ABEND codes

None.

Return codes


Equate symbol Meaning and Action Return code in: Decimal

(Hex)

00 (00) IEA_SUCCESS

Meaning


Action

: None

Chapter 35. IEAVTPE — Test_Pause_Element service

275



(Hex)

04 (04)

Equate symbol

IEA_PE_TOKEN_BAD



Meaning


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


Action


276


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN


Primary mode.


No Locks held.




HLL Definition

IEAASM

IEAC

Description



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.


Before calling the Transfer service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:

Register

Contents

1

13




277

IEAVXFR callable service

Syntax



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1


2-14

15

Unchanged




None.

Syntax

Description

CALL IEAVXFR

,(return_code

,auth_level

,current_du_pause_element_token


,current_du_release_code



Parameters


return_code


Length: 4 bytes

Contains the return code from the Transfer service.

,auth_level

Supplied parameter

278



v Type: Integer v


Indicates the maximum authorization level of the pause element being deallocated. IEAASM and IEAC define constants IEA_UNAUTHORIZED and


Variable

IEA_UNAUTHORIZED

Value (HEX) Meaning

0 The pause elements must have been allocated with auth_level=_UNAUTHORIZED.

,current_du_pause_element_token


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.



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


Chapter 36. IEAVXFR — Transfer service

279


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.



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.




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


Meaning and Action Return Code in: Decimal

(Hex)

00 (00)

Equate symbol

IEA_SUCCESS


Meaning


Action

: None

Meaning


Action


280



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)


IEA_DUPLICATE_PAUSE

IEA_SLEEP_DISRUPTED


IEA_LOCK_HELD

IEA_PE_BAD_STATE



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


Meaning

: The work unit has already been paused using the specified pause element token. The system rejects the service call.

Action


Meaning


Action

: None

Meaning

: The address space that contains the task is terminating; no release is necessary.

Action

: None

Meaning


Action


Meaning


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.


Meaning


Action


Meaning



Action


Chapter 36. IEAVXFR — Transfer service

281



(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



Meaning


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


Action


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.


Meaning:

Program error. The specified current_du_pause_element_token and target_du_pause_element_token are the same.

Action


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


Action


282


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN


Primary mode.


No locks held.





HLL Definition

IEAASM

IEAC

Description



Restrictions



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



Register

Contents

1



283

IEAVXFR2 callable service

Syntax

13




Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-14

15


Unchanged



None.

Syntax


Description

CALL IEAVXFR2

,(return_code






,linkage)

Parameters


return_code


Length: 4 bytes


284






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.








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.




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


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:




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


Specifies how the Transfer service routine is to be invoked. The following options are supported:

Variable

IEA_LINKAGE_SVC

IEA_LINKAGE_BRANCH


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


Meaning and Action Return Code in:

Decimal (Hex)

00 (00)

Equate symbol

IEA_SUCCESS


Meaning


Action

: None

Meaning


Action


286


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_LOCK_HELD

32 (20) IEA_PE_BAD_STATE

36 (24)

44 (2C)


IEA_INVALID_MODE

52 (34)

60 (3C)


IEA_AUTH_TOKEN



Meaning


Pause or Transfer.

Action


Meaning


Action


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


Meaning


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


Action


Meaning


Action


Meaning


Action


Meaning:


Action


Chapter 37. IEAVXFR2 — Transfer service

287


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



Meaning:


Action:


Meaning

: Program error. The specified current_du_pause_element_token and target_du_pause_element_token are the same.

Action


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:


Action:


Meaning


Action


288


Chapter 38. IEA4APE — Allocate_Pause_Element

|

Description


Environment




:


:


:

AMODE

:

RMODE:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

64-bit

Includes 64-bit

Primary


No locks held.




(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



Restrictions







289

IEA4APE callable service

Register

Contents

1

13





Register

Contents

0-1

2-13

14

15


Unchanged


Return Code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

Syntax


Description

CALL IEA4APE

,(return_code

,auth_level


Parameters


return_code



290




,auth_level



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.



IEAASM and IEAC defined constants

IEA_UNAUTHORIZED


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.


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:




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


Return codes



Decimal (Hex)

Equate symbol

00 (0)

IEA_SUCCESS

24 (18)

IEA_LOCK_HELD

36 (24)


40 (28)

IEA_PE_NOT_HOME

44 (2C)

IEA_XFER_TO_SELF

48 (30)

IEA_XFER_FAILED

56 (38)


4095 (FFF)


Meaning


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.


Action


Meaning


Action


Meaning


Action


Meaning


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

: Retry the request later.

Meaning


Action:

Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center.

292


Chapter 39. IEA4APE2 — Allocate_Pause_Element

|

Description


Environment




:


:


:

AMODE

:

RMODE:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

64-bit

Includes 64-bit

Primary


No locks held.




(IEA4CSS from SYS1.CSSLIB) or load the calling program and then call the service.


HLL Definition

IEAASM

IEAC

Description



Restrictions



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


293

IEA4APE2 callable service



Register

Contents

1

13





Register

Contents

0-1


2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

Syntax


Description

CALL IEA4APE2

,(return_code


,pause_element_owner_stoken

,owner_termination_release_code

,linkage)

Parameters


294


IEA4APE2 callable service return_code






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


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:


IEA4APE


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.



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


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.



PURGEDQ.


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


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


Specifies how the Allocate_Pause_Element service routine is to be invoked. The following options are supported:

296



Table 23. Linkage option

Variable

IEA_LINKAGE_SVC

IEA_LINKAGE_BRANCH


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_INVALID_MODE

Meaning:


Action:

None.

Meaning:

Program error. One or more locks other than the local lock are held.


Action:


Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


Chapter 39. IEA4APE2 — Allocate_Pause_Element

297



(Hex)

48 (30)

Equate Symbol

IEA_OUT_OF_STORAGE

56 (38) IEA_NO_PETS_AVAILABLE



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:


Action:


298


Chapter 40. IEA4DPE - Deallocate_Pause_Element

|

Description


Environment




:


:


:

AMODE

:

RMODE:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

64-bit

Includes 64-bit

Primary mode.


No locks held.





HLL Definition

IEAASM

IEAC

Description



Restrictions





Register

Contents

1

13






299

IEA4DPE callable service

Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax


Syntax


Description

CALL IEA4DPE

,(return_code

,auth_level


Parameters


return_code



,auth_level

Supplied parameter v Type: Integer v Character Set: N/A

300



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.





ABEND codes

None.

Return codes



Decimal (Hex)

Equate symbol

00 (00)

IEA_SUCCESS

04 (04)

08 (08)

IEA_PE_TOKEN_STALE

24 (18)

IEA_LOCK_HELD

Meaning


Action

: None.

Meaning


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


Meaning


Action


Chapter 40. IEA4DPE - Deallocate_Pause_Element

301


Return code in:

Decimal (Hex)

Equate symbol

32 (20)

IEA_PE_BAD_STATE

36 (24)


40 (28)


44 (2C)

IEA_INVALID_MODE

60 (3C)

IEA_AUTH_TOKEN

64 (40)

IEA_PE_NOT_HOME

4095 (FFF)



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


Meaning


Action


Meaning


Action


Meaning

: Program error. The calling program is not in primary ASC mode, which this service requires.


Action


Meaning

: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was allocated with auth_level=AUTHORIZED.


Action


Meaning


Action


Meaning


Action:

Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM

Support Center.

302


Chapter 41. IEA4DPE2 — Deallocate_Pause_Element

|

Description


Environment






AMODE:

RMODE:

ASC mode:


Locks:


Requirement


Task

PASN=HASN=SASN

64-bit

Includes 64-bit

Primary mode.


No locks held.

Must in the primary address space and addressable by the caller.





HLL Definition

IEAASM

IEAC

Description



Restrictions




Register

Contents

1

13





Register

Contents


303

IEA4DPE2 callable service

0-1

2-13

14

15


Unchanged


Return code


Register

Contents

0-1


2-13

Unchanged

14-15




None.

Syntax


Syntax


Description

CALL IEA4DPE2

,(return_code


,linkage)

Parameters


return_code




Supplied parameter v Type: Character string v Character Set: N/A v

Length: 16 bytes


304


IEA4DPE2 callable service linkage



Specifies how the Deallocate_Pause_Element service routine is to be invoked.

The following options are supported:

Variable

IEA_LINKAGE_SVC

IEA_LINKAGE_BRANCH


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


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:


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


Action:


Meaning:

Program error. One or more locks other than the local lock are held.


Action:


Chapter 41. IEA4DPE2 — Deallocate_Pause_Element

305

IEA4DPE2 callable service


(Hex)

32 (20)

Equate symbol

IEA_PE_BAD_STATE

36 (24)

44 (2C)

64 (40)

4095 (FFF)


IEA_INVALID_MODE

IEA_PE_NOT_HOME



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:


Meaning:


Action:


Meaning:


Action:


Meaning:

Program error. The pause element token was for an unauthorized pause element allocated to another address space.

Action:


Meaning:


Action:


306


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

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


Primary mode.


No locks held.




HLL Definition

IEAASM

IEAC

Description



Restrictions



IEA_LINKAGE_SVC is limited to pausing upon no more than 1000 PETs.


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



Register

Contents

1

13


Note that register 13 is not required to contain any particular value. See the

workarea

parameter description.



Register

Contents

0-1

2-13


Unchanged

14

15


Return code.

Note that this service saves and restores full 64-bit GPRs.


Register

Contents

0-1

2-13


Unchanged

14-15




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



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


CALL IEA4PME2:

1.

LOAD EP=IEA4PME2

Save the 8-byte entry point address with bit 63 changed to 0 (...)


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


return_code


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.


,updated_pause_element_token_list


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


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.


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


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




v


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




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.


,workarea


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.


311



(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:


Action:

None.

Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


Meaning:

Program error. The caller is holding one or more locks; no locks may be held. The system rejects the service call.

Action:


Meaning:


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.


Meaning:


Action:


Meaning:


Action:


312




(Hex)

53 (35)

Equate Symbol


61 (3D)

65 (41)

76 (4C)

80 (50)

84 (54)

104(68)

108(6C)



IEA_PE_NOT_HOME

IEA_ABENDED_47B

IEA_INSUSPEND_EXIT

IEA_INVALID_LINKAGE

IEA_INVALID_NUMBER_OF_PETS

IEA_INVALID_NUMBER_TO_

RELEASE

Meaning:


Action:


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:


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:


Action:


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:


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:



313



(Hex)

4094(FFE)

Equate Symbol

IEA_ERROR_PETS_INVALIDATED

4095(FFF) IEA_UNEXPECTED_ERROR


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:


Action:


314


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




:


:


:

AMODE

:

RMODE:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

64-bit

Includes 64-bit

Primary mode


No locks held.





HLL Definition

IEAASM

IEAC

Description



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.





315

IEA4PSE callable service

Register

Contents

1

13





Register

Contents

0-1

2-13

14

15


Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

Syntax


Description

CALL IEA4PSE

,(return_code

,auth_level



,release_code)

Parameters


return_code



316




,auth_level


Indicates the maximum level that the specified pause element was allocated with. IEAASM and IEAC define constants IEA_UNAUTHORIZED and


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.



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.



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


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


ABEND codes

Abend Code

AC7

Reason Code

001A0001

Description

This is an internal error. Contact IBM support.

Return codes



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)


40 (28)


Meaning


Action

: None.

Meaning


Action


Meaning


Transfer service. This service requires the updated PET be returned on Pause or Transfer.

Action


Meaning


Action


Meaning


Action


Meaning


Action



Meaning


Action


Meaning


Action


318


Return code in:

Decimal (Hex)

Equate symbol

44 (2C)

IEA_INVALID_MODE

52 (34)


60 (3C)

IEA_AUTH_TOKEN

64 (40)

IEA_PE_NOT_HOME

4095 (FFF)




Meaning


Action


Meaning


Action


Meaning

: Program error. The caller specified auth_level=UNAUTHORIZED, but the pause element token was allocated with auth_level=AUTHORIZED.


Action


Meaning


Action


Meaning


Action:


Support Center.

Chapter 43. IEA4PSE — Pause service

319


320


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






AMODE:

RMODE:

ASC mode:


Locks:


Requirement


Task

PASN=HASN=SASN

64-bit

Includes 64-bit

Primary mode


No locks held.






HLL Definition

IEAASM

IEAC

Description



Restrictions


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


321

IEA4PSE2 callable service



Register

Contents

1

13





Register

Contents

0-1


2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

Syntax


Description

CALL IEA4PSE2

,(return_code



,release_code

,linkage)

Parameters


return_code

Returned parameter

322



v Type: Integer v





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.



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


The release code is specified by the issuer of the release service, which can release the task or SRB of the paused condition.

,linkage



Variable

IEA_LINKAGE_SVC


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


Variable

IEA_LINKAGE_BRANCH


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.


Return code in:

Decimal (Hex)

00 (00)

Return codes



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:


Action:

None

Meaning:


Action:


Meaning:




Action:


Meaning:


Action:


Meaning:


Action:


Meaning


Action



324


Return code in:

Decimal (Hex)

36 (24)

Equate symbol



52 (34)

60 (3C)


IEA_AUTH_TOKEN


76 (4C) IEA_ABENDED_47B

80 (50) IEA_IN_SUSPEND_EXIT




Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


Meaning:

After an SRB received ABEND 47B, it invoked IEA4PSE2. It is not valid to invoke IEA4PSE2 after receiving ABEND 47B.

Action:


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:


IEA4PSE2 from a suspend exit.

Meaning:


Action:


Support Center.

Chapter 44. IEA4PSE2 — Pause service

325


326


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

64-bit

Primary mode.


No locks held.



Either link the calling program's object code with the linkable stub routine


HLL Definition

IEAASM

IEAC

Description



Restrictions





Register

Contents

1

13




327

IEA4RLS callable service



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1


2-13

Unchanged

14-15




None.

Syntax

Syntax


Description

CALL IEA4RLS

,(return_code

,auth_level



Parameters


return_code



,auth_level

Supplied Parameter v Type: Integer

328




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.



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.



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



Decimal (Hex)

Equate symbol

00 (00)

IEA_SUCCESS

04 (04)

IEA_PE_TOKEN_BAD

Meaning


Action

: None.

Meaning

: The specified pause element token is not valid.


Action


Chapter 45. IEA4RLS — Release

329


Return code in:

Decimal (Hex)

Equate symbol

08 (08)

IEA_PE_TOKEN_STALE

16 (10)

IEA_SLEEP_DISRUPTED

20 (14)


24 (18)

IEA_LOCK_HELD

32 (20)

IEA_PE_BAD_STATE

36 (24)


40 (28)


44 (2C)

IEA_INVALID_MODE

60 (3C)

IEA_AUTH_TOKEN

64 (40)

IEA_PE_NOT_HOME

4095 (FFF)



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


Meaning

: RTM has ended the task; no release is necessary.

Action

: None.

Meaning


Action

: None.

Meaning


Action


Meaning

: Program error. The pause element associated with the pause element token specified is not valid or has already been prereleased.

Action


Meaning


Action


Meaning


Action


Meaning


Action


Meaning


Action


Meaning


Action


Meaning


Action


330


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






AMODE:

ASC mode:


Locks:


Requirement


Task

PASN=HASN=SASN

64-bit

Primary mode.


No locks held.






HLL Definition

IEAASM

IEAC

Description



Restrictions


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



Register

Contents


331

IEA4RLS2 callable service

1

13





Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

Syntax


Description

CALL IEA4RLS2

,(return_code



,linkage)

Parameters


return_code


Length: 4 bytes


332






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.



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


Specifies how the Release service routine is to be invoked. The following options are supported:

Variable

IEA_LINKAGE_SVC

IEA_LINKAGE_BRANCH


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



IEA_SUCCESS

Meaning:


Action:

None.

Chapter 46. IEA4RLS2 — Release

333


Return code in:

Decimal (Hex)

04 (04)

Equate symbol

IEA_PE_TOKEN_BAD


16 (10)

20 (14)

24 (18)

IEA_SLEEP_DISRUPTED


IEA_LOCK_HELD







Meaning:

The specified pause element token is not valid. The system rejects the service call.

Action:


Meaning:




Action:


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:


Meaning:

Program error. The pause element associated with the pause element token specified is invalid or has already been prereleased.

Action:


Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


334


Return code in:

Decimal (Hex)

4095 (FFF)

Equate symbol




Meaning:


Action:


Support Center.

Chapter 46. IEA4RLS2 — Release

335


336


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


Environment




:


:


:

AMODE

:

RMODE:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

64-bit

Includes 64-bit

Primary mode.


No locks held.



Either link the object code of calling program with the linkable stub routine


HLL Definition

IEAASM

IEAC

Description



Restrictions

None.


337

IEA4RPI callable service





Register

Contents

0-1

2-13

14

15


Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

Syntax


Description

CALL IEA4RPI

,(return_code

,auth_level


,authorization

,owner

,state

,release_code)

Parameters


return_code

Returned parameter v Type: Integer

338




Length: 4 bytes


,auth_level


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


0 The caller is not key 0 and supervisor state.

1 The caller is both key 0 and supervisor state.




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


Length: 4 bytes




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




,owner

Returned parameter v Type: Character string

Chapter 47. IEA4RPI — Retrieve_Pause_Element_Information service

339



Length: 8 bytes


,state



Note:

The value returned is the state at the time the service obtained it. The state might have changed after it was obtained.


Hexadecimal

(Decimal)

IEA4_PET_PRERELEASED

1

(1)

IEA4_PET_RESET

2

(2)


IEA4_PET_RELEASED

40

(64)

IEA4_PET_PAUSED

80

(128)



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.


,release_code


The release code is specified by the issuer of the release service, which can release the task or SRB from the paused condition.

Note:


IEA4_PET_RELEASED or IEA4_PET_PRERELEASED.

ABEND codes

None.

340



Return codes



(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

Meaning


Action

: None.

Meaning


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


Meaning


Action



Meaning


44 (2C)

60 (3C)

64 (40)

IEA_INVALID_MODE

IEA_AUTH_TOKEN

IEA_PE_NOT_HOME

Action


Meaning


Action


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


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


Chapter 47. IEA4RPI — Retrieve_Pause_Element_Information service

341



(Hex)

4095 (FFF)

Equate symbol



Meaning


Action:


342


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


Environment




:


:


:

AMODE

:

RMODE:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

64-bit

Includes 64-bit

Primary mode.


No locks held.



Either link the object code of calling program with the linkable stub routine


HLL Definition

IEAASM

IEAC

Description



Restrictions



343

IEA4RPI2 callable service





Register

Contents

0-1

2-13

14

15


Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

Syntax


Description

CALL IEA4RPI2

,(return_code


,linkage

,owner

,current_stoken

,authorization

,state

,release_code)

Parameters


return_code

Returned parameter

344



v Type: Integer v





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


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


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



,current_stoken


Chapter 48. IEA4RPI2 — Retrieve_Pause_Element_Information service

345


|

|

|

|

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





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.



,state



Note:



Hexadecimal

(Decimal)


1

(1)

IEA4_PET_RESET

2

(2)


IEA4_PET_RELEASED

40

(64)



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



State Constant

Hexadecimal

(Decimal)

IEA4_PET_PAUSED

80

(128)

Meaning


,release_code


The release code is specified by the issuer of the release service, which can release the task or SRB from the paused condition.

Note:



ABEND codes

None.

Return codes



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


Meaning


Action

: None.

Meaning


Action


Meaning


Pause or Transfer.

Action


Meaning


Action


Meaning


Action


Chapter 48. IEA4RPI2 — Retrieve_Pause_Element_Information service

347


Return code in:

Decimal (Hex)

40 (28)

Equate symbol







Meaning:


Action:


Meaning


Action


Meaning:


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


Meaning


Action:


348


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

64-bit

Primary mode.


No locks held.





HLL Definition

IEAASM

IEAC

Description



Restrictions

None.


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.



Register

Contents


349

IEA4TPE callable service

0-1

2-13

14

15


Unchanged


Return code


Register

Contents

0-1


2-13

Unchanged

14-15




None.

Syntax

Syntax


Description

CALL IEA4TPE

,(return_code


,state

,release_code)

Parameters


return_code


Contains the return code from the Test_Pause_Element service.


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



,state




Note:



Hexadecimal

(Decimal)


1

(1)

IEA4_PET_RESET

2

(2)


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.


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.


,release_code


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:



ABEND codes

None.

Return codes


Chapter 49. IEA4TPE — Test_Pause_Element service

351


Return code in:

Decimal

(Hex)

00 (00)

Equate symbol

IEA_SUCCESS




Meaning


Action

: None.

Meaning


Action


Meaning


Transfer service. This service requires the updated PET returned on Pause or Transfer.

Action


352


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




:


:


:

AMODE

:

RMODE:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

64-bit

Includes 64-bit

Primary mode.


No Locks held.





HLL Definition

IEAASM

IEAC

Description



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.



Register

Contents

1

13




353

IEA4XFR callable service



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1


2-14

15

Unchanged




None.

Syntax

Syntax


Description

CALL IEA4XFR

,(return_code

,auth_level






Parameters


return_code


Length: 4 bytes

Contains the return code from the transfer service.

354



,auth_level



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.



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:





The PET originally specified in current_du_pause_element_token cannot be reused after a successful call to pause or transfer service.




Chapter 50. IEA4XFR — Transfer service

355


Contains the release code set by the issuer of the release or transfer service that released the current task from the paused condition.




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:





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


Meaning and Action Return Code in: Decimal

(Hex)

00 (00)

Equate symbol

IEA_SUCCESS


Meaning


Action

: None.

Meaning


Action


356




(Hex)

08 (08)

Equate symbol

IEA_PE_TOKEN_STALE

12 (0C)

16 (10)

20 (14)

24 (18)

32 (20)

36 (24)

40 (28)


IEA_DUPLICATE_PAUSE

IEA_SLEEP_DISRUPTED


IEA_LOCK_HELD

IEA_PE_BAD_STATE



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


Meaning


Action


Meaning


Action

: None

Meaning


Action

: None

Meaning


Action


Meaning


Action


Transfer using a pause element token that has already been used to Pause or

Transfer by another unit of work.


Meaning


Action


Meaning



Action


Chapter 50. IEA4XFR — Transfer service

357



(Hex)

44 (2C)

Equate symbol

IEA_INVALID_MODE

52 (34) IEA_ALREADY_SUSPENDED


64 (40)

68 (44)

72 (48)

4095 (FFF)

IEA_PE_NOT_HOME

IEA_XFER_TO_SELF

IEA_XFER_FAILED



Meaning


Action


Meaning


Action


Meaning


Action


Meaning


Action


Meaning:

Program error. The specified current_du_pause_element_token and target_du_pause_element_token are the same.

Action


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


Action:

Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support

Center.

358


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




:


:


:

AMODE

:

RMODE:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

64-bit

Includes 64-bit

Primary mode.


No locks held.



Either link the calling program's object code with the linkable stub routine



HLL Definition

IEAASM

IEAC

Description



Restrictions


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



Register

Contents

1


13



359

IEA4XFR2 callable service



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1


2-14

15

Unchanged




None.

Syntax

Syntax


Description

CALL IEA4XFR2

,(return_code






,linkage)

Parameters


return_code




Supplied parameter

360



v Type: Character string v


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:









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.




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


CAUTION:




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


Specifies how the Transfer service routine is to be invoked. The following options are supported:

Variable

IEA_LINKAGE_SVC

IEA_LINKAGE_BRANCH


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



IEA_SUCCESS

04 (04)

08 (08)

IEA_PE_TOKEN_BAD

IEA_PE_TOKEN_STALE

Meaning


Action

: None

Meaning


Action


Meaning




Action


362


Return Code in:

Decimal (Hex)

12 (0C)

Equate symbol

IEA_DUPLICATE_PAUSE

16 (10)

20 (14)

24 (18)

IEA_SLEEP_DISRUPTED


IEA_LOCK_HELD




52 (34)

60 (3C)


IEA_AUTH_TOKEN



Meaning


Action


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


Meaning


Action



Meaning


Action


Meaning


Action


Meaning


Action


Meaning:


Action


Chapter 51. IEA4XFR2 — Transfer service

363


Return Code in:

Decimal (Hex)

64 (40)

Equate symbol

IEA_PE_NOT_HOME

68 (44) IEA_XFER_TO_SELF

72 (48) IEA_XFER_FAILED



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


Meaning

: Program error. The specified current_du_pause_element_token and target_du_pause_element_token are the same.

Action


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


Action:


Support Center.

364


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

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


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.



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:


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


⌂

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.


There are no input register requirements for issuing the IEFDDSRV macro.



0

1

Register

Contents

Reason code

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15



None.

Syntax

The standard form of the IEFDDSRV macro is written as follows:

Description


One or more blanks must precede IEFDDSRV.

IEFDDSRV

Chapter 52. IEFDDSRV — DD service

367

IEFDDSRV macro


⌂ 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



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



newddname: RS-type address, or register (2)-(12).

tcbptr: RS-type address, or register (2)-(12).


,PLISTVER=MAX

,PLISTVER=0

368


IEFDDSRV macro

Syntax

,PLISTVER=1

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



Description

Default

: MF=S

Parameters


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


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.


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:


,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:


,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:


,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


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


To code:



371

IEFDDSRV macro

,DSABPTR=dsabptr


To code:


,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


To code:


,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


To code:


,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:


,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


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:


,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


Note:

Multiple DDs with the same name are allowed, and all references to that DDNAME use the first DD found.

To code:


,DSABPTR=dsabptr


To code:


,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


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:


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:


,RETCODE=retcode


GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value is left in GPR 15.

To code:


(15), (GPR15), (REG15), or (R15).

,RSNCODE=rsncode


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


IEFDDSRV macro

To code:


(2)-(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).


,PLISTVER=MAX

,PLISTVER=0

,PLISTVER=1



v MAX

, if you want the parameter list to be the largest size currently possible.



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:


IMPLIED_VERSION v MAX v A decimal value of 0, or 1

,MF=S










375

IEFDDSRV macro



,list addr


MF=E, the name can be an RS-type address or an address in register

(1)-(12).

,attr


,COMPLETE


,NOCHECK


ABEND codes

None.


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


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:

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.


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:

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


|

|

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


Environmental Factor Requirement

||

||

|

|

|

|

|

||

|

|

|

|

|

|

||

||

||

||

|||

||

||

|




AMODE:

ASC mode:


Locks:


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.


If in Access Register ASC mode, specify SYSSTATE

ASCENV=AR before invoking this macro. Do not use ALET value 1 ("secondary") for addressing parameters.




Control parameters above 2GB are allowed for AMODE 64 callers only.

|

|

|

|

|

|


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.


|

|

|

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.


379

|

| |

|||||||||||||||||||||||||||||||||||||||||||||||

| |

||||||||||||||||||||||||||||||||

|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

|

||

||

||

||

||

|

|

|

|

||

||

||

|

|

|

|

|

|

|

|

|

|

|

|

||||||||||||||||

| |

|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

IEFOPZQ macro



Register

Contents

0

0-1

Reason code, when register 15 is not 0.


2-13

14

15

Unchanged.


Return code.


Register

0-1

2-13

Contents


Unchanged.

14-15




None.


►► ⌂ 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 = MAX

, PLISTVER = 0

, 0D

,

attr

, COMPLETE

)

)

►

►

►◄

380


|

|

|

|||||||||||||||||||||||||||||||||||||||||||||||||||||||

|||||||||||||||||||||||||||

|

||||||||||||||||||||||||||||||||||||

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|||||||||||||||||||||||||||||||||||||||||||||||||||||||

|

| |

||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

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


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:


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:


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:


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)




382


|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

IEFOPZQ macro



,list addr


MF=E, this can be an RS-type address or an address in register (1) - (12).

,attr


,COMPLETE


,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:


16-character field.


,PLISTVER=MAX

,PLISTVER=0





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


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


To code:


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


|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

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



To code:

Specify the RS-type address of a fullword field, or register (2) - (12) or

(15), (GPR15), (REG15), or (R15).


385

IEFOPZQ macro

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

,RSNCODE=rsncode



To code:


(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:


6-character field.

ABEND codes

None.


|

|

|

|

When the IEFOPZQ macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return code.



386


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.

|||

|

|

|||

|

|

|

|

|

|

|||

|||

|

|

|

|||

|

|

|||

|

|

|

|

|

|

|||

|||

|

|

|||

||

|||

|

|

|


Table 26. Return and reason codes for the IEFOPZQ macro

Return code

0

Reason code

–


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


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.


387

IEFOPZQ macro

|

|

|

|

|

|

|

|

|||

|

|

|

|

|||

|||

|

|

|||

|

|

|

|

|||

|

|

|

|

|||

|

|

|

|||

|

|||

|||

|

|

Table 26. Return and reason codes for the IEFOPZQ macro (continued)

Return code

8

Reason code

xxxx0806


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


|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

IEFOPZQ macro


* Invoke IEFOPZQ

IEFOPZQ REQUEST=BY_OLD,

DSNAME=d,

MEMBERS=NO,STATE=ACTIVE,

ARCH=ar,

STATUSINFO=NO,

ANSAREA=a,ANSLEN=al,


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.


* 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,


MF=(E,OPTQL)


* 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


IEFOPZAA

*

*

*

*

Example 3:

This example finds the matching DDName/Jobname pairs.


* 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, *


389

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

IEFOPZQ macro

DDNAME=dd,JOBNAME=j,

ANSAREA=(n),ANSLEN=al,


MF=(E,OPTQL)


* 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)


IEFOPZAA

*

*

*

390


|

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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31-bit






The caller should include the IEFZPRC mapping macro to get return and reason code equates for all the functions.


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.


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.



0

1

Register

Contents

Reason code when GPR15 is not 0


2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

REQUEST=ALLOCATE option of IEFPRMLB

Syntax

name

Syntax

The IEFPRMLB macro is written as follows:

Description


392


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


,RSNCODE=rsncode



Default


,PLISTVER=MAX


,MF=S

,MF=(L,list addr)



,MF=(E,list addr)


Default

: MF=S


Parameters


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


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.


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=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:


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:


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


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:


,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:


,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:


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


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:


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:


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


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


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.


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:


16-character field.

,RETCODE=retcode


GPR 15.


399

IEFPRMLB macro

To code:


,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX








To code:


,MF=S










400


IEFPRMLB macro

,list addr


(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


ABEND codes

None.


When the IEFPRMLB macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.


RSNCODE) contains reason code.

Return and reason code constants are defined in macro IEFZPRC.


Table 27. Return and Reason Codes for the IEFPRMLB Macro

Return Code

X'00'

Reason Code

—


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.


401

IEFPRMLB macro

Table 27. Return and Reason Codes for the IEFPRMLB Macro (continued)

Return Code

X'0C'

Reason Code

—


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


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


Equate Symbol

: PRMLB_CONCAT_Failed

Meaning

: Concatenation of the logical parmlib data sets failed

Action


Equate Symbol

: PRMLB_Reader_Load_Failed

Meaning

: Load of the parmlib read routine failed.

Action


Equate Symbol

: PRMLB_Unable_To_Access_DS

Meaning

: The parmlib read routine was unable to access the logical parmlib

Action


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


IEFPRMLB macro


Return Code

X'0C'

Reason Code

X'09'


Equate Symbol

: PRMLB_UNALLOC_Failed

X'0C'

X'0C'

X'0A'

X'0B'

Meaning

: Unallocation of the logical parmlib data sets failed.

Action


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


Equate Symbol

: PRMLB_Unknown_Reason

Meaning

: Return Code - Reason for failure is unknown.

Action


Equate Symbol

: PRMLB_Not_Task_Mode

Meaning

: Return Code - the caller is not in Task mode.

Action


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.


403

IEFPRMLB macro


Return Code

X'1C'

Reason Code

X'02'


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


IEFPRMLB macro


Return Code

X'20'

Reason Code

—


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


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


Description

name

�



IEFPRMLB

� One or more blanks must follow IEFPRMLB.

REQUEST=FREE

,RETMSG=NO

,RETMSG=YES



,CART=cart

Default

: RETMSG=NO


Default

: CONSOLID=NOCONSID



405

IEFPRMLB macro

Syntax

,CART=NOCART

,MSGBUF=msgbuf


,DDNAME=ddname


Description

Default

Default

: CART=NOCART


: MSGBUF=NOMSGBUF


callername: RS-type address or register (2) - (12),

,RETCODE=retcode

,RSNCODE=rsncode




Default


,PLISTVER=MAX


,MF=S

,MF=(L,list addr)



,MF=(E,list addr)


Default

: MF=S


Parameters


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



406


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.



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:


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:


8-character field.

,MSGBUF=msgbuf


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.


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


To code:


,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:


8-character field.


407

IEFPRMLB macro



IBM use.


Example:



THIS TASK

To code:


16-character field.

,RETCODE=retcode


GPR 15.

To code:


,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX








To code:


,MF=S





408


IEFPRMLB macro






,list addr


(1)-(12).

,attr


,COMPLETE


ABEND codes

None.



v

When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded


See the return codes in under REQUEST=ALLOCATE option of IEFPRMLB.

Examples

None.

REQUEST=LIST option of IEFPRMLB


409

IEFPRMLB macro

Syntax

Syntax


Description

�

name



IEFPRMLB

�

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



REQUEST=LIST

,BUFFER=buffer buffer: RS-type address or register (2) - (12).

callername: RS-type address or register (2) - (12).


,RETCODE=retcode

,RSNCODE=rsncode




Default


,PLISTVER=MAX


Default

: MF=S

list addr: RS-type address or register (1) - (12),

Parameters


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


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:




IBM use.


Example:



THIS TASK

To code:


16-character field.

,RETCODE=retcode


GPR 15.

To code:



411

IEFPRMLB macro

,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX








To code:


IMPLIED_VERSION v MAX v A decimal value of 0

,MF=S










412


IEFPRMLB macro

,list addr


(1)-(12).

,attr


,COMPLETE


ABEND codes

None.





See return codes under REQUEST=ALLOCATE option of IEFPRMLB.

Examples

None.

REQUEST=READMEMBER option of IEFPRMLB

Syntax

Syntax


Description



name

⌂

IEFPRMLB

⌂

REQUEST=READMEMBER

,DDNAME=ddname




413

IEFPRMLB macro

Syntax

,MEMNAME=memname

,READBUF=readbuf

,BLANK72=YES

,BLANK72=NO

,STARCOMMENT=NO

,STARCOMMENT=YES

,MSG=YES

,MSG=NO

,RETMSG=NO

,RETMSG=YES



,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


Default

: CONSOLID=NOCONSID


Default

: CART=NOCART

,MSGBUF=msgbuf



,RETCODE=retcode


Default

: MSGBUF=NOMSGBUF

callername: RS-type address or register (2) - (12).


,RSNCODE=rsncode rsncode: RS-type address or register (2) - (12).


Default


,PLISTVER=MAX


,MF=S

,MF=(L,list addr)



,MF=(E,list addr)

Default

: MF=S


414


IEFPRMLB macro

Syntax


Description

Parameters


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:


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:


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:


,BLANK72=YES


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


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.


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



,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


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.



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:


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:


8-character field.

,MSGBUF=msgbuf


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.


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


To code:




IBM use.


Example:


417

IEFPRMLB macro



THIS TASK

To code:


16-character field.

,RETCODE=retcode


GPR 15.

To code:


,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX




v MAX





To code:



,MF=S









418


IEFPRMLB macro



,list addr


(1)-(12).

,attr


,COMPLETE


ABEND codes

None.





See return codes under REQUEST=ALLOCATE option of IEFPRMLB.

Examples

None.


419

420


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

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)


No locks held



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.


421

IEFSSI macro

Syntax

Restrictions

The caller must not have established an EUT FRR.


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.



0

1

Register

Contents

Reason code


2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




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

�


One or more blanks must precede IEFSSI.

422


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=MAX


Default

: IMPLIED_VERSION

plistver: 1

,RETCODE=retcode

,RSNCODE=rsncode

,COM=com

,COM=NULL

,MF=S

,MF=(L,list addr)



,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


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=MAX


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


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.


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






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.


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.


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)


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


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)


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


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement

Problem state, with any PSW key.

Task or SRB


24- or 31- bit



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


If in AR mode, specify SYSSTATE ASCENV=AR before invoking the macro.

Restrictions

None.


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.



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


Unchanged



429

IOCINFO macro

Syntax

15

Return code


Register

Contents

0-1

2-13


Unchanged

14-15



None.

Syntax

The standard form of the IOCINFO macro is written as follows:

Description

�

name


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


Syntax

IOCINFO macro

Description

Parameters



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.


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.


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


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.


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


00

00

08

08

08

08

00

01

01

02

05

09

Meaning


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


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


Hexadecimal

Return Code

08

20

24

IOCINFO macro

Hexadecimal

Reason Code

0F

07


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

�



IOCINFO

�

MF=(L,list addr)

MF=(L,list addr,attr)


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:



433

IOCINFO macro

MF=(L,list addr,attr)


Specifies the list form of the IOCINFO macro.



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

�



IOCINFO

�


,CSSID=cssid addr

,MAXMBI=maxmbi addr




,MF=(E,list addr)


One or more blanks must follow IOCINFO.


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


rsncode addr: RX-type address or register (2) - (12).

list addr: RX-type address or register (2) - (12).

Default

: COMPLETE

434


IOCINFO macro

Parameters

The parameters are explained under the standard form of the IOCINFO macro with the following exceptions:



Specifies the execute form of the IOCINFO macro.


COMPLETE, which is the default, specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.


435

IOCINFO macro

436


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement

Problem or Supervisor state and any PSW key

Task or SRB


24- or 31-bit


Enabled or disabled for I/O and external interrupts.


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


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


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.


The contents of registers 14 through 1 are altered during processing.


Register

Contents

0

Reason code


437

IOSCHPD macro

Syntax

1

2-13

14

15

Unpredictable (Used as a work register by the system)

Unchanged


Return code


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)


None.

Syntax

The IOSCHPD macro is written as follows:

Description

⌂

name


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


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=MAX

,PLISTVER=1

,PLISTVER=2

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)


Description

Default

: LINKAGE=SYSTEM



Default


Default

: MF=S


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


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


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


,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


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


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


GPR 15.

To code

: Specify the RS-type address of a fullword field, or register (2)-(12).

,RSNCODE=rsncode


GPR 0.

To code



,PLISTVER=MAX

,PLISTVER=1

,PLISTVER=2







v 2 , which supports ATTR and WWPN, in addition to those from version 1.

To code

: Specify one of the following: v


,MF=S









441

IOSCHPD macro



,list addr



,attr


,COMPLETE


ABEND codes

None.


When the IOSCHPD macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return 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


IOSCHPD macro

Table 29. Return and reason codes for the IOSCHPD macro (continued)


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.


443

IOSCHPD macro

444


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.


On the first invocation of the IOSCUMOD macro, it includes the parameters listed below in the manufacturer's module.

Syntax

Restrictions

None.


None.

Syntax

The IOSCUMOD macro is written as follows:

Description


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.





445

IOSCUMOD macro

Syntax

,DCM_SUPPORTED=YES

,DCM_SUPPORTED=NO

Description

Default

: YES

Parameters


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


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.


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


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






AMODE:

ASC mode:


Locks:


Requirement

For LINKAGE=SYSTEM, problem state and any PSW key.

Task or SRB mode


31-bit or 64-bit


Primary


None


For LINKAGE=BRANCH, the parameter list (including any data areas pointed to by the parameter list) must reside in fixed or DREF storage.


None.

Restrictions

None.


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.



0

1

Register

Contents

Reason code if GPR15 is not 0


2-13

14

15

Unchanged


Return code



449

IOSSCM macro

►►

name



None.

Syntax

Register

Contents

0-1

2-13


Unchanged

14-15


⌂ IOSSCM ⌂ CONFIGINFO

DEVINFO

, INFOAREA =

infoareaptr

►

► ► , INFOAREALEN =

infoarealen

, OUTVERSION =

0

version

, LINKAGE = SYSTEM


, PLISTVER = MAX

, PLISTVER = 1

►

, RETCODE =

retcode

, RSNCODE =

rsncode

►

, MF = S

, MF = ( L ,

list addr

, MF = ( E ,

list addr

, 0D

,

attr

, COMPLETE

)

)

►

►◄

Parameters


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


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


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


GPR 0.

To code:


(12).


,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:


,MF=S








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


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


,COMPLETE


ABEND codes

None.


When the IOSSCM macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return 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


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

: 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


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




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.



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.


455

ISGENQ macro


AMODE:

ASC mode:


Locks:


Requirement

31- or 64-bit



If in access register ASC mode, specify SYSSTATE

ASCENV=AR before invoking this macro.


The caller must not be locked.


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.


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.


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.



Register

Contents

0

Reason code if GPR15 is not 0

456


ISGENQ macro

1

2-13

14

15


Unchanged


Return code


Register

Contents

0-1


2-13

Unchanged

14-15




None.

Chapter 60. ISGENQ — Global resource serialization ENQ service

457

ISGENQ macro


►►

►

,

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 = 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 =

owningttoken

,

,

CONTROL

CONTROL

=

=

EXCLUSIVE

SHARED

parameters-3

►►

, RESLIST = NO

, ENQTOKEN =

enqtoken

, RESLIST = YES , NUMRES =

numres

, ENQTOKENTBL =

enqtokentbl

, RETURNTABLE =

returntable

►


, OWNINGTTOKEN =

owningttoken

►

►

►◄

►

►◄

►

►◄

►

►◄

458


ISGENQ macro parameters-4

►►

►

,

, CONTENTIONACT = WAIT

CONTENTIONACT = FAIL

, WAITTYPE = SUSPEND


,

, 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

►

►◄

►

►◄

►

►


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


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:


,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


►

►

►

►

►

►◄

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:


,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


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.


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


Indicates that all requests are for exclusive control of the resources.

,CONTROL=SHARED

Indicates that all requests are for shared control of the resources.


462


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.


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:


,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:


32-character field.


When RESLIST=NO and REQUEST=CHANGE are specified, a required input parameter that is an ENQ Token of the ENQ to be changed.


463

ISGENQ macro

To code:


32-character field.


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:


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:



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:



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:


,MF=S










464


ISGENQ macro

,list addr



,attr


,COMPLETE


,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:


,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:


,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:


,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:


16-character field.



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.


CURRENT_TASK.

To code:


16-character field.


465

ISGENQ macro



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.


CURRENT_TASK.

To code:


16-character field.



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:


16-character field.



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:


16-character field.


,PLISTVER=MAX

,PLISTVER=1

,PLISTVER=2







v 2 , which supports both the following parameters and those from version 1:

USERDATA

466


ISGENQ macro

To code:


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:


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:


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.


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


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:


,RETCODE=retcode



To code:


(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:



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:



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.


To code:


,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:


,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


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:


,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:



,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:


,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


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



To code:



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


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:


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


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


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


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.


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


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:


,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:


,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

USERDATA for requests, see Chapter 61, “ISGQUERY — Global resource serialization query service,” on page 489.

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:


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


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.


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

Table 31.


When the ISGENQ macro returns control to your program: v GPR 15 (and retcode, when you code RETCODE) contains a return 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

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


475

ISGENQ macro

Table 31. Return and Reason Codes for the ISGENQ Macro (continued)

Return Code

04

Reason Code

—


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


476


ISGENQ macro


Return Code

04

Reason Code

xxxx0406


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


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


Equate Symbol

: ISGENQRsn_OtherSharedOwners

Meaning

: For REQUEST=CHANGE. The control cannot be changed to exclusive. There are other shared owners of the resource.

Action


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


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.


477

ISGENQ macro


Return Code

04

Reason Code

xxxx040D


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


478


ISGENQ macro


Return Code

08

Reason Code

xxxx0801


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


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


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


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.


479

ISGENQ macro


Return Code

08

Reason Code

xxxx0809


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


08


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


480


ISGENQ macro


Return Code

08

Reason Code

xxxx0810


Equate Symbol

: ISGENQRsn_BadUCB@

08


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


Meaning

: Bad SYNCHRES keyword parameter.

Action


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


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)


481

ISGENQ macro


Return Code

08

Reason Code

xxxx0817


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


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


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


ISGENQ macro


Return Code

08

Reason Code

xxxx081D


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


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


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


Action

: Ensure that the ALET of the userdata is valid. Its access register may not have been set up properly.


483

ISGENQ macro


Return Code

08

Reason Code

xxxx0824


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


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


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


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


ISGENQ macro


Return Code

0C

Reason Code

xxxx0C05


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.


485

ISGENQ macro


Return Code

0C

Reason Code

xxxx0C11


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


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


RNAME ADDR31

RNAME ALET

A(0)

AL1(L’RNAM2)

UCB@

RNAME LENGTH

AL1(ISGYENQ_kSYSTEM)


XL1’00’

XL4’00’

CL8’QNAME3’

F’0’

A(RNAM3)

F’0’

A(0)

AL1(L’RNAM3)

FLAGS

RESERVED

QNAME


RNAME ADDR31

RNAME ALET

UCB@

RNAME LENGTH

AL1(ISGYENQ_kSYSTEMS)


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)


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


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






AMODE:

ASC mode:


Locks:


Requirement


Task


31- or 64-bit



If in Access Register ASC mode, specify SYSSTATE

ASCENV=AR before invoking this macro.


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.


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.


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.


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.



0

1

Register

Contents

Reason code if GPR15 is not 0.


2-13

14

15

Unchanged


Return code.


Register

Contents

0-1


490


ISGQUERY macro

2-13

Unchanged

14-15




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


►► 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 = 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


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

►

►

►

►

►

►◄

►◄


493

ISGQUERY macro

Parameters


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:


,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:


,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:


,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:


,ANSDETAIL=SUMMARY

,ANSDETAIL=FULL

,ANSDETAIL=FULL2

494


ISGQUERY macro


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.


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.


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:


,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


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:


,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:


,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:


,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:


,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:



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:


32-character field.

,GATHERFROM=SYSTEM

496


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:


8-character field.

,MF=S








497

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


,list addr



,attr


,COMPLETE


,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:


,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:


,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


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:



,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 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


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:


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:


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


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,

see the TEST=YES function in Chapter 60, “ISGENQ — Global resource serialization ENQ service,” on page 455.

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:



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:


16-character field.


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:


16-character field.


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:


16-character field.

,RETCODE=retcode



To code:


(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:


,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:


,RNAME=rname

When RNAMEMATCH=PATTERN, SEARCH=BY_FILTER,

SCANACTION=START and REQINFO=QSCAN are specified, a required input

502


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:



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:



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.


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.


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:


,RSNCODE=rsncode


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:



,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


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:


8-character field.

,TTOKEN=ttoken


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:


16-character field.


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:


32-character field.


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:


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:


,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

USERDATA on an ISGENQ request, see Chapter 60, “ISGENQ — Global resource serialization ENQ service,” on page 455. Note that USERDATA

can only be attached to a request through the ISGENQ interface.

This request requires a version 2 parameter list.

506


ISGQUERY macro


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

ENQ service,” on page 455.

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.


USERDATAMATCH=PATTERN option.

ABEND codes

None.


When the ISGQUERY macro returns control to your program: v

GPR 15 (and retcode, when you code RETCODE) contains a return 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

: 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



507

ISGQUERY macro

Table 32. Return and Reason Codes for the ISGQUERY Macro (continued)

Return Code

04

Reason Code

xxxx0401


Equate Symbol

: ISGQUERYRsn_NoMatchingRNLE

04 xxxx0402

Meaning

: For a REQINFO=RNLSEARCH request. No matching

RNLE was found for the given resource name.

Action


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


Action


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


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


—

Action


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


508


ISGQUERY macro


Return Code

08

Reason Code

xxxx0801


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


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


Action


Equate Symbol

: ISGQUERYRsn_BadReqInfo

Meaning

: Bad REQINFO parameter.

Action


Equate Symbol

: ISGQUERYRsn_BadRNL

Meaning

: Bad RNL parameter.

Action


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.


509

ISGQUERY macro


Return Code

08

Reason Code

xxxx0808


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


Action

: Ensure that the ALET of the answer area is valid. Its access register might have been set up properly.

510


ISGQUERY macro


Return Code

08

Reason Code

xxxx080F


Equate Symbol

: ISGQUERYRsn_BadScanAction

08


Meaning

: Bad SCANACTION parameter.

Action


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


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


Equate Symbol

: ISGQUERYRsn_BadSearch

Meaning

: Bad SEARCH keyword parameter.

08

08


Action


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



511

ISGQUERY macro


Return Code

08

Reason Code

xxxx0817


Equate Symbol

: ISGQUERYRsn_BadRNameMatch

08 xxxx0818

Meaning

: Bad RNAMEMATCH keyword parameter.

Action


Equate Symbol

: ISGQUERYRsn_BadScope

Meaning

: Bad SCOPE keyword parameter.

08

08

08 xxxx0819 xxxx081A xxxx081B

Action


Equate Symbol

: ISGQUERYRsn_BadSerializeBy

Meaning

: Bad SERIALIZEBY keyword parameter.

Action


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


ISGQUERY macro


Return Code

08

Reason Code

xxxx0820


Equate Symbol

: ISGQUERYRsn_BadAnsDetail

08


Meaning

: Bad ANSDETAIL keyword parameter.

Action


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


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


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


Equate Symbol

: ISGQUERYRsn_BadAnalyze

Meaning

: The ANALYZE keyword parameter is not valid.

Action



513

ISGQUERY macro


Return Code

08

Reason Code

xxxx0828


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


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


ISGQUERY macro


Return Code

0C

Reason Code

xxxx0C06


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


515

ISGQUERY macro

* ***********************************************************************

ISGQUERY REQINFO=QSCAN,SCANACTION=START,

ANSAREA=MYAREA,ANSLEN=MYAREALEN,

SEARCH=BY_ENQTOKEN,ENQTOKEN=MYENQTOKEN,


X

X

X

* ***********************************************************************

* Start a resumable query for resources of a specific job that

* matches a specific QNAME and pattern RNAME

* ***********************************************************************



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

* ***********************************************************************



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,



X

X

X

* ***********************************************************************

* Quit a query that was started but not completed

* ***********************************************************************

ISGQUERY REQINFO=QSCAN,SCANACTION=QUIT,

RESUMETOKEN=MYRESTOKEN,


X

X

* ***********************************************************************

* Gather ENQ statistics for a particular address space

* ***********************************************************************

ISGQUERY REQINFO=ENQSTATS,

ANSAREA=MYAREA,ASID=MYASID,


X

X

* ***********************************************************************

* Gather query latch enhanced contention analysis (LATCHECA) data from the *

* global resource serialization queues for waiters delayed because of *

* contention *

*************************************************************************

516


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.


517

518


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31-bit

Primary


No locks held

Must be in the primary address space.


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.


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.


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



Register

Contents

0-1

2-13


Unchanged

14

15

Used as work register by the system

Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

520



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


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.


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


522


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31-bit

Primary


No locks held



The caller determines whether ITTUTERM processing was successful by examining the return code.

Restrictions



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


Before linking to ITTUTERM, the caller does not have to place any information into any access register (AR).



Register

Contents

0-1


2-13

Unchanged


523

ITTUTERM service

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




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:


1.

Issue the MVS LOAD macro to load the ITTUTERM service and obtain its entry point address.

2.


Parameters


label


LINK

LINKX


EP=ITTUTERM

Specifies the entry point name for the ITTUTERM service.


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






When the ITTUTERM service returns control to your program, Register 15 contains a return code.


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


526


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31-bit

Primary


No locks held



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



Before linking to ITTUWRIT, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:


527

ITTUWRIT service

Register

Contents

1

13

Address of parameter list


Before linking to ITTUWRIT, the caller does not have to place any information into any access register (AR).



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




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:


1.

Issue the MVS LOAD macro to load the ITTUWRIT service and obtain its entry point address.

2.


528



Parameters


label


LINK

LINKX


EP=ITTUWRIT

Specifies the entry point name for the ITTUWRIT service.


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.




When the ITTUWRIT service returns control to your program, Register 15 contains a return code.


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


530


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement

Problem state. PSW key 8 - 15

Task or SRB


31-bit

Primary

Enabled forI/O and external interrupts

No locks may be held


The data pointed to by DATAADDR must reside in the caller's primary address space.


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.


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



Register

Contents

0

Contains the reason code when GPR15 is not 0


531

ITZEVENT macro

Syntax

1

2-13

14

15


Unchanged


Contains the return code


Register

Contents

0-1


2-13

Unchanged

14-15


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.


None.

Syntax

The ITZEVENT macro is written as follows:

Description

name

⌂


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


Syntax


,DATALEN=datalen

,GTFID=gtfid

,GTFFID=gtffid

,FMTTYPE=HEX

,FMTTYPE=MODEL

,FMTTYPE=ROUTINE

,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,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:


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


Parameters


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:


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:


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.


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:


,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:


534


ITZEVENT macro


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:


,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:


,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:


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:


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.


535

ITZEVENT macro


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:


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:


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:


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.


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:


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


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


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:


,MF=S










This is an optional input parameter that specifies the macro form.




537

ITZEVENT macro



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.


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


ITZEVENT macro

Table 33. Return and Reason Codes for the ITZEVENT Macro

Return Code

0

Reason Code

—


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’


539

ITZEVENT macro

540


Chapter 66. ITZQUERY — Transaction trace query

Description

The ITZQUERY macro is used to query whether a transaction or work unit should be traced.

Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement

Problem state. PSW key 8 - 15

Task or SRB


31-bit

Primary


No locks may be held



Any module that invokes this macro must include the CVT and IHAECVT macros.

Restrictions

None.


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



0

1

Register

Contents

Reason code


2-13

14

15

Unchanged


Return code


541

ITZQUERY macro

Syntax


Register

Contents

0-1

2-13


Unchanged

14–15


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.


Specifying the MONTKN in a monitoring environment results in a faster query.

Syntax

The ITZQUERY macro is written as follows:

Description

name

⌂

ITZQUERY

⌂


One or more blanks must precede ITZQUERY.

,MONTKN=montkn

,MONTKN64=montkn

,MONTKN=0


,TRACELVL=tracelvl

,PLISTVER=

IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=0

,MF=S

,MF=(L,list addr)


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:


Default

: MF=S

list addr: RS-type address or register (1) - (12)

542


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


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.


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.


To code:

Specify the RS-type address, or address in register (2)-(12), of a 31-bit or 64-bit field.


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


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:


,MF=S










This is an optional input parameter that specifies the macro form.

544


ITZQUERY macro





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


(1)-(12).

,attr


,COMPLETE


,NOCHECK


ABEND codes

None.


When the ITZQUERY macro returns control to your program, GPR 15 contains a return 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


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




:


:


:

AMODE

:

ASC mode

:


:

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



No locks held.


547

IXGBRWSE macro



:

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


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


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.


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.



0

1

Register

Contents

Reason code, if register 15 contains a non-zero return code


2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15


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



Chapter 67. IXGBRWSE — Browse/read a log stream

549

IXGBRWSE macro

Syntax


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

�


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


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=MAX


,RETCODE=retcode

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)

,MF=(M,list addr,COMPLETE)


IXGBRWSE macro

Description

Default

: MODE=SYNC


Default

: DIAG=NO_DIAG

Default

: IMPLIED_VERSION



Default

: MF=S

Parameters for REQUEST=START


REQUEST=START

Requests that a browse session be started.


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.


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


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


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.


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=MAX


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.



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.


– 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


IXGBRWSE macro

,MF=S











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.



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


,COMPLETE


,NOCHECK



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

�


One or more blanks must precede IXGBRWSE.

One or more blanks must follow IXGBRWSE.

REQUEST=READCURSOR



,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).


556


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=MAX


,RETCODE=retcode

,RSNCODE=rsncode

,MF=S

IXGBRWSE macro

Description


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


Default

: IMPLIED_VERSION



Default

: MF=S


557

IXGBRWSE macro

Syntax

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



Description

Parameters for REQUEST=READCURSOR


REQUEST=READCURSOR

Requests that a program read the next consecutive log block in the log stream, in the direction specified on the DIRECTION parameter.


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.


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


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


IXGBRWSE macro

consecutive log block. Specify OLDTOYOUNG to get the next youngest block or YOUNGTOOLD to get the next oldest block.

,ANSAREA=ansarea


,ANSLEN=anslen





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.


Specifies the name or address (using a register) of an 8-byte output field where the identifier or the requested log block is returned


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


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.


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.





,PLISTVER=MAX



The values are:

560


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.






– DIAG


– 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


,RSNCODE=rsncode


,MF=S













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.



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.



,list addr


,attr


,COMPLETE


,NOCHECK


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

�



562


Syntax

IXGBRWSE

�

REQUEST=READBLOCK



,BLOCKID=blockid

,SEARCH=search

,BUFFER=buffer


,BUFFLEN=bufflen

,ANSAREA=ansarea

,ANSLEN=anslen

GMT=YES

GMT=NO


,BLKSIZE=blksize



MODE=SYNC

MODE=SYNCECB

,ECB=ecb

IXGBRWSE macro

Description




blockid: RS-type address or register (2) - (12).

search: RS-type address or register (2) - (12).



bufflen: 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



563

IXGBRWSE macro

Syntax


,PLISTVER=MAX


,RETCODE=retcode

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



Description

Default

: IMPLIED_VERSION



Default

: MF=S

Parameters for REQUEST=READBLOCK


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.


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.


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


,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


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


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


,ANSLEN=anslen




,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


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


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


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.


Specifies the name or address (using a register) of a 8-byte output field where the identifier of the requested log block is returned.


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



ECB=ecb



v

The ECB must reside in either common storage or the home address space at the time the IXGBRWSE request is issued.



,PLISTVER=MAX




566


IXGBRWSE macro






– DIAG


– MAXNUMLOGBLOCKS

– MULTIBLOCK

– RETBLOCKINFO

To code


,RETCODE=retcode


,RSNCODE=rsncode


,MF=S













567

IXGBRWSE macro

Syntax



IBM recommends


v

Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.


,list addr


,attr


,COMPLETE


,NOCHECK


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

�



IXGBRWSE

� One or more blanks must follow IXGBRWSE.

568


Syntax

REQUEST=RESET



,POSITION=YOUNGEST

,POSITION=OLDEST

,ANSAREA=ansarea

,ANSLEN=anslen

VIEW=ACTIVE

VIEW=ALL

MODE=SYNC

MODE=SYNCECB

,ECB=ecb


,PLISTVER=MAX


,RETCODE=retcode

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



IXGBRWSE macro

Description





Default

: MODE=SYNC


Default

: IMPLIED_VERSION



Default

: MF=S


569

IXGBRWSE macro

Parameters for REQUEST=RESET


REQUEST=RESET

Requests that the browse cursor be repositioned at either the oldest or youngest block in the log stream.






,POSITION=YOUNGEST

,POSITION=OLDEST

Specifies the cursor position desired, at either the youngest or the oldest log block in the log stream.

,ANSAREA=ansarea


,ANSLEN=anslen




,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


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


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



ECB=ecb




v

The virtual storage area specified for the ECB must reside on a fullword boundary.


,PLISTVER=MAX









– DIAG

– REQDATA


571

IXGBRWSE macro

v 2 , supports both the following parameters and parameters from version 0 and 1:

– MAXNUMLOGBLOCKS

– MULTIBLOCK

– RETBLOCKINFO

To code


,RETCODE=retcode


,RSNCODE=rsncode


,MF=S














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


�

�

Syntax

name

IXGBRWSE macro


v

Use MF=(E,list_addr,NOCHECK), to execute the macro.

,list addr


,attr


,COMPLETE


,NOCHECK


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



IXGBRWSE


REQUEST=END



,ANSAREA=ansarea

,ANSLEN=anslen

MODE=SYNC





Default

: MODE=SYNC


573

IXGBRWSE macro

Syntax

MODE=SYNCECB

,ECB=ecb


,PLISTVER=MAX


,RETCODE=retcode

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



Description


Default

: IMPLIED_VERSION



Default

: MF=S

Parameters for REQUEST=END


REQUEST=END

Requests that the browse session be ended.






,ANSAREA=ansarea


,ANSLEN=anslen

Specifies the name (or address in a register) of the 4-byte field containing the

574


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.



,MODE=SYNC

,MODE=SYNCECB



ECB=ecb




v

The virtual storage area specified for the ECB must reside on a fullword boundary.


,PLISTVER=MAX









– DIAG

– REQDATA


575

IXGBRWSE macro

v 2 , supports both the following parameters and parameters from version 0 and 1:

– MAXNUMLOGBLOCKS

– MULTIBLOCK

– RETBLOCKINFO

To code


,RETCODE=retcode


,RSNCODE=rsncode


,MF=S














IBM recommends

that you use the modify and execute forms in the following order: v


576


IXGBRWSE macro


v

Use MF=(E,list_addr,NOCHECK), to execute the macro.

,list addr


,attr


,COMPLETE


,NOCHECK


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.


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


Equate Symbol

: IxgRsnCodeOk

Explanation

: Request processed successfully.


577

IXGBRWSE macro

Table 35. Return and Reason Codes for the IXGBRWSE Macro (continued)

Return Code

04

Reason Code

xxxx0401


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


IXGBRWSE macro


Return Code

04

Reason Code

xxxx0405


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


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






579

IXGBRWSE macro


Return Code

04

Reason Code

xxxx0417


Equate Symbol

: IxgRsnCodeMultiblockErrorWarning

08 xxxx0801

Explanation


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





Equate Symbol

: IxgRsnCodeBadParmlist

08


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


IXGBRWSE macro


Return Code

08

Reason Code

xxxx0804


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.


581

IXGBRWSE macro


Return Code

08

Reason Code

xxxx0814


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


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


IXGBRWSE macro


Return Code

08

Reason Code

xxxx0836


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.


583

IXGBRWSE macro


Return Code

08

Reason Code

xxxx083F


Equate Symbol

: IxgRsnCodeTestartError

08


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


IXGBRWSE macro


Return Code

08

Reason Code

xxxx0847


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


585

IXGBRWSE macro


Return Code

08

Reason Code

xxxx084A


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.



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


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


586


IXGBRWSE macro


Return Code

08

Reason Code

xxxx0852


Equate Symbol

: IxgRsnCodeBadBlkSizeStor

Explanation

: Program error. The storage area specified on the BLKSIZE parameter cannot be accessed.

08


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


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



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




587

IXGBRWSE macro


Return Code

08

Reason Code

xxxx0864


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


IXGBRWSE macro


Return Code

08

Reason Code

xxxx08D1


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


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


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,


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


IXGBRWSE macro

BLKSIZE=BLKSIZE,

RETBLOCKID=RETBLK,

TIMESTAMP=TIMESTMP,


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,


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,


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


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.


STREAMTOKEN=TOKEN,


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


STREAMTOKEN=(6),


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN, any SASN

31-bit or 64-bit




None.


593

IXGCONN macro


v

The parameter list for this service must be addressable in the caller's primary address space.


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


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


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.


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.



Register

Contents

0

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




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


Chapter 68. IXGCONN — Connect/disconnect to log stream

595

IXGCONN macro

Syntax

⌂

IXGCONN

⌂

REQUEST=CONNECT

REQUEST=DISCONNECT

,STREAMNAME=streamname


,ANSAREA=ansarea

,ANSLEN=anslen

,AUTH=READ

,AUTH=WRITE

,STRUCTNAME=structname

,AVGBUFSIZE=avgbufsize

,MAXBUFSIZE=maxbufsize

,ELEMENTSIZE=elementsize

,LSVERSION=lsversion


,IMPORTCONNECT=NO

,IMPORTCONNECT=YES

,DIAG=NO_DIAG

,DIAG=NO

596


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




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=MAX

,PLISTVER=1

,PLISTVER=2

,RETCODE=retcode

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



Description

Default

: IMPLIED_VERSION



Default

: MF=S

Parameters


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.


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.


Specifies the 16-byte token uniquely identifying the program's connection to the 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


,ANSLEN=anslen




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


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.



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.



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


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


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.


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


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=MAX

,PLISTVER=1

,PLISTVER=2







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


IXGCONN macro

v A decimal value of 1 or 2

,RETCODE=retcode


,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














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.



,list addr


,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


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


,NOCHECK


ABEND codes

None.


When IXGCONN macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.


00

04

IXGRETCODEOK - Service completes successfully.

IXGRETCODEWARNING - Service completes with a warning.

08

0C




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


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


IXGCONN macro

Table 36. Return and reason codes for the IXGCONN macro (continued)

Return code

04

Reason code

xxxx0406


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


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.


603

IXGCONN macro


Return code

04

Reason code

xxxx0409


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


08


Explanation


Action


Equate symbol


Explanation


Action


Equate symbol


Explanation

: Program error. The stream token was not valid.

08


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


Explanation


Action


604


IXGCONN macro


Return code

08

Reason code

xxxx080B


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.


605

IXGCONN macro


Return code

08

Reason code

xxxx0811


Equate symbol

: IxgRsnCodeBadStrname

08


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


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


Explanation


Action


Equate symbol


Explanation


Action


Equate symbol


Explanation




Action


606


IXGCONN macro


Return code

08

Reason code

xxxx0819


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.


607

IXGCONN macro


Return code

08

Reason code

xxxx081E


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


Explanation


Action


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


IXGCONN macro


Return code

08

Reason code

xxxx083A


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.


609

IXGCONN macro


Return code

08

Reason code

xxxx0850


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


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


Explanation


Action



Equate symbol


Explanation


Action



610


IXGCONN macro


Return code

08

Reason code

xxxx0863


Equate symbol

: IXGRSNCODESTRUCTUREFAILED

08 xxxx0864

Explanation


Action



Equate symbol

: IXGRSNCODENOCONNECTIVITY

08


Explanation


Action


The log stream is available because the re-build completed successfully. Re-issue the request.



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


Action



611

IXGCONN macro


Return code

08

Reason code

xxxx0891


Equate symbol

:

IXGRSNCODEADDRSPACEINITIALIZING

08 xxxx08B0

Explanation


Action


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


IXGCONN macro


Return code

08

Reason code

xxxx08D6


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.


613

IXGCONN macro


Return code

08

Reason code

000008E3


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


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


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


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


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



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.


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


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


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




:


:


:

AMODE

:

ASC mode

:


:

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


Task

PASN=HASN, any SASN

31-bit or 64-bit



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.


v The current primary address space must be the same primary address space used at the time your program issued the IXGCONN request.

v


v The calling program must be connected to the log stream with write authority through the IXGCONN service.



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.


– The virtual storage area specified for the ECB resides on a full word boundary.


617

IXGDELET macro


– 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




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.



0

1

Register

Contents



2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

618


⌂

⌂

Syntax

name

IXGDELET macro

Syntax

The standard form of the IXGDELET macro is written as follows:

Description


One or more blanks must precede

IXGDELET.

IXGDELET


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


Default

: DIAG=NO_DIAG

Chapter 69. IXGDELET — Deleting log data from a log stream

619

IXGDELET macro

Syntax

,DIAG=NO

,DIAG=YES


,PLISTVER=MAX

,PLISTVER=0

,PLISTVER=1

,RETCODE=retcode

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)


,MF=(M,list addr)



Description

Default

: IMPLIED_VERSION

retcode: RS-type address or register (2) -

(12).

rsncode: RS-type address or register (2) -

(12).

Default:

MF=S

Parameters




,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


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


,ANSLEN=anslen




,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


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.


ECB=ecb



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.


,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=MAX

,PLISTVER=0

,PLISTVER=1








– FORCE

– OBLOCKID

To code

: specify in this input parameter one of the following: v


622


IXGDELET macro

,RETCODE=retcode


,RSNCODE=rsncode


,MF=S

















,list addr


,attr



623

IXGDELET macro

,COMPLETE


,NOCHECK


ABEND codes

None.


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



08

0C




Table 37. Return and Reason Codes for the IXGDELET Macro

Return Code

00

Reason Code

xxxx0000


Equate Symbol

: IxgRsnCodeOk

04 xxxx0401

Explanation


Equate Symbol


Explanation



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


IXGDELET macro

Table 37. Return and Reason Codes for the IXGDELET Macro (continued)

Return Code

04

Reason Code

xxxx040B


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.


625

IXGDELET macro


Return Code

04

Reason Code

xxxx040F


Equate Symbol

: IxgRsnCodeRMEOFGap

04

04


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


IXGDELET macro


Return Code

04

Reason Code

xxxx0414


Equate Symbol

: IxgRsnCodeRMStoppedDelete

08

08

08


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


Explanation


Action


Equate Symbol


Explanation


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


Explanation

: Program error. One of the following occurred: v The stream token was not valid.


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


Explanation


Action



627

IXGDELET macro


Return Code

08

Reason Code

xxxx0814


Equate Symbol


08

08

08

08

08 xxxx0815 xxxx0816 xxxx0817 xxxx081C xxxx081F

Explanation


Action


Equate Symbol


Explanation


Action


Equate Symbol


Explanation



Ansaa_Preferred_Size field of the answer area, mapped by

IXGANSAA macro.

Action


Equate Symbol


Explanation


Action


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


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


Explanation


Action


628


IXGDELET macro


Return Code

08

Reason Code

xxxx0836


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


Explanation


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



629

IXGDELET macro


Return Code

08

Reason Code

xxxx0861


Equate Symbol


08

08


Explanation


Action


v

The re-build failed and the log stream is not available.

Equate Symbol


Explanation


Action


v


Equate Symbol


Explanation


Action


v


Equate Symbol


Explanation


Action




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


IXGDELET macro


Return Code

08

Reason Code

xxxx0890


Equate Symbol


08

08

08

08

08 xxxx0891 xxxx08D0 xxxx08D1 xxxx08D2 xxxx085F

Explanation


Action


Equate Symbol


Explanation


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


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.


Action

: Change the invoking environment to supervisor state.

Equate Symbol

: IxgRsnCodeProgramKey

Explanation



Action

: Change the invoking environment to a system key

(key 0-7).

Equate Symbol


Explanation


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.


631

IXGDELET macro


Return Code

0C

Reason Code

xxxx0000


Equate Symbol


Explanation


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


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


633

IXGDELET macro

634


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN, any SASN

31-bit 64-bit




None.


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.




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.


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.


635

IXGIMPRT macro

Syntax



0

1

Register

Contents



2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15


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




None.

Syntax

The IXGIMPRT macro is written as follows:

Description

�

name


One or more blanks must precede IXGIMPRT.

IXGIMPRT

636


IXGIMPRT macro


�

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


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=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




Default


,PLISTVER=MAX

,PLISTVER=0

Default

: MF=S


,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



Chapter 70. IXGIMPRT — Import log blocks

637

IXGIMPRT macro


Parameters


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.


A required input parameter that specifies the log stream token that was returned by the IXGCONN service.

To code


16-character field.

,BUFFER=buffer


Required input parameter that specifies the buffer from which the log stream block is to be written.



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.


A required input parameter that specifies the length of the log block to be written. The maximum block length is 65,536.

To code:


,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


8-character field.


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


8-character field.

638


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


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=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


GPR 15.

To code


,RSNCODE=rsncode


GPR 0.

To code



,PLISTVER=MAX

,PLISTVER=0





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


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

















,list addr


,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


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


,NOCHECK


ABEND codes

Abend 1C5 Ixg_Abend_Code - See z/OS MVS System Codes for more information on this abend.


When the IXGIMPRT macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.




00

04



08

0C


IXGRETCODECOMPERROR - Service does not complete. A system logger component error has been encountered.


Table 38. Return and Reason Codes for the IXGIMPRT Macro

Return Code

00

Reason Code

xxxx0000


IxgRsnCodeOk -

Explanation



641

IXGIMPRT macro

Table 38. Return and Reason Codes for the IXGIMPRT Macro (continued)

Return Code

04

Reason Code

xxxx0405


IxgRsnCodeWarningLossOfData -

Explanation


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


Action


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


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


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


IXGIMPRT macro


Return Code

04

Reason Code

0000040A


IxgRsnCodeDuplexFailureWarning -

08

08


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


Action



IxgRsnCodeBadBuffer -

Explanation

: Program error. The virtual storage area specified on the BUFFER parameter is not addressable.

Action


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.


643

IXGIMPRT macro


Return Code

08

Reason Code

xxxx0806


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


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


Action


IxgRsnCodeNotAvailForIPL -

Explanation


Action


IxgRsnCodeNotEnabled -

Explanation


Action


IxgRsnCodeBadAnslen -

Explanation




IXGANSAA macro.

Action

: Reissue the request, specifying an answer area of the required size.

644


IXGIMPRT macro


Return Code

08

Reason Code

xxxx0817


IxgRsnCodeBadAnsarea -

08

08 xxxx0819 xxxx082D

Explanation


Action


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


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


645

IXGIMPRT macro


Return Code

08

Reason Code

xxxx0849


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


IXGIMPRT macro


Return Code

08

Reason Code

xxxx085D


Equate Symbol

: IxgRsnCodeWowError

08


Explanation


DASD have failed because of severe errors. No further write requests can be processed until the offload error condition is cleared.



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:


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


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.



647

IXGIMPRT macro


Return Code

08

Reason Code

xxxx0862


IxgRsnCodeXESPurge -

08

08


Explanation


Action


The log stream is available because the re-build completed successfully. Reissue the request.


IxgRsnCodeStructureFailed -

Explanation


Action



IxgRsnCodeNoConnectivity -

Explanation


Action


v The re-build failed and the log stream is not available. #

The log stream has been disconnected from this system.


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


IXGIMPRT macro


Return Code

08

Reason Code

xxxx0867


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


Action


IxgRsnCodeAddrSpaceInitializing -

Explanation


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.


649

IXGIMPRT macro


Return Code

08

Reason Code

xxxx08DA


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.


Action



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


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


IXGIMPRT macro


651

IXGIMPRT macro

652


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN, any SASN

31-bit or 64-bit



No locks held.



653

IXGINVNT macro





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


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.



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.



Register

Contents

0

2-13


Unchanged

14

15


Return code


Register

Contents

0-1


2-13

Unchanged

14-15


Chapter 71. IXGINVNT — Managing the LOGR inventory couple data set

655

IXGINVNT macro

Syntax



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

⌂


One or more blanks must precede IXGINVNT.

IXGINVNT

⌂ One or more blanks must follow IXGINVNT.

REQUEST=DEFINE

,TYPE=LOGSTREAM

,ANSAREA=ansarea

,ANSLEN=anslen


,GROUP=PRODUCTION

,GROUP=TEST


,DASDONLY=NO

,DASDONLY=YES




Default

: GROUP=PRODUCTION


Default

: NO_STRUCTNAME

Default

: DASDONLY=NO

656


Syntax


,RMNAME=rmname

,DESCRIPTION=description

IXGINVNT macro

Description


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


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


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=MAX

,PLISTVER=0

,PLISTVER=1

,PLISTVER=2

,PLISTVER=3

,RETCODE=retcode

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



Description

Default

: ZAI=NO

Default

: ZAIDATA=NO_ZAIDATA

Default

: IMPLIED_VERSION



Default

: MF=S

Parameters for REQUEST=DEFINE,TYPE=LOGSTREAM


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.


659

IXGINVNT macro

,ANSAREA=ansarea


,ANSLEN=anslen





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


IXGINVNT macro


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.


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


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


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.


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.


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.


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


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.


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.


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


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


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


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


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


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


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.


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.


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


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.


666


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



DASD log data set for this log stream.


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


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


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.


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




,LS_SIZE=ls_size

Specifies the size, in 4K blocks, of the log stream offload DASD data sets for the log stream being defined.



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.


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


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


Specifies the name (or address in a register) of an 4-byte input field containing


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


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.


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


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


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.



,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


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.


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


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


IXGINVNT macro

,PLISTVER=MAX

,PLISTVER=0

,PLISTVER=1

,PLISTVER=2








– 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


,MF=S



675

IXGINVNT macro
















,list addr


,attr


,COMPLETE


,NOCHECK


676


⌂

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



IXGINVNT

⌂

One or more blanks must follow IXGINVNT.

REQUEST=DEFINE

,TYPE=STRUCTURE

,ANSAREA=ansarea

,ANSLEN=anslen


,LOGSNUM=logsnum






Default

: NO_STRUCTNAME

logsnum: RS-type address or register (2) - (12).


Default

: 65532

avgbufsize: RS-type address or register (2) - (12).

Default

: 1/2 of maxbufsize


,PLISTVER=MAX

,PLISTVER=0

,PLISTVER=1

,PLISTVER=2

Default

: IMPLIED_VERSION


677

IXGINVNT macro

Syntax

,PLISTVER=3

,RETCODE=retcode

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



Description



Default

: MF=S

Parameters for REQUEST=DEFINE,TYPE=STRUCTURE


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


,ANSLEN=anslen





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


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.


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.


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=MAX

,PLISTVER=0

,PLISTVER=1

,PLISTVER=2

,PLISTVER=3



v MAX




679

IXGINVNT macro



To code


,RETCODE=retcode


,RSNCODE=rsncode


,MF=S














IBM recommends that you use the modify and execute forms in the following order:

680


⌂

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.


,list addr


,attr


,COMPLETE


,NOCHECK


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



IXGINVNT

⌂

One or more blanks must follow IXGINVNT.

REQUEST=UPDATE

,TYPE=LOGSTREAM

,ANSAREA=ansarea

,ANSLEN=anslen




681

IXGINVNT macro

Syntax


,NEWSTREAMNAME=newstreamname

,GROUP=PRODUCTION

,GROUP=TEST


,RMNAME=rmname



,LOGGERDUPLEX=UNCOND

,LOGGERDUPLEX= COND

,STG_DUPLEX=NO

,STG_DUPLEX=YES

,DUPLEXMODE=COND

,DUPLEXMODE=UNCOND

,DUPLEXMODE=DRXRC





,LS_ALLOCAHEAD={xls_allocahead | *}



682


Description


newstreamname: RS-type address or register (2) - (12).

Default

: GROUP=PRODUCTION


rmname: RS-type address or register (2) - (12).

description: 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



,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



,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=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



683

IXGINVNT macro

Syntax

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



Description


Default

: MF=S

Parameters for REQUEST=UPDATE


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


,ANSLEN=anslen





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.



684


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


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.


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


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.


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.


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


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


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


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.


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


|

|

|

|

|

IXGINVNT macro



,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'.


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.



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.


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.


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.


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.



DASD staging data set for this log stream.



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


|

|

IXGINVNT macro


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.



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.


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.



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


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.


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.


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.


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


IXGINVNT macro


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.



DASD log data set for this log stream.





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.


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.


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


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.



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.


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


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.


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.


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


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.


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.


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


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.


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.


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


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.


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'


X'40'

X'4A'

X'4B'

X'4C'

X'4D'

X'4E'

X'4F'


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'


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=MAX

,PLISTVER=0

,PLISTVER=1

,PLISTVER=2

,PLISTVER=3



v MAX




700


IXGINVNT macro


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


,RETCODE=retcode


,RSNCODE=rsncode


,MF=S












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


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.





,list addr


,attr


,COMPLETE


,NOCHECK


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

⌂



IXGINVNT


REQUEST=CHECKDEF

702


IXGINVNT macro

Syntax

,TYPE=LOGSTREAM

,TYPE=STRUCTURE



,EXTRACT=NO

,EXTRACT=YES

,ANSAREA=ansarea

,ANSLEN=anslen


,PLISTVER=MAX

,PLISTVER=0 - 4

,RETCODE=retcode

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



Description





Default

: IMPLIED_VERSION



Default

: MF=S

Parameters for REQUEST=CHECKDEF


REQUEST=CHECKDEF

Requests that an entry for a log stream or coupling facility structure be checked in the LOGR policy.


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,



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


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.


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


IXGINVNT macro

,ANSAREA=ansarea


,ANSLEN=anslen





,PLISTVER=MAX

,PLISTVER=4






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


,RSNCODE=rsncode


,MF=S








705

IXGINVNT macro











,list addr


,attr


,COMPLETE


,NOCHECK


ABEND codes

None.


When IXGINVNT macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.

706


IXGINVNT macro


00

04



08

0C



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


Equate Symbol

: IxgRsnCodeOk

Explanation



707

IXGINVNT macro

Table 41. Return and Reason Codes for the IXGINVNT Macro (continued)


04 xxxx0418


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


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


Explanation


Action


Equate Symbol


Explanation


Action


708


IXGINVNT macro



08 xxxx0805


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:


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:



709

IXGINVNT macro


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


Explanation


Action


Equate Symbol


Explanation


Action


Equate Symbol


Explanation


Action



710


IXGINVNT macro



08 xxxx080D


Equate Symbol


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.


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.


711

IXGINVNT macro



08 xxxx080E


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


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



Equate Symbol


Explanation


Action


Equate Symbol


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


712


IXGINVNT macro



08 xxxx0815


Equate Symbol


Explanation


08

08


Action


Equate Symbol


Explanation




Action


Equate Symbol


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


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



713

IXGINVNT macro



08 xxxx081A


Equate Symbol


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.





Action


Equate Symbol


Explanation


08


Action


Equate Symbol


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


Explanation


Action


714


IXGINVNT macro



08 xxxx0821


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



Message IXG003I is documented in z/OS MVS System

Messages, Vol 10 (IXC-IZP).


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


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.



715

IXGINVNT macro



08 xxxx0824


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



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.


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.


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


IXGINVNT macro



08 xxxx0828


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



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.


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.


717

IXGINVNT macro



08 xxxx082E


Equate Symbol


08


Explanation


Action

: System logger services are unavailable for the remainder of this IPL.

Equate Symbol

: IxgRsnCodeBadStgDataClas

Explanation


LS_DATACLAS parameter is not valid.

Action

: Change the data class specified to meet the

LS_DATACLAS syntax requirements.

Equate Symbol

: IxgRsnCodeBadLSDataClas

08

08


Explanation


STG_DATACLAS parameter is not valid.

Action


STG_DATACLAS syntax requirements.

Equate Symbol


Explanation


Action

: Reissue the request with a valid log stream name on the STREAMNAME parameter.


Equate Symbol

: IxgRsnCodeBadStgMgmtClas

Explanation


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


LS_MGMTCLAS parameter is not valid.

Action

: Change the log stream data set management class specified to meet the LS_MGMTCLAS syntax requirements.

718


IXGINVNT macro



08 xxxx0834


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.


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



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.


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.


719

IXGINVNT macro



08 xxxx083C


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


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


IXGINVNT macro



08 xxxx0842


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



Equate Symbol


Explanation


Action

: Reformat the system logger couple data set.


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.


Equate Symbol


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.


721

IXGINVNT macro



08 xxxx0850


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


08

08


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


LOWOFFLOAD is not valid.

Action

: Change the value to meet the LOWOFFLOAD syntax requirements.


Equate Symbol

: IxgRsnCodeBadHighoffload

Explanation


HIGHOFFLOAD is invalid.

Action

: Change the value to meet the HIGHOFFLOAD syntax requirements.


722


IXGINVNT macro



08 xxxx0856


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


Equate Symbol

: IxgRsnCodeStgSizeDuplexNo

Explanation

: This reason code is obsolete and will no longer be returned.

Equate Symbol

: IxgRsnCodeDataClasDuplexNo

Explanation


Equate Symbol

: IxgRsnCodeMgmtClasDuplexNo

Explanation


Equate Symbol

: IxgRsnCodeStorClasDuplexNo

Explanation


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.



723

IXGINVNT macro



08 xxxx0890


Equate Symbol


08 xxxx0891

Explanation


Action



Equate Symbol


08 xxxx08D4

Explanation


Action


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.


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


IXGINVNT macro



08 xxxx08E0


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


UPDATE requests specify DUPLEXMODE=UNCOND or omit the DUPLEXMODE keyword.



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



725

IXGINVNT macro



08 xxxx08E3


Equate Symbol


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.


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


IXGINVNT macro



08 xxxx08E5


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


UPDATE requests specify LOGGERDUPLEX=UNCOND or omit the LOGGERDUPLEX keyword.



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.


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.



727

IXGINVNT macro



08 xxxx08E8


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


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


Explanation



Action


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


⌂

Syntax

name

Syntax for REQUEST=DELETE

The IXGINVNT REQUEST=DELETE macro is written as follows:

Description

IXGINVNT macro



IXGINVNT


REQUEST=DELETE

,TYPE=LOGSTREAM

,TYPE=STRUCTURE

,ANSAREA=ansarea

,ANSLEN=anslen







Default

: NO_STRUCTNAME


,PLISTVER=MAX

,PLISTVER=0

,PLISTVER=1

,PLISTVER=2

,PLISTVER=3

,RETCODE=retcode

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)



Default

: IMPLIED_VERSION



Default

: MF=S


729

IXGINVNT macro

Syntax

,MF=(E,list addr)



,MF=(M,list addr)



Description

Parameters for REQUEST=DELETE


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,


,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=ansarea


,ANSLEN=anslen





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 Each segment must be separated by periods, which count as characters.

STREAMNAME is required for TYPE=LOGSTREAM.

730


IXGINVNT macro


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.


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=MAX

,PLISTVER=0

,PLISTVER=1

,PLISTVER=2

,PLISTVER=3







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


,RSNCODE=rsncode


,MF=S






731

IXGINVNT macro










IBM recommends that you use the modify and execute forms in the following order: v




,list addr


,attr


,COMPLETE


,NOCHECK


ABEND codes

None.

732


IXGINVNT macro


When IXGINVNT macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.


00

04



08

0C



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


00 xxxx0000


Equate Symbol

: IxgRsnCodeOk

Explanation



733

IXGINVNT macro



04 xxxx0418


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


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.


Equate Symbol


Explanation


Action


Equate Symbol


Explanation


Action


734


IXGINVNT macro



08 xxxx0805


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



IXG003I is documented in z/OS MVS System Messages,

Vol 10 (IXC-IZP).


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:


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



735

IXGINVNT macro


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


Explanation


Action


Equate Symbol


Explanation


Action


Equate Symbol


Explanation


Action



736


IXGINVNT macro



08 xxxx080D


Equate Symbol


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.


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.



737

IXGINVNT macro



08 xxxx0810


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.


Equate Symbol


08

08


Explanation


Action


Equate Symbol


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


Equate Symbol


Explanation


Action


Equate Symbol


Explanation




Action


738


IXGINVNT macro



08 xxxx0817


Equate Symbol


08


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


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


Equate Symbol


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.





Action


Equate Symbol


Explanation


Action



739

IXGINVNT macro



08 xxxx081E


Equate Symbol


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


Explanation


08 xxxx0821

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



Message IXG003I is documented in z/OS MVS System

Messages, Vol 10 (IXC-IZP).


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


IXGINVNT macro



08 xxxx0823


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


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.


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.


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.


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.



741

IXGINVNT macro



08 xxxx0827


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.


Equate Symbol

: IxgRsnCodeBadStgStorClas

Explanation


STG_STORCLAS parameter is incorrect.

08


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.


742


IXGINVNT macro



08 xxxx082C


Equate Symbol

: IxgRsnCodeBadStructName

Explanation

: Program error. The coupling facility structure name specified on the STRUCTNAME parameter is not valid.

08


Action

: Reissue the request with a valid structure name on the STRUCTNAME parameter.

Equate Symbol


Explanation


Action

: System logger services are unavailable for the remainder of this IPL.

Equate Symbol

: IxgRsnCodeBadStgDataClas

08

08


Explanation


LS_DATACLAS parameter is not valid.

Action


LS_DATACLAS syntax requirements.

Equate Symbol

: IxgRsnCodeBadLSDataClas

Explanation


STG_DATACLAS parameter is not valid.

Action


STG_DATACLAS syntax requirements.

Equate Symbol


Explanation


Action

: Reissue the request with a valid log stream name on the STREAMNAME parameter.


Equate Symbol

: IxgRsnCodeBadStgMgmtClas

Explanation


STG_MGMTCLAS parameter is not valid.

Action

: Change the staging data set management class specified to meet the STG_MGMTCLAS syntax requirements.


743

IXGINVNT macro



08 xxxx0833


Equate Symbol

: IxgRsnCodeBadLSMgmtClas

Explanation


LS_MGMTCLAS parameter is not valid.

08


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



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


08



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.


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


IXGINVNT macro



08 xxxx083C


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


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.


745

IXGINVNT macro



08 xxxx0842


Equate Symbol

: IxgRsnCodeBadAvgBufSize

Explanation


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



Equate Symbol


Explanation


Action

: Reformat the system logger couple data set.


Equate Symbol

: IxgRsnCodeNoStreamLike

08


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.


Equate Symbol


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


IXGINVNT macro



08 xxxx0850


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


08

08


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


LOWOFFLOAD is not valid.

Action

: Change the value to meet the LOWOFFLOAD syntax requirements.


Equate Symbol

: IxgRsnCodeBadHighoffload

Explanation


HIGHOFFLOAD is invalid.

Action

: Change the value to meet the HIGHOFFLOAD syntax requirements.



747

IXGINVNT macro



08 xxxx0856


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


Equate Symbol

: IxgRsnCodeStgSizeDuplexNo

Explanation


Equate Symbol

: IxgRsnCodeDataClasDuplexNo

Explanation


Equate Symbol

: IxgRsnCodeMgmtClasDuplexNo

Explanation


Equate Symbol

: IxgRsnCodeStorClasDuplexNo

Explanation


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.


748


IXGINVNT macro



08 xxxx0890


Equate Symbol


08 xxxx0891

Explanation


Action



Equate Symbol


08 xxxx08D4

Explanation


Action


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.


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.


749

IXGINVNT macro



08 xxxx08E0


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


UPDATE requests specify STG_DUPLEX=YES or omit the STG_DUPLEX keyword.



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


UPDATE requests specify DUPLEXMODE=UNCOND or omit the DUPLEXMODE keyword.



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


750


IXGINVNT macro



08 xxxx08E3


Equate Symbol


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.


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.


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.


751

IXGINVNT macro



08 xxxx08E5


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


UPDATE requests specify LOGGERDUPLEX=UNCOND or omit the LOGGERDUPLEX keyword.



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.


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.


752


IXGINVNT macro



08 xxxx08E8


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


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


Explanation



Action


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


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.


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


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


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


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


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.


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


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


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


755

IXGINVNT macro

RSCODE DS F

DSECT ,

IXGANSAA ,

Reason code


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.


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


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)


STREAMNAME=STRNAME,

MF=(M,IXGINVNT_PLIST,NOCHECK)

ANSLEN DC

STRNAME DC

ANSAREA DS

RETCODE DS


TYPE=LOGSTREAM,

MODEL=NO,

ANSAREA=ANSAREA,

ANSLEN=ANSLEN,

RSNCODE=RSNCODE,

MF=(E,IXGINVNT_PLIST,NOCHECK)

RETCODE=RETCODE



CL(ANSAA_LEN)

F answer area for log requests return code from logger

X

X

X

X

X

X

X

X

X

756


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:


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:


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


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


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task


31-bit or 64-bit



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.


None.


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.




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.


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.


759

IXGOFFLD

Syntax



Register

Contents

0

2-13


Unchanged

14

15


Return code


Register

Contents

0-1


2-13

Unchanged

14-15




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

⌂


One or more blanks must precede IXGOFFLD.

IXGOFFLD

⌂


,ANSAREA=ansarea

,ANSLEN=anslen

One or more blanks must follow IXGOFFLD.

streamtoken: RS-type address or address in register (2) - (12).



760


IXGOFFLD

Syntax

,RETCODE=retcode

Description


,RSNCODE=rsncode rsncode: RS-type address or register (2) - (12).


Default


,PLISTVER=MAX

,PLISTVER=0

Default

: MF=S


,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



Parameters


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.


A required input parameter that specifies the log stream token that was returned on the IXGCONN service.

To code:


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:


Chapter 72. IXGOFFLD — Initiate offload to DASD log data sets

761

IXGOFFLD

,RETCODE=retcode


GPR 15.

To code:


,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX

,PLISTVER=0






v 0 , which supports all parameters except those referenced in higher versions.

To code:


,MF=S











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


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.






,list addr


,attr


,COMPLETE


,NOCHECK


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.


763

IXGOFFLD


When the IXGOFFLD macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return 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.


Table 43. Return and Reason Codes for the IXGOFFLD Macro

Return Code

00

Reason Code

xxxx0000


IxgRsnCodeOk -

08

08


Explanation:

Request processed successfully.


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.


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



Explanation:

Program error. One of the following occurred: v The stream token was not valid.


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


IXGOFFLD

Table 43. Return and Reason Codes for the IXGOFFLD Macro (continued)

Return Code

08

Reason Code

xxxx080A



08


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.


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.


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.


Explanation:

Program error. The answer area length



IXGANSAA macro.

Action:

Reissue the request, specifying an answer area of the required size.


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.


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.


765

IXGOFFLD


Return Code

08

Reason Code

xxxx082D



08


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.


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.


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


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.


Explanation:

Environment error. An cross-system extended services (XES) request has been purged due to rebuild processing.

Action:




Explanation:

Environment error. Either the coupling facility structure associated with the log stream has failed or the coupling facility itself has failed.

Action:



766


IXGOFFLD


Return Code

08

Reason Code

xxxx0864



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:






Explanation:

System error. The system logger address space failed and is not available.

Action:

Do not issue system logger requests.


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


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.


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



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


@

@

@

@

768


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task


31-bit or 64-bit




None.


v




ANSAREA parameter.

When coding REQUEST=LSCONNINFO or when using default: v The caller must have a valid connection to the log stream.


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.


769

IXGQUERY

Syntax


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.


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.



Register

Contents

0

2-13


Unchanged

14

15


Return code


Register

Contents

0-1


2-13

Unchanged

14-15


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.



None.

Syntax

The IXGQUERY macro is written as follows:

Description

name


� One or more blanks must precede IXGQUERY.

770


IXGQUERY


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






Default


,PLISTVER=MAX

,PLISTVER=0

,PLISTVER=1

,PLISTVER=2

Default

: MF=S


,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)


Chapter 73. IXGQUERY — Query a log stream for information

771

IXGQUERY

Syntax


Description

Parameters


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.


A required input parameter that specifies the log stream token that was returned by the IXGCONN service.

To code:


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:


,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


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:


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:


,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:


,ANSAREA=ansarea


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:


,ANSLEN=anslen



To code:



773

IXGQUERY

,RETCODE=retcode


GPR 15.

To code:


,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX

,PLISTVER=0

,PLISTVER=1

,PLISTVER=2








– CHECKCONNSTATUS

– REQUEST v 2

, which supports both the following parameters and parameters from version 0 and 1:

– BUFFER64

To code:


,MF=S








774


IXGQUERY







IBM recommends




,list addr


,attr


,COMPLETE


,NOCHECK


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.


When the IXGQUERY macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.


775

IXGQUERY



00

04



08

0C




Table 44. Return and Reason Codes for the IXGQUERY Macro

Return Code

00

Reason Code

xxxx0000


IxgRsnCodeOk -

08 xxxx0801

Explanation:



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


Action:



Explanation:


Action:

In the answer area mapped by IXGANSAA, see

ANSAA_DIAG1 for the XES return code and


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.


Explanation:


v The specified request was issued from an address space other than the connectors address space.

Action:


v Ensure that IXGQUERY requests were issued from the connectors address space.

776


IXGQUERY

Table 44. Return and Reason Codes for the IXGQUERY Macro (continued)

Return Code

08

Reason Code

xxxx080A



08


Explanation:


Action:


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.


Explanation:


08

08

08


Action:



Explanation:


Action:



Explanation:




IXGANSAA macro.

Action:



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:



Explanation:


Action:



777

IXGQUERY


Return Code

08

Reason Code

xxxx081B


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.


Explanation:


Action:



Explanation:


08

08


Action:



Explanation:


Action:




Explanation:


Action:




Explanation:


Action:



778


IXGQUERY


Return Code

08

Reason Code

xxxx0864



08

08

08

0C xxxx0890 xxxx0891 xxxx08D3 xxxx0000

Explanation:


Action:




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.


Explanation:


Action:



Explanation:


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


Explanation:



Action:




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


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task


31-bit or 64-bit




None.


v The caller must have a valid connection to the target log stream, specifying

AUTH=WRITE.




ANSAREA parameter.


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.


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.




781

IXGUPDAT

Syntax

Register

Contents

0

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

The IXGUPDAT macro is written as follows:

Description

name

⌂


One or more blanks must precede IXGUPDAT.

IXGUPDAT

⌂


One or more blanks must follow IXGUPDAT.

streamtoken: RS-type address or address in register (2) -

(12).


,GMT_TIMESTAMP=NO_GMT_TIMESTAMP

gmt_timestamp: RS-type address or address in register (2)

- (12).

Default

: GMT_TIMESTAMP=NO_GMT_TIMESTAMP


,ANSAREA=ansarea

782


Syntax

,ANSLEN=anslen

,RETCODE=retcode

,RSNCODE=rsncode


,PLISTVER=MAX

,PLISTVER=0

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



IXGUPDAT

Description




Default


Default

: MF=S


Parameters


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.


A required input parameter that specifies the log stream token that was returned on the IXGCONN service.

To code:


16-character field.


,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:


8-character field.

,ANSAREA=ansarea


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:


,ANSLEN=anslen



To code:


,RETCODE=retcode


GPR 15.

To code:


,RSNCODE=rsncode


GPR 0.

To code:



,PLISTVER=MAX

,PLISTVER=0



v MAX





To code:



784


IXGUPDAT

,MF=S

















,list addr


,attr


,COMPLETE


,NOCHECK



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.


When the IXGUPDAT macro returns control to your program: v GPR 15 (and retcode, if you coded RETCODE) contains a return code.



00

04

08

0C






Table 45. Return and Reason Codes for the IXGUPDAT Macro

Return Code

00

Reason Code

xxxx0000


IxgRsnCodeOk -

08

08


Explanation:



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:



Explanation:


Action:

See ANSAA_DIAG1 for the XES return code and



Explanation:


v

The specified request was issued from an address space other than the connectors address space.

Action:


v Ensure that IXGUPDAT requests were issued from the connectors address space.

786


IXGUPDAT

Table 45. Return and Reason Codes for the IXGUPDAT Macro (continued)

Return Code

08

Reason Code

xxxx080A



08


Explanation:


Action:



Explanation:


Action:



Explanation:


08

08

08

08 xxxx0816 xxxx0817 xxxx0819 xxxx081C

Action:



Explanation:




IXGANSAA macro.

Action:



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:



Explanation:


Action:


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.


787

IXGUPDAT


Return Code

08

Reason Code

xxxx082D



08


Explanation:


Action:



Explanation:


Action:



Explanation:


08


Action:




Explanation:


Action:




Explanation:


Action:



788


IXGUPDAT


Return Code

08

Reason Code

xxxx0864



08

08

08 xxxx0890 xxxx0891 xxxx08DD

Explanation:


Action:






Explanation:


Action:



Explanation:


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.


789

IXGUPDAT


Return Code

0C

Reason Code

xxxx0000


Equate Symbol


Explanation:


v


Action:



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


@

@

@

@

@

790


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

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


Task


31-bit or 64-bit



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


791

IXGWRITE macro


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



ANSAREA parameter.


– The virtual storage area specified for the ECB resides on a full word boundary.


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


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.



792


⌂

Syntax

name

IXGWRITE macro

0

1

Register

Contents



2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

The standard form of the IXGWRITE macro is written as follows:

Description


One or more blanks must precede IXGWRITE.

IXGWRITE

⌂


,BUFFER=buffer

BUFFER64=buffer64



One or more blanks must follow IXGWRITE.




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


MODE=SYNC

MODE=ASYNCNORESPONSE

MODE=SYNCECB

,ECB=ecb


,PLISTVER=MAX


,PLISTVER=0

,PLISTVER=1

,RETCODE=retcode

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)



,MF=(E,list addr)



,MF=(M,list addr)



Description



timestamp: RS-type address or register (2) - (12).

Default

: NO_TIMESTAMP

Default

: MODE=SYNC


Default

: IMPLIED_VERSION



Default

: MF=S

Parameters



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


IXGWRITE macro

,BUFFER=buffer


Specifies the field name (or address in a register) of the data to be written to the log.



The BUFFER and BUFFER64 parameters are mutually exclusive.


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


,ANSLEN=anslen




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


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.


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.


v The ECB must reside in either common storage or the home address space where the IXGWRITE service was issued.



,PLISTVER=MAX

,PLISTVER=0

,PLISTVER=1








– REQDATA

To code

: Specify in this input parameter one of the following: v


,RETCODE=retcode


,RSNCODE=rsncode


,MF=S


796


IXGWRITE macro
















,list addr


,attr


,COMPLETE


,NOCHECK


ABEND codes

None.


797

IXGWRITE macro


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.


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.


Table 46. Return and reason codes for the IXGWRITE macro

Return code

00

Reason code

xxxx0000


Equate symbol

: IxgRsnCodeOk

04 xxxx0401

Explanation


Equate symbol


Explanation



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


IXGWRITE macro

Table 46. Return and reason codes for the IXGWRITE macro (continued)

Return code

04

Reason code

xxxx0405


Equate symbol

: IxgRsnCodeWarningLossOfData

Explanation


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


Action


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


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


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.


799

IXGWRITE macro


Return code

04

Reason code

0000040A


Equate symbol

: IxgRsnCodeDuplexFailureWarning

08

08


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


Explanation


Action


Equate symbol


Explanation


Action



Equate symbol

: IxgRsnCodeBadBuffer

Explanation

: Program error. The virtual storage area specified on the BUFFER or BUFFER64 parameter is not addressable.

Action


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


IXGWRITE macro


Return code

08

Reason code

xxxx0806


Equate symbol


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.


Action


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


Explanation


Action


Equate symbol


Explanation


Action


Equate symbol


Explanation


Action


Equate symbol


Explanation




IXGANSAA macro.

Action



801

IXGWRITE macro


Return code

08

Reason code

xxxx0817


Equate symbol


08

08

08

08

08

08 xxxx0818 xxxx081C xxxx082D xxxx0837 xxxx083D xxxx083F

Explanation


Action


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


Explanation


Action


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


Explanation


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


IXGWRITE macro


Return code

08

Reason code

xxxx0841


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


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.


803

IXGWRITE macro


Return code

08

Reason code

xxxx085C


Equate symbol

: IxgRsnCodeDsDirectoryFull

Explanation


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.



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


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


804


IXGWRITE macro


Return code

08

Reason code

xxxx085D


Equate symbol

: IxgRsnCodeWowError

08 xxxx0860

Explanation


DASD have failed because of severe errors. No further write requests can be processed until the offload error condition is cleared.



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:


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.


805

IXGWRITE macro


Return code

08

Reason code

xxxx0861


Equate symbol


08

08


Explanation


Action


v


Equate symbol


Explanation


Action


v


Equate symbol


Explanation


Action


v


Equate symbol


Explanation


Action





806


IXGWRITE macro


Return code

08

Reason code

xxxx0865


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.


807

IXGWRITE macro


Return code

08

Reason code

xxxx0868


Equate symbol

: IxgRsnCodeStagingDSFormat

08


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


Explanation


Action


Equate symbol


Explanation


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


Equate symbol

: IxgRsnCodePrgramKey

Explanation



Action

: Change the invoking environment to a system key

(key 0-7).

Equate symbol


Explanation


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


IXGWRITE macro


Return code

0C

Reason code

xxxx0000


Equate symbol


Explanation


v


Action



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


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


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


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


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:



:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31-bit for LINK. 24- or 31- or 64-bit for LINKX.

Primary


No locks held



811

LINK and LINKX macros


None.

Restrictions



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


⌂

Syntax

name


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


Address of the ERRET exit.


None.

Syntax

The standard form of the LINK macro is written as follows:

Description


One or more blanks must precede LINK.

LINK

⌂

EP=entry name


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


Syntax

,LSEARCH=YES

Description

Parameters


EP=entry name



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



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.


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.


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.


815


Syntax


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.


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


One or more blanks must precede LINKX.

LINKX

⌂

EP=entry name



,DCB=dcb addr

,PARAM=(addr)


One or more blanks must follow LINKX.


entry name addr: A-type address, or register (2) - (12).



addr: A-type address, or register (2) - (12).

Note


(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


Syntax

,ID=id nmbr


,LSEARCH=NO

,LSEARCH=YES

,AMODE64OK=NO

,AMODE64OK=YES


Description


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

more information about ALETs and 8-bytes-per-entry parameter lists. See “User parameters” on page 4 for an example of passing a parameter list in AR mode.

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.


817


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.


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.


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.


Indicates that the 8-byte-per-entry parameter list is to consist of just the

8-byte addresses.


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



,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

⌂


One or more blanks must precede LINK or LINKX.

LINK

LINKX

⌂

EP=entry name



,DCB=dcb addr


,PLISTARALETS=NO

,PLIST8ARALETS=NO

,PLIST8ARALETS=YES


,LSEARCH=NO

,LSEARCH=YES

One or more blanks must follow LINK or LINKX.


entry name addr: A-type address.

list entry addr: A-type address.

dcb addr: A-type address.

Default


Note


Default

: PLIST8ARALETS=NO

Note


err rtn addr: A-type address.

Default

: No


819


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

⌂


One or more blanks must precede LINK or LINKX.

LINK

LINKX

⌂ One or more blanks must follow LINK or LINKX.

820


Syntax

EP=entry name



,DCB=dcb addr

,PARAM=(addr)


,PLIST4=YES

,PLIST4=NO

,PLIST8=YES

,PLIST8=NO


,PLISTARALETS=NO

,PLIST8ARALETS=NO

,PLIST8ARALETS=YES

,ID=id nmbr


,LSEARCH=NO

,LSEARCH=YES

,AMODE64OK=NO

,AMODE64OK=YES

,MF=(E,prob addr)

,SF=(E,ctrl addr)

,MF=(E,prob addr),SF=(E,ctrl

addr)


Description


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,addr,addr)

PLIST4 is valid only with LINKX.

Default

: None.

PLIST8 is valid only with LINKX.

Default

: None.

Default


Note


Default

: PLIST8ARALETS=NO

Note



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:


821


,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


|

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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31- or 64-bit

Primary


No locks held



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.



823

LOAD macro

|

|

|


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.


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.


Zero, indicating successful completion.

If the LOAD is not successful and the caller provided an ERRET exit to receive control, the GPRs contain:

824


⌂

Syntax

name

LOAD macro

0

1

Register

Contents


System completion code for the abend that would have been issued had the caller not provided an ERRET exit.

2-13

14

15

Unchanged.


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.



None.

Syntax

The standard form of the LOAD macro is written as follows:

Description


One or more blanks must precede LOAD.

LOAD

⌂

EP=entry name



,DCB=dcb addr


,LSEARCH=NO

One or more blanks must follow LOAD.


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


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



Parameters


EP=entry name



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)


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


|

|

|

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.


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’)


827

LOAD macro


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



LOAD

�

EP=entry name



,DCB=dcb addr



entry name addr: A-type address.



,LSEARCH=NO

,LSEARCH=YES

Default

: No

828


LOAD macro

Syntax

,LOADPT=addr

,EXTINFO=addr

,RELATED=value

,SF=L

Description

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

�



LOAD

�

EP=entry name



,DCB=dcb addr


,LSEARCH=NO



entry name addr: RX-type address, or register (2) - (12).



err rtn addr: RX-type address, or register (2) - (12).

Default

: No


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


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN = HASN

31-bit

Primary or AR


No locks held

Not applicable


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.


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.



Register

Contents

0-1

2-13


Unchanged

14

15


Return code



831

LSEXPAND macro

Syntax

Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

The LSEXPAND macro is written as follows:

Description

name

�


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


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


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


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


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


835

PGLOAD macro

Syntax

,RELEASE=Y

Description

Note:

RELEASE=Y may only be specified with EA above.

Parameters


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


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:


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


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

�


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


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

�


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


839

PGOUT macro

Parameters


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



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


One or more blanks must precede PGOUT.

PGOUT

840


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


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.





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

�


One or more blanks must precede PGRLSE.

PGRLSE


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


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.



Meaning

00

04


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


� One or more blanks must precede PGRLSE.

844


PGRLSE macro

Syntax

PGRLSE

�

LA=low addr,

,HA=high addr,

,MF=L

Description


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

�


One or more blanks must precede PGRLSE.

LA=low addr,

,HA=high addr,

,MF=(E,ctrl addr)


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

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


No locks held



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.


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.


847

PGSER macro

Syntax



Register

Contents

0-4

5-13


Unchanged

14

15


Return code

When control returns to the caller, the access registers (ARs) are unchanged.



None.

Syntax

The PGSER macro is written as follows:

Description

�

name


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


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.


v

Page is in PSA, SQA or LSQA.





,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


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.


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

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


v Page is in PSA, SQA or LSQA.




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


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


Environment

The requirements for callers of POST are:



:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


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.


None.

Restrictions

None.


853

POST macro

Syntax


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.


When control returns to the caller the general purpose registers (GPRs) contain:

Register

Contents

0-1

2-13

14

15


Unchanged


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



None.

Syntax

The POST macro is written as follows:

Description

name

⌂


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


POST macro

Syntax

,LINKAGE=SYSTEM

,RELATED=value

Description


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.



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’)


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task or SRB

PASN=HASN=SASN or PASN¬=HASN¬=SASN

24- or 31-bit

Primary


No locks held

Not applicable


Before invoking QRYLANG you must allocate storage for the LQB.

You must include the following mapping macros: v CNLMLQB v CNLMMCA

Restrictions

None.


Before issuing the QRYLANG macro, the caller must ensure that the following general purpose register (GPR) contains the specified information:


857

QRYLANG macro

Syntax

Register

Contents

13

Points to a save area


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


Return code



None.

Syntax

The QRYLANG macro is written as follows:

Description

name

�


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


QRYLANG macro

Parameters


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.


When QRYLANG completes, register 15 contains one of the following hexadecimal return codes:


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:


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.


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


The passed storage address is not valid.


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.


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


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


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




:


:


:

Requirement


Task

PASN=HASN=SASN


863

REFPAT macro


AMODE

:

ASC mode

:


:

Locks

:


:

Requirement

31-bit



No locks held



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.


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.



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


Unchanged

14

15


Return code


Register

Contents

1

2-13


Unchanged

14-15




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


�

Syntax

name

Syntax

The standard form of the REFPAT macro is written as follows:

Description


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


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:


,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:


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


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.


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


REFPAT macro


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

�




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.


Default

: 0D

Parameters

The parameters are explained under the standard form of the REFPAT macro with the following exception:


Specifies the list form of the REFPAT macro. list addr defines the area that the system is to use for the parameter list.


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

�



REFPAT

� One or more blanks must follow REFPAT.

INSTALL

REMOVE

,PSTART=start

start: RX-type address or register (2) - (12).

868


REFPAT macro

Syntax

,PEND=end

,STOKEN=stoken


,GAP=gap variable


,MF=(E,list addr)


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:



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.


869

REFPAT macro

870


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

For LINKAGE=SVC: PASN=HASN=SASN

For LINKAGE=SYSTEM: PASN=HASN=SASN or

PASN¬=HASN¬=SASN

24- or 31- or 64-bit

Primary


No locks held

If the caller's AMODE is 24-bit, all parameters must reside below 16 megabytes.


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


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



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.



Register

Contents

0-1

2-13


Unchanged

14

15


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.


Register

Contents

0-1

2-13


Unchanged

14-15



Syntax

The standard form of the RESERVE macro is written as follows:

Description

�

name


One or more blanks must precede RESERVE.

RESERVE

� One or more blanks must follow RESERVE.

872


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


(

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


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.


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.


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

described in Table 48.

Table 48. Return Codes for the RESERVE Macro with the RET=TEST Parameter

Hexadecimal

Return Code

0


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


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


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


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

: The active task now has control of the resource.

Action

: None.

876


RESERVE macro

Table 49. Return Codes for the RESERVE Macro with the RET=USE Parameter (continued)

Hexadecimal

Return Code

4


Meaning

: The resource is not immediately available.

8

Action


Meaning


Action


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


Action


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

: The active task now has control of the resource.

8

Action

: None.

Meaning


Action


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


Action



877

RESERVE macro

Table 50. Return Codes for the RESERVE Macro with the RET=HAVE

Parameter (continued)


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:


�

name



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


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:


name

�



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.


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


RESERVE macro

,MF=(E,ctrl addr)

Specifies the execute form of the RESERVE macro.



881

RESERVE macro

882


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

�


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


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


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


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

�


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


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


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


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


Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task or SRB


24- or 31- or 64-bit

Primary, secondary, or access register (AR)

Note:

Callers in secondary ASC mode cannot specify the

DUMPOPX parameter.



None


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.


Before issuing the SETRP macro, the caller must ensure that the following general purpose register (GPRs) contain the specified information:

Register

Contents


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.


Note:

Control does not return to the caller if the caller specifies the REGS parameter.


Register

Contents

0-1

2-13


Unchanged

14-15



Register

Contents

0-1


2-13

Unchanged

14-15




None.

888


SETRP macro

�

Syntax

name

Syntax

The SETRP macro is written as follows:

Description


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


Default

: FRESDWA=NO

Note


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


,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


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


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


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


ABEND codes

None.


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


893

SETRP macro

894


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:


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




:


:


:

AMODE

:

Requirement


Task

PASN=HASN=SASN

24- or 31-bit


895

SNAP and SNAPX macros


ASC mode

:


:

Locks

:


:

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.


No locks held, and no enabled, unlocked task (EUT) FRRs established



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.



Register

Contents

0-1

2-14

15


Unchanged

Return code


Register

Contents

0-1

2-13


Unchanged

14-15


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.


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


|

|

|

⌂

Syntax

name


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.


None.

Syntax

The standard form of the SNAP macro is written as follows:

Description


One or more blanks must precede SNAP.

Chapter 90. SNAP and SNAPX — Dump virtual storage and continue

897


Syntax

SNAP

⌂

DCB=dcb addr

,TCB=tcb addr

,ID=id nmbr

Description

One or more blanks must follow SNAP.


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


Syntax

,SUBPLST=sbp list addr


Description

sbp list addr: A-type address, or register (2) - (12).

Parameters


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.


899


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



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)


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.


901


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.


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.


Control is returned to the instruction following the SNAP macro. When control is returned, register 15 contains one of the following return codes:


Code

00

04

08

0C

10


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



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


903


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


One or more blanks must precede SNAPX.

SNAPX

�

DCB=dcb addr

,TCB=tcb addr

,ID=id nmbr

One or more blanks must follow SNAPX.


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


Syntax


addr)

,LIST=list addr

,STRHDR=(hdr addr)



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


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


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


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.


905


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


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.


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


Syntax


addr)

,LIST=list addr

,STRHDR=(hdr addr)



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



,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



907


Syntax

�

SNAP

SNAPX

�

DCB=dcb addr

Description

One or more blanks must precede SNAP.

One or more blanks must follow SNAP.


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)


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


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


Syntax

,STRHDR=(hdr addr)



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



,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’.


specifies the execute form of the SNAP or SNAPX macro using a remote control program parameter list.


909


910


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.


911

SPIE macro

Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

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


No locks held



The caller must include the following mapping macros: v IHAPIE v IHAPICA

Restrictions

None.


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.


When control returns to the caller, the general purpose registers (GPRs) contain the following information:

0

1

Register

Contents


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



Register

Contents

912


⌂

⌂

Syntax

name

SPIE macro

0-1

2-13


Unchanged

14-15




None.

Syntax

The standard form of the SPIE macro is written as follows:

Description


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


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.


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


SPIE macro

�

Syntax

name

Syntax

The list form of the SPIE macro is written as follows:

Description



SPIE

�

exit addr

,(interrupts)


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

�



Chapter 91. SPIE — Specify program interruption exit

915

SPIE macro

Syntax

SPIE

�

exit addr

,(interrupts)

Description


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))


,MF=(E,ctrl addr)

Parameters

The parameters are explained under the standard form of the SPIE macro, with the following exception:


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


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


v


v


v


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.


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task or SRB


24- or 31-bit




None.

�

Syntax

name


None.

Restrictions

None.


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.


When control returns to the caller, the general purpose registers (GPRs) and access registers (ARs) are all unchanged.


None.

Syntax

The SPLEVEL macro is written as follows:

Description


One or more blanks must precede SPLEVEL.

SPLEVEL

� One or more blanks must follow SPLEVEL.

TEST

918


SPLEVEL macro

Syntax

SET=n

SET

Description

n: 2, 3, 4, 5 or 6

Default

: SET=6

Parameters


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.


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


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

⌂


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


One or more blanks must follow STAE.

exit addr: A-type address, or register (2) - (12).

Default

: CT


Default

: XCTL=NO

Default

: PURGE=QUIESCE

Default

: ASYNCH=NO

921

STAE macro

Syntax

,RELATED=value

Description


Parameters


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


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

�



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


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


�

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



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)




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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task


31-bit



No locks held.

No requirements.


None.

Restrictions



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.



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged


927

STATUS macro

Syntax

14-15




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

�


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


Parameters


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


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.





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

: 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


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task or SRB


24-bit or 31-bit addressing mode



No requirement



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.


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.


933

STCKCONV macro

Syntax



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1


2-13

Unchanged

14-15




None.

Syntax

The standard form of the STCKCONV macro is written as follows:

Description

�

name


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


STCKCONV macro

Syntax

,DATETYPE=YYYYDDD

,DATETYPE=DDMMYYYY

,DATETYPE=MMDDYYYY

,DATETYPE=YYYYMMDD

Description

Default

: DATETYPE=YYYYDDD

Parameters



Specifies the address of an 8-byte storage area containing the 64-bit TOD clock value to be converted.


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.


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


C

Action

: None.

Meaning

: System error.

10

14

Action


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


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

�



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.


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

�



STCKCONV

�




,TIMETYPE=DEC

,TIMETYPE=BIN

,TIMETYPE=MIC

,DATETYPE=YYYYDDD

,DATETYPE=DDMMYYYY

,DATETYPE=MMDDYYYY

,DATETYPE=YYYYMMDD

,MF=(E,list addr)


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


Parameters

The parameters are explained under the standard form of the STCKCONV macro with the following exception:


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


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


939

STCKCONV macro

940


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


Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task or SRB


31-bit



Any locks may be held, no locks required




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.


941

STCKSYNC macro

Syntax


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.



Register

Contents

0-1

2-13

14

15


Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

The STCKSYNC macro is written as follows:

Description


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


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


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

: 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

: 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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31- or 64-bit

Primary


No locks held



The timer completion exit routine must be in virtual storage when it is required.

Restrictions

The following restrictions apply to the STIMER macro:


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.


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.


When control returns to the caller, the registers contain:

Register

Contents

0-1

2-13


Unchanged

14

15


0 (zero)


946


�

Syntax

name

STIMER macro

Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

The STIMER macro is written as follows:

Description


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


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


,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


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.


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


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.


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:


Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31- or 64-bit

Primary

Enabled for I/O or external interrupts

No locks held.



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


�

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.


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.


When control returns to the caller, the general purpose registers contain:

Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15


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 STIMERM macro is written as follows:

Description


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


,TOD=stor addr

,LT=stor 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


stor addr: RX-type address or register (2) - (12).

Note

: ID=ALL is only valid on the CANCEL request.




exit rtn addr: RX-type address or register (2) - (12).

Note

: EXIT must not be specified if WAIT=YES is specified.


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


SET

954


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


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


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.


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


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.


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.


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'


– X'210'

– X'220'

– X'224'

On STIMERM CANCEL requests: v X'32E'


– 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

: The STIMERM service has completed successfully.

Action

: None.

958


STIMERM macro

Table 55. Return Codes for the STIMERM Macro (continued)

Hexadecimal

Return Code

04


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


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.


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


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


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

�



STIMERM

� One or more blanks must follow STIMERM.

SET

TEST

CANCEL

,MF=L

,RELATED=value

Parameters


,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


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

�



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


,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


For CANCEL


stor addr: A-type address or register (2) - (12).

Note

: ID=ALL is valid only on the CANCEL request.



962


Syntax


,WAIT=YES

,WAIT=NO


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


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.


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


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


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


964


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:



:


:


:

AMODE

:

RMODE

:

ASC mode

:


:

Locks

:


:

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


24- or 31- or 64-bit

Includes 64-bit

For LINKAGE=SYSTEM: Primary or AR

For LINKAGE=SVC: Primary


No locks held.

No requirement.


None.

Restrictions

None.


Register usage varies depending on the type of STORAGE request. For specific information, see the descriptions of STORAGE OBTAIN and STORAGE RELEASE.


None.


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.


For a conditional request, contains the return code. For an unconditional request, which is used as a work register by the system.


Register

Contents

0


966


STORAGE macro

1

0 when the STORAGE OBTAIN is successful; otherwise, used as work register by the system.

2-13

Unchanged

14-15


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.


Contains the return code.


0

1

Register

Contents


0 when the STORAGE OBTAIN is successful; otherwise, used as work register by the system.

2-13

Unchanged

14-15



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

�


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


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


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


969

STORAGE macro

|

Syntax

,EXECUTABLE=NO

,RELATED=value

Description

value: Any valid macro parameter specification.

Parameters


OBTAIN

Requests that the system obtain virtual storage.


,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


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


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


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,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


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,


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


|

|

|

|

|

|

|

|

|

|

|

|

|

|

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


,EXECUTABLE=NO


,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


975

STORAGE macro

v 878 v

978 v A78 v B78 v D78


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

: 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


|

STORAGE macro

Table 56. Return Codes for STORAGE OBTAIN (continued)

Return Code

10


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.


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.



Register

Contents

0-1



977

STORAGE macro

Syntax

2-13

14

15

Unchanged.


For a conditional request, contains the return code. For an unconditional request, used as a work register by the system.


Register

Contents

0-1

2-13


Unchanged

14-15



Syntax

The STORAGE macro with the RELEASE option is written as follows:

Description

name

�


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


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


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


Parameters


RELEASE

Requests that the system release virtual storage.


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.


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.


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


,EXECUTABLE=NO


,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


STORAGE macro


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


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


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


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


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:



:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement

Problem state, and any PSW key.

Task or SRB


24- or 31-bit



No locks held.



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.


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.



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


Unchanged.

984


�

Syntax

name

SYMRBLD macro

14

15


Return code from the SYMREC macro if you code SYMRBLD COMPLETE with INVOKE=YES; otherwise, used as a work register by the system.


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

The standard form of the SYMRBLD macro with the INITIAL option is written as follows:

Description


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.


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


SYMRBLD macro


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:




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.


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.


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

�



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


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


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.


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’).


989

SYMRBLD macro


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


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.


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.


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.


Specifies the address of an optional halfword that contains the length of the


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

�



SYMRBLD


SECONDARY

,SR=storage addr


,SDBKEY=SDB key



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


Syntax


,DATA=data

,LEN=data length


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


Note

: DATA is required with SDBKEY only.



Note:

1.


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


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.


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.


,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’). See Table 58 on page 990 for valid SDB key names and literals.



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.


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.


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


�

�

Syntax

name

SYMRBLD macro

,TYPE=TEST

,TYPE=NOTEST



Syntax

The standard form of the SYMRBLD macro with the VARIABLE option is written as follows:

Description



SYMRBLD


VARIABLE

,SR=storage addr

,S5KEY=5key

,DATA=data

,LEN=data length


,TYPE=NOTEST

,TYPE=TEST


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.




Note:


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


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


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.


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



Syntax

The standard form of the SYMRBLD macro with the COMPLETE option is written as follows:

Description

name


�


996


SYMRBLD macro

Syntax

SYMRBLD

�

COMPLETE

,SR=storage addr

,INVOKE=YES

,INVOKE=NO

,RETCODE=return code

,RSNCODE=reason code

Description



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


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.


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

�



SYMRBLD


RESET

,SR=storage addr





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


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


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.


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:




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.


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:




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.


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


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


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


1001

SYMRBLD macro

1002


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task or SRB


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


1003

SYMREC macro

Syntax


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



0

1

Register

Contents

Reason code


2-13

14

15

Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

The standard form of the SYMREC macro is written as follows:

Description

name


1004


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


SR=addr

Specifies the address of the symptom record. The SR parameter is required.

ABEND codes

None.


When SYMREC returns control, registers 15 and 0 contain the following hexadecimal return codes and reason codes, respectively:


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

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


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.


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


Hexadecimal

Return Code

000C

000C

000C

0010

0010

0010

SYMREC macro

Hexadecimal

Reason Code

0134

0144

0F1C

0F04

0F08

0F0C


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.


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.


1007

SYMREC macro

Hexadecimal

Return Code

0010

0010

0010

0014

Hexadecimal

Reason Code

0F10

0F14

0F18

—


Meaning

: System error. The SYMREC service has a logic error. No symptom record was recorded.

Action


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


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


Meaning

: System error. SYMREC is not operable.

Action


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

�



SYMREC

� One or more blanks must follow SYMREC.

addr: A-type address (31 bit).

SR=addr

,MF=(L)

1008


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

�



SYMREC

�

SR=addr

,MF=(E,list addr)

One or more blanks must follow SYMREC.

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.


1009

SYMREC macro

1010


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31-bit for SYNCH; 24- or 31- or 64-bit for SYNCHX.

Primary


No locks held



1011

SYNCH and SYNCHX macros

Syntax


None.

Restrictions

None.


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.



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


Value the processing program placed there before it returned to the caller



None.

Syntax

The standard form of the SYNCH macro is written as follows:

Description

�

name


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


|

|

|

|

|

|

|

||

||

Syntax

,AMODE=24

,AMODE=31

,AMODE=DEFINED

,AMODE=CALLER

,RMODE64=NO

,RMODE64=YES


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


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



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


�

Syntax

name



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

Contents

0-13

Unchanged

14-15


Syntax

The SYNCHX macro is written as follows:

Description


One or more blanks must precede SYNCHX.

SYNCHX

�

entry point addr

One or more blanks must follow SYNCHX.


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



1015


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


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



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


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.


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:


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)


1017


1018


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.


1019

1020


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.


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task or SRB


24- or 31- or 64-bit

Primary or AR



None.


None.

Restrictions

None.


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.


When control returns to the caller, the general purpose registers (GPRs) contain the following information:

Register

Contents

0-15

Unchanged


Register

Contents

0-15

Unchanged

1022


SYSSTATE macro

⌂

Syntax

name


None.

Syntax

The SYSSTATE macro is written as follows:

Description


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


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


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.


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

Any

31-bit

Primary or AR


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


None.

Restrictions

None.


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.



Register

Contents

0



1027

TCBTOKEN macro

Syntax

1

2-13

14

15

Address of the TCBTOKEN parameter list

Unchanged


Return code


Register

Contents

0


1

2-13

ALET used to address the TCBTOKEN parameter list

Unchanged

14-15




None.

Syntax

The standard form of the TCBTOKEN macro is written as follows:

Description

name

⌂


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.


1028


TCBTOKEN macro

Parameters


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


Specifies the address at which the 16-byte TTOKEN associated with the specified TCB is returned.

,RELATED=value


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


00


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)


10


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



TCBTOKEN

1030


TCBTOKEN macro

Syntax

�

,RELATED=value

,MF=L

Description

One or more blanks must follow TCBTOKEN.


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

�



TCBTOKEN

�

One or more blanks must follow TCBTOKEN.

TYPE=CURRENT

TYPE=PARENT

TYPE=JOBSTEP


,RELATED=value

,MF=(E,cntl addr)

ttoken addr: RX-type address.


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks held

:


:

Requirement

Problem state.

Task or SRB


Any

Primary or AR


The caller can be locked or unlocked.

Not applicable


None.

Restrictions

None.


The input to the macro is the ALET and the caller's EAX.



Register

Contents

0-1

2-13

14


Unchanged



1033

TESTART macro

Syntax

15

Return code


Register

Contents

0-1

2-13


Unchanged

14-15



None.

Syntax

The TESTART macro is written as follows:

Description

name

�


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


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


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


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


Meaning

: The specified ALET represents a valid entry on the

PASN-AL.

Action


Meaning

: The specified ALET is 1.

Action


Meaning

: The specified ALET and/or EAX will cause an ART program interruption.

Action


Meaning

: A system error occurred in the TESTART service routine.

Action


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


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


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


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




:


:


:

Requirement


Task or SRB


2. External time reference (ETR) is the MVS generic name for the IBM Sysplex Timer.


1037

TIME macro


AMODE

:

ASC mode

:


:

Locks

:

Control Parameters

:

Requirement

24- or 31- or 64-bit







TIME. SYSSTATE ASCENV=AR tells the system to generate code appropriate for

AR mode.

Restrictions

None.


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.



Register

Contents

0-1

2-13


Unchanged

14

15


Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

1038


⌂

Syntax

name

TIME macro

Syntax

The standard form of the TIME macro with LINKAGE=SYSTEM is written as follows:

Description


One or more blanks must precede TIME.

TIME

⌂ One or more blanks must follow TIME.

Default

: DEC


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


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


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


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


Meaning

: System error.

Action


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


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

�



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


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



TIME

⌂ One or more blanks must follow TIME.

Default

: DEC


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


,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:


1043

TIME macro


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:

Control Parameters

:

Requirement


Task

PASN=HASN=SASN

24- or 31-bit addressing mode

Primary


No locks held



None.

Restrictions



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.


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


�

�

Syntax

name

TIME macro

14

15


Return code.



None.

Syntax

The standard form of the TIME macro with LINKAGE=SVC is written as follows:

Description



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


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


DEC

BIN

TU


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


TIME macro


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


1047

TIME macro

1048


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task


31- or 64-bit



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


None.

Restrictions

None.


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.


When control returns to the caller after the call to TIMEUSED, the general-purpose registers (GPR) contain:


1049

TIMEUSED macro

Register

0-1

2-13

14

15

Contents


Unchanged


Return code

||

|||

||

|

||

|

|

When control returns to the caller after the call to TIMEUSED, the AR contains:

Register

0-1

2-13

14-15

Contents


Unchanged


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.


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


⌂

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


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


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


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

: 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


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.


TRANMSG.

Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task or SRB


24- or 31-bit

Primary


No locks held

Not applicable


1055

TRANMSG macro


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.


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.


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


Unchanged


Return code



Translating multiple messages on one invocation of TRANMSG is more efficient than invoking TRANMSG multiple times with one message for each invocation.

1056


�

Syntax

name

Syntax

If you build the MIO, code the TRANMSG macro as follows:

Description


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

�


,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


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


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



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.


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:


Return Code

00

04

08


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


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:


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





The passed storage address is not valid.


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.



Input for the date format is not numeric. TRANMSG returned the date without formatting it.


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.



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


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.


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.


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 *

***********************************************************************

* *


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


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 *

***********************************************************************

* *


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

* *

***********************************************************************


***********************************************************************

* *

TRANMSG MIO=(R4)

OBTAIN INPUT AREA ADDRESS

SAVE INPUT AREA ADDRESS

INDICATE TRANSLATE

* *


1063

TRANMSG macro

***********************************************************************

* FREE STORAGE AREA *

***********************************************************************

* *


* *

***********************************************************************

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’


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

* *

***********************************************************************


***********************************************************************

* *



USING MIO,R4

L

AR

R2,MLENGTH

R2,R1


CALCULATE ADDRESS OF OUTPUT BUFFER

* *

***********************************************************************


***********************************************************************

*

TRANMSG MIO=MIO,MIOL=MLENGTH,INBUF=(SDT1A,THREE),


*

C

***********************************************************************

1064


TRANMSG macro


***********************************************************************

* *


* *

***********************************************************************

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

* *

***********************************************************************


***********************************************************************

* *



USING MIO,R4

L R2,MLENGTH

AR R2,R4

USING MTB,R2


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


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

***********************************************************************


***********************************************************************

*

TRANMSG MIO=MIO,MIOL=MLENGTH,INBUF=(LIST,ONE),


*

C

***********************************************************************


***********************************************************************

* *


* *

***********************************************************************

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’


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


TRANMSG macro


***********************************************************************

* *


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


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


GET ADDRESS OF SDT

INDICATE TRANSLATE

INDICATE CONTINUATION

POINT TO NEXT MESSAGE ADDR.

POINT TO NEXT MESSAGE ENTRY

LOOP UNTIL ALL MSGS PROCESSED

*

***********************************************************************


***********************************************************************

* *

TRANMSG MIO=(R4)

* *

***********************************************************************


***********************************************************************

* *


* *

***********************************************************************

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


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31- or 64-bit

Primary


No locks held



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.


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.



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.


1069

TTIMER macro

Syntax

1

2-13

14

15


Unchanged.


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.


None.

Syntax

The TTIMER macro is written as follows:

Description

name

�


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


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


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


04

Action

: None.

Meaning

: You specified the TU parameter, but the time remaining is greater than X'FFFFFFFF'.

Action


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task or SRB


24- or 31-bit

Primary


No locks held

No requirement


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.


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.


Before issuing the UCBDEVN macro, the caller must ensure that GPR 13 contains the address of an 18-word save area.



Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

The UCBDEVN macro is written as follows:

Description

name

⌂


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


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


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.


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


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





Requirement


Task or SRB


1077

UCBINFO macro



AMODE:

ASC mode:


Locks:


Requirement


24- or 31-bit



The caller may hold locks, but is not required to hold any



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.


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.



0

1

Register

Contents

A reason code; otherwise, used as a work register by the system


1078


UCBINFO macro

2-13

14

15

Unchanged


A return code


Register

Contents

0-1

2-13


Unchanged

14-15



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

�


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



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2





Parameters


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


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


Indicates the UCB count is based on one subchannel set. DEFAULT: ID


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


Indicates the UCB count is based on all subchannel sets. DEFAULT: ID


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=MAX




1081

|

|

|

|

|

UCBINFO macro





To code

, specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 2.


Specifies the address of a fullword field into which the system copies the return code from GPR 15.


Specifies the address of a fullword field into which the system copies the reason code from GPR 0.


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:

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


UCBINFO macro

Hexadecimal

Return Code

0C

20

Hexadecimal

Reason Code

None

None


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



UCBINFO

�



,PLISTVER=MAX

Default:

IMPLIED_VERSION


1083

UCBINFO macro

Syntax


MF=(L,list addr)

MF=(L,list addr, attr)


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:




Specifies the list form of the UCBINFO DEVCOUNT macro.



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

�



UCBINFO

� One or more blanks must follow UCBINFO.

DEVCOUNT

,COUNT=count addr count addr: RS-type address or register (2) - (12).

1084


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=0

,SUBCHANNELSET=ALL



Default:

0



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2




,MF=(E,list addr)




Default:

COMPLETE

UCBINFO macro

Parameters

The parameters are explained under the standard form of UCBINFO DEVCOUNT with the following exceptions:



Specifies the execute form of the UCBINFO DEVCOUNT macro.



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

�



UCBINFO


DEVINFO

,DEVIAREA=deviarea addr

,DEVN=devn addr


,SCHSET=0

deviarea addr: RX-type address or register (2) - (12).

devn addr: RS-type address or register (2) - (12).


Default:

0

,IOCTOKEN=ioctoken addr ioctoken addr: RX-type address or register (2) - (12).


,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2





Parameters


1086


|

|

UCBINFO macro

DEVINFO

Specifies that the system is to return information about the specified device.


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


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.




,PLISTVER=MAX







To code

, specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v

A decimal value of 2




1087

|

|

|

|

UCBINFO macro




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:


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:


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:


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


UCBINFO macro

Hexadecimal Return

Code

20

28


Code

None

None


Meaning:


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



The list form of the DEVINFO option of the UCBINFO macro is written as follows:

Description

�

name



UCBINFO



,PLISTVER=MAX

Default:

IMPLIED_VERSION


1089

UCBINFO macro

Syntax


MF=(L,list addr)



Description

plistver: 2



Default:

0D

Parameters

The parameters are explained under the standard form of UCBINFO DEVINFO with the following exceptions:




Specifies the list form of the UCBINFO DEVINFO macro.



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

�



UCBINFO


DEVINFO

,DEVIAREA=deviarea addr deviarea addr: RX-type address or register (2) - (12).

1090


Syntax

,DEVN=devn addr


,SCHSET=0


Description


schset addr RS-type address or register (2) - (12).

Default:

0



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2



,RSNCODE=rsncode addr rsncode addr: RX-type address or register (2) - (12).

,MF=(E,list addr)



Default:

COMPLETE

UCBINFO macro

Parameters

The parameters are explained under the standard form of UCBINFO DEVINFO with the following exceptions:



Specifies the execute form of the UCBINFO DEVINFO macro.



|

|

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




1091

UCBINFO macro

|

|

|

|

|

|

|

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

|

||

||

||

||

||

||

|

|

Syntax

UCBINFO

�

DEVINFO


,DEVN=devn addr

,SCHSET=schset

,SCHSET=0



,PLISTVER=MAX




Description


deviarea addr: RX-type address or register (2) - (12).


schset RS-type address or register (2) - (12).

Default:

0


Default:

IMPLIED_VERSION

plistver: 2



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.



The list form of the GETCDR option of the UCBINFO macro is written as follows:

Description

||

||

||

|||

||

||

|

Syntax

�

name



1092


UCBINFO macro

|

|

|

|

|

|

|

|

|

|

|

|

|

|

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

Syntax

UCBINFO

�

GETCDR


,PLISTVER=MAX


MF=(L,list addr)



Description


Default:

IMPLIED_VERSION

plistver: 2



Default:

0D

Parameters

The parameters are explained under the standard form of UCBINFO GETCDR with the following exceptions:




Specifies the list form of the UCBINFO GETCDR macro.



|

|

|

|

|

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




1093

UCBINFO macro

|

|

|

|

|

|

|

|

|

||

||

||

||

|

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

Syntax

UCBINFO

�

GETCDR

,DEVN=devn addr


,SCHSET=0

,PATHMASK=pathmask addr

,PATHMASK=0

,CDRAREA=cdrarea addr

,CDRLEN=cdrlen addr




,MF=(E,list addr)


Description




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



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2




Default:

COMPLETE

Parameters

The parameters are explained under the standard form of UCBINFO GETCDR with the following exceptions:



Specifies the execute form of the UCBINFO GETCDR macro.



1094


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=0

The standard form of the HYPERPAVALIASES option of the UCBINFO macro is written as follows:



Description




pavarea addr: RS-type address or register (2) - (12).

pavlen addr: RS-type address or register (2) - (12).

Default:

NO



Default:

0



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2



1095

UCBINFO macro

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

||

||

||

||

Syntax


Description


Parameters



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.


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


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.




,PLISTVER=MAX


Specifies the version of the macro. PLISTVER determines which parameter list

1096


|

|

|

|

|

||

|

| |

|

|||

|

|||

|

|

|||

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

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.





To code

, specify in this input parameter one of the following: v IMPLIED_VERSION v MAX v A decimal value of 2






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.


Code

00


Code

None

04

08

None

01

Meaning:

The HYPERPAVALIASES function completed successfully.

Action:

None.

Meaning:


Action:


Meaning:


Action:



1097

|

|

|||

|

|

|

|

|

|

|||

|

|

|

|

|||

|

|

|

|||

|

|

|

|

|

|||

|

|

|

|

|

|

|

|||

|

|

|

|

|||

|

|

|

|

|||

|

|

|

|

|

|

|||

|

| | |

| |

UCBINFO macro


Code

08

08

08

08

0C

20

30

30

30


Code

02

05

0A

0B

None

None

01

02

03


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:


Meaning:


IOCTOKEN parameter.

Action:


Meaning:

Program error. An error occurred when the system attempted to reference the area specified by the PAVAREA parameter.

Action:


PAVAREA parameter and reissue the macro.

Meaning:


Action:


Meaning:



IOCTOKEN parameter.

Action:



Meaning:


Action:



Meaning:

Program error. The device number provided by the caller is not a HyperPAV device.

Action:


Meaning:

Program error. The work area specified with the PAVAREA parameter is not large enough to contain the minimum amount of data.


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:


1098


UCBINFO macro

|

|||

|

| | |

| |

|

|


Code

34


Code

01


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.



||

||

||

||

||

||

||

||

||

|||

||

||

||

||

||

|

|

Syntax

�

name

UCBINFO

�

HYPERPAVALIASES

The list form of the HYPERPAVALIASES option of the UCBINFO macro is written as follows:


,PLISTVER=MAX


Description




Default:

IMPLIED_VERSION

plistver: 2


1099

UCBINFO macro

|

|

|

|

|

|

|

|

|

|

|

|

|

||

||

||

||

|

||

||

Syntax

MF=(L,list addr)



Description



Default:

0D

Parameters

The parameters are explained under the standard form of UCBINFO

HYPERPAVALIASES with the following exceptions:




Specifies the list form of the UCBINFO HYPERPAVALIASES macro.



|

|

|

|

|

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



The execute form of the HYPERPAVALIASES option of the UCBINFO macro is written as follows:

Description




pavarea addr: RS-type address or register (2) - (12).

pavlen addr: RS-type address or register (2) - (12).

1100


UCBINFO macro

|

|

|

|

|

|

|

|

|

||

||

||

||

||

||

||

||

||

||

||

||

||

||

||

|

||

||

||

||

||

||

||

||

Syntax

,SCHINFO=NO | YES

,DEVN=devn addr


,SCHSET=0




,MF=(E,list addr)


Description

Default:

NO



Default:

0



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2




Default:

COMPLETE

Parameters

The parameters are explained under the standard form of UCBINFO

HYPERPAVALIASES with the following exceptions:



Specifies the execute form of the UCBINFO HYPERPAVALIASES macro.



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:


1101

|

|

UCBINFO macro

Syntax

name

�

UCBINFO

�

PATHINFO

,PATHAREA=patharea addr

,DEVN=devn addr


,SCHSET=0

Description




patharea addr: RX-type address or register (2) - (12).



Default:

0



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2





Parameters


PATHINFO

Specifies that the system is to return information about the device path and type of channel path for the specified device.


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


|

UCBINFO macro

,DEVN=devn 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.






,PLISTVER=MAX


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 2


To code







1103

|

|

|

|

UCBINFO macro


When the UCBINFO PATHINFO macro returns control to your program, GPR 15




Code

00


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:


Action:


Meaning:


Action:


Meaning:


Action:


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:


IOCTOKEN parameter.

Action:


Meaning:

Program error. An error occurred when the system attempted to reference the area specified by the PATHAREA parameter.

Action:


PATHAREA parameter and reissue the macro.

Meaning:


Action:


Meaning:



IOCTOKEN parameter.

Action:



1104


UCBINFO macro


Code

18

18

20


Code

04

08

None


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:


Action:



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.



Syntax

The list form of the PATHINFO option of the UCBINFO macro is written as follows:

Description

name

�

UCBINFO




1105

UCBINFO macro

Syntax

�

Description



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2

MF=(L,list addr)





Default:

0D

Parameters

The parameters are explained under the standard form of UCBINFO PATHINFO with the following exceptions:




Specifies the list form of the UCBINFO PATHINFO macro.



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

�



UCBINFO


1106


Syntax

PATHINFO


,DEVN=devn addr


,SCHSET=0

Description

patharea addr: RX-type address or register (2) - (12).



Default:

0



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2



,MF=(E,list addr)





Default:

COMPLETE

UCBINFO macro

Parameters

The parameters are explained under the standard form of UCBINFO PATHINFO with the following exceptions:



Specifies the execute form of the UCBINFO PATHINFO macro.



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:


1107

UCBINFO macro


�

name



UCBINFO


PATHMAP

,MAPAREA=maparea addr

,DEVN=devn addr


,SCHSET=0


maparea addr: RX-type address or register (2) - (12).



Default:

0



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2





|

|

Parameters


PATHMAP

Specifies that the system is to return information about the device path for the specified device.


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



1108


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.






,PLISTVER=MAX







To code

, specify in this input parameter one of the following: v IMPLIED_VERSION v

MAX v A decimal value of 2






When the UCBINFO PATHMAP macro returns control to your program, GPR 15




1109

UCBINFO macro

|

|

|

|


Code

00

04

08

08

08

08

08

0C

10

20


Code

None

None

01

02

05

06

0B

None

04

None


Meaning:

The PATHMAP function completed successfully.

Action:

None.

Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


Meaning:


IOCTOKEN parameter.

Action:


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:


Action:


Meaning:



IOCTOKEN parameter.

Action:



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:


Action:



1110


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



The list form of the PATHMAP option of the UCBINFO macro is written as follows:

Description

�

name



UCBINFO



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2

MF=(L,list addr)





Default:

0D

Parameters

The parameters are explained under the standard form of UCBINFO PATHMAP with the following exceptions:


1111

UCBINFO macro




Specifies the list form of the UCBINFO PATHMAP macro.



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



UCBINFO

�


PATHMAP


,DEVN=devn addr


,SCHSET=0


maparea addr: RX-type address or register (2) - (12).



Default:

0



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2

1112


Syntax



,MF=(E,list addr)


Description




Default:

COMPLETE

UCBINFO macro

Parameters

The parameters are explained under the standard form of the UCBINFO

PATHMAP macro with the following exceptions:



Specifies the execute form of the UCBINFO PATHMAP macro.



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

�




PAVINFO

PAVINFOSUM=NO

PAVINFOSUM=YES


Default

: NO

pavarea addr: RX-type address or register (2) - (12).


1113

UCBINFO macro

Syntax

,PAVLEN=pavarea addr

,SCHINFO=NO

,SCHINFO=YES

,EXTFORMAT=NO

,EXTFORMAT=YES

,OUTVERSION=outver

,DEVN=devn addr


,SCHSET=0

Description


Default

: NO

Default

: NO

Default

: 3



Default:

0



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2





Parameters


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


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.


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.


1115

UCBINFO macro

YES

Create the extended format PAV area.


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






,PLISTVER=MAX







To code

, specify in this input parameter one of the following: v IMPLIED_VERSION

1116


|

|

|

|

UCBINFO macro

v MAX v

A decimal value in the range of 1 - 3.






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



Code

00


Code

None

04

08

08

08

08

08

None

01

02

03

05

0A


Meaning:

The PAVINFO function completed successfully.

Action:

None.

Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


Meaning:


Action:

Specify the DEVN parameter instead of the UCBPTR parameter to indicate the device for which the system is to obtain information.

Meaning:


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:


PAVAREA parameter and reissue the macro.


1117

UCBINFO macro


Code

08

0C

1C

1C

1C

20

28


Code

0B

None

01

02

03

None

None


Meaning:


Action:


Meaning:



IOCTOKEN parameter.

Action:



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:


Meaning:

Program error. The work area specified with the PAVAREA parameter is not large enough to contain the minimum amount of data.


Action:


Meaning:

Program error. The work area specified with the PAVAREA parameter is not large enough to contain an entry for each alias device.

Action:


Meaning:


Action:



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:


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


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



�

UCBINFO



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2

MF=(L,list addr)





Default:

0D

Parameters

The parameters are explained under the standard form of UCBINFO PAVINFO with the following exceptions:




Specifies the list form of the UCBINFO PAVINFO macro.


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.


1119

UCBINFO macro

Syntax

The execute form of the PAVINFO option of the UCBINFO macro is written as follows:

Description

name

�

UCBINFO

�




PAVINFO

PAVINFOSUM=NO

PAVINFOSUM=YES

Default

: NO




pavlen addr: RX-type address or register (2) - (12).

Default

: NO ,SCHINFO=NO

,SCHINFO=YES

,EXTFORMAT=NO

,EXTFORMAT=YES


Default

: NO

Default

: 3

,DEVN=devn addr


,SCHSET=0

devn addr: RX-type address or register (2) - (12).


Default:

0




,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2





,MF=(E,list addr) list addr: RX-type address or address in register (2) - (12).

1120


UCBINFO macro

Syntax


Description

Default:

COMPLETE

Parameters

The parameters are explained under the standard form of UCBINFO PAVINFO with the following exceptions:



Specifies the execute form of the UCBINFO PAVINFO macro.



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

�



UCBINFO

�


PRFXDATA

,DEVN=devn addr


,SCHSET=0



Default:

0

,UCBPAREA=ucbparea addr


ucbparea addr: RX-type address or register (2) - (12).



1121

UCBINFO macro



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2





|

Parameters


PRFXDATA

Specifies that the system is to obtain information from the UCB prefix extension segment.

,DEVN=devn 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.


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.






,PLISTVER=MAX



1122


|

|

|

|

UCBINFO macro





To code







When the UCBINFO PRFXDATA macro returns control to your program, GPR 15




Code

00


Code

None

04

08

08

08

None

01

02

03


Meaning:

The PRFXDATA function completed successfully.

Action:

None.

Meaning:


Action:


Meaning:


Action:


Meaning:


Action:


Meaning:


Action:

Specify the DEVN parameter instead of the UCBPTR parameter to indicate the device for which the system is to obtain information.


1123

UCBINFO macro


Code

08

08

0C

20


Code

05

0B

None

None


Meaning:


IOCTOKEN parameter.

Action:


Meaning:


Action:


Meaning:



IOCTOKEN parameter.

Action:



Meaning:


Action:



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



The list form of the PRFXDATA option of the UCBINFO macro is written as follows:

Description

name


1124


UCBINFO macro


� One or more blanks must precede UCBINFO.

UCBINFO



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2

MF=(L,list addr)





Default:

0D

Parameters

The parameters are explained under the standard form of UCBINFO PRFXDATA with the following exceptions:




Specifies the list form of the UCBINFO PRFXDATA macro.



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

�




1125

UCBINFO macro


UCBINFO


PRFXDATA

,DEVN=devn addr


,SCHSET=0

,UCBPTR=ucbptr addr



Default:

0

ucbptr addr: RS-type address or register (2) - (12).

Note:

Specify either DEVN or UCBPTR, but not both.



ucbparea addr: RX-type address or register (2) - (12).



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 2



,MF=(E,list addr)





Default:

COMPLETE

Parameters

The parameters are explained under the standard form of UCBINFO PRFXDATA with the following exceptions:



Specifies the execute form of the UCBINFO PRFXDATA macro.



1126


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






AMODE:

ASC mode:


Requirement


Task or SRB


24- or 31-bit.



Locks:



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


If in AR mode, issue SYSSTATE ASCENV=AR before issuing UCBSCAN.

Restrictions

None.


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.


1127

UCBSCAN macro

Syntax



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


Unchanged


Return code


Register

Contents

0-1

2-13


Unchanged

14-15



None.

Syntax

The standard form of the UCBSCAN macro is written as follows:

Description

name

�


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


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=NONE

Description

Default:

0

ioctoken addr: RX-type address or register (2) - (12).

Default:

NONE


,PLISTVER=MAX




Default:

IMPLIED_VERSION

plistver: 1

retcode addr: RX-type address or register (2) - (12).

rsncode addr: RX-type address or register (2) - (12).

Parameters


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


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.


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


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


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




Indicates the UCB scan is based on one subchannel set. DEFAULT: ID

,SCHSET=xschset


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.


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


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


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=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=MAX







To code

, specify in this input parameter one of the following: v IMPLIED_VERSION


1133

UCBSCAN macro

v MAX v

A decimal value of 1


Specifies the fullword location where the system is to store the return code.

The return code is also in GPR 15.


Specifies the fullword location where the system is to store the reason code.

The reason code is also in GPR 0.


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



Code

00


Code

None

04

08

08

08

08

08

01

01

02

03

04

05


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:


Action:


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:


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:


IOCTOKEN parameter.

Action:


1134


UCBSCAN macro


Code

08

08

08

08

08

08

0C

20


Code

08

09

0B

0C

0D

0E

None

None


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:


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.

Action:


UCBINFO macro to zero. Start the scan from the beginning.

Meaning:


Action:



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.


1135

UCBSCAN macro

Syntax

Syntax



The list form of the COPY function of the UCBSCAN macro is written as follows:

Description

�

name



UCBSCAN



,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 1

MF=(L,list addr)

MF=(L,list addr,attr)


list addr: Symbol.


Default:

0D

Parameters

The parameters are explained under that standard form of the UCBSCAN macro with the following exceptions:


MF=(L,list addr,attr)


Specifies the list form of the UCBSCAN macro.

The list addr parameter specifies the address of the storage area for the parameter list.


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


�

Syntax

name

UCBSCAN macro

Syntax

The execute form of the COPY function of the UCBSCAN macro is written as follows:

Description



UCBSCAN


COPY



workarea addr: RX-type address or register (2) - (12).

ucbarea addr: RX-type address or register (2) - (12).

,CMXTAREA= cmxtarea addr

,CMXTAREA=NONE


,UCBPAREA=NONE

,DCEAREA= dcearea addr

,DCEAREA=NONE



,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


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=0


,IOCTOKEN=NONE

devcid addr: RS-type address

Default:

0

ioctoken addr: RX-type address or register (2) - (12).

Default:

NONE


,PLISTVER=MAX


Default:

IMPLIED_VERSION

plistver: 1

,RETCODE=retcode addr retcode addr: RX-type address or register (2) - (12).


,MF=(E,list addr)


rsncode addr: RX-type address or register (2) - (12).

list addr: RX-type address or register (2) - (12).

Default:

COMPLETE

1138


UCBSCAN macro

Parameters

The parameters are explained under the standard form of the COPY function of the UCBSCAN macro with the following exceptions:



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.


1139

UCBSCAN macro

1140


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task or SRB


24- or 31-bit

Primary


No locks held

Not applicable


You must include the mapping macro CNLMMPB.

Restrictions

None.


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.



0

1

Register

Contents

Reason code


2-13

14

15

Unchanged


Return code


1141

UPDTMPB macro

Syntax



None.

Syntax

The UPDTMPB macro is written as follows:

Description


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


UPDTMPB macro

Parameters


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.


When UPDTMPB completes, register 15 contains one of the following hexadecimal return codes:


Return Code

00

0C


Processing unsuccessful. See reason codes.

When UPDTMPB completes, register 0 contains one of the following hexadecimal reason codes:


Return Code

0C

0C

0C

0C

00

0C

0C

Hexadecimal

Reason Code

36

37

38

3B

00

33

35


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


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 *

***********************************************************************


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

*

*

***********************************************************************


X

X

***********************************************************************

*


*

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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task or SRB


24- or 31- or 64-bit




None


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.


1147

VRADATA macro


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.



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.


Register

Contents

0-1

2-13


Unchanged

14-15


1148


⌂

⌂

Syntax

name

VRADATA macro



None.

Syntax

The VRADATA macro is written as follows:

Description


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


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.


Default

: 15

Default

: LEN,TEST

Parameters


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


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


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


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


Environment

The requirements for callers of WAIT are:



:


:


:

AMODE

:

RMODE:

ASC mode

:


:

Locks

:


:

Requirement


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.


None.

Restrictions

When using LINKAGE=SVC (the default), the caller cannot have an EUT FRR established.


1153

WAIT macro

Syntax


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.



Register

Contents

0-1


2-13

Unchanged

14-15


When control returns to the caller, the access registers (AR) contain:

Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

The WAIT macro is written as follows:

Description

�

name


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


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


Parameters


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


Chapter 116. WAIT — Wait for one or more events

1155

WAIT macro





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.


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


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31-bit

Primary


No locks held



None.


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.


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.



Register

Contents

0

Reason code

1-14

15

Unchanged

Return code


Register

Contents

0-1

2-13


Unchanged

14-15




None.

Syntax

The standard form of the WTL macro is written as follows:

Description

name

�


One or more blanks must precede WTL.

WTL

� One or more blanks must follow WTL.

1160


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.


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

: 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

: 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


Return Code

04

04

04

04

WTL macro

Reason Code

10

14

18

1C


Meaning

: System error. An internal error occurred.

The system issues message IEE390I.

Action


Meaning

: System error. The system encountered a

(VSM) error. The system issues message IEE390I.

Action


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.


1163

WTL macro

Return Code

04

04

Reason Code

20

24


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

�



WTL

�

‘msg’

One or more blanks must follow WTL.


1164


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

�



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.


1165

WTL macro

1166


Chapter 118. WTO- Write to operator

Description

The WTO macro allows you to write messages to one or more operator consoles.


WTO.

Environment




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31- or 64-bit

Primary


No locks held



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.


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,

see “Example 4” on page 1178.

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.



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.


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.


Return code.


Register

Contents

0-1

2-13


Unchanged

14-15



1168


WTO macro

⌂

Syntax

name


None.

Syntax

The standard form of the WTO macro is written as follows:

Description


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.


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


‘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


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:


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


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


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.


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


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.


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.


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.


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



When the WTO macro returns control to your program, GPR 15 contains one of the following return codes:


Return Code

00

02

Meaning


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


Hexadecimal

Return Code

04

18

30

WTO macro


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


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’


MSG2TXT DC C’JOBS REQUIRING 2 TAPES MAY BE RUN ON SECOND SHIFT’


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


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

�



WTO

�

‘msg’

(‘text’)

(‘text’,line type)

TEXT=

TEXT=((,line type),(,line

type),...(,line type))



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.


1179

WTO macro

Syntax




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



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


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

�



WTO

�

TEXT=(text addr)

TEXT=((text addr,),(text

addr,),...(text addr,))


,KEY=key



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.


If you code CART on the execute form of WTO, you must code

CART on the list form.


If you code KEY on the execute form of WTO, you must code KEY on the list form.


1181

WTO macro

Syntax

,TOKEN=token



,MF=(E,list addr)

Description


If you code TOKEN on the execute form of WTO, you must code TOKEN on the list form.


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.


Parameters

The parameters are explained under the standard form of the WTO macro, with the following exception:


Specifies the execute form of the WTO macro.


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

Requirement


Task

PASN=HASN=SASN

24- or 31- or 64-bit

Primary


No locks held



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.


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.



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.



0

1

Register

Contents


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.


Return code.


Register

Contents

0-1

2-13


Unchanged

14-15




None.

1184


WTOR macro

�

Syntax

name

Syntax

The standard form of the WTOR macro is written as follows:

Description


One or more blanks must precede WTOR.

WTOR

�

‘msg’,reply addr,reply length,ecb addr

TEXT=(text addr,reply

addr,reply length,ecb addr)



One or more blanks must follow WTOR.



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



BRDCST

HRDCPY

RESP

REPLY

NOTIME


,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




,KEY=key

,TOKEN=token

Description



console name: RX-type address or register (2) - (12).



Parameters


‘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


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.



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


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


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.


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.


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


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.


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



When the WTOR macro returns control to your program, GPR 15 contains one of the following return codes.


Return Code

00

Meaning


Action

: None. Be sure to delete the request by issuing the DOM macro.

1190


Hexadecimal

Return Code

02

04

18

WTOR macro


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


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

�



WTOR

�


1192


Syntax

‘msg’,reply addr,reply length,ecb addr

TEXT=(,reply addr,reply

length,ecb addr)




,RPLYISUR=

,CART=

,CONSID=

,CONSNAME=

,KEY=

,TOKEN=

WTOR macro

Description


reply addr: A-type address.

reply length: Symbol or decimal number.


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.



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


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

�



WTOR

�

,reply addr,reply length,ecb addr

TEXT=(text addr,reply addr,reply

length,ecb addr)

,RPLYISUR=reply console



reply addr: RX-type address, or register (2) - (12).

reply length: Symbol, decimal number, or register 2-12.


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


If you code CART on the execute form of WTOR, you must code

CART on the list form.

1194


Syntax



,KEY=key

,TOKEN=token

,MF=(E,list addr)

,MF=(E,list addr,EXTENDED)

WTOR macro

Description


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.


If you code KEY on the execute form of WTOR, you must code

KEY on the list form.


If you code TOKEN on the execute form of WTOR, you must code

TOKEN on the list form.


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,EXTENDED)

Specifies the execute form of the WTOR macro.


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


1195

WTOR macro

1196


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


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




:


:


:

AMODE

:

ASC mode

:


:

Locks

:


:

User parameters

:

Requirement


Task

PASN=HASN=SASN

24-bit or 31-bit for XCTL; 24- or 31- or 64-bit for XCTLX

Primary or access register


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


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



,DCB=dcb addr


entry name addr: A-type address or register (2) - (12).



1198



Syntax

,LSEARCH=NO

,LSEARCH=YES

Description

Default

: LSEARCH=NO

Parameters


(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



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)


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


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.


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

�


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




entry name addr: A-type address or register (2) - (12).


1200


Syntax

,DCB=dcb addr

,LSEARCH=NO

,LSEARCH=YES

Description


Default

: LSEARCH=NO


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

�


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 addr: A-type addresses.



Default

: LSEARCH=NO


1201


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


One or more blanks must precede XCTL.

XCTL

�

(reg1),

(reg1,reg2),

EP=entry name,



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





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


Syntax

,SF=(E,ctrl area)

,MF=(E,user area),SF=(E,ctrl

area)


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.


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


1203


Syntax

Syntax

The execute form of the XCTLX macro is written as follows:

Description

⌂

name


One or more blanks must precede XCTLX.

XCTLX

⌂

(reg1),

(reg1,reg2),

EP=entry name,



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





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=NO

,PLIST8ARALETS=NO

,PLIST8ARALETS=YES

Default

: None.

Default

: None.

Default


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



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

more information about ALETs and 8-bytes-per-entry parameter lists. See “User parameters” on page 4 for an example of passing a parameter list in AR mode.

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:


,PLIST4=YES

,PLIST4=NO


1205


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



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.


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.


Indicates that the parameter list is not also to contain the ALETs. Do not specify this parameter with 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.


Indicates that the 8-byte-per-entry parameter list is to consist of just the

8-byte addresses.


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



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.


1207

1208


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


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


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


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.


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


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


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


Index

Numerics

31-bit addressing mode macros requiring expansion

STIMER macro 945

SYNCH 1011

WTOR macro 1183

XCTL macro 1197

A

accessibility 1209 contact IBM 1209 features 1209

action message 1175, 1186

addressing mode and the services 2

ALET qualification

of parameters 4

AMODE (addressing mode) changing

using the LINK macro 811

AR () mode

description 3

ASC (address space control) mode

defining 3

assistive technologies 1209

B

branch macro

converting to relative branch 125,

127

C

callable service

coding 16

central storage

loading virtual storage 835

coding the callable services 16

coding the macros 13

completion of an event

signalling 853

contact

z/OS 1209

continuation line 16

control

passing to another load module 811

D

data sharing with IARVSERV macro 63

device measurement block index

obtaining 429

E

ECB (event control block)

setting 853


ETR (external time reference)

checking for TOD clock

event

synchronization with 941

signalling completion 853

I

I/O configuration token

obtaining 429

IARCP64 macro 25

IARR2V macro 41

IARST64 macro 47

IARV64 macro 77

IARVSERV macro

data sharing 63

IDENTIFY macro 115

IEA4APE callable service 289

IEA4APE2 callable service 293

IEA4DPE callable service 299

IEA4DPE2 callable service 303

IEA4PME2 callable service 307

IEA4PSE callable service 315

IEA4PSE2 callable service 321

IEA4RLS callable service 327

IEA4RLS2 callable service 331

IEA4RPI callable service 337

IEA4RPI2 callable service 343

IEA4TPE callable service 349

IEA4XFR callable service 353

IEA4XFR2 callable service 359

IEAARR macro 119

IEABRC macro 125

IEABRCX macro 127

IEAFP macro 131

IEAINTKN macro 143

IEALSQRY macro 147

IEAMETR macro 151

IEAN4CR callable service 171

IEAN4DL macro 177

IEAN4RT callable service 181

IEANTCR callable service 155

IEANTDL macro 161

IEANTRT callable service 165

IEATXDC macro 205

IEAVAPE callable service 209

IEAVAPE2 callable service 213

IEAVDPE callable service 221

IEAVDPE2 callable service 225

IEAVPME2 callable service 229

IEAVPSE callable service 237

IEAVPSE2 callable service 243

IEAVRLS callable service 249

IEAVRLS2 callable service 255

IEAVRPI callable service 261

IEAVRPI2 callable service 267

IEAVTPE callable service 273

IEAVXFR callable service 277

IEAVXFR2 callable service 283

IEFDDSRV macro 365

IEFOPZQ macro 379

IEFPRMLB macro 391

IEFSSI macro 421

incident token

building 143

IOCINFO macro 429

IOS (input/output supervisor)

building control unit entry 445

obtaining information 437

IOSCHPD macro 437

IOSCUMOD macro 445

ITTUINIT service 519

ITTUTERM service 523

ITTUWRIT service 527

ITZEVENT macro 531

ITZQUERY macro 541

IXGBRWSE macro 547

IXGCONN macro 593

IXGDELET macro 617

IXGIMPRT macro 635

IXGINVNT macro 653

IXGOFFLD macro 769

IXGQUERY macro 780

IXGUPDAT macro 791

IXGWRITE macro 791

K

keyboard

navigation 1209

PF keys 1209 shortcut keys 1209

L

LINK and LINKX macros 811

linkage stack

query macro 147

LOAD macro 823

load module

adding an entry name 115

bringing into virtual storage 823

passing control 811

Logrec Data Set

symptom record entries from

SYMREC macro 1003

LSEXPAND macro 831

M

macro

coding 13

forms 12

level

selecting 1

sample 14

selecting level 1

user parameter, passing 4

X-macros

using 11

1219

multiple timer

setting 951

N

navigation

keyboard 1209

summary of changes xxix

Summary of changes xxx

symptom record 1003

SYMRBLD macro 983

SYMREC macro 1003

SYNCH and SYNCHX macros 1011

synchronous exit 1014

SYSEVENT macro 1019

SYSSTATE macro 1021

P

paging service

PGLOAD macro 835

PGOUT macro 839

PGRLSE macro 843

PGSER macro 847

PGLOAD macro 835

PGOUT macro 839

PGRLSE macro 843

PGSER macro 847

POST macro 853

process symptom record 1003

program object

bringing into virtual storage 823

T

TCBTOKEN macro 1027

TESTART macro 1033

time interval

testing 951

TIME macro 1037

timer

setting a multiple 951

TIMEUSED macro 1049

TOD (time-of-day) clock

checking for synchronization with

ETR 941

converting value 933

obtaining contents 941, 1037

TRANMSG macro 1055

TTIMER macro 1069

Q

QRYLANG macro 857

R

REFPAT macro 863

RESERVE macro 871

RETURN macro 883

S

SAVE macro 885

sending comments to IBM xxvii

service

ALET qualification 4

summary 18

services

addressing mode 2

ASC mode

defining 3

using 1

SETRP macro 887

shared DASD

reserve a device 871

sharing storage with IARVSERV macro 63

shortcut keys 1209

SNAP and SNAPX macros 895

specify program interruption exit 911

SPIE macro 911

SPLEVEL macro 917

STAE macro 921

STATUS macro 927

STCKCONV macro 933

STCKSYNC macro 941

STIMER macro 945

STIMERM macro 951

STORAGE macro 965

subtask

changing status 927

U

UCB (unit control block)

scanning 1127

UCBDEVN macro 1073

UCBINFO macro 1077

UCBSCAN macro 1127

UPDTMPB macro 1141

user interface

ISPF 1209

TSO/E 1209

user parameter

passing 4

V

virtual storage

bringing in a load module 823 bringing in a program object 823

loading 835, 847

page-ahead function 835

paging out 839, 847

planning for future needs 835

releasing contents 843, 847

Virtual storage

sharing with IARVSERV macro 63

VRA (variable recording area)

updating data 1147

VRADATA macro 1147

W

WAIT macro 1153

WTL macro 1159

WTO macro 1167

WTOR macro 1183

1220


X

X-macros

using 11

XCTL and XCTLX macros 1197

IBM®

Product Number: 5650-ZOS

Printed in USA

SA23-1370-30

z/OS MVS Assembler Services Reference IAR-XCT

MVS Programming: Assembler Services

Reference, Volume 2 (IAR-XCT)

IBM®

Key Features

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?

Table of contents