z/OS

IBM

MVS Programming: Assembler Services

Guide

SA22-7605-04

z/OS

IBM

MVS Programming: Assembler Services

Guide

SA22-7605-04

Note
Before using this information and the product it supports, be sure to read the general information under Notices on
page C-1.

Fifth Edition, September 2002

This is a major revision of SA22-7605-03
This edition applies to Version 1 Release 4 of z/OS (5694-A01), Version 1 Release 4 of z/OS.e (5655-G52), and
to all subsequent releases and modifications until otherwise indicated in new editions.
Order documents through your IBM representative or the IBM branch office serving your locality. Documents are not
stocked at the address below.
IBM welcomes your comments. A form for readers comments may be provided at the back of this document, or you
may address your comments to the following address:
International Business Machines Corporation
Department 55JA, Mail Station P384
2455 South Road
Poughkeepsie, NY 12601-5400
United States of America
FAX (United States & Canada): 1+845+432-9405
FAX (Other Countries):
Your International Access Code +1+845+432-9405
IBMLink (United States customers only): IBMUSM10(MHVRCFS)
Internet e-mail: mhvrcfs@[Link]
World Wide Web: [Link]
If you would like a reply, be sure to include your name, address, telephone number, or FAX number.
Make sure to include the following in your comment or note:
v Title and order number of this document
v Page number or topic related to your comment
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
Copyright International Business Machines Corporation 1988, 2002. All rights reserved.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Tables

. . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

About this document . . . . . . . . . . . .

Who should use this document . . . . . . . . .
How to use this document. . . . . . . . . . .
Where to find more information . . . . . . . . .
Accessing z/OS licensed documents on the Internet
Using LookAt to look up message explanations . .
Information updates on the web . . . . . . . .

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

xix
xix
xix
xix
xx
xx
xx

Summary of changes . . . . . . . . . . . . . . . . . . . . . xxiii

Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . 1-1
Chapter 2. Linkage Conventions . . . . . . . . . . . . .
Saving the Calling Programs Registers . . . . . . . . . . .
Caller-Provided Save Area . . . . . . . . . . . . . . .
Linkage Convention for Floating Point Registers . . . . . . .
Linkage Convention for the Floating Point Control Register . . .
System-Provided Linkage Stack . . . . . . . . . . . . .
Using the Linkage Stack . . . . . . . . . . . . . . . . .
Example of Using the Linkage Stack . . . . . . . . . . .
Using a Caller-Provided Save Area . . . . . . . . . . . . .
If Not Changing Bits 031 of the 64bit GPR . . . . . . . .
If Changing the contents of bits 0-31 of the 64-bit GPRs . . . .
If Starting in AMODE 64 . . . . . . . . . . . . . . . .
Establishing a Base Register for AMODE 24 or AMODE 31 programs
Establishing a Base Register for AMODE 64 programs . . . . .
Linkage Procedures for Primary Mode Programs. . . . . . . .
Primary Mode Programs Receiving Control . . . . . . . . .
Primary Mode Programs Returning Control . . . . . . . . .
Primary Mode Programs Calling Another Program . . . . . .
Linkage Procedures for AR Mode Programs . . . . . . . . .
AR Mode Programs Receiving Control . . . . . . . . . .
AR Mode Programs Returning Control . . . . . . . . . .
AR Mode Programs Calling Another Program . . . . . . . .
Conventions for Passing Information Through a Parameter List . .
Program in Primary Mode . . . . . . . . . . . . . . .
Programs in AR Mode . . . . . . . . . . . . . . . .
Chapter 3. Subtask Creation and Control . . . .
Creating the Task. . . . . . . . . . . . . .
Priorities . . . . . . . . . . . . . . . . .
Address Space Priority. . . . . . . . . . .
Task Priority. . . . . . . . . . . . . . .
Subtask Priority . . . . . . . . . . . . .
Assigning and Changing Priority . . . . . . .
Stopping and Restarting a Subtask (STATUS Macro)
Task and Subtask Communications . . . . . . .

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

. 2-1
. 2-2
. 2-2
. 2-2
. 2-2
. 2-3
. 2-3
. 2-3
. 2-4
. 2-4
. 2-6
. 2-7
. 2-9
. 2-10
. 2-10
. 2-10
. 2-11
. 2-12
. 2-12
. 2-12
. 2-13
. 2-13
. 2-13
. 2-13
. 2-14
.
.
.
.
.
.
.
.
.

3-1
3-1
3-1
3-1
3-2
3-2
3-2
3-3
3-3

Chapter 4. Program Management . . . . . . . . . . . . . . . . . 4-1

Copyright IBM Corp. 1988, 2002

iii

Residency and Addressing Mode of Programs . . . . . . .

Residency Mode Definitions . . . . . . . . . . . . .
Addressing Mode Definitions . . . . . . . . . . . .
Linkage Considerations . . . . . . . . . . . . . . .
Floating Point Considerations . . . . . . . . . . . .
Passing Control Between Programs with the Same AMODE .
Passing Control Between Programs with Different AMODEs .
Passing Control Between Programs with All Registers Intact .
Load Module Structure Types . . . . . . . . . . . . .
Simple Structure . . . . . . . . . . . . . . . . .
Dynamic Structure . . . . . . . . . . . . . . . .
Load Module Execution . . . . . . . . . . . . . . .
Passing Control in a Simple Structure . . . . . . . . . .
Passing Control without Return . . . . . . . . . . .
Passing Control with Return . . . . . . . . . . . . .
Passing Control in a Dynamic Structure . . . . . . . . .
Bringing the Load Module into Virtual Storage. . . . . .
Passing Control with Return . . . . . . . . . . . .
Passing Control without Return . . . . . . . . . . .
APF-authorized Programs and Libraries . . . . . . . . .
Additional Entry Points . . . . . . . . . . . . . . .
Entry Point and Calling Sequence Identifiers as Debugging Aids
Retrieving Information About Loaded Modules. . . . . . .
Using the CSVINFO Macro. . . . . . . . . . . . .
Coding a MIPR for the CSVINFO Macro . . . . . . . .
Using CSVRTLS to Request Run-Time Library Services (RTLS)

iv

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 4-1
. 4-2
. 4-2
. 4-2
. 4-3
. 4-3
. 4-3
. 4-4
. 4-6
. 4-6
. 4-7
. 4-7
. 4-7
. 4-7
. 4-9
. 4-14
. 4-15
. 4-21
. 4-24
. 4-27
. 4-28
. 4-28
. 4-29
. 4-29
. 4-31
. 4-33

Chapter 5. Understanding 31-Bit Addressing . . . . . . . . . . .

Virtual Storage. . . . . . . . . . . . . . . . . . . . . . . .
Addressing Mode and Residency Mode . . . . . . . . . . . . .
Requirements for Execution in 31-Bit Addressing Mode . . . . . . . .
Rules and Conventions for 31-Bit Addressing . . . . . . . . . . .
Mode Sensitive Instructions . . . . . . . . . . . . . . . . . .
Branching Instructions . . . . . . . . . . . . . . . . . . . .
Use of 31-Bit Addressing . . . . . . . . . . . . . . . . . . .
Planning for 31-Bit Addressing . . . . . . . . . . . . . . . . . .
Converting Existing Programs . . . . . . . . . . . . . . . . .
Writing New Programs That Use 31-Bit Addressing . . . . . . . . .
Writing Programs for MVS/370 and MVS Systems with 31-Bit Addressing
Addressing Mode and Residency Mode . . . . . . . . . . . . . .
Addressing Mode - AMODE . . . . . . . . . . . . . . . . .
Residency Mode - RMODE . . . . . . . . . . . . . . . . .
AMODE and RMODE Combinations . . . . . . . . . . . . . .
AMODE and RMODE Combinations at Execution Time . . . . . . .
Determining the AMODE and RMODE of a Load Module. . . . . . .
Assembler H Support of AMODE and RMODE . . . . . . . . . .
DFP Linkage Editor Support of AMODE and RMODE . . . . . . . .
DFP Loader Support for AMODE and RMODE . . . . . . . . . .
MVS Support of AMODE and RMODE . . . . . . . . . . . . .
How to Change Addressing Mode . . . . . . . . . . . . . . .
Establishing Linkage . . . . . . . . . . . . . . . . . . . . .
Using the BASSM and BSM Instructions . . . . . . . . . . . . .
Using Pointer-Defined Linkage . . . . . . . . . . . . . . . .
Using Supervisor-Assisted Linkage . . . . . . . . . . . . . . .
Linkage Assist Routines . . . . . . . . . . . . . . . . . . .
Using Capping - Linkage Using a Prologue and Epilogue . . . . . .

. 5-1
. 5-1
. 5-1
. 5-3
. 5-4
. 5-4
. 5-5
. 5-5
. 5-6
. 5-6
. 5-9
5-10
. 5-12
. 5-12
. 5-12
. 5-12
. 5-12
. 5-13
. 5-14
. 5-15
. 5-17
. 5-18
. 5-20
. 5-21
. 5-23
. 5-26
. 5-28
. 5-29
. 5-34

z/OS V1R4.0 MVS Assembler Services Guide

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

Performing I/O in 31-Bit Addressing Mode . . . . .

Using the EXCP Macro . . . . . . . . . . .
Using EXCPVR . . . . . . . . . . . . . .
Understanding the Use of Central Storage . . . . .
Central Storage Considerations for User Programs .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

Chapter 6. Resource Control . . . . . . . . . . . . . . . . .

Synchronizing Tasks (WAIT, POST, and EVENTS Macros) . . . . . .
Synchronizing Tasks (Pause, Release, and Transfer) . . . . . . . .
Pause Elements and Pause Element Tokens . . . . . . . . . .
Using the Services . . . . . . . . . . . . . . . . . . . .
Serializing Access to Resources (ENQ and DEQ Macros) . . . . . . .
Naming the Resource . . . . . . . . . . . . . . . . . . .
Defining the Scope of a Resource . . . . . . . . . . . . . .
Requesting Exclusive or Shared Control . . . . . . . . . . . .
Limiting Concurrent Requests for Resources . . . . . . . . . .
Processing the Requests . . . . . . . . . . . . . . . . .
Serializing Access to Resources through the RESERVE Macro . . .
Collecting Information about Resources and Their Requestors (GQSCAN
Macro) . . . . . . . . . . . . . . . . . . . . . . . .
How GQSCAN Returns Resource Information . . . . . . . . . .
Chapter 7. Program Interruption Services . . .
Specifying User Exit Routines . . . . . . . .
Using the SPIE Macro . . . . . . . . . .
Using the ESPIE Macro . . . . . . . . .
Environment Upon Entry to Users Exit Routine.
Functions Performed in User Exit Routines . .

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

Chapter 8. Providing Recovery . . . . . . . . . . . . . .

Understanding General Recovery Concepts . . . . . . . . . .
Deciding Whether to Provide Recovery. . . . . . . . . . .
Understanding Errors in MVS . . . . . . . . . . . . . .
Understanding Recovery Routine States . . . . . . . . . .
Understanding the Various Routines in a Recovery Environment .
Choosing the Appropriate Recovery Routine . . . . . . . . .
Understanding Recovery Routine Options . . . . . . . . . .
Understanding How Routines in a Recovery Environment Interact .
Writing Recovery Routines . . . . . . . . . . . . . . . .
Understanding What Recovery Routines Do . . . . . . . .
Understanding the Means of Communication . . . . . . . .
Special Considerations for ESTAE-Type Recovery Routines . .
Understanding the Recovery Environment . . . . . . . . . .
Register Contents . . . . . . . . . . . . . . . . . .
Other Environmental Factors in Recovery . . . . . . . . .
Understanding Recovery through a Coded Example . . . . . .
Understanding Advanced Recovery Topics . . . . . . . . . .
Invoking RTM (ABEND Macro) . . . . . . . . . . . . .
Providing Multiple Recovery Routines . . . . . . . . . . .
Providing Recovery for Recovery Routines . . . . . . . . .
Providing Recovery for Multitasking Programs. . . . . . . .
Using STAE/STAI Routines. . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 6-1
. 6-2
. 6-3
. 6-4
. 6-5
. 6-8
. 6-9
. 6-10
. 6-11
. 6-11
. 6-11
. 6-15

. . 6-16
. . 6-16

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

5-35
5-36
5-36
5-47
5-48

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

7-1
7-1
7-2
7-3
7-4
7-4

. 8-1
. 8-2
. 8-3
. 8-4
. 8-5
. 8-5
. 8-6
. 8-8
. 8-9
. 8-10
. 8-11
. 8-17
. 8-23
. 8-27
. 8-28
. 8-32
. 8-37
. 8-39
. 8-39
. 8-40
. 8-41
. 8-41
. 8-42

Chapter 9. Dumping Virtual Storage (ABEND, SNAPX, SNAP, and

IEATDUMP Macros). . . . . . . . . . . . . . . . . . . . . . 9-1
ABEND Dumps . . . . . . . . . . . . . . . . . . . . . . . . 9-1
Contents

Obtaining a Symptom Dump. . . . . . . . . . . .

Suppressing Dumps That Duplicate Previous Dumps . .
SNAP Dumps . . . . . . . . . . . . . . . . . .
Finding Information in a SNAP Dump . . . . . . . .
Obtaining a Summary Dump for an ABEND or SNAP Dump
Transaction Dumps . . . . . . . . . . . . . . . .

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

Chapter 10. Reporting Symptom Records (SYMRBLD and SYMREC

Macros) . . . . . . . . . . . . . . . . . . . . . . .
Writing Symptom Records to Logrec Data Set. . . . . . . . . .
The Format of the Symptom Record . . . . . . . . . . . . .
Symptom Strings SDB Format . . . . . . . . . . . . .
Building a Symptom Record Using the SYMRBLD Macro . . . . .
Building a Symptom Record Using the ADSR and SYMREC Macros .
Programming Notes for Section 1 . . . . . . . . . . . . .
Programming Notes for Section 2 . . . . . . . . . . . . .
Programming Notes for Section 2.1 . . . . . . . . . . . .
Programming Notes for Section 3 . . . . . . . . . . . . .
Programming Notes for Section 4 . . . . . . . . . . . . .
Programming Notes for Section 5 . . . . . . . . . . . . .
Chapter 11. Virtual Storage Management . . . . .
Explicit Requests for Virtual Storage . . . . . . .
Obtaining Storage Through the GETMAIN Macro .
Obtaining Storage Through the STORAGE Macro .
Using the CPOOL Macro . . . . . . . . . .
Subpool Handling . . . . . . . . . . . . .
Implicit Requests for Virtual Storage . . . . . . .
Reenterable Load Modules . . . . . . . . .
Reenterable Macros . . . . . . . . . . . .
Non-reenterable Load Modules . . . . . . . .
Freeing of Virtual Storage . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

. 11-1
. 11-1
. 11-2
. 11-4
. 11-6
. 11-6
. 11-10
. 11-10
. 11-11
. 11-12
. 11-12

.
.
.
.
.
.
.
.
.
.
.

. 12-1
. 12-1
. 12-2
. 12-2
. 12-3
. 12-3
. 12-5
. 12-8
. 12-9
. 12-9
. 12-9
. 12-10
. 12-12
12-12
. 12-12
. 12-13
. 12-13
. 12-14
. 12-14

.
.
.
.
.

Chapter 12. Using the 64-bit Address Space . . . . . . . . . .

What is the 64-bit Address Space? . . . . . . . . . . . . . . .
Why do you use Virtual Storage Above the Bar? . . . . . . . . . .
Memory Objects. . . . . . . . . . . . . . . . . . . . . .
Using Assembler Instructions in the 64-bit Address Space . . . . . .
64-bit Binary Operations. . . . . . . . . . . . . . . . . .
64-bit Addressing Mode (AMODE) . . . . . . . . . . . . . .
IARV64 Services . . . . . . . . . . . . . . . . . . . . .
Protecting Storage above the Bar . . . . . . . . . . . . . .
Relationship Between the Memory Object and Its Owner. . . . . .
Creating Memory Objects . . . . . . . . . . . . . . . . .
Using a Memory Object . . . . . . . . . . . . . . . . .
Discarding Data in a Memory Object. . . . . . . . . . . . . .
Releasing the Physical Resources that Back Pages of Memory Objects
Freeing a Memory Object . . . . . . . . . . . . . . . . . .
Example of Freeing a Memory Object . . . . . . . . . . . .
Creating a Guard Area and Changing its Size . . . . . . . . . .
Example of Creating a Memory Object with a Guard Area . . . . .
An Example of Creating, Using, and Freeing a Memory Object . . . .

.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

9-2
9-2
9-8
9-8
9-8
9-9

10-1
10-1
10-2
10-3
10-3
10-3
10-4
10-5
10-5
10-7
10-7
10-7

Chapter 13. Callable Cell Pool Services . . . . . . . . . . . . . . 13-1

Comparison of CPOOL Macro and Callable Cell Pool Services . . . . . . 13-2
Storage Considerations . . . . . . . . . . . . . . . . . . . . 13-2

vi

z/OS V1R4.0 MVS Assembler Services Guide

Link-editing Callable Cell Pool Services .

Using Callable Cell Pool Services . . . .
Handling Return Codes . . . . . . . .
Callable Cell Pool Services Coding Example
AMODE 24 or 31 . . . . . . . . .
AMODE 64 . . . . . . . . . . .

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

Chapter 14. Data-in-Virtual . . . . . . . . .

When to Use Data-in-Virtual . . . . . . . . .
Factors Affecting Performance . . . . . . .
Creating a Linear Data Set . . . . . . . . .
Using the Services of Data-in-Virtual . . . . . .
Identify . . . . . . . . . . . . . . . .
Access . . . . . . . . . . . . . . . .
Map . . . . . . . . . . . . . . . . .
Save, Savelist, and Reset . . . . . . . . .
Unmap . . . . . . . . . . . . . . . .
Unaccess . . . . . . . . . . . . . . .
Unidentify . . . . . . . . . . . . . . .
The IDENTIFY Service . . . . . . . . . . .
The ACCESS Service . . . . . . . . . . .
The MAP Service . . . . . . . . . . . . .
The SAVE Service . . . . . . . . . . . .
The SAVELIST Service. . . . . . . . . . .
The RESET Service . . . . . . . . . . . .
Effect of RETAIN mode on RESET . . . . .
The UNMAP Service . . . . . . . . . . .
The UNACCESS and UNIDENTIFY Services . .
Sharing Data in an Object . . . . . . . . .
Miscellaneous Restrictions for Using Data-in-Virtual
DIV Macro Programming Examples . . . . . .
General Program Description . . . . . . .
Data-in-Virtual Sample Program Code . . . .
Executing the Program . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Chapter 15. Using Access Registers . .

Access Lists . . . . . . . . . . . .
Types of Access Lists. . . . . . . .
Writing Programs in AR Mode . . . . .
Coding Instructions in AR Mode . . . . .
Manipulating the Contents of ARs . . . .
Loading an ALET into an AR . . . . .
Loading the Value of Zero into an AR . .
The ALESERV Macro. . . . . . . . .
Adding an Entry to an Access List . . .
Deleting an Entry from an Access List. .
Issuing MVS Macros in AR Mode . . . .
Example of Using SYSSTATE. . . . .
Using X-Macros . . . . . . . . . .
Formatting and Displaying AR Information.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

Chapter 16. Data Spaces and Hiperspaces . . . . . . . . . .

What are Data Spaces and Hiperspaces? . . . . . . . . . . .
What Can a Program Do With a Data Space or a Hiperspace? . . .
How Does a Program Obtain a Data Space and a Hiperspace? . .
How Does a Program Move Data into a Data Space or Hiperspace?

.
.
.
.

.
.
.
.

.
.
.
.
.
.

13-4
13-4
13-6
13-6
13-6
13-9

. 14-1
. 14-1
. 14-2
. 14-3
. 14-3
. 14-3
. 14-4
. 14-4
. 14-5
. 14-6
. 14-6
. 14-6
. 14-6
. 14-7
. 14-9
. 14-14
. 14-16
. 14-17
. 14-17
. 14-18
. 14-19
. 14-20
. 14-20
. 14-20
. 14-20
. 14-21
. 14-26

. 15-1
. 15-3
. 15-3
. 15-4
. 15-5
. 15-6
. 15-6
. 15-7
. 15-7
. 15-7
. 15-8
. 15-9
. 15-9
. 15-9
. . . . . . . . . . . . . 15-10
.
.
.
.

16-1
16-1
16-1
16-2
16-2

Contents

vii

Who Owns a Data Space or Hiperspace? . . . . . . . . . . . . . 16-2

Can an Installation Limit the Use of Data Spaces and Hiperspaces? . . . 16-3
How Does a Program Manage the Storage in a Data Space or Hiperspace? 16-3
Differences Between Data Spaces and Hiperspaces . . . . . . . . . . 16-4
Comparing Data Space and Hiperspace Use of Physical Storage . . . . 16-5
Which One Should Your Program Use? . . . . . . . . . . . . . . . 16-5
An Example of Using a Data Space . . . . . . . . . . . . . . . 16-6
An Example of Using a Hiperspace . . . . . . . . . . . . . . . 16-6
Creating and Using Data Spaces . . . . . . . . . . . . . . . . . 16-6
Manipulating Data in a Data Space. . . . . . . . . . . . . . . . 16-7
Rules for Creating, Deleting, and Managing Data Spaces . . . . . . . 16-7
Creating a Data Space . . . . . . . . . . . . . . . . . . . . 16-8
Establishing Addressability to a Data Space . . . . . . . . . . . . 16-12
Examples of Moving Data into and out of a Data Space . . . . . . . 16-12
Extending the Current Size of a Data Space . . . . . . . . . . . . 16-14
Releasing Data Space Storage . . . . . . . . . . . . . . . . . 16-15
Paging Data Space Storage Areas into and out of Central Storage
16-15
Deleting a Data Space . . . . . . . . . . . . . . . . . . . . 16-16
Using Callable Cell Pool Services to Manage Data Space Areas . . . . 16-16
Sharing Data Spaces among Problem-State Programs with PSW Keys 8 F . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-18
Sharing Data Spaces through the PASN-AL . . . . . . . . . . . . 16-20
Example of Mapping a Data-in-Virtual Object to a Data Space . . . . . 16-20
Using Data Spaces Efficiently . . . . . . . . . . . . . . . . . 16-22
Example of Creating, Using, and Deleting a Data Space . . . . . . . 16-22
Dumping Storage in a Data Space . . . . . . . . . . . . . . . 16-23
Using Checkpoint/Restart . . . . . . . . . . . . . . . . . . . 16-23
Creating and Using Hiperspaces . . . . . . . . . . . . . . . . . 16-24
Standard Hiperspaces . . . . . . . . . . . . . . . . . . . . 16-25
Creating a Hiperspace . . . . . . . . . . . . . . . . . . . . 16-26
Transferring Data To and From Hiperspaces . . . . . . . . . . . . 16-27
Extending the Current Size of a Hiperspace . . . . . . . . . . . . 16-32
Releasing Hiperspace Storage . . . . . . . . . . . . . . . . . 16-32
Deleting a Hiperspace . . . . . . . . . . . . . . . . . . . . 16-32
Example of Creating a Standard Hiperspace and Using It . . . . . . . 16-33
Using Data-in-Virtual with Hiperspaces . . . . . . . . . . . . . . 16-34
Using Checkpoint/Restart . . . . . . . . . . . . . . . . . . . 16-38
Chapter 17. Window Services . . . . . . . . . .
Data Objects . . . . . . . . . . . . . . . . .
Permanent. . . . . . . . . . . . . . . . .
Temporary Data Objects. . . . . . . . . . . .
Structure of a Data Object . . . . . . . . . . .
What Does Window Services Provide? . . . . . .
The Ways That Window Services Can Map an Object .
Access to Permanent Data Objects . . . . . . .
Access to Temporary Data Objects . . . . . . . .
Using Window Services . . . . . . . . . . . . .
Obtaining Access to a Data Object . . . . . . . .
Defining a View of a Data Object . . . . . . . .
Defining the Expected Reference Pattern . . . . .
Defining Multiple Views of an Object . . . . . . .
Saving Interim Changes to a Permanent Data Object
Updating a Temporary Data Object . . . . . . .
Refreshing Changed Data . . . . . . . . . .
Updating a Permanent Object on DASD . . . . .

viii

z/OS V1R4.0 MVS Assembler Services Guide

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 17-1
. 17-1
. 17-1
. 17-1
. 17-1
. 17-2
. 17-3
. 17-6
. 17-7
. 17-7
. 17-9
. 17-10
. 17-12
. 17-13
. 17-14
. 17-15
. 17-15
. 17-16

Changing a View in a Window . . .

Terminating Access to a Data Object.
Link-editing Callable Window Services
Window Services Coding Example . .

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

Chapter 18. Sharing Application Data (Name/Token Callable Services)

Understanding Name/Token Pairs and Levels . . . . . . . . . . .
Name/Token Pairs . . . . . . . . . . . . . . . . . . . .
Levels for Name/Token Pairs . . . . . . . . . . . . . . . .
Determining What Your Program Can Do with Name/Token Pairs . .
Deciding What Name/Token Level You Need . . . . . . . . . . .
Task-Level Name/Token Pair . . . . . . . . . . . . . . . .
Home-Level Name/Token Pair . . . . . . . . . . . . . . .
Owning and Deleting Name/Token Pairs . . . . . . . . . . . . .
Using Checkpoint/Restart with Name/Token Pairs . . . . . . . . .
Link-Editing Name/Token Services . . . . . . . . . . . . . . .
Chapter 19. Processor Storage Management . . . . . .
Freeing Virtual Storage . . . . . . . . . . . . . . .
Releasing Storage . . . . . . . . . . . . . . . . .
Protecting a Range of Virtual Storage Pages . . . . . . .
Loading/Paging Out Virtual Storage Areas . . . . . . . .
Virtual Subarea List (VSL) . . . . . . . . . . . . . .
Page Service List (PSL) . . . . . . . . . . . . . . .
Defining the Reference Pattern (REFPAT) . . . . . . . .
How Does the System Handle the Data in an Array? . . .
Using the REFPAT Macro . . . . . . . . . . . . .
Examples of Using REFPAT to Define a Reference Pattern
Removing the Definition of the Reference Pattern . . . .

.
.
.
.
.
.
.
.
.
.

.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

Chapter 20. Sharing Data in Virtual Storage (IARVSERV Macro) .

Understanding the Concepts of Sharing Data with IARVSERV . . .
Storage You Can Use with IARVSERV . . . . . . . . . . .
Obtaining Storage for the Source and Target . . . . . . . . .
Defining Storage for Sharing Data and Access . . . . . . . .
Changing Storage Access . . . . . . . . . . . . . . . .
How to Share and Unshare Data . . . . . . . . . . . . .
Accessing Data in a Sharing Group . . . . . . . . . . . .
Example of Sharing Storage with IARVSERV . . . . . . . . .
Use with Data-in-Virtual (DIV Macro) . . . . . . . . . . . .
Diagnosing Problems with Shared Data . . . . . . . . . . .
Converting a Central to Virtual Storage Address (IARR2V Macro) .

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

Chapter 21. Timing and Communication . . . . . . . . . . .

Checking for Timer Synchronization . . . . . . . . . . . . .
Obtaining Time of Day and Date. . . . . . . . . . . . . . .
Converting Between Time of Day and Date and TOD Clock Formats .
Interval Timing . . . . . . . . . . . . . . . . . . . . .
Obtaining Accumulated Processor Time . . . . . . . . . . . .
Writing and Deleting Messages (WTO, WTOR, DOM, and WTL) . . .
Routing the Message . . . . . . . . . . . . . . . . . .
Writing a Multiple-Line Message . . . . . . . . . . . . . .
Embedding Label Lines in a Multiple-Line Message. . . . . . .
Communicating in a Sysplex Environment . . . . . . . . . . .
Writing to the Programmer . . . . . . . . . . . . . . . .
Writing to the System Log . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

17-16
17-18
17-18
17-19

.
.
.
.
.
.
.
.
.
.

18-1
18-1
18-1
18-2
18-2
18-3
18-3
18-4
18-5
18-5
18-6

. 19-1
. 19-2
. 19-2
. 19-3
. 19-3
. 19-4
. 19-5
. 19-5
. 19-6
. 19-9
. . . . . . 19-13
. . . . . . 19-14
.
.
.
.
.
.
.
.
.
.
.
.

20-1
20-2
20-2
20-3
20-3
20-4
20-5
20-6
20-7
20-8
20-9
20-9

. 21-1
. 21-1
. 21-1
. 21-2
. 21-2
. 21-4
. 21-4
. 21-6
. 21-9
. 21-9
. 21-9
. . . 21-10
. . . 21-10
Contents

ix

Deleting Messages Already Written . . . . .

Retrieving Console Information (CONVCON Macro)
Determining the Name or ID of a Console . . .
Validating a Console Name or ID and Checking if
Validating a Console Area ID . . . . . . .

.
.
.
a
.

. . . . . . .
. . . . . . .
. . . . . . .
Console Is Active
. . . . . . .

Chapter 22. Translating Messages . . . . . . . . . . . . .

Allocating Data Sets for an Application . . . . . . . . . . . .
Creating Install Message Files . . . . . . . . . . . . . . .
Creating a Version Record . . . . . . . . . . . . . . . .
Creating Message Skeletons . . . . . . . . . . . . . . .
Message Skeleton Format . . . . . . . . . . . . . . . .
Message Text in a Skeleton . . . . . . . . . . . . . . .
Validating Message Skeletons . . . . . . . . . . . . . . .
Allocating Storage for Validation Run-Time Message Files . . . .
Compiling Message Files . . . . . . . . . . . . . . . .
Checking the Message Compiler Return Codes . . . . . . . .
Updating the System Run-Time Message Files . . . . . . . . .
Using MMS Translation Services in an Application. . . . . . . .
Determining which Languages are Available (QRYLANG Macro) .
Retrieving Translated Messages (TRANMSG Macro) . . . . . .
Example of Displaying Messages . . . . . . . . . . . . .
Using Message Parameter Blocks for New Messages (BLDMPB and
UPDTMPB Macros) . . . . . . . . . . . . . . . . . .
Support for Additional Languages . . . . . . . . . . . . . .
Example of an Application that Uses MMS Translation Services. . .

. . 21-10
. . 21-11
. . 21-11
21-12
. . 21-13
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

22-1
22-3
22-3
22-3
22-4
22-4
22-6
22-7
22-7
22-8
22-11
22-11
22-12
22-12
22-13
22-14

. . . 22-15
. . . 22-16
. . . 22-17

Chapter 23. Data Compression and Expansion Services . . . .

Services Provided by CSRCESRV . . . . . . . . . . . . . .
Running under an MVS/ESA System . . . . . . . . . . . .
Running under an MVS/XA System . . . . . . . . . . . .
Services Provided by CSRCMPSC . . . . . . . . . . . . . .
Compression and Expansion Dictionaries . . . . . . . . . .
Building the CSRYCMPS Area . . . . . . . . . . . . . .
Determining if the CSRCMPSC Macro Can Be Issued on a System.
Compression Processing . . . . . . . . . . . . . . . .
Expansion Processing . . . . . . . . . . . . . . . . .
Dictionary Entries . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

23-1
23-1
23-2
23-3
23-4
23-5
23-5
23-7
23-8
23-9
23-9

Chapter 24. Accessing Unit Control Blocks (UCBs)

Detecting I/O Configuration Changes . . . . . . .
Scanning UCBs . . . . . . . . . . . . . . .
Obtaining UCB Information for a Specified Device . .
Obtaining Eligible Device Table Information . . . . .
Using the EDTINFO Macro. . . . . . . . . .

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

24-1
24-1
24-2
24-3
24-3
24-4

Chapter 25. The Internal Reader . . . . .

Setting Up and Using an Internal Reader . .
Allocating the Internal Reader Data Set . .
Opening the Internal Reader Data Set . .
Sending Job Output to the Internal Reader .
Closing the Internal Reader Data Set . . .

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

25-1
25-1
25-1
25-2
25-2
25-3

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

Chapter 26. Using the Symbol Substitution Service . . . . . . . . . 26-1

What Are Symbols? . . . . . . . . . . . . . . . . . . . . . . 26-1
Types of Symbols . . . . . . . . . . . . . . . . . . . . . . 26-1

z/OS V1R4.0 MVS Assembler Services Guide

Examples of User Symbols. . . . . . .

Calling the ASASYMBM Service . . . . . .
Setting Up the ASASYMBP Mapping Macro
Providing a Symbol Table to ASASYMBM .
Using Symbols in Programs . . . . . .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

Chapter 27. Using System Logger Services . . . . . . . . . . .

What is System Logger? . . . . . . . . . . . . . . . . . . .
The Log Stream. . . . . . . . . . . . . . . . . . . . . .
The System Logger Configuration . . . . . . . . . . . . . . . .
The System Logger Component . . . . . . . . . . . . . . . .
The LOGR Couple Data Set (LOGR Policy) . . . . . . . . . . .
Log Data on The Coupling Facility . . . . . . . . . . . . . . .
Log Data on DASD Log Data Sets . . . . . . . . . . . . . . .
Duplexing Log Data . . . . . . . . . . . . . . . . . . . .
Overview of System Logger Services . . . . . . . . . . . . . . .
Summary of System Logger Services . . . . . . . . . . . . .
Define Authorization to System Logger Resources. . . . . . . . .
Synchronous and Asynchronous Processing . . . . . . . . . . .
Coding a System Logger Complete Exit for IXGBRWSE, IXGWRITE, and
IXGDELET . . . . . . . . . . . . . . . . . . . . . .
How System Logger Handles Gaps in the Log Stream . . . . . . .
Dumping on Data Loss (804type) Conditions . . . . . . . . . .
Using the System Logger Answer Area (ANSAREA parameter) . . . .
Using ENF Event Code 48 in System Logger Applications . . . . . .
IXGINVNT: Managing the LOGR Policy . . . . . . . . . . . . . .
Defining a Model Log Stream in the LOGR Couple Data Set . . . . .
Defining a Log Stream as DASD-Only . . . . . . . . . . . . .
Upgrading an Existing Log Stream Configuration . . . . . . . . .
Updating a Log Streams Attributes . . . . . . . . . . . . . .
IXGCONN: Connecting to and Disconnecting From a Log Stream . . .
IXGWRITE: Writing to a Log Stream . . . . . . . . . . . . . .
IXGBRWSE: Browsing/Reading a Log Stream . . . . . . . . . .
IXGDELET: Deleting Log Blocks from a Log Stream . . . . . . . .
IXGIMPRT: Import Log Blocks . . . . . . . . . . . . . . . .
IXGQUERY: Get Information About a Log Stream . . . . . . . . .
IXGOFFLD: Initiate Offload to DASD Log Data Sets . . . . . . . .
IXGUPDAT: Modify Log Stream Control Information . . . . . . . .
Setting Up the System Logger Configuration . . . . . . . . . . .
Reading Data From Log Streams in Data Set Format . . . . . . .
When Things Go Wrong - Recovery Scenarios for System Logger

.
.
.
.
.

26-2
26-3
26-3
26-4
26-9

. 27-1
. 27-1
. 27-2
. 27-4
. 27-6
. 27-7
. 27-8
. 27-8
. 27-8
. 27-9
. 27-10
. 27-10
. 27-11
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

27-13
27-14
27-15
27-17
27-18
27-20
27-20
27-21
27-22
27-23
27-23
27-32
27-34
27-39
27-40
27-41
27-45
27-46
27-47
27-49
27-54

Chapter 28. Unicode Instruction Services: CSRUNIC . . . . . . . . . 28-1

Appendix A. Using the Unit Verification Service . . . . . .
Functions of Unit Verification . . . . . . . . . . . . . .
Check Groups - Function Code 0 . . . . . . . . . . . .
Check Units - Function Code 1 . . . . . . . . . . . .
Return Unit Name - Function Code 2 . . . . . . . . . .
Return Unit Control Block (UCB) Addresses - Function Code 3 .
Return Group ID - Function Code 4 . . . . . . . . . . .
Indicate Unit Name is a Look-up Value - Function Code 5. . .
Return Look-up Value - Function Code 6 . . . . . . . . .
Convert Device Type to Look-up Value - Function Code 7. . .
Return Attributes - Function Code 8 . . . . . . . . . . .
Specify Subpool for Returned Storage - Function Code 10 . .

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

A-1
A-1
A-1
A-1
A-1
A-2
A-2
A-2
A-2
A-2
A-2
A-2

Contents

xi

Return Unit Names for a Device Class - Function Code 11 . . . . . . . A-2

Appendix B. Accessibility . . . . . . . . . . . . . . . . . . . . B-1
Using assistive technologies . . . . . . . . . . . . . . . . . . . B-1
Keyboard navigation of the user interface . . . . . . . . . . . . . . . B-1
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1
Programming Interface Information . . . . . . . . . . . . . . . . . C-2
Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . C-2
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-1

xii

z/OS V1R4.0 MVS Assembler Services Guide

Figures
2-1.
2-2.
2-3.
2-4.
2-5.
3-1.
4-1.
4-2.
4-3.
4-4.
4-5.
4-6.
4-7.
4-8.
4-9.
4-10.
4-11.
4-12.
4-13.
4-14.
4-15.
4-16.
4-17.
4-18.
4-19.
4-20.
5-1.
5-2.
5-3.
5-4.
5-5.
5-6.
5-7.
5-8.
5-9.
5-10.
5-11.
5-12.
5-13.
5-14.
5-15.
6-1.
6-2.
6-3.
6-4.
6-5.
6-6.
6-7.
6-8.
6-9.
6-10.
7-1.

Format of the Save Area . . . . . . . . . . . . . . . . . . . . . . . .

Format of the Format 5 Save Area (F5SA) . . . . . . . . . . . . . . . . . .
Format of the Format 4 Save Area (F4SA) . . . . . . . . . . . . . . . . . .
Primary Mode Parameter List . . . . . . . . . . . . . . . . . . . . . .
AR Mode Parameter List . . . . . . . . . . . . . . . . . . . . . . . .
Levels of Tasks in a Job Step. . . . . . . . . . . . . . . . . . . . . . .
Assembler Definition of AMODE/RMODE . . . . . . . . . . . . . . . . . .
Example of Addressing Mode Switch . . . . . . . . . . . . . . . . . . . .
Passing Control in a Simple Structure. . . . . . . . . . . . . . . . . . . .
Passing Control With a Parameter List . . . . . . . . . . . . . . . . . . .
Passing Control With Return . . . . . . . . . . . . . . . . . . . . . .
Passing Control With CALL . . . . . . . . . . . . . . . . . . . . . . .
Test for Normal Return . . . . . . . . . . . . . . . . . . . . . . . . .
Return Code Test Using Branching Table . . . . . . . . . . . . . . . . . .
Establishing a Return Code . . . . . . . . . . . . . . . . . . . . . . .
Using the RETURN Macro . . . . . . . . . . . . . . . . . . . . . . .
RETURN Macro with Flag . . . . . . . . . . . . . . . . . . . . . . .
Search for Module, EP or EPLOC Parameter With DCB=0 or DCB Parameter Omitted
Search for Module, EP or EPLOC Parameters With DCB Parameter Specifying Private
Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Search for Module Using DE Parameter . . . . . . . . . . . . . . . . . .
Use of the LINK Macro with the Job or Link Library . . . . . . . . . . . . . .
Use of the LINK Macro with a Private Library . . . . . . . . . . . . . . . .
Use of the BLDL Macro . . . . . . . . . . . . . . . . . . . . . . . .
The LINK Macro with a DE Parameter . . . . . . . . . . . . . . . . . . .
Misusing Control Program Facilities Causes Unpredictable Results . . . . . . . .
Processing Flow for the CSVINFO Macro and the Callers MIPR . . . . . . . . .
Two Gigabyte Virtual Storage Map . . . . . . . . . . . . . . . . . . . . .
Maintaining Correct Interfaces to Modules that Change to AMODE 31 . . . . . . . .
AMODE and RMODE Combinations . . . . . . . . . . . . . . . . . . . .
AMODE and RMODE Processing by the Linkage Editor . . . . . . . . . . . .
AMODE and RMODE Processing by the Loader . . . . . . . . . . . . . . .
Mode Switching to Retrieve Data from Above 16 Megabytes . . . . . . . . . . .
Linkage Between Modules with Different AMODEs and RMODEs . . . . . . . . .
BRANCH and SAVE and Set Mode Description. . . . . . . . . . . . . . . .
Branch and Set Mode Description. . . . . . . . . . . . . . . . . . . . .
Using BASSM and BSM . . . . . . . . . . . . . . . . . . . . . . . .
Example of Pointer-Defined Linkage . . . . . . . . . . . . . . . . . . . .
Example of Supervisor-Assisted Linkage . . . . . . . . . . . . . . . . . .
Example of a Linkage Assist Routine . . . . . . . . . . . . . . . . . . .
Cap for an AMODE 24 Module . . . . . . . . . . . . . . . . . . . . . .
Performing I/O While Residing Above 16 Megabytes . . . . . . . . . . . . . .
Event Control Block (ECB) . . . . . . . . . . . . . . . . . . . . . . . .
Using LINKAGE=SYSTEM on the WAIT and POST Macros. . . . . . . . . . . .
Pause and Release Example . . . . . . . . . . . . . . . . . . . . . . .
Release and Pause Example . . . . . . . . . . . . . . . . . . . . . . .
Transfer without Pause Example . . . . . . . . . . . . . . . . . . . . .
ENQ Macro Processing . . . . . . . . . . . . . . . . . . . . . . . .
Interlock Condition . . . . . . . . . . . . . . . . . . . . . . . . . .
Two Requests For Two Resources . . . . . . . . . . . . . . . . . . . .
One Request For Two Resources . . . . . . . . . . . . . . . . . . . . .
Work Area Contents for GQSCAN with a Scope of STEP, SYSTEM, SYSTEMS, or ALL
Using the SPIE Macro . . . . . . . . . . . . . . . . . . . . . . . . .

Copyright IBM Corp. 1988, 2002

. . 2-4
. . 2-6
. . 2-8
. . 2-14
. . 2-14
. . 3-4
. . 4-1
. . 4-4
. . 4-8
. . 4-9
. . 4-10
. . 4-11
. . 4-12
. . 4-12
. . 4-13
. . 4-14
. . 4-14
4-17
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

4-18
4-19
4-22
4-22
4-23
4-23
4-27
4-31
. 5-2
. 5-7
. 5-13
. 5-16
. 5-18
. 5-21
. 5-23
. 5-24
. 5-25
. 5-26
. 5-28
. 5-29
. 5-31
. 5-35
. 5-38
. 6-2
. 6-3
. 6-6
. 6-7
. 6-8
. 6-12
. 6-14
. 6-15
. 6-15
6-18
. 7-3

xiii

8-1.
8-2.
11-1.
11-2.
11-3.
13-1.
14-1.
14-2.
14-3.
15-1.
15-2.
15-3.
16-1.
16-2.
16-3.
16-4.
16-5.
16-6.
16-7.
16-8.
16-9.
16-10.
16-11.
17-1.
17-2.
17-3.
17-4.
17-5.
17-6.
18-1.
18-2.
18-3.
19-1.
19-2.
19-3.
19-4.
19-5.
19-6.
20-1.
20-2.
21-1.
21-2.
21-3.
22-1.
22-2.
22-3.
22-4.
22-5.
22-6.
22-7.
22-8.
22-9.
23-1.
26-1.

xiv

Mainline Routine with One Recovery Routine . . . . . . . . . . . . . . . . . . . 8-9

Mainline Routine with Several Recovery Routines . . . . . . . . . . . . . . . . . 8-10
Example of Using the GETMAIN Macro . . . . . . . . . . . . . . . . . . . . 11-4
Virtual Storage Control . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
Using the List and the Execute Forms of the DEQ Macro . . . . . . . . . . . . . 11-12
Cell Pool Storage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3
Mapping from an Address Space . . . . . . . . . . . . . . . . . . . . . . 14-10
Mapping from a Data Space or Hiperspace . . . . . . . . . . . . . . . . . . . 14-10
Multiple Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-12
Using an ALET to Identify an Address Space or a Data Space . . . . . . . . . . . . 15-2
An Illustration of a DU-AL. . . . . . . . . . . . . . . . . . . . . . . . . . 15-3
Using Instructions in AR Mode . . . . . . . . . . . . . . . . . . . . . . . . 15-5
Accessing Data in a Data Space . . . . . . . . . . . . . . . . . . . . . . . 16-4
Accessing Data in a Hiperspace . . . . . . . . . . . . . . . . . . . . . . . 16-5
Example of Specifying the Size of a Data Space . . . . . . . . . . . . . . . . . 16-11
Example of Extending the Current Size of a Data Space . . . . . . . . . . . . . . 16-15
Example of Using Callable Cell Pool Services for Data Spaces . . . . . . . . . . . 16-18
Two Problem Programs Sharing a SCOPE=SINGLE Data Space. . . . . . . . . . . 16-19
Example of Scrolling through a Standard Hiperspace . . . . . . . . . . . . . . . 16-25
Illustration of the HSPSERV Write and Read Operations . . . . . . . . . . . . . . 16-28
Example of Creating a Standard Hiperspace and Transferring Data . . . . . . . . . . 16-33
Example of Mapping a Data-in-Virtual Object to a Hiperspace . . . . . . . . . . . . 16-36
A Standard Hiperspace as a Data-in-Virtual Object . . . . . . . . . . . . . . . . 16-37
Structure of a Data Object . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Mapping a Permanent Object That Has No Scroll Area . . . . . . . . . . . . . . . 17-3
Mapping a Permanent Object That Has A Scroll Area . . . . . . . . . . . . . . . 17-4
Mapping a Temporary Object . . . . . . . . . . . . . . . . . . . . . . . . 17-4
Mapping an Object To Multiple Windows . . . . . . . . . . . . . . . . . . . . 17-5
Mapping Multiple Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 17-6
Using the Name and the Token . . . . . . . . . . . . . . . . . . . . . . . 18-1
Using the Task Level in a Single Address Space . . . . . . . . . . . . . . . . . 18-3
Using Home-Level and Task-Level Name/Token Pairs . . . . . . . . . . . . . . . 18-4
Releasing Virtual Storage . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3
Example of using REFPAT with a Large Array . . . . . . . . . . . . . . . . . . 19-6
Illustration of a Reference Pattern with a Gap . . . . . . . . . . . . . . . . . . 19-8
Illustration of Forward Direction in a Reference Pattern . . . . . . . . . . . . . . 19-10
Illustration of Backward Direction in a Reference Pattern . . . . . . . . . . . . . . 19-10
Two Typical Reference Patterns . . . . . . . . . . . . . . . . . . . . . . . 19-11
Data Sharing with IARVSERV . . . . . . . . . . . . . . . . . . . . . . . . 20-2
Sharing Storage with IARVSERV . . . . . . . . . . . . . . . . . . . . . . . 20-8
Interval Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-3
Writing to the Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-8
Writing to the Operator With a Reply . . . . . . . . . . . . . . . . . . . . . 21-9
Preparing Messages for Translation . . . . . . . . . . . . . . . . . . . . . . 22-2
Sample job to invoke IDCAMS to obtain a data set for the run-time message files
22-8
Using JCL to Invoke the Compiler with a single PDS as input . . . . . . . . . . . . 22-8
Using JCL to Invoke the Compiler with a concatenation of partitioned Data Sets as input
22-9
Using a TSO/E CLIST to Invoke the Compiler with a single PDS input . . . . . . . . . 22-9
Using a TSO/E CLIST to Invoke the Compiler with a concatenation of partitioned Data Set as
input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-9
Using a REXX exec to Invoke the Compiler with a single PDS as input . . . . . . . . 22-10
Using a REXX exec to Invoke the Compiler with a concatenation of partitioned Data Sets
as input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-10
Using the TRANMSG Macro . . . . . . . . . . . . . . . . . . . . . . . . 22-14
Testing the Level of the MVS System at Execution Time . . . . . . . . . . . . . . 23-3
Contiguous Symbol Table . . . . . . . . . . . . . . . . . . . . . . . . . . 26-7

z/OS V1R4.0 MVS Assembler Services Guide

26-2.
27-1.
27-2.
27-3.
27-4.
27-5.
27-6.
27-7.
27-8.
27-9.
27-10.
27-11.
A-1.
A-2.
A-3.
A-4.
A-5.
A-6.
A-7.
A-8.
A-9.
A-10.
A-11.
A-12.
A-13.
A-14.
A-15.
A-16.
A-17.
A-18.
A-19.
A-20.
A-21.
A-22.
A-23.
A-24.

Non-contiguous Symbol Table . . . . . . . . . . . . . . . . . . . . . . . . 26-8

System Logger Log Stream . . . . . . . . . . . . . . . . . . . . . . . . . 27-2
Log Stream Data on the Coupling Facility and DASD . . . . . . . . . . . . . . . 27-3
Log Stream Data in Local Storage Buffers and DASD Log Data Sets. . . . . . . . . . 27-4
A Complete Coupling Facility Log Stream Configuration . . . . . . . . . . . . . . 27-5
A DASD-Only Configuration . . . . . . . . . . . . . . . . . . . . . . . . . 27-6
Issuing ENFREQ to Listen for ENF Event Code 48 . . . . . . . . . . . . . . . . 27-19
Define a Log Stream as a Model and then Model a Log Stream After It . . . . . . . . 27-21
Searching for a Log Block by Time . . . . . . . . . . . . . . . . . . . . . . 27-37
Deleting a Range of Log Blocks . . . . . . . . . . . . . . . . . . . . . . . 27-39
How Source and Target Log Streams Can Get Out of Sync . . . . . . . . . . . . . 27-43
Log Stream SUBSYS Data Set Specification . . . . . . . . . . . . . . . . . . 27-50
Input Parameter List . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Requesting Function Code 0 (Check Groups) . . . . . . . . . . . . . . . . . . . A-5
Requesting Function Code 1 (Check Units) . . . . . . . . . . . . . . . . . . . A-5
Requesting Function Code 2 (Return Unit Name) . . . . . . . . . . . . . . . . . A-6
Output from Function Code 2 (Return Unit Name) . . . . . . . . . . . . . . . . . A-6
Requesting Function Code 3 (Return UCB Addresses) . . . . . . . . . . . . . . . A-7
Output from Function Code 3 (Return UCB Addresses) . . . . . . . . . . . . . . . A-7
Requesting Function Code 4 (Return Group ID) . . . . . . . . . . . . . . . . . . A-8
Output from Function Code 4 (Return Group ID). . . . . . . . . . . . . . . . . . A-8
Requesting Function Code 5 (Indicate Unit Name is a Look-up Value). . . . . . . . . . A-9
Requesting Function Code 6 (Return Look-up Value) . . . . . . . . . . . . . . . . A-9
Output from Function Code 6 (Return Look-up Value) . . . . . . . . . . . . . . . A-10
Requesting Function Code 7 (Convert Device Type to Look-up Value) . . . . . . . . . A-10
Output from Function Code 7 (Convert Device Type to Look-up Value) . . . . . . . . . A-10
Requesting Function Code 8 (Return Attributes) . . . . . . . . . . . . . . . . . A-11
Requesting Function Code 10 (Specify Subpool for Returned Storage) . . . . . . . . . A-12
Requesting Function Code 11 (Return Unit Names for a Device Class) . . . . . . . . . A-12
Output from Function Code 11 (Return Unit Names for a Device Class). . . . . . . . . A-13
Input for Function Codes 0 and 1 . . . . . . . . . . . . . . . . . . . . . . . A-14
Output from Function Codes 0 and 1 . . . . . . . . . . . . . . . . . . . . . A-14
Input for Function Codes 3 and 10 . . . . . . . . . . . . . . . . . . . . . . A-15
Output from Function Codes 3 and 10 . . . . . . . . . . . . . . . . . . . . . A-15
Input for Function Codes 1 and 5 . . . . . . . . . . . . . . . . . . . . . . . A-15
Output from Function Codes 1 and 5 . . . . . . . . . . . . . . . . . . . . . A-16

Figures

xv

xvi

z/OS V1R4.0 MVS Assembler Services Guide

Tables
4-1.
4-2.
5-1.
6-1.
6-2.
6-3.
8-1.
8-2.
8-3.
8-4.
8-5.
8-6.
8-7.
8-8.
8-9.
8-10.
8-11.
8-12.
9-1.
12-1.
15-1.
15-2.
16-1.
16-2.
18-1.
20-1.
21-1.
21-2.
22-1.
22-2.
22-3.
22-4.
23-1.
27-1.
27-2.
27-3.

Characteristics of Load Modules. . . . . . . . . . . . . . . . . . . . . . . . 4-6

CSVINFO Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32
Establishing Correct Interfaces to Modules That Move Above 16 Megabytes . . . . . . . 5-8
Task Synchronization Techniques . . . . . . . . . . . . . . . . . . . . . . . 6-1
Pause Element (PE) and Event Control Block (ECB) . . . . . . . . . . . . . . . . 6-4
GQSCAN Results with a Scope of STEP, SYSTEM, SYSTEMS, or ALL . . . . . . . . . 6-17
Summary of Recovery Routine States . . . . . . . . . . . . . . . . . . . . . 8-8
Contents of GPR 0 on Entry to a Retry Routine . . . . . . . . . . . . . . . . . 8-16
Key Fields in the SDWA . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
Restoring Quiesced Restorable I/O Operations . . . . . . . . . . . . . . . . . . 8-26
Where to Find Register Content Information . . . . . . . . . . . . . . . . . . . 8-28
Register ContentsESTAE-Type Recovery Routine With an SDWA . . . . . . . . . . 8-28
Register ContentsESTAE-Type Recovery Routine Without an SDWA . . . . . . . . . 8-29
Register ContentsRetry from an ESTAE-Type Recovery Routine Without an SDWA
8-30
Register ContentsRetry from an ESTAE-Type Recovery Routine With an SDWA,
RETREGS=NO, and FRESDWA=NO . . . . . . . . . . . . . . . . . . . . . 8-31
Register ContentsRetry from an ESTAE-Type Recovery Routine With an SDWA,
RETREGS=NO, and FRESDWA=YES . . . . . . . . . . . . . . . . . . . . . 8-31
Register ContentsRetry from an ESTAE-Type Recovery Routine With an SDWA and
RETREGS=YES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-32
Environments of ESTAE-type Recovery Routines and their Retry Routines. . . . . . . . 8-35
Reasons for Selecting the Type of Dump . . . . . . . . . . . . . . . . . . . . 9-1
Comparing Tasks and Concepts: Below the Bar and Above the Bar . . . . . . . . . . 12-11
Characteristics of DU-ALs and PASN-ALs . . . . . . . . . . . . . . . . . . . . 15-4
Base and Index Register Addressing in AR Mode . . . . . . . . . . . . . . . . . 15-6
Rules for How Problem State Programs with Key 8-F Can Use Data Spaces . . . . . . . 16-7
Facts about a Non-shared Standard Hiperspace . . . . . . . . . . . . . . . . . 16-26
Summary of What Programs Do with Name/Token Pairs . . . . . . . . . . . . . . 18-2
Allowed Source/Target View Combinations for Share. . . . . . . . . . . . . . . . 20-4
Characters Printed or Displayed on an MCS Console . . . . . . . . . . . . . . . 21-4
Descriptor Code Indicators . . . . . . . . . . . . . . . . . . . . . . . . . 21-7
Format of Version Record Fields . . . . . . . . . . . . . . . . . . . . . . . 22-3
Version Record Example . . . . . . . . . . . . . . . . . . . . . . . . . . 22-4
Message Skeleton Fields . . . . . . . . . . . . . . . . . . . . . . . . . . 22-4
Languages Available to MVS Message Service . . . . . . . . . . . . . . . . . 22-16
Summary of Data Compression and Expansion Services . . . . . . . . . . . . . . 23-2
Defining SAF Authorization For System Logger Resources . . . . . . . . . . . . . 27-11
How IXGBRWSE Requests Handle Gaps in a Log Stream . . . . . . . . . . . . . 27-15
How IXGDELET Requests Handle Gaps in a Log Stream . . . . . . . . . . . . . 27-15

Copyright IBM Corp. 1988, 2002

xvii

xviii

z/OS V1R4.0 MVS Assembler Services Guide

About this document

This book supports z/OS (5694-A01) and z/OS.e (5655-G52).
This document describes the operating system services that an unauthorized
program can use. An unauthorized program is one that does not run in supervisor
state, or have PSW key 0-7, or reside on an APF-authorized library. To use a
service, the program issues a macro. A companion document, z/OS MVS
Programming: Assembler Services Reference ABE-HSP, provides the detailed
information for coding the macros.
Some of the topics discussed in this document are also discussed in z/OS MVS
Programming: Authorized Assembler Services Guide and in the following other
documents:
v z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
v z/OS MVS Programming: Authorized Assembler Services Reference ENF-IXG
v z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU
v z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
However, the services and macros in those documents are for authorized programs.

Who should use this document

This document is for the programmer who is coding in assembler language, and
who needs to become familiar with the operating system and the services that
programs running under it can invoke.
The document assumes that the reader understands system concepts and writes
programs in assembler language.
Assembler language programming is described in the following books:
v HLASM Programmers Guide
v HLASM Language Reference
Using this book also requires you to be familiar with the operating system and the
services that programs running under it can invoke.

How to use this document

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

Where to find more information

Where necessary, this document references information in other documents, using
shortened versions of the document title. For complete titles, and order numbers of
the documents for all products associated with of z/OS see z/OS Information
Roadmap.

Copyright IBM Corp. 1988, 2002

xix

Accessing z/OS licensed documents on the Internet

z/OS licensed documentation is available on the Internet in PDF format at the IBM
Resource Link Web site at:
[Link]

Licensed documents are available only to customers with a z/OS license. Access to
these documents requires an IBM Resource Link user ID and password, and a key
code. With your z/OS order you received a Memo to Licensees, (GI10-0671), that
includes this key code. 1
To obtain your IBM Resource Link user ID and password, log on to:
[Link]

To register for access to the z/OS licensed documents:

1. Sign in to Resource Link using your Resource Link user ID and password.
2. Select User Profiles located on the left-hand navigation bar.
Note: You cannot access the z/OS licensed documents unless you have registered
for access to them and received an e-mail confirmation informing you that
your request has been processed.
Printed licensed documents are not available from IBM.
You can use the PDF format on either z/OS Licensed Product Library CD-ROM or
IBM Resource Link to print licensed documents.

Using LookAt to look up message explanations

LookAt is an online facility that allows you to look up explanations for most
messages you encounter, as well as for some system abends and codes. Using
LookAt to find information is faster than a conventional search because in most
cases LookAt goes directly to the message explanation.
You can access LookAt from the Internet at:
[Link]

or from anywhere in z/OS where you can access a TSO/E command line (for
example, TSO/E prompt, ISPF, z/OS UNIX System Services running OMVS). You
can also download code from the z/OS Collection (SK3T-4269) and the LookAt Web
site that will allow you to access LookAt from a handheld computer (Palm Pilot VIIx
suggested).
To use LookAt as a TSO/E command, you must have LookAt installed on your host
system. You can obtain the LookAt code for TSO/E from a disk on your z/OS
Collection (SK3T-4269) or from the News section on the LookAt Web site.
Some messages have information in more than one document. For those
messages, LookAt displays a list of documents in which the message appears.
|

Information updates on the web

For the latest information updates that have been provided in PTF cover letters and
Documentation APARs for z/OS and z/OS.e, see the online document at:

|
|

1. z/OS.e customers received a Memo to Licensees, (GI10-0684) that includes this key code.

xx

z/OS V1R4.0 MVS Assembler Services Guide

|
|

[Link]

|
|

This document is updated weekly and lists documentation changes before they are
incorporated into z/OS publications.

About this document

xxi

xxii

z/OS V1R4.0 MVS Assembler Services Guide

Summary of changes
Summary of changes
for SA22-7605-04
z/OS Version 1 Release 4
The document contains information previously presented in z/OS MVS
Programming: Assembler Services Guide, SA22-7605-03, which supports z/OS
Version 1 Release 3.
New information
v A new set of callable cell pool services is added, for use when running AMODE
64. See Chapter 13, Callable Cell Pool Services on page 13-1.
v Information is added to indicate this document suppors z/OS.e.
This document contains terminology, maintenance, and editorial changes. Technical
changes or additions to the text and illustrations are indicated by a vertical line to
the left of the change.
Starting with z/OS V1R2, you may notice changes in the style and structure of
some content in this documentfor example, headings that use uppercase for the
first letter of initial words only, and procedures that have a different look and format.
The changes are ongoing improvements to the consistency and retrievability of
information in our documents.
Summary of Changes
for SA22-7605-03
as updated June 2002
The document contains information previously presented in z/OS MVS
Programming: Assembler Services Guide, SA22-7605-02, which supports z/OS
Version 1 Release 3.
This document contains terminology, maintenance, and editorial changes, including
changes to improve consistency and retrievability.
Summary of changes
for SA22-7605-02
z/OS Version 1 Release 3
The document contains information previously presented in z/OS MVS
Programming: Assembler Services Guide, SA22-7605-01, which supports z/OS
Version 1 Release 2.
New information
v An appendix with z/OS product accessibility information has been added.
This document contains terminology, maintenance, and editorial changes, including
changes to improve consistency and retrievability.
Summary of changes
for SA22-7605-01
z/OS Version 1 Release 2

Copyright IBM Corp. 1988, 2002

xxiii

The document contains information previously presented in z/OS MVS

Programming: Assembler Services Guide, SA22-7605-00, which supports z/OS
Version 1 Release 1.
New information
v A new chapter, Chapter 12, Using the 64-bit Address Space on page 12-1, has
been added providing guidance for 64bit virtual storage addressing.
Changed information
v The following chapters have been updated with information concerning 64bit
virtual addressing:
Chapter 11, Virtual Storage Management on page 11-1
Chapter 2, Linkage Conventions on page 2-1
Moved information
v Information describing System Logger Configuration, previously found in
Chapter 27, Using System Logger Services on page 27-1 has been moved to
z/OS MVS Setting Up a Sysplex.
v Information describing System Logger Recovery, previously found in Chapter 27,
Using System Logger Services on page 27-1 has been moved to z/OS MVS
Setting Up a Sysplex.
This document contains terminology, maintenance, and editorial changes, including
changes to improve consistency and retrievability.
Summary of changes
for SA22-7605-00
z/OS Version 1 Release 1
The document contains information also presented in MVS/ESA Programming:
Assembler Services Guide.
Changed information
v Retrieving Console Information (CONVCON Macro) on page 21-11 is updated
with support for SMCS consoles.

xxiv

z/OS V1R4.0 MVS Assembler Services Guide

Chapter 1. Introduction
The system controls the flow of work through the computer so that all programs
obtain a fair share of the processing. To make efficient use of the system, you must
understand the services that the system provides and observe the programming
conventions for their use.
The chapters in this book discuss the following topics:
Linkage Conventions A program must follow register and save area
conventions when it is called by another program or when it calls another program.
These conventions ensure that the programs can successfully pass control to each
other while preserving the register contents and the parameter data required for
successful execution.
Subtask Creation and Control Because the system can handle small programs
easier than large ones, a large program might execute faster if you divide it into
parts, called tasks. By following the appropriate conventions, you can break your
programs into tasks that compete more efficiently for the resources of the system.
Program Management Program residence and addressing modes are
discussed in this chapter, as well as the linkage between programs. Save areas,
addressability, and conventions for passing control from one program to another are
also discussed.
Understanding 31-Bit Addressing 31-bit addressing terms are defined in this
chapter. Read this chapter before modifying existing programs to use 31-bit
addresses.
Resource Control Anything necessary for program execution, such as a table, a
storage device, or another program, can be considered a resource. If a program
depends on an event that occurs in another program, it might need to defer part of
its execution until the event, which is considered a resource, is completed. Because
many programs might need the same resource, and because some resources can
only be used by one program at a time, synchronization is often necessary.
Resource control helps to regulate access to the resources that your programs
depend on for successful execution. By using the GQSCAN macro, you can obtain
information about resources and their requestors.
Program Interruption Services The system offers many services to detect and
process abnormal conditions during system processing. Some conditions
encountered in a program cause program interruptions or program exceptions. This
topic includes how to specify user exit routines, using the SPIE or ESPIE macros,
and function performed in user exit routines.
Providing Recovery When your program encounters an error, the program
might end abnormally unless you provide recovery. To recover from errors, you can
write recovery routines that get control when the error occurs. These routines can
attempt to correct the error and allow your program to resume normal processing.
This topic explains recovery concepts and how to write recovery routines.
Dumping Virtual Storage (ABEND, SNAPX, and SNAP Macros) If your
program makes serious errors, the system terminates it. If you request it, the
system generates a dump to accompany the termination, and the resulting dump is
called an abend dump. You can also request another type of dump, called a SNAP
Copyright IBM Corp. 1988, 2002

1-1

dump. Programs can request a SNAP dump at any time, and they can specify the
source, the format, and the destination of the information in the dump.
Reporting Symptom Records (SYMRBLD and SYMREC Macros) An
application can write a symptom record for each error to the logrec data set, the
online repository where MVS collects error information. The unit of information
stored in the logrec data set is called a symptom record. The data in the symptom
record is a description of some programming failure combined with a description of
the environment where the failure occurred. An application can build and write
symptom records in the logrec data set by invoking either the SYMRBLD or
SYMREC macro.
Virtual Storage Management The system combines central storage and
auxiliary storage to make the addressable memory appear larger than it really is.
The apparent memory capacity is called virtual storage. By managing storage in this
way, the system relaxes the size limit on programs and data. The storage that the
system gives to each related group of programs is called an address space. As a
program executes, its storage requirements might vary. Conventions described in
this chapter allow a program to obtain any extra storage it might require, and to
return storage that is no longer required.
Using the 64bit Address Space As of z/OS Release 2, virtual storage
addressing is extended to allow access to chunks of virtual storage called memory
objects above 2 gigabytes. This chapter describes how to use the virtual storage
addressing above 2 gigabytes and to control the physical frames that back this
storage.
Callable Cell Pool Services Callable cell pool services manage user-obtained
areas of virtual storage efficiently, provide high performance service, and allow you
to use storage in both address spaces and data spaces. This chapter describes
callable cell pool services and helps you make the decision between using the
CPOOL macro or callable cell pool services.
Data-In-Virtual By using a simple technique that lets you create, read, or update
external storage data without the traditional GET and PUT macros, you can write
programs that use very large amounts of this type of data. The data, which is not
broken up into individual records, appears in your virtual storage all at once. This
technique also provides better performance than the traditional access methods for
many applications.
Using Access Registers If you need to access data in a data space, you need
to use the set of registers called access registers and be in the address space
control (ASC) mode called AR mode. This chapter helps you access data in data
spaces and use the system services while you are in AR mode.
Data Spaces and Hiperspaces If you need more virtual storage than a single
address space allows, and if you want to prevent other users from accessing this
storage, you can use data spaces and hiperspaces.
Window Services Window services enable assembler language programs to
access or create permanent or temporary data objects. By invoking the service
programs provided by window services, a program can:
v Read or update an existing data-in-virtual object
v Create and save a new permanent data-in-virtual object
v Create and use a temporary data-in-virtual object

1-2

z/OS V1R4.0 MVS Assembler Services Guide

Sharing Application Data (Name/Token Callable Services) Name/token

callable services allow a user to share data between two programs running under
the same task, or between two or more tasks or address spaces. This topic
includes understanding what a name/token pair is, descriptions of the levels of
name/token pairs, ownership and deletion of the pairs, using checkpoint/restart with
name/token pairs, and an example of JCL that can link-edit a reentrant program
with linkage-assist routines.
Processor Storage Management The system administers the use of processor
storage (that is, central and expanded storage) and directs the movement of virtual
pages between auxiliary storage and central storage in page-size blocks. You can
release virtual storage contents, load virtual storage areas into central storage,
make virtual storage pages read-only or modifiable, and page out virtual storage
areas from central storage. Reference pattern services allow programs to define a
reference pattern for a specified area that the program is about to reference.
Sharing Data in Virtual Storage (IARVSERV Macro) This topic describes the
IARVSERV macro, which provides services that allow programs to share virtual
storage in address spaces or data spaces. The topic also includes a section for the
IARR2V macro, which converts a central storage address to a virtual storage
address.
Timing and Communication The system has an internal clock. Your program
can use it to obtain the date and time, or use it as an interval timer. You can set a
time interval, test how much time is left in an interval, or cancel it. Communication
services let you send a message to the system operator, to a TSO/E terminal, or to
the system log.
Translating Messages The MVS message service (MMS) enables you to
display MVS or MVS-based application messages that have been translated from
U.S. English into a foreign language. The service also allows application programs
to store messages in and retrieve them from the MMS run-time message file.
Using Data Compression and Expansion Services Data compression and
expansion services allow you to compress certain types of data so that the data
occupies less space while you are not using it. You can then restore the data to its
original state when you need it.
Accessing Unit Control Blocks (UCBs) Each device in a configuration is
represented by a unit control block (UCB). This chapter contains information about
scanning UCBs and detecting I/O configuration changes.
The Internal Reader The internal reader facility is a logical device similar to a
card reader, a tape drive, or a TSO/E terminal that allows you to submit jobs to
JES. This chapter describes how to set up and use an internal reader, allocating the
internal reader data set, opening and closing the internal reader data set, and
sending job output to the internal reader.
Using the Symbol Substitution Service This topic describes types of symbols
you can use in application and vendor programs, and describes how to call the
ASASYMBM service, which substitutes text for those symbols.
Using System Logger Services System logger services allow an application to
manage log data in a sysplex environment. This topic describes how to plan the
system logger configuration, plan and set up a system logger application, and plan
for recovery for system logger applications.
Chapter 1. Introduction

1-3

Appendixes This book also contains an appendix for each of the following
topics:
v Using the Unit Verification Service
v Using the Virtual Fetch Service.

IMPORTANT -------- READ THIS

As you read the book, keep in mind how the book uses the following terms:
v The term registers means general purpose registers. In sections where
general purpose registers might be confused with other kinds of registers
(such as access registers), the book uses the longer term general purpose
registers.
v Unless otherwise specified, the address space control (ASC) mode of a
program is primary mode.

1-4

z/OS V1R4.0 MVS Assembler Services Guide

Chapter 2. Linkage Conventions

Linkage conventions are the register and save area conventions a program must
follow when it receives control from another program or when it calls another
program. It is important that all programs follow the linkage conventions described
here to ensure that the programs can successfully pass control from one to the
other while preserving register contents and parameter data that they need to run
successfully.
One program can invoke another program through any one of the following branch
instructions or macros:
v BALR, BASR, or BASSM instructions
v LINK, LINKX, XCTL, XCTLX, and CALL macros
The program that issues the branch instruction or the macro is the calling
program. The program that receives control is the target program. A program
should follow these conventions when it:
v Receives control from a calling program
v Returns control to the calling program
v Calls another program
The PC instruction provides another means of program linkage. Linkage
conventions for the PC instruction are described in z/OS MVS Programming:
Extended Addressability Guide.
In this chapter, programs are classified by their address space control (ASC) mode
as follows:
v A primary mode program is one that executes all its instructions in primary ASC
mode and does not change the contents of ARs 2 through 13.
v An AR mode program is one that executes one or more instructions in AR mode
or it changes the contents of ARs 2 through 13. A program that switches from
one mode to another is considered to be an AR mode program. A program that
runs in AR mode can access data that is outside its primary address space.
The ASC mode at the time a program issues the call determines whether addresses
passed by the program must be qualified by access list entry tokens (ALETs). An
ALET identifies the address space or data space that contains the passed
addresses. An ALET-qualified address is an address for which the calling program
has provided an ALET. The ASC mode at the time of the call also determines
whether the program can call a primary mode program or an AR mode program.
v A calling program that is in primary mode at the time of the call can call either
another primary mode program or an AR mode program. Addresses passed by
the calling program are not ALET-qualified.
v A calling program that is in AR mode at the time of the call can call only another
AR mode program. Addresses passed by the calling program are ALET-qualified.
An AR mode program can call a primary mode program, but the calling program
must first switch to primary mode and then follow the linkage conventions for a
primary mode caller. Addresses passed by the calling program cannot be
ALET-qualified.
When one program calls another, the target program receives control in the callers
ASC mode at the time the call was made. If the calling program is in AR mode at
the time of the call, the target program receives control in AR mode. If the calling
Copyright IBM Corp. 1988, 2002

2-1

program is in primary mode at the time of the call, the target program receives
control in primary mode. After a target program receives control, it can switch its
ASC mode by issuing the Set Address Control (SAC) instruction. For more
information on ASC mode, see Chapter 15, Using Access Registers on page 15-1.

Saving the Calling Programs Registers

Unless otherwise defined by the individual interface, the calling program should
expect, upon return, that
v The low halves (Bits 32-63) of GPRs 2 through 13 are unchanged
v The high halves (Bits 0-31) of GPRs 2 through 14 are unchanged
v ARs 2 through 13 are unchanged
v FPRs 8 through 15 are unchanged; The Floating Point Control (FPC) Register is
unchanged with the exception of two fields: the IEEE exception flags and the
data exception code (DXC).
v When return information is provided in GPR 0, 1, and/or 15 (for example return
and reason codes), only bits 32-63 of the register contain the returned value.
Individual interfaces may define that additional registers are unchanged, or that
additional registers are not unchanged, or that returned information in registers uses
more than bits 32-63.
This discussion pertains to programs that do not reference the high 32 bits of 64bit
GPR.
At entry, all target programs save the callers registers; at exit, they restore those
registers. The two places where a program can save registers are in a
caller-provided save area or in a system-provided linkage stack. The ASC
mode of the target program determines how the target program saves the registers.
A primary mode program can use the linkage stack or the save area its calling
program provides. An AR mode program must use the linkage stack.

Caller-Provided Save Area

A primary mode calling program must provide its target program with an 18-word
register save area unless the target programs interface requirements have
specified otherwise. Likewise, an AR mode program that switches to primary mode
and then makes a call must provide a register save area unless the target
programs interface requirements have specified otherwise. In both cases, the
calling program obtains storage for the save area from its primary address space.
The save area must begin on a word boundary. Before invoking the target program,
the calling program loads the address of the save area into general purpose
register 13.

Linkage Convention for Floating Point Registers

With 16 Floating Point Registers (FPRs), registers 0 to 7 are volatile, and registers
8 to 15 are non-volatile. That is, if a called routine uses any of FPRs 8 to 15, it
must save the callers data in those FPRs before use and restore them before
returning to the caller. The called routine can use any of FPRs 0 to 7 without saving
and restoring the callers data. If the caller wants to keep data in FPRs 0 to 7, it
must save those FPRs before the call and restore them afterward.

Linkage Convention for the Floating Point Control Register

The Floating Point Control (FPC) Register is non-volatile across calls with the
exception of two fields: the IEEE exception flags and the DXC, which are volatile.

2-2

z/OS V1R4.0 MVS Assembler Services Guide

That is, if a called routine changes any fields in the FPC register other than the
IEEE exception flags and the DXC, it must save the callers values before making
the change and restore them before returning to the caller. The called routine may
change the IEEE exception flags and DXC, explicitly or by triggering exception
conditions, without saving and restoring the callers values.
Note: A program can rely on the FPC register being zero (IEEE default) ONLY
when it determines that the MVS task under which it is running is not
enabled to use the AFP and FPC registers.

System-Provided Linkage Stack

The system provides the linkage stack where a target program can save the calling
programs access registers and general purpose registers (AR/GPRs). Use of the
linkage stack has the following advantages:
v The linkage stack saves both ARs and GPRs; the caller-provided save area
saves only GPRs.
v The system provides the linkage stack for use by all programs. The stack
eliminates the need for the AR mode calling program to obtain storage for a save
area and then pass the address to its target program.
v The save areas are located in one place, rather than chained throughout the
users address space.
v User programs cannot accidentally make changes to the linkage stack.

Using the Linkage Stack

To add an entry to the linkage stack, the target program issues the BAKR
instruction. The BAKR instruction stores all GPRs and ARs on the linkage stack.
The target program must then indicate that it used the linkage stack, which is useful
information for anyone who later needs to trace the program linkages. The
procedure for indicating use of the linkage stack is described in:
v Primary Mode Programs Receiving Control on page 2-10
v AR Mode Programs Receiving Control on page 2-12
When the target program is ready to return to the calling program, it issues the PR
instruction. The PR instruction restores the calling programs AR/GPRs 2 - 14,
removes the entry from the linkage stack, and returns control to the calling program.

Example of Using the Linkage Stack

In this example, an AR mode target program receives control from another program,
either in primary mode or AR mode. The calling program can make the call through
the following two instructions:
L
15,=V(PGM)
BASR 14,15

The target program uses the linkage stack to save the calling programs registers. It
uses the STORAGE macro to obtain storage for its own save area. The code is in
31-bit addressing mode and is reentrant.
PGM
PGM
PGM
*
*

CSECT
AMODE 31
RMODE ANY
BAKR 14,0
SAC
LAE

512
12,0(15,0)

SAVE CALLERS ARS AND GPRS

ON LINKAGE STACK
SWITCH TO AR ADDRESSING MODE
SET UP PROGRAM BASE REGISTER
AND ADDRESSING REGISTER
Chapter 2. Linkage Conventions

2-3

*
*
.
.
.
*

USING PGM,12
STORAGE OBTAIN,LENGTH=72
LAE 13,0(0,1)
MVC 4(4,13),=CF1SA

GET MY REENTRANT SAVEAREA

PUT MY SAVEAREA ADDRESS IN AR/GPR13
PUT ACRONYM INTO MY SAVEAREA BACKWARD
POINTER INDICATING REGS SAVED ON STACK
END OF ENTRY CODE, BEGIN PROGRAM CODE HERE
BEGIN EXIT CODE
LAE 1,0(0,13)
COPY MY SAVEAREA ADDRESS
STORAGE RELEASE,ADDR=(1),LENGTH=72 FREE MY REENTRANT SAVEAREA
SLR 15,15
SET RETURN CODE OF ZERO
PR
RESTORE CALLERS ARs AND
GPRS 2-14 AND RETURN TO CALLER
END

Using a Caller-Provided Save Area

The contents of the caller-provided save area and the rules for using it differ
whether the calling program is or is not changing bits 031 of the 64bit GPR. The
differences can be summarizes as affecting: how you save and restore register
information for program interface, how you pass information to the target program,
and where the target program can place output information.
v For programs that do not change bits 031 of the 64bit GPR see If Not
Changing Bits 031 of the 64bit GPR
v For programs that change the contents of bits 031 of the 64bit GPRs:
for AMODE 24 or AMODE 31 programs see If Changing the contents of bits
0-31 of the 64-bit GPRs on page 2-6
For programs that start running in AMODE 64 see If Starting in AMODE 64
on page 2-7

If Not Changing Bits 031 of the 64bit GPR

When the target program receives control, it saves the GPRs in the 18-word
caller-provided save area pointed to by GPR 13. The format of this area is shown in
Figure 2-1. As indicated by this figure, the contents of each GPR, except GPR 13,
must be saved in a specific location within the save area. GPR 13 is not saved; it
holds the address of the save area.
Word

Contents

Used by language products

Address of previous save area (stored by calling program)

Address of next save area (stored by target program)

GPR 14 (return address)

GPR 15 (entry address)

5 - 17

GPRs 0 - 12

Figure 2-1. Format of the Save Area

You can save GPRs either with a store-multiple (STM) instruction or with the SAVE
macro. Use the following STM instruction to place the contents of all GPRs except
GPR 13 in the proper words of the save area:
STM 14,12,12(13)

2-4

z/OS V1R4.0 MVS Assembler Services Guide

The SAVE macro stores GPRs in the save area. Code the GPRs to be saved in the
same order as in an STM instruction. The following example of the SAVE macro
places the contents of all GPRs except GPR 13 in the proper words of the save
area.
PROGNAME

SAVE (14,12)

Later, the program can use the RETURN macro to restore GPRs and return to the
caller.
Whether or not the target program obtains its own save area for another program, it
must save the address of the calling programs save area (which it used). If the
target program is creating a save area for another program, it:
1. Stores the address of the calling programs save area (the address passed in
register 13) in the second word of its own save area.
2. Stores the address of its own save area (the address the target program will
pass to another program in register 13) in the third word of the calling programs
save area.
These steps enable the target program to find the save area when it needs it to
restore the registers, and they enable a trace from save area to save area should
one be necessary while examining a dump.
If the target program is not providing a save area for another program, it can keep
the address of the calling programs save area in GPR 13 or store it in a location in
virtual storage.
If you choose not to use the SAVE and RETURN macros, you can use the
IHASAVER macro to map the fields in the standard save area.

Example
In this example, a primary mode target program receives control from a calling
program which provided an 18-word save area pointed to by GPR 13. The calling
program can make the call through the following two instructions:
L
15,=V(PGM)
BASR 14,15

The target program saves its calling programs registers in the save area that the
calling program provides. It uses the GETMAIN macro to obtain storage for its own
save area. The code is in 31-bit addressing mode and is reentrant.
PGM
PGM
PGM
*

*
*
*
.
.
.
*

CSECT
AMODE 31
RMODE ANY
STM
14,12,12(13)
LR
12,15
USING PGM,12
GETMAIN RU,LV=72
ST
13,4(,1)

SAVE CALLERS REGISTERS IN CALLERPROVIDED R13 SAVE AREA

SET UP PROGRAM BASE REGISTER

GET MY REENTRANT SAVEAREA

SAVE CALLERS SAVEAREA ADDRESS IN MY
SAVEAREA (BACKWARD CHAIN)
ST
1,8(,13)
SAVE MY SAVEAREA ADDRESS IN CALLERS
SAVEAREA (FORWARD CHAIN)
LR
13,1
PUT MY SAVEAREA ADDRESS IN R13
END OF ENTRY CODE, BEGIN PROGRAM CODE HERE
BEGIN EXIT CODE
LR
1,13
COPY MY SAVEAREA ADDRESS
L
13,4(,13)
RESTORE CALLERS SAVEAREA ADDRESS
FREEMAIN RU,A=(1),LV=72 FREE MY REENTRANT SAVEAREA
Chapter 2. Linkage Conventions

2-5

SLR
L
LM
BR
END

15,15
14,12(,13)
2,12,28(13)
14

SET RETURN CODE OF ZERO

RESTORE CALLERS R14
RESTORE CALLERS R2-R12
RETURN TO CALLER

If Changing the contents of bits 0-31 of the 64-bit GPRs

If the caller has provided a 144-byte save area, then the protocol described for
AMODE 64 programs can be used.
If the caller has provided a 72-byte save area, then the target program must save
the low halves of the GPRs in that 72-byte area, and then must save the high
halves in its own Format 5 save area. The format of this area is shown in
Figure 2-2. As indicated by this figure, the contents of each GPR, except GPR 13,
must be saved in a specific location within the save area. GPR 13 is not saved; it
holds the address of the save area.
Word

Contents

Used by language products

Value of F5SA

2-3

64-bit GPR 14 (return address)

4-5

64-bit GPR 15

6-31

64-bit GPRs 0-12

32-33

Address of previous save area (stored by calling program)

34-35

Address of next save area (stored by target program)

36-53

High halves of GPRs 0-15

Figure 2-2. Format of the Format 5 Save Area (F5SA)

The target program must create its own save area for another program. It:
1. Stores the low halves of the calling programs GPRs in the calling programs
save area (the address passed in register 13).
2. Creates its own 216-byte save area, taking care to preserve the values of the
high halves of any of the calling programs GPRs
3. Stores the address of the calling programs save area (the address passed in
register 13) in the 33rd and 34th words of its own save area.
4. Saves the string F5SA in the 2nd word of its own save area.
These steps enable the target program to find the save area when it needs it to
restore the registers, and they enable a trace backward from the most recent save
area to previous save areas should one be necessary while examining a dump.

Example
In this example, a primary mode target program receives control from calling
program which provided a 36-word doubleword-aligned save area pointed to by
GPR 13. The calling program can make the call through the following two
instructions:

2-6

z/OS V1R4.0 MVS Assembler Services Guide

L 15,=V(PGM)
BASR 14,15

The target program saves its calling programs registers in the save area that the
calling program provides. It uses the GETMAIN macro to obtain storage for its own
save area. The code is in 31-bit addressing mode and is reentrant.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

PGM CSECT
PGM AMODE 31
PGM RMODE 31
SYSSTATE ARCHLVL=2
STM 14,12,SAVGRS14-SAVER(13)
*
Save callers registers in caller*
provided R13 savearea
CNOP 0,4
BRAS 12,*+8
DC
A(STATIC_DATA)
L
12,0(12,0)
Set up to address of static data
USING STATIC_DATA,12
SRLG 0,0,32
Move high half of GPR 0 into low half of GPR 0
LR
2,0
Save high half of GPR 0 in low half of GPR 2
SRLG 1,1,32
Move high half of GPR 1 into low half of GPR 1
LR
3,1
Save high half of GPR 1 in low half of GPR 3
SRLG 15,15,32
Move high half of GPR 15 into low half of GPR 15
LR
4,15
Save high half of GPR 15 in low half of GPR 4
GETMAIN RU,LV=SAVF5SA_LEN Get my reentrant savearea
STG 13,SAVF5SAPREV-SAVF5SA(,1)
*
Save callers savearea address in my
*
savearea (backward chain)
STMH 2,14,SAVF5SAG64HS2-SAVF5SA(1)
ST
2,SAVF5SAG64HS0-SAVF5SA(1)
ST
3,SAVF5SAG64HS1-SAVF5SA(1)
ST
4,SAVF5SAG64HS15-SAVF5SA(1)
MVC SAVF5SAID-SAVF5SA(4,1),=A(SAVF5SAID_VALUE)
*
Set ID into savearea
LGR 13,1
Put my savearea address in R13
* End of entry code. Begin program code here . . .
*
*
*
*
* Begin exit code
LGR 1,13
Copy my savearea address
LMH 2,14,SAVF5SAG64HS2-SAVF5SA(13)
*
Restore high halves
LG
13,SAVF5SAPREV-SAVF5SA(,13)
*
Restore callers savearea address
FREEMAIN RU,A=(1),LV=SAVF5SA_LEN Free my reentrant savearea
SLR 15,15
Set return code of zero
L
14,SAVGRS14-SAVER(,13) Restore callers R14
LM
2,12,SAVGRS2-SAVER(13) Restore callers R2-R12
BR
14 Return to caller
*
STATIC_DATA DS 0D
* Begin static data here
* ...
*
IHASAVER
PGM CSECT
LTORG ,
END

If Starting in AMODE 64
An AMODE 64 program must specify SYSSTATE AMODE64=YES.

Chapter 2. Linkage Conventions

2-7

When it receives control, the target program saves the GPRs in the 36-word
doubleword-aligned caller-provided save area pointed to by 64-bit GPR 13. The
format of this area is shown in Figure 2-3. As indicated by this figure, the contents
of each GPR, except GPR 13, must be saved in a specific location within the save
area. GPR 13 is not saved; it holds the address of the save area.
Word

Contents

Used by language products

Value of F4SA

2-3

64-bit GPR 14 (return address)

4-5

64-bit GPR 15

6-31

64-bit GPRs 0-12

32-33

Address of previous save area (stored by calling program)

34-35

Address of next save area (stored by target program)

Figure 2-3. Format of the Format 4 Save Area (F4SA)

You can save GPRs either with a store-multiple (STMG) instruction or with the
SAVE macro. Use the following STMG instruction to place the contents of all GPRs
except GPR 13 in the proper words of the save area:
STMG 14,12,8(13)

The SAVE macro stores GPRs in the save area. Code the GPRs to be saved in the
same order as in a STMG instruction. The following example of the SAVE macro
places the contents of all GPRs except GPR 13 in the proper words of the save
area.
PROGNAME SAVE (14,12)

Later, the program can use the RETURN macro to restore GPRs and return to the
caller.
Whether or not the target program obtains its own save area for another program, it
must save the address of the calling programs save area (which it used). If the
target program is creating a save area for another program, it:
1. Stores the address of the calling programs save area (the address passed in
register 13) in the 33rd and 34th words of its own save area.
2. Stores the address of its own save area (the address the target program will
pass to another program in register 13) in the 35th and 36th words of the calling
programs save area.
3. Saves the string F4SA in the 2nd word of its own save area.
These steps enable the target program to find the save area when it needs it to
restore the registers, and they enable a trace backward from the most recent save
area to previous save areas should one be necessary while examining a dump. If
the target program is not providing a save area for another program, it can keep the
address of the calling programs save area in GPR 13 or store it in a location in
virtual storage.

2-8

z/OS V1R4.0 MVS Assembler Services Guide

If you choose not to use the SAVE and RETURN macros, you can use the
IHASAVER macro to map the fields in the standard save area.

Example
In this example, a primary mode target program receives control from calling
program which provided a 36-word doubleword-aligned save area pointed to by
GPR 13. The calling program can make the call through the following two
instructions:
L 15,=V(PGM)
BASR 14,15

The target program saves its calling programs registers in the save area that the
calling program provides. It uses the GETMAIN macro to obtain storage for its own
save area. The code is in 64-bit addressing mode and is reentrant.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
||
|
|
|
|
|
|
|
|
|
|
||
||
|
|
|
|

PGM CSECT
PGM AMODE 64
PGM RMODE 31
SYSSTATE AMODE64=YES
STMG 14,12,SAVF4SAG64RS14-SAVF4SA(13)
*
Save callers registers in caller*
provided R13 save area
CNOP 0,4
BRAS 12,*+8
DC A(STATIC_DATA)
L
12,0(12,0)
Set up to address of static data
USING STATIC_DATA,12
GETMAIN RU,LV=144
Get my reentrant savearea
STG 13,SAVF4SAPREV-SAVF4SA(,1)
*
Save callers savearea address in my
*
savearea (backward chain)
STG 1,SAVF4SANEXT-SAVF4SA(,13)
*
Save my savearea address in callers
*
savearea (forward chain)
MVC SAVF4SAID-SAVF4SA(4,1),=A(SAVF4SAID_VALUE)
*
Set ID into savearea
LGR 13,1
Put my savearea address in R13
*
End of entry code. Begin program code here . . .
.
.
.
* Begin exit code
LGR 1,13
Copy my savearea address
LG 13,SAVF4SAPREV-SAVF4SA(,13)
*
Restore callers savearea address
FREEMAIN RU,A=(1),LV=144 Free my reentrant savearea
SLR 15,15
Set return code of zero
LG 14,SAVF4SAG64RS14-SAVF4SA(,13)
*
Restore callers R14
LMG 2,12,SAVF4SAG64RS2-SAVF4SA(13)
*
Restore callers R2-R12
BR
14
Return to caller
.
.
.
STATIC_DATA DS 0D
* Begin static data here
IHASAVER
END

Establishing a Base Register for AMODE 24 or AMODE 31 programs

Each program must establish a base register immediately after it saves the calling
programs registers. When selecting a base register, keep in mind that:
v Some instructions alter register contents (for example, TRT alters register 2). A
complete list of instructions and their processing is available in Principles of
Operation.
Chapter 2. Linkage Conventions

2-9

v Registers 13 through 1 are used during program linkage.

v Register 12 is reserved for LE use when writing an LE-conforming assembler
program. For more information see z/OS Language Environment Programming
Guide.
Register 12 is generally a good choice for base register.

Establishing a Base Register for AMODE 64 programs

AMODE 64 programs are expected to make use of the relative and immediate
instruction set and thus not to need code addressability, in general. But they do
need to establish addressability to any static data that they might need. The
program should do this immediately after it saves the calling programs registers.
The program might also need temporary code addressability when invoking system
macros. Macros such as STORAGE require the invoker to have code addressability
surrounding the macro invocation. The same considerations about selecting a base
register as described in the preceding section, apply.

Linkage Procedures for Primary Mode Programs

A primary mode program can be called only by a primary mode program running in
primary ASC mode. Thus an AR mode program must switch to primary ASC mode
before calling a primary mode program. The following sections summarize the
linkage procedures a primary mode program follows when it receives control, when
it returns control to a caller, and when it calls another program.

Primary Mode Programs Receiving Control

When a primary mode program receives control after being called, it can save the
calling programs registers on the linkage stack or in the caller-provided save area.
If using the caller-provided save area, then distinctions are made whether the
primary mode program isor is notchanging the 64bit GPRs. Each option is
discussed below.
Note that the linkage conventions assume that a primary mode program does not
use ARs. By leaving the contents of the ARs untouched, the program preserves the
ARs across program linkages.
A primary mode program that uses the linkage stack must:
v Issue a BAKR instruction to save the callers GPRs and ARs on the linkage
stack.
v Establish a GPR as a base register.
v Set GPR 13 to indicate that the callers registers are saved on the linkage stack:
If the program intends to call another program, obtain an 18-word save area
on a word boundary in the primary address space. Set the second word of the
save area to the character string F1SA and load GPR 13 with the save area
address.
If the program does not intend to call another program, do one of following:
- If not changing 64bit GPRs, obtain an 18-word save area on a word
boundary in the primary address space. Set the second word of the save
area to the character string F1SA and load the save area address into
GPR 13.

2-10

z/OS V1R4.0 MVS Assembler Services Guide

- If changing 64bit GPRs, obtain a 36word save area on a doubleword

boundary in the primary address space. Set the second word of the save
area to the character string F6SA and load the save area address into
GPR 13.
- Load 0 into GPR 13.
- Set the second word of a two-word area in the primary address space to
the character string F1SA. Load the address of the two-word area into
GPR 13.
A primary mode program that uses the caller-provided save area :
The conditions described are:
v does not change 64bit GPRs and that uses the 72byte caller-provided save
area
v changes 64-bit GPRs and that uses the 72-byte caller-provided save area
v changes 64-bit GPRs and that uses the 144-byte caller-provided save area
Does not change 64bit GPRs and that uses the 72byte caller-provided save
area must:
v Save GPRs 0 - 12, 14, and 15 in the caller-provided save area pointed to by
GPR 13.
v Establish a base register.
v Obtain an 18-word save area on a word boundary in the primary address space.
v Store the address of the callers save area and the forward and back chains of
its own save area, as the comments in Example on page 2-5 indicate.
Changes 64-bit GPRs and that uses the 72-byte caller-provided save area
must:
v Save the low halves (bits 32 through 63) of GPRs 0 - 12, 14, and 15 in the
caller-provided save area pointed to by GPR 13.
v Obtain a 54-word save area on a doubleword boundary in the primary address
space
v Save the high halves (bits 0ul
v through 31) of GPRs 0 - 15 in its own save area
v Store the address of the callers save area in the back chain of its own save area
Changes 64-bit GPRs and that uses the 144-byte caller-provided save area
must:
v Save GPRs 0 - 12, 14, and 15 in the caller-provided save area pointed to by
GPR 13.
v Obtain a 36-word save area on a doubleword boundary in the primary address
space.
v Store the address of the callers save area and the forward and back chains of
its own save area.

Primary Mode Programs Returning Control

The method that a primary mode program uses to return control to a caller depends
on whether the primary mode program used the linkage stack or the caller-provided
save area.
A primary mode program that uses the linkage stack must:
Chapter 2. Linkage Conventions

2-11

v Place parameter information to return to the caller, if any, into GPR 0, 1, or both.
For information about passing information through a parameter list, see
Conventions for Passing Information Through a Parameter List on page 2-13.
v Load the return code, if any, into GPR 15.
v Issue the PR instruction. The PR instruction restores the callers AR/GPRs 2 - 14
from the linkage stack, removes the entry from the linkage stack, and returns
control to the caller.
A primary mode program that uses the caller-provided save area must:
v Place parameter information to return to the caller, if any, into GPR 0, 1, or both.
For information about passing information through a parameter list, see
Conventions for Passing Information Through a Parameter List on page 2-13.
v Load GPR 13 with the address of the save area that the program passed when it
made the call.
v Load the return code, if any, into GPR 15.
v Restore GPRs 2 - 12 and 14.
v Return to the calling program.

Primary Mode Programs Calling Another Program

When a primary mode program calls another program, the calling program must:
v Place the address of its 18-word save area into GPR 13.
v Load parameter information, if any, into GR 0, GR 1, or both.
v Place the entry point address of the target program into GPR 15.
v Call the target program.

Linkage Procedures for AR Mode Programs

An AR mode program can be called by other AR mode programs or by primary
mode programs. The following sections summarize the linkage procedures an AR
mode program must follow when it receives control, when it returns control to a
caller, and when it calls another program.

AR Mode Programs Receiving Control

When an AR mode program receives control, it must:
v Issue a BAKR instruction to save the callers GPRs and ARs on the linkage
stack. (Although a primary mode caller provides a save area, an AR mode target
program does not use the area.
v Establish a GPR as a base register and load an ALET of 0 into the
corresponding AR. An ALET of 0 causes the system to reference an address
within the primary address space.
v Set GPR 13 to indicate that the callers registers are saved on the linkage stack:
If the program intends to switch to primary mode and call another program,
obtain an 18-word save area on a word boundary in the primary address
space. Set the second word of the save area to the character string F1SA
and load GPR 13 with the save area address. Set AR 13 to zero to indicate
that the storage resides in the primary address space.
If the program does not intend to switch to primary mode and call a program,
do one of following:
- Obtain an 18-word save area on a word boundary in the primary address
space. Set the second word of the save area to the character string F1SA
and load the save area address into GPR 13.

2-12

z/OS V1R4.0 MVS Assembler Services Guide

- Load 0 into GPR 13.

- Set the second word of a two word area in the primary address space to
the character string F1SA. Load the address of the two word area into
GPR 13.

AR Mode Programs Returning Control

To return control to the calling program, an AR mode program must:
v Place parameter information to return to the caller, if any, into AR/GPR 0,
AR/GPR 1, or both. For information about passing information through a
parameter list, see Conventions for Passing Information Through a Parameter
List.
v Load the return code, if any, into GPR 15.
v Issue the PR instruction. The PR instruction restores the callers AR/GPRs 2 - 14
from the linkage stack, removes the entry from the linkage stack, and returns
control to the caller.

AR Mode Programs Calling Another Program

The definition of an AR mode program, as stated in the beginning of this chapter,
includes the fact that such a program might switch from one ASC mode to another.
Procedures for an AR mode program calling another program differ depending on
whether the AR mode program is in primary mode or AR mode at the time of the
call.
To make the call while it is in AR mode, an AR mode program must:
v Load parameter information, if any, into AR/GPR 0, AR/GPR 1, or both. For
information about passing information through a parameter list, see Conventions
for Passing Information Through a Parameter List.
v Place the entry point address of the target program into GPR 15. There is no
need to load an ALET into AR 15.
v Call the target program.
To make the call while it is in primary mode, an AR mode program must follow
the linkage conventions described in Primary Mode Programs Calling Another
Program on page 2-12.

Conventions for Passing Information Through a Parameter List

The ASC mode of a calling program at the time it makes a call determines whether
addresses that the program passes are ALET-qualified. The following two sections
describe how programs in primary mode and AR mode pass parameters through a
parameter list.

Program in Primary Mode

If the calling program is in primary mode, the parameter list must be in the primary
address space. All addresses passed by the programs must be contained in the
primary address space and must not be ALET-qualified. The program that passes
parameter data can use GPRs 0 and 1, or both. To pass the address of a
parameter list, the program should use GPR 1.
For a good example of how your primary mode programs can pass parameters,
consider the way the system uses a register to pass information in the PARM field
of an EXEC statement to your program. Unlike the parameter list produced for an
EXEC statement, a general parameter list can have multiple parameters, there is no
Chapter 2. Linkage Conventions

2-13

system-imposed limitation on the length of any parameter, and no parameter has a

system-defined format. Lengths and formats of parameters are defined by the called
service. When your program receives control from the system, register 1 contains
the address of a fullword on a fullword boundary in your programs address space
(see Figure 2-4). The high-order bit (bit 0) of this word is set to 1. The system uses
this convention to indicate the last word in a variable-length parameter list. Bits 1-31
of the fullword contain the address of a two-byte length field on a halfword
boundary. The length field contains a binary count of the number of bytes in the
PARM field, which immediately follows the length field. If the PARM field was
omitted in the EXEC statement, the count is set to zero. To prevent possible errors,
always use the count as a length attribute in acquiring the information in the PARM
field.
GPR1
@
4 Bytes
1

@
2 Bytes

0 to 100 Bytes

Full-Word
Boundary
Length Field

PARM Field

Half-Word
Boundary

Figure 2-4. Primary Mode Parameter List

Programs in AR Mode
If the calling program is in AR mode, all addresses that it passes, whether they are
in a GPR or in a parameter list, must be ALET-qualified. A parameter list can be in
an address space other than the calling programs primary address space or in a
data space, but it cannot be in the calling programs secondary address space.
Figure 2-5 shows one way to format addresses and ALETs in a parameter list. The
addresses passed to the called program are at the beginning of the list and their
associated ALETs follow the addresses. Notice that the third address has the high
order bit set on to indicate the size of the list.

GPR1
AR1

@A

@B

@C

ALET A

ALET

ALET B
ALET C

Figure 2-5. AR Mode Parameter List

2-14

z/OS V1R4.0 MVS Assembler Services Guide

All addresses that an AR mode target program returns to an AR mode caller,

whether the address is in GPR 0 or 1 or in a parameter list, must be ALET-qualified.

Chapter 2. Linkage Conventions

2-15

2-16

z/OS V1R4.0 MVS Assembler Services Guide

Chapter 3. Subtask Creation and Control

The control program creates one task in the address space as a result of initiating
execution of the job step (the job step task). You can create additional tasks in your
program. However, if you do not, the job step task is the only task in the address
space being executed. The benefits of a multiprogramming environment are still
available even with only one task in the job step; work is still being performed for
other address spaces when your task is waiting for an event, such as an input
operation, to occur.
The advantage in creating additional tasks within the job step is that more tasks are
competing for control. When a wait condition occurs in one of your tasks, it is not
necessarily a task from some other address space that gets control; it may be one
of your tasks, a portion of your job.
The general rule is that you should choose parallel execution of a job step (that is,
more than one task in an address space) only when a significant amount of overlap
between two or more tasks can be achieved. You must take into account the
amount of time taken by the control program in establishing and controlling
additional tasks, and your increased effort to coordinate the tasks and provide for
communications between them.

Creating the Task

A new task is created by issuing an ATTACH, or, if your program runs in access
register ASC mode, an ATTACHX macro. The task that is active when the ATTACH
or ATTACHX is issued is the originating task; the newly created task is the subtask
of the originating task. The subtask competes for control in the same manner as
any other task in the system, on the basis of priority (both address space priority
and task priority within the address space) and the current ability to use a
processor. The address of the task control block for the subtask is returned in
register 1.
If the ATTACH or ATTACHX executes successfully, control returns to the user with a
return code of 0 in register 15.
The entry point in the load module to be given control when the subtask becomes
active is specified as it is in a LINK or LINKX macro, that is, through the use of the
EP, EPLOC, and DE parameters. The use of these parameters is discussed in
Chapter 4, Program Management. You can pass parameters to the subtask using
the PARAM and VL parameters, also described under the LINK macro. Additional
parameters deal with the priority of the subtask, provide for communication between
tasks, specify libraries to be used for program linkages, and establish an error
recovery environment for the new subtask.

Priorities
This section considers three priorities: address space priorities, task priorities, and
subtask priorities.

Address Space Priority

When a job is initiated, the control program creates an address space. All
successive steps in the job execute in the same address space. The address space
has a dispatching priority, which is normally determined by the control program. The
Copyright IBM Corp. 1988, 2002

3-1

control program will select, and alter, the priority in order to achieve the best load
balance in the system, that is, in order to make the most efficient use of processor
time and other system resources.
When the system is running in WLM compatibility mode the IEAIPSxx and
IEAICSxx definitions determine the dispatching priority assigned to the job. See
z/OS MVS Initialization and Tuning Guide for additional information. might want
some jobs to execute at a different address space priority than the default priority
assigned
When the system is running in WLM goal mode, the active WLM service policy
determines the dispatching priority assigned to the job. See z/OS MVS Planning:
Workload Management for additional information.

Task Priority
Each task in an address space has a limit priority and a dispatching priority
associated with it. The control program sets these priorities when a job step is
initiated. When you use the ATTACH or ATTACHX macro to create other tasks in
the address space, you can use the LPMOD and DPMOD parameters to give them
different limit and dispatching priorities.
The dispatching priorities of the tasks in an address space do not affect the order in
which the control program selects jobs for execution because that order is selected
on the basis of address space dispatching priority. Once the control program selects
an address space for dispatching, it selects from within the address space the
highest priority task awaiting execution. Thus, task priorities may affect processing
within an address space. Note, however, that in a multiprocessing system, task
priorities cannot guarantee the order in which the tasks will execute because more
than one task may be executing simultaneously in the same address space on
different processors. Page faults may alter the order in which the tasks execute.

Subtask Priority
When a subtask is created, the limit and dispatching priorities of the subtask are the
same as the current limit and dispatching priorities of the originating task except
when the subtask priorities are modified by the LPMOD and DPMOD parameters of
the ATTACH and ATTACHX macro. The LPMOD parameter specifies the signed
number to be subtracted from the current limit priority of the originating task. The
result of the subtraction is assigned as the limit priority of the subtask. If the result
is zero or negative, zero is assigned as the limit priority. The DPMOD parameter
specifies the signed number to be added to the current dispatching priority of the
originating task. The result of the addition is assigned as the dispatching priority of
the subtask, unless the number is greater than the limit priority or less than zero. In
that case, the limit priority or 0, respectively, is used as the dispatching priority.

Assigning and Changing Priority

Assign tasks with a large number of I/O operations a higher priority than tasks with
little I/O, because the tasks with much I/O will be in a wait condition for a greater
amount of time. The lower priority tasks will be executed when the higher priority
tasks are in a wait condition. As the I/O operations are completed, the higher
priority tasks get control, so that more I/O can be started.
You can change the priorities of subtasks by using the CHAP macro. The CHAP
macro changes the dispatching priority of the active task or one of its subtasks by
adding a positive or negative value. The dispatching priority of an active task can

3-2

z/OS V1R4.0 MVS Assembler Services Guide

be made less than the dispatching priority of another task. If this occurs and the
other task is dispatchable, it would be given control after execution of the CHAP
macro.
You can also use the CHAP macro to increase the limit priority of any of an active
tasks subtasks. An active task cannot change its own limit priority. The dispatching
priority of a subtask can be raised above its own limit priority, but not above the
limit of the originating task. When the dispatching priority of a subtask is raised
above its own limit priority, the subtasks limit priority is automatically raised to equal
its new dispatching priority.

Stopping and Restarting a Subtask (STATUS Macro)

To stop a subtask means to change its dispatchability status from ready to not
ready. You might need to stop a subtask that is currently ready or running, and then
to restart, or make ready, that subtask. Stopping a subtask is a programming
technique to control the dispatchability of other related tasks or subtasks in a
multi-tasking environment when the tasks are in problem state.
To stop all subtasks of an originating task, issue the STATUS macro with the STOP
parameter. To stop a specific subtask, issue the STATUS macro with the STOP,TCB
parameter, which identifies a specific subtask.
To restart the stopped subtask or subtasks, issue STATUS START. As with STATUS
STOP, use the TCB parameter to restart a specific subtask.

Task and Subtask Communications

The task management information in this section is required only for establishing
communications among tasks in the same job step. The relationship of tasks in a
job step is shown in Figure 3-1. The horizontal lines in Figure 3-1. separate
originating tasks and subtasks; they have no bearing on task priority. Tasks A, A1,
A2, A2a, B, B1 and B1a are all subtasks of the job-step task; tasks A1, A2, and A2a
are subtasks of task A. Tasks A2a and B1a are the lowest level tasks in the job
step. Although task B1 is at the same level as tasks A1 and A2, it is not considered
a subtask of task A.
Task A is the originating task for both tasks A1 and A2, and task A2 is the
originating task for task A2a. A hierarchy of tasks exists within the job step.
Therefore the job step task, task A, and task A2 are predecessors of task A2a,
while task B has no direct relationship to task A2a.

Chapter 3. Subtask Creation and Control

3-3

Job
Step
Task

Task A

Task A1

Task B

Task A2

Task B1

Task A2a

Task B1a

Figure 3-1. Levels of Tasks in a Job Step

All of the tasks in the job step compete independently for processor time; if no
constraints are provided, the tasks are performed and are terminated
asynchronously. However, since each task is performing a portion of the same job
step, some communication and constraints between tasks are required, such as
notifying each other when a subtask completes. If a predecessor task attempts to
terminate before all of its subtasks are complete, those subtasks and the
predecessor task are abnormally terminated.
Two parameters, the ECB and ETXR parameters, are provided in the ATTACH or
ATTACHX macro to assist in communication between a subtask and the originating
task. These parameters are used to indicate the normal or abnormal termination of
a subtask to the originating task. If you coded the ECB or ETXR parameter, or both,
in the ATTACH or ATTACHX macro, the task control block of the subtask is not
removed from the system when the subtask is terminated. The originating task must
remove the task control block from the system after termination of the subtask by
issuing a DETACH. If you specified the ECB parameter in the ATTACH or ATTACHX
macro, the ECB must be in storage addressable by the attaching task and control
program so that the issuer of ATTACH can wait on it (using the WAIT macro) and
the control program can post it on behalf of the terminating task. The task control
blocks for all subtasks must be removed before the originating task can terminate
normally.
The ETXR parameter specifies the address of an end-of-task exit routine in the
originating task, which is to be given control when the subtask being created is
terminated. The end-of-task routine is given control asynchronously after the

3-4

z/OS V1R4.0 MVS Assembler Services Guide

subtask has terminated and must therefore be in virtual storage when it is required.
After the control program terminates the subtask, the end-of-task routine specified is
scheduled to be executed. It competes for CPU time using the priority of the
originating task and of its address space and can receive control even though the
originating task is in the wait condition. Although the DETACH does not have to be
issued in the end-of-task routine, this is a good place for it.
The ECB parameter specifies the address of an event control block (discussed
under Task Synchronization), which is posted by the control program when the
subtask is terminated. After posting occurs, the event control block contains the
completion code specified for the subtask.
If you specified neither the ECB nor the ETXR parameter in the ATTACH or
ATTACHX macro, the task control block for the subtask is removed from the system
when the subtask terminates. Its originating task does not have to issue a DETACH.
A reference to the task control block in a CHAP or a DETACH macro in this case is
as risky as task termination. Since the originating task is not notified of subtask
termination, you may refer to a task control block that has been removed from the
system, which would cause the active task to be abnormally terminated.
Note: The originating task is abended if it attempts to normally terminate when it
has active subtasks.

Chapter 3. Subtask Creation and Control

3-5

3-6

z/OS V1R4.0 MVS Assembler Services Guide

Chapter 4. Program Management

This chapter discusses facilities that will help you to design your programs. It
includes descriptions of the residency mode and addressing mode of programs,
linkage considerations, load module structures, facilities for passing control between
programs, and the use of the associated macro. This chapter also includes a
description of the macro used to request services from run-time library services
(RTLS), a function that eases installation by allowing you to eliminate STEPLIBs
from the JCL that runs your applications. In place of STEPLIBs, the new macro
connects to and loads from a given RTLS logical library.

Residency and Addressing Mode of Programs

The control program ensures that each load module is loaded above or below 16
megabytes virtual as appropriate and that it is invoked in the correct addressing
mode (24-bit or 31-bit). The placement of the module above or below 16 megabytes
depends on the residency mode (RMODE) that you define for the module. Whether
a module executes in 24-bit or 31-bit addressing mode depends on the addressing
mode (AMODE) that you define for the module.
When a program is executing in 24-bit addressing mode, the system treats both
instruction and data addresses as 24-bit addresses. This allows programs executing
in 24-bit addressing mode to address 16 megabytes (16,777,216 bytes) of storage.
Similarly, when a program is executing in 31-bit addressing mode, the system treats
both instruction and data addresses as 31-bit addresses. This allows a program
executing in 31-bit addressing mode to address 2 gigabytes (2,147,483,648 bytes
or 128 x 16 megabytes) of storage.
You can define the residency mode and the addressing mode of a program in the
source code. Figure 4-1 shows an example of the definition of the AMODE and
RMODE attributes in the source code. This example defines the addressing mode
of the load module as 31-bit and the residency mode of the load module as 24-bit.
Therefore, the program will receive control in 31-bit addressing mode and will reside
below 16 megabytes.
SAMPLE CSECT
SAMPLE AMODE
SAMPLE RMODE

31
24

Figure 4-1. Assembler Definition of AMODE/RMODE

The assembler places the AMODE and RMODE in the external symbol dictionary
(ESD) of the output object module for use by the linkage editor. The linkage editor
passes this information on to the control program through the directory entry for the
partitioned data set (PDS) that contains the load module and the composite external
symbol dictionary (CESD) record in the load module. You can also specify the
AMODE/RMODE attributes of a load module by using linkage editor control cards.
Chapter 5, Understanding 31-Bit Addressing on page 5-1 contains additional
information about residency and addressing mode; z/OS DFSMS Program
Management contains information about the linkage editor control cards.

Copyright IBM Corp. 1988, 2002

4-1

Residency Mode Definitions

The control program uses the RMODE attribute from the PDS directory entry for the
module to load the program above or below 16 megabytes. The RMODE attribute
can have one of the following values:
24

specifies that the program must reside in 24-bit addressable virtual storage.

ANY

specifies that the program can reside anywhere in virtual storage because
the code has no virtual storage residency restrictions.

Note: The default value for RMODE is 24.

Addressing Mode Definitions

The AMODE attribute, located in the PDS directory entry for the module, specifies
the addressing mode that the module expects at entry. Bit 32 of the program status
word (PSW) indicates the addressing mode of the program that is executing. The
system supports programs that execute in either 24-bit or 31-bit addressing mode.
The AMODE attribute can have one of the following values:
24

specifies that the program is to receive control in 24-bit addressing mode.

31

specifies that the program is to receive control in 31-bit addressing mode.

ANY

specifies that the program is to receive control in either 24-bit or 31-bit

addressing mode.

Note: The default value for AMODE is 24.

Linkage Considerations
The system supports programs that execute in either 24-bit or 31-bit addressing
mode. The following branch instructions take addressing mode into consideration:
Branch and link (BAL)
Branch and link, register form (BALR)
Branch and save (BAS)
Branch and save, register form (BASR)
Branch and set mode (BSM)
Branch and save and set mode (BASSM)
Branch and stack (BAKR)
See Principles of Operation for a complete description of how these instructions
function. The following paragraphs provide a general description of these branch
instructions.
The BAL and BALR instructions are unconditional branch instructions (to the
address in operand 2). BAL and BALR function differently depending on the
addressing mode in which you are executing. The difference is in the linkage
information passed in the link register when these instructions execute. In 31-bit
addressing mode, the link register contains the AMODE indicator (bit 0) and the
address of the next sequential instruction (bits 1-31); in 24-bit addressing mode, the
link register contains the instruction length code, condition code, program mask,
and the address of the next sequential instruction.
BAS and BASR perform the same function that BAL and BALR perform when BAL
and BALR execute in 31-bit addressing mode.

4-2

z/OS V1R4.0 MVS Assembler Services Guide

The BSM instruction provides problem programs with a way to change the AMODE
bit in the PSW. BSM is an unconditional branch instruction (to the address in
operand 2) that saves the current AMODE in the high-order bit of the link register
(operand 1), and sets the AMODE indicator in the PSW to agree with the AMODE
of the address to which you are transferring control (that is, the high order bit of
operand 2).
The BASSM instruction functions in a manner similar to the BSM instruction. In
addition to saving the current AMODE in the link register, setting the PSW AMODE
bit, and transferring control, BASSM also saves the address of the next sequential
instruction in the link register thereby providing a return address.
BASSM and BSM are used for entry and return linkage in a manner similar to
BALR and BR. The major difference from BALR and BR is that BASSM and BSM
can save and change addressing mode.
The BAKR instruction is an unconditional branch to the address in operand 2. In
addition to the branching action, it adds an entry to the linkage stack.
For more information on the linkage stack, see System-Provided Linkage Stack on
page 2-3.

Floating Point Considerations

The application program and run-time environment are responsible for managing
the contents of the Floating Point Control (FPC) register. The system will normally
not change the FPC register settings of an existing MVS task or SRB.
The S/390 linkage convention for the Floating Point Registers and the FPC register
in described in Chapter 2, Linkage Conventions on page 2-1. To summarize the
convention, FPRs 0 to 7 are volatile and FPRs 8 to 15 are non-volatile across a
call. The FPC register is non-volatile except for two fields: the IEEE exception flags
and the DXC, which are volatile.

Passing Control Between Programs with the Same AMODE

If you are passing control between programs that execute in the same addressing
mode, there are several combinations of instructions that you can use. Some of
these combinations are:
Transfer

Return

BAL/BALR

BR

BAS/BASR

BR

Passing Control Between Programs with Different AMODEs

If you are passing control between programs executing in different addressing
modes, you must change the AMODE indicator in the PSW. The BASSM and BSM
instructions perform this function for you. You can transfer to a program in another
AMODE using a BASSM instruction and then return by means of a BSM instruction.
This sequence of instructions ensures that both programs execute in the correct
AMODE.
Figure 4-2 shows an example of passing control between programs with different
addressing modes. In the example, TEST executes in 24-bit AMODE and EP1
executes in 31-bit AMODE. Before transferring control to EP1, the TEST program
loads register 15 with EPA, the pointer defined entry point address (that is, the
Chapter 4. Program Management

4-3

address of EP1 with the high order bit set to 1 to indicate 31-bit AMODE). This is
followed by a BASSM 14,15 instruction, which performs the following functions:
v Sets the high-order bit of the link register (register 14) to 0 (because TEST is
currently executing in 24-bit AMODE) and puts the address of the next sequential
instruction into bits 1-31.
v Sets the PSW AMODE bit to 1 to agree with bit 0 of register 15.
v Transfers to EP1 (the address in bits 1-31 of register 15).
The EP1 program executes in 31-bit AMODE. Upon completion, EP1 sets a return
code in register 15 and executes a BSM 0,14 instruction, which performs the
following functions:
v Sets the PSW AMODE bit to 0 to correspond to the high-order bit of register 14.
v Transfers control to the address following the BASSM instruction in the TEST
program.
TEST
TEST
TEST

CSECT
AMODE 24
RMODE 24
.
.
L
15,EPA
OBTAIN TRANSFER ADDRESS
BASSM 14,15
SWITCH AMODE AND TRANSFER
.
.
EXTRN EP1
EPA
DC
A(X80000000+EP1) POINTER DEFINED ENTRY POINT ADDRESS
.
.
END
____________________________________________________________
EP1
CSECT
EP1
AMODE 31
EP1
RMODE ANY
.
.
SLR
15,15
SET RETURN CODE 0
BSM
0,14
RETURN TO CALLERS AMODE AND TRANSFER
END

Figure 4-2. Example of Addressing Mode Switch

Passing Control Between Programs with All Registers Intact

The CSRL16J callable service allows you to transfer control to another program
running under the same request block (RB) as the calling program. The CSRL16J
callable service functions much like a branch instruction except that you can specify
the contents of all 16 registers when you transfer control. You do not have to use
one register to specify the address of the target routine, as you do with a branch
instruction.
When you transfer control to the other routine, use the CSRL16J callable service to:
v Define the entry characteristics and register contents for the target routine.
v Optionally free dynamic storage associated with the calling program.
When the CSRL16J callable service is successful, control transfers to the target
routine. After the target routine runs, it can transfer control to any program running
under the same RB, including the calling program.

4-4

z/OS V1R4.0 MVS Assembler Services Guide

Defining the Entry Characteristics of the Target Routine

Before calling CSRL16J, you must build the L16J data area to form a parameter list
that defines the entry characteristics and register contents for the target routine.
Include the CSRYL16J mapping macro to map data area L16J. To build the L16J
parameter list, first initialize the parameter list with zeroes and then fill in the
desired fields. This processing ensures that all fields requiring zeroes are correct.
You can specify the following characteristics for the target routine in the indicated
fields of data area L16J:
L16JLENGTH

Length of the L16J parameter list. Initialize this field

with constant L16J_LEN.

L16JGRS

General purpose registers (GPRs) 0-15 on entry to

the target routine.

L16JARS

Access registers (ARs) 0-15 on entry to the target

routine, if you set the L16JPROCESSARS bit on.

L16JPSW

Includes the following PSW information for the

target routine. See Principles of Operation for more
information about the contents of the PSW.
v PSW address and AMODE
v PSW ASC mode primary or AR
v PSW program mask
v PSW condition code
APF-authorized callers, callers in supervisor state,
PSW key 0-7, or PKM allowing key 0-7, can
specify:
v PSW state - problem or supervisor
v PSW key.
For unauthorized callers, the PSW state and key of
the calling program are used for the target routine.

L16JPROCESSARS

A bit indicating whether or not you want to specify

the contents of the access registers (ARs) for the
target routine. Set the bit on if you want to specify
the contents of the ARs. If you set the bit off, the
access registers (ARs) contents are determined by
the system.

When CSRL16J passes control to the target routine, the GPRs contain:
Register

Contents

0-15

Values specified by the caller

If the L16JPROCESSARS bit is set on, when CSRL16J passes control to the target
routine the access registers (ARs) contain:
Register

Contents

0-15

Values specified by the caller

If the L16JPROCESSARS bit is set off, when CSRL16J passes control to the target
routine the access registers (ARs) contain:
Register

Contents

0-1

Do not contain any information for use by the routine

Chapter 4. Program Management

4-5

2-13

The contents are the same as they were when the caller issued the
CSRL16J callable service.

14-15

Do not contain any information for use by the routine

Freeing Dynamic Storage Associated with the Caller

If the calling program has a dynamic storage area associated with it, you can
specify that CSRL16J free some or all of this storage area before it transfers control
to the target routine. In the L16J parameter list, specify the following fields:
L16JSUBPOOL

Specify the subpool of the area that you want the

system to free.

L16JLENGTHTOFREE

Specify the length, in bytes, of the dynamic storage

area you want the system to free.

L16JAREATOFREE

Specify the address of the dynamic storage area

you want the system to free.
Make sure that the address is on a doubleword
boundary. Otherwise, the service ends with an
abend code X'978'. See z/OS MVS System Codes
for information on abend code X'978'.

The system frees the storage only when the CSRL16J callable service is
successful.

Load Module Structure Types

Each load module used during a job step can be designed in one of three load
module structures: simple, planned overlay, or dynamic. A simple structure does not
pass control to any other load modules during its execution, and comes into virtual
storage all at one time. A planned overlay structure may, if necessary, pass control
to other load modules during its execution, and it does not come into virtual storage
all at one time. Instead, segments of the load module reuse the same area of virtual
storage. A dynamic structure comes into virtual storage all at one time, and passes
control to other load modules during its execution. Each of the load modules to
which control is passed can be one of the three structure types. Characteristics of
the load module structure types are summarized in Table 4-1.
Because the large capacity of virtual storage eliminates the need for complex
overlay structures, planned overlays will not be discussed further.
Table 4-1. Characteristics of Load Modules
Structure Type

Loaded All at One Time

Passes Control to Other Load

Modules

Simple
Planned Overlay
Dynamic

Yes
No
Yes

No
Optional
Yes

Simple Structure
A simple structure consists of a single load module produced by the linkage editor.
The single load module contains all of the instructions required and is paged into
central storage by the control program as it is executed. The simple structure can
be the most efficient of the two structure types because the instructions it uses to
pass control do not require control-program assistance. However, you should design
your program to make most efficient use of paging.

4-6

z/OS V1R4.0 MVS Assembler Services Guide

Dynamic Structure
A dynamic structure requires more than one load module during execution. Each
required load module can operate as either a simple structure or another dynamic
structure. The advantages of a dynamic structure over a simple structure increase
as the program becomes more complex, particularly when the logical path of the
program depends on the data being processed. The load modules required in a
dynamic structure are paged into central storage when required, and can be deleted
from virtual storage when their use is completed.

Load Module Execution

Depending on the configuration of the operating system and the macros used to
pass control, execution of the load modules is serial or in parallel. Execution is
serial in the operating system unless you use an ATTACH or ATTACHX macro to
create a new task. The new task competes for processor time independently with all
other tasks in the system. The load module named in the ATTACH or ATTACHX
macro is executed in parallel with the load module containing the ATTACH or
ATTACHX macro. The execution of the load modules is serial within each task.
The following paragraphs discuss passing control for serial execution of a load
module. For information on creating and managing new tasks, see Creating the
Task on page 3-1.

Passing Control in a Simple Structure

There are certain procedures to follow when passing control to an entry point in the
same load module. The established conventions to use when passing control are
also discussed. These procedures and conventions are the framework for all
program interfaces.

Passing Control without Return

Some control sections pass control to another control section of the load module
and do not receive control back. An example of this type of control section is a
housekeeping routine at the beginning of a program that establishes values,
initializes switches, and acquires buffers for the other control sections in the
program. Use the following procedures when passing control without return.

Preparing to Pass Control

v Restore the contents of register 14.
Because control will not be returned to this control section, you must restore the
contents of register 14. Register 14 originally contained the address of the
location in the calling program (for example, the control program) to which control
is to be passed when your program is finished. Since the current control section
does not make the return to the calling program, the return address must be
passed on to the control section that does make the return.
v Restore the contents of registers 2-12.
In addition, the contents of registers 2-12 must be unchanged when your
program eventually returns control, so you must also restore these registers.
If control were being passed to the next entry point from the control program,
register 15 would contain the entry address. You should use register 15 in the
same way, so that the called routine remains independent of the program that
passed control to it.
v Use register 1 to pass parameters.
Chapter 4. Program Management

4-7

Establish a parameter list and place the address of the list in register 1. The
parameter list should consist of consecutive fullwords starting on a fullword
boundary, each fullword containing an address to be passed to the called control
section. When executing in 24-bit AMODE, each address is located in the three
low-order bytes of the word. When executing in 31-bit AMODE, each address is
located in bits 1-31 the word. In both addressing modes, set the high-order bit of
the last word to 1 to indicate that it is the last word of the list. The system
convention is that the list contain addresses only. You may, of course, deviate
from this convention; however, when you deviate from any system convention,
you restrict the use of your programs to those programmers who know about
your special conventions.
v Pass the address of the save area in register 13 just as it was passed to you.
Since you have reloaded all the necessary registers, the save area that you
received on entry is now available, and should be reused by the called control
section. By passing the address of the old save area, you save the 72 bytes of
virtual storage for a second, unnecessary, save area.
Note: If you pass a new save area instead of the one received on entry, errors
could occur.

Passing Control
v Load register 15 with a V-type address constant for the name of the external
entry point, then branch to the address in register 15.
This is the common way to pass control between one control section and an
entry point in the same load module. The external entry point must have been
identified using an ENTRY instruction in the called control section if the entry
point is not the same as the control sections CSECT name.
Figure 4-3 shows an example of loading registers and passing control. In this
example, no new save area is used, so register 13 still contains the address of the
old save area. It is also assumed for this example that the control section will pass
the same parameters it received to the next entry point. First, register 14 is
reloaded with the return address. Next, register 15 is loaded with the address of the
external entry point NEXT, using the V-type address constant at the location
NEXTADDR. Registers 0-12 are reloaded, and control is passed by a branch
instruction using register 15. The control section to which control is passed contains
an ENTRY instruction identifying the entry point NEXT.
.
.
L
L
LM
BR
.
.
NEXTADDR DC

14,12(13)
15,NEXTADDR
0,12,20(13)
15

LOAD CALLERS RETURN ADDRESS

ENTRY NEXT
RETURN CALLERs REGISTERS
NEXT SAVE (14,12)

V(NEXT)

Figure 4-3. Passing Control in a Simple Structure

Figure 4-4 shows an example of passing a parameter list to an entry point with the
same addressing mode. Early in the routine the contents of register 1 (that is, the
address of the fullword containing the PARM field address) were stored at the
fullword PARMADDR. Register 13 is loaded with the address of the old save area,

4-8

z/OS V1R4.0 MVS Assembler Services Guide

which had been saved in word 2 of the new save area. The contents of register 14
are restored, and register 15 is loaded with the entry address.

EARLY

PARMLIST
DCBADDRS
PARMADDR
NEXTADDR

.
.
USING
ST
.
.
L
L
L
L
LA
OI
LM
BR
.
.
DS
DC
DC
DC
DC

*,12
1,PARMADDR

Establish addressability
Save parameter address

13,4(13)
0,20(13)
14,12(13)
15,NEXTADDR
1,PARMLIST
PARMADDR,X80
2,12,28(13)
15

Reload address of old save area

Load return address
Load address of next entry point
Load address of parameter list
Turn on last parameter indicator
Reload remaining registers
Pass control

0A
A(INDCB)
A(OUTDCB)
A(0)
V(NEXT)

Figure 4-4. Passing Control With a Parameter List

The address of the list of parameters is loaded into register 1. These parameters
include the addresses of two data control blocks (DCBs) and the original register 1
contents. The high-order bit in the last address parameter (PARMADDR) is set to 1
using an OR-immediate instruction. The contents of registers 2-12 are restored.
(Since one of these registers was the base register, restoring the registers earlier
would have made the parameter list unaddressable.) A branch register instruction
using register 15 passes control to entry point NEXT.

Passing Control with Return

The control program passed control to your program, and your program will return
control when it is through processing. Similarly, control sections within your program
will pass control to other control sections, and expect to receive control back. An
example of this type of control section is a monitoring routine; the monitor
determines the order of execution of other control sections based on the type of
input data. Use the following procedures when passing control with return.

Preparing to Pass Control

v Use registers 15 and 1 in the same manner they are used to pass control without
return.
Register 15 contains the entry address in the new control section and register 1
is used to pass a parameter list.
v Ensure that register 14 contains the address of the location to which control is to
be returned when the called control section completes execution.
The address can be the instruction following the instruction which causes control
to pass, or it can be another location within the current control section designed
to handle all returns.
Registers 2-12 are not involved in the passing of control; the called control
section should not depend on the contents of these registers in any way.
v Provide a new save area for use by the called control section as previously
described, and pass the address of that save area in register 13.
Chapter 4. Program Management

4-9

Note that the same save area can be reused after control is returned by the
called control section. One new save area is ordinarily all you will require
regardless of the number of control sections called.

Passing Control
You may use two standard methods for passing control to another control section
and providing for return of control. One is an extension of the method used to pass
control without a return, and requires a V-type address constant and a branch, a
branch and link, or a branch and save instruction provided both programs execute
in the same addressing mode. If the addressing mode changes, use a branch and
save and set mode instruction. The other method uses the CALL macro to provide
a parameter list and establish the entry and return addresses. With either method,
you must identify the entry point by an ENTRY instruction in the called control
section if the entry name is not the same as the control section CSECT name.
Figure 4-5 and Figure 4-6 illustrate the two methods of passing control; in each
example, assume that register 13 already contains the address of a new save area.
Figure 4-5 also shows the use of an inline parameter list and an answer area. The
address of the external entry point is loaded into register 15 in the usual manner. A
branch and link instruction is then used to branch around the parameter list and to
load register 1 with the address of the parameter list. An inline parameter list, such
as the one shown in Figure 4-5, is convenient when you are debugging because the
parameters involved are located in the listing (or the dump) at the point they are
used, instead of at the end of the listing or dump. Note that the high-order bit of the
last address parameter (ANSWERAD) is set to 1 to indicate the end of the list. The
area pointed to by the address in the ANSWERAD parameter is an area to be used
by the called control section to pass parameters back to the calling control section.
This is a possible method to use when a called control section must pass
parameters back to the calling control section. Parameters are passed back in this
manner so that no additional registers are involved. The area used in this example
is twelve words. The size of the area for any specific application depends on the
requirements of the two control sections involved.
.
.
L
CNOP
BAL
PARMLIST DS
DCBADDRS DC
DC
ANSWERAD DC

15,NEXTADDR
0,4
1,GOOUT
0A
A(INDCB)
A(OUTDCB)
A(AREA+X80000000)

NEXTADDR DC
GOOUT
BALR

V(NEXT)
14,15

RETURNPT ...
AREA
DC

12F0

Entry address in register 15

Parameter list address in register 1
Start of parameter list
Input DCB address
Output DCB address
Answer area address with
high-order bit on
Address of entry point
Pass control; register 14 contains
return address and current AMODE
Answer area from NEXT

Note: This example assumes that you are passing control to a program that
executes in the same addressing mode as your program. See Linkage
Considerations on page 4-2 for information on how to handle branches
between programs that execute in different addressing modes.
Figure 4-5. Passing Control With Return

4-10

z/OS V1R4.0 MVS Assembler Services Guide

RETURNPT
AREA

CALL
...
DC

NEXT,(INDCB,OUTDCB,AREA),VL
12F0

Note: If you are using the CALL macro to pass control to a program that executes
in a different addressing mode, you must include the LINKINST=BASSM
parameter.
Figure 4-6. Passing Control With CALL

The CALL macro in Figure 4-6 provides the same functions as the instructions in
Figure 4-5. When the CALL macro is expanded, the parameters cause the following
results:
NEXT - A V-type address constant is created for NEXT, and the address is
loaded into register 15.
(INDCB,OUTDCB,AREA) - A-type address constants are created for the three
parameters coded within parentheses, and the address of the first A-type
address constant is placed in register 1.
VL - The high-order bit of the last A-type address constant is set to 1.
Control is passed to NEXT using a branch and link instruction. (Optionally, you can
specify either a BASR or BASSM instruction, with the LINKINST= parameter.) The
address of the instruction following the CALL macro is loaded into register 14 before
control is passed.
In addition to the results described above, the V-type address constant generated
by the CALL macro requires the load module with the entry point NEXT to be link
edited into the same load module as the control section containing the CALL macro.
The z/OS DFSMS Program Management publication tells more about this service.
The parameter list constructed from the CALL macro in Figure 4-6, contains only
A-type address constants. A variation on this type of parameter list results from the
following coding:
CALL

NEXT,(INDCB,(6),(7)),VL

In the above CALL macro, two of the parameters to be passed are coded as
registers rather than symbolic addresses. The expansion of this macro again results
in a three-word parameter list; in this example, however, the expansion also
contains instructions that store the contents of registers 6 and 7 in the second and
third words, respectively, of the parameter list. The high-order bit in the third word is
set to 1 after register 7 is stored. You can specify as many address parameters as
you need, and you can use symbolic addresses or register contents as you see fit.

Analyzing the Return

When the control program returns control to a caller after it invokes a system
service, the contents of registers 2-13 are unchanged. When control is returned to
your control section from the called control section, registers 2-14 contain the same
information they contained when control was passed, as long as system
conventions are followed. The called control section has no obligation to restore
registers 0 and 1; so the contents of these registers may or may not have been
changed.
When control is returned, register 15 can contain a return code indicating the
results of the processing done by the called control section. If used, the return code
should be a multiple of four, so a branching table can be used easily, and a return
code of zero should be used to indicate a normal return. The control program
Chapter 4. Program Management

4-11

frequently uses this method to indicate the results of the requests you make using
system macros; an example of the type of return codes the control program
provides is shown in the description of the IDENTIFY macro.
The meaning of each of the codes to be returned must be agreed upon in advance.
In some cases, either a good or bad indication (zero or nonzero) will be sufficient
for you to decide your next action. If this is true, the coding in Figure 4-7 could be
used to analyze the results. Many times, however, the results and the alternatives
are more complicated, and a branching table, such as shown in Figure 4-8 could be
used to pass control to the proper routine.
Note: Explicit tests are required to ensure that the return code value does not
exceed the branch table size.
RETURNPT

LTR
BNZ
.
.

15,15
ERRORTN

Test return code for zero

Branch if not zero to error routine

Figure 4-7. Test for Normal Return

RETURNPT
RETTAB

B RETTAB(15)
B NORMAL
B COND1
B COND2
B GIVEUP
.
.

Branch
Branch
Branch
Branch
Branch

to
to
to
to
to

table using return code

normal routine
routine for condition 1
routine for condition 2
routine to handle impossible situations.

Figure 4-8. Return Code Test Using Branching Table

How Control is Returned

In the discussion of the return under Analyzing the Return on page 4-11, it was
indicated that the control section returning control must restore the contents of
registers 2-14. Because these are the same registers reloaded when control is
passed without a return, refer to the discussion under Passing Control without
Return for detailed information and examples. The contents of registers 0 and 1 do
not have to be restored.
Register 15 can contain a return code when control is returned. As indicated
previously, a return code should be a multiple of four with a return code of zero
indicating a normal return. The return codes other than zero that you use can have
any meaning, as long as the control section receiving the return codes is aware of
that meaning.
The return address is the address originally passed in register 14; you should
always return control to that address. If an addressing mode switch is not involved,
you can either use a branch instruction such as BR 14, or you can use the
RETURN macro. An example of each of these methods of returning control is
discussed in the following paragraphs. If an addressing mode switch is involved,
you can use a BSM 0,14 instruction to return control. See Figure 4-2 for an
example that uses the BSM instruction to return control.
Figure 4-9 shows a portion of a control section used to analyze input data cards
and to check for an out-of-tolerance condition. Each time an out-of-tolerance
condition is found, in addition to some corrective action, one is added to the
one-byte value at the address STATUSBY. After the last data card is analyzed, this

4-12

z/OS V1R4.0 MVS Assembler Services Guide

control section returns to the calling control section, which bases its next action on
the number of out-of-tolerance conditions encountered. The coding shown in
Figure 4-9 loads register 14 with the return address. The contents of register 15 are
set to zero, and the value at the address STATUSBY (the number of errors) is
placed in the low-order eight bits of the register. The contents of register 15 are
shifted to the left two places to make the value a multiple of four. Registers 2-12 are
reloaded, and control is returned to the address in register 14.
.
.
L
L
SR
IC
SLA
LM
BR
.
.
STATUSBY DC

13,4(13)
14,12(13)
15,15
15,STATUSBY
15,2
2,12,28(13)
14

Load address of previous save area

Load return address
Set register 15 to zero
Load number of errors
Set return code to multiple of 4
Reload registers 2-12
Return

X00

Note: This example assumes that you are returning to a program with the same
AMODE. If not, use the BSM instruction to transfer control.
Figure 4-9. Establishing a Return Code

The RETURN macro saves coding time. The expansion of the RETURN macro
provides instructions that restore a designated range of registers, load a return code
in register 15, and branch to the address in register 14. If T is specified, the
RETURN macro flags the save area used by the returning control section (that is,
the save area supplied by the calling routine). It does this by setting the low-order
bit of word four of the save area to one after the registers have been restored. The
flag indicates that the control section that used the save area has returned to the
calling control section. The flag is useful when tracing the flow of your program in a
dump. For a complete record of program flow, a separate save area must be
provided by each control section each time control is passed.
You must restore the contents of register 13 before issuing the RETURN macro.
Code the registers to be reloaded in the same order as they would have been
designated for a load-multiple (LM) instruction. You can load register 15 with the
return code before you write the RETURN macro, you can specify the return code
in the RETURN macro, or you can reload register 15 from the save area.
The coding shown in Figure 4-10 provides the same result as the coding shown in
Figure 4-9. Registers 13 and 14 are reloaded, and the return code is loaded in
register 15. The RETURN macro reloads registers 2-12 and passes control to the
address in register 14. The save area used is not flagged. The RC=(15) parameter
indicates that register 15 already contains the return code, and the contents of
register 15 are not to be altered.

Chapter 4. Program Management

4-13

.
.
L
L
SR
IC
SLA
RETURN
.
.
STATUSBY DC

13,4(13)
14,12(13)
15,15
15,STATUSBY
15,2
(2,12),RC=(15)

Restore save area address

Return address in register 14
Zero register 15
Load number of errors
Set return code to multiple of 4
Reload registers and return

X00

Note: You cannot use the RETURN macro to pass control to a program that
executes in a different addressing mode.
Figure 4-10. Using the RETURN Macro

Figure 4-11 illustrates another use of the RETURN macro. The correct save area
address is again established, and then the RETURN macro is issued. In this
example, registers 14 and 0-12 are reloaded, a return code of 8 is placed in register
15, the save area is flagged, and control is returned. Specifying a return code
overrides the request to restore register 15 even though register 15 is within the
designated range of registers.
.
.
L
RETURN

13,4(13)
(14,12),T,RC=8

Figure 4-11. RETURN Macro with Flag

Return to the Control Program

The discussion in the preceding paragraphs has covered passing control within one
load module, and has been based on the assumption that the load module was
brought into virtual storage because of the program name specified in the EXEC
statement. The control program established only one task to be performed for the
job step. When the logical end of the program is reached, control passes to the
return address passed (in register 14) to the first control section in the control
program. When the control program receives control at this point, it terminates the
task it created for the job step, compares the return code in register 15 with any
COND values specified on the JOB and EXEC statements, and determines whether
or not subsequent job steps, if any are present, should be executed.
When your program returns to the control program, your program should use a
return code between 0 and 4095 (X'0FFF'). A return code of more than 4095 might
make return code testing, message processing, and report generation inaccurate.

Passing Control in a Dynamic Structure

The discussion of passing control in a simple structure provides the background for
the discussion of passing control in a dynamic structure. Within each load module,
control should be passed as in a simple structure. If you can determine which
control sections will make up a load module before you code the control sections,
you should pass control within the load module without involving the control
program. The macros discussed in this section provide increased linkage capability,
but they require control program assistance and possibly increased execution time.

4-14

z/OS V1R4.0 MVS Assembler Services Guide

Bringing the Load Module into Virtual Storage

The control program automatically brings the load module containing the entry
name you specified on the EXEC statement into virtual storage. Each load module
or program object resides in a library, either a partitioned data set (PDS) or
partitioned data set extended (PDSE). A load module resides in a PDS, and a
program object resides in a PDSE. In most cases, references in this book to load
modules apply to both load modules and program objects. Any exceptions are
specifically noted. As the control program brings the load module into virtual
storage, it places the load module above or below 16 megabytes according to its
RMODE attribute. Any other load modules you require during your job step are
brought into virtual storage by the control program when requested. Make these
requests by using the LOAD, LINK, LINKX, ATTACH, ATTACHX, XCTL, and XCTLX
macros. The LOAD macro sets the high-order bit of the entry point address to
indicate the addressing mode of the load module. The ATTACH, ATTACHX, LINK,
LINKX, XCTL, and XCTLX macros use this information to set the addressing mode
for the module that gets control. If the AMODE is ANY, the module will get control in
the same addressing mode as the program that issued the ATTACH, ATTACHX,
LINK, LINKX, XCTL, or XCTLX macro. If a copy of the load module must be
brought into storage, the control program places the load module above or below
16 megabytes according to its RMODE attribute. The following paragraphs discuss
the proper use of these macros.

Location of the Load Module

Load modules and program objects can reside in the link library, the job or step
library, the task library, or a private library.
v The link library (defined by the LNKLSTxx or PROGxx member of
[Link]) is always present and is available to all job steps of all jobs.
The control program provides the data control block for the library and logically
connects the library to your program, making the members of the library available
to your program. For more information, see z/OS MVS Initialization and Tuning
Guide.
v The job and step libraries are explicitly established by including //JOBLIB and
//STEPLIB DD statements in the input stream. The //JOBLIB DD statement is
placed immediately after the JOB statement, while the //STEPLIB DD statement
is placed among the DD statements for a particular job step. The job library is
available to all steps of your job, except those that have step libraries. A step
library is available to a single job step; if there is a job library, the step library
replaces the job library for the step. For either the job library or the step library,
the control program provides the data control block and issues the OPEN macro
to logically connect the library to your program.
Authorization: If an authorized program (supervisor state, APF-authorized, PSW
key 0 - 7, or PKM allowing key 0 - 7) invokes an unauthorized program, the
unauthorized program must reside in an APF-authorized library. See
APF-authorized Programs and Libraries on page 4-27 for more information
about APF-authorized libraries.
v Unique task libraries can be established by using the TASKLIB parameter of the
ATTACH or ATTACHX macro. The issuer of the ATTACH or ATTACHX macro is
responsible for providing the DD statement and opening the data set or sets. If
the TASKLIB parameter is omitted, the task library of the attaching task is
propagated to the attached task. In the following example, task As job library is
LIB1. Task A attaches task B, specifying TASKLIB=LIB2 in the ATTACH or
ATTACHX macro. Task Bs task library is therefore LIB2. When task B attaches
task C, LIB2 is searched for task C before LIB1 or the link library. Because task

Chapter 4. Program Management

4-15

B did not specify a unique task library for task C, its own task library (LIB2) is
propagated to task C and is the first library searched when task C requests that
a module be brought into virtual storage.
Task A
Task B

ATTACH EP=B,TASKLIB=LIB2
ATTACH EP=C

v Including a DD statement in the input stream defines a private library that is

available only to the job step in which it is defined. You must provide the data
control block and issue the OPEN macro for each data set. You may use more
than one private library by including more than one DD statement and an
associated data control block.
A library can be a single partitioned data set, or a collection of such data sets.
When it is a collection, you define each data set by a separate DD statement, but
you assign a name only to the statement that defines the first data set. Thus, a job
library consisting of three partitioned data sets would be defined as follows:
//JOBLIB
//
//

DD DSNAME=PDS1,...
DD DSNAME=PDS2,...
DD DSNAME=PDS3...

The three data sets (PDS1, PDS2, PDS3) are processed as one, and are said to be
concatenated. Concatenation and the use of partitioned data sets is discussed in
more detail in z/OS DFSMS: Using Data Sets.
Some of the load modules from the link library may already be in virtual storage in
an area called the link pack area. The contents of these areas are determined
during the nucleus initialization process and will vary depending on the
requirements of your installation. The link pack area contains all reenterable load
modules from the LPA library, along with installation selected modules. These load
modules can be used by any job step in any job.
With the exception of those load modules contained in this area, copies of all of the
reenterable load modules you request are brought into your area of virtual storage
and are available to any task in your job step. The portion of your area containing
the copies of the load modules is called the job pack area. Any program loaded by
a particular task is also represented within that tasks load list.

The Search for the Load Module

In response to your request for a copy of a load module, the control program
searches the tasks load list and the job pack area. If a copy of the load module is
found, the control program determines whether that copy can be used (see Using
an Existing Copy). If an existing copy can be used, the search stops. If it cannot be
used, the search continues until the module is located in a library or the link pack
area. The load module is then brought into the job pack area or placed into the load
list.
The order in which the control program searches the libraries, load list, and pack
areas depends on the parameters used in the macro (LINK, LINKX, LOAD, XCTL,
XCTLX, ATTACH or ATTACHX) requesting the load module. The parameters that
define the order of the search are EP, EPLOC, DE, DCB, and TASKLIB.
Use the TASKLIB parameter only for ATTACH or ATTACHX. If you know the
location of the load module, you should use parameters that eliminate as many of
these searches as possible, as indicated in Figure 4-12, Figure 4-13, and
Figure 4-14.

4-16

z/OS V1R4.0 MVS Assembler Services Guide

The EP, EPLOC, or DE parameter specifies the name of the entry point in the load
module. Code one of the three every time you use a LINK, LINKX, LOAD, XCTL,
XCTLX, ATTACH, or ATTACHX macro. The optional DCB parameter indicates the
address of the data control block for the library containing the load module. Omitting
the DCB parameter or using the DCB parameter with an address of zero specifies
that the system is to do its normal search. If you specified TASKLIB and if the DCB
parameter contains the address of the data control block for the link library, the
control program searches no other library.
To avoid using system copies of modules resident in LPA and LINKLIB, you can
specifically limit the search for the load module to the load list and the job pack
area and the first library on the normal search sequence by specifying the
LSEARCH parameter on the LINK, LOAD, or XCTL macro with the DCB for the
library to be used.
The following paragraphs discuss the order of the search when the entry name
used is a member name.
The EP and EPLOC parameters require the least effort on your part; you provide
only the entry name, and the control program searches for a load module having
that entry name. Figure 4-12 shows the order of the search when EP or EPLOC is
coded, and the DCB parameter is omitted or DCB=0 is coded.

The control program searches:

1. The requesting tasks load list for an available copy.
2. The job pack area for an available copy.
3. The requesting tasks task library and all the unique task libraries of its
preceding tasks. (For the ATTACH or ATTACHX macro, the attached tasks
library and all the unique task libraries of its preceding tasks are searched.)
4. The step library; if there is no step library, the job library (if any).
5. The link library.
Figure 4-12. Search for Module, EP or EPLOC Parameter With DCB=0 or DCB Parameter
Omitted

When used without the DCB parameter, the EP and EPLOC parameters provide the
easiest method of requesting a load module from the link, job, or step library. The
control program searches the task libraries before the job or step library, beginning
with the task library of the task that issued the request and continuing through the
task libraries of all its antecedent tasks. It then searches the job or step library,
followed by the link library.
A job, step, or link library or a data set in one of these libraries can be used to hold
one version of a load module, while another can be used to hold another version
with the same entry name. If one version is in the link library, you can ensure that
the other will be found first by including it in the job or step library. However, if both
versions are in the job or step library, you must define the data set that contains the
version you want to use before the data set that contains the other version. For
example, if the wanted version is in PDS1 and the unwanted version is in PDS2, a
step library consisting of these data sets should be defined as follows:
//STEPLIB
//

DD DSNAME=PDS1,...
DD DSNAME=PDS2,...
Chapter 4. Program Management

4-17

Use extreme caution when specifying duplicate module names. Even if you code
the DCB parameter, the wrong module can still receive control. For example,
suppose there are two modules with the same name you want to invoke, one after
the other. To distinguish between them in this example they are called PROG2 and
PROG2. PROG1 issues a LOAD for PROG2 and BALRs to it. PROG2 issues a
LINK specifying a DCB for the library with the other copy of PROG2 (which we are
calling PROG2). The LINK will find a useable copy of PROG2 in the Job Pack Area
and invoke it again, regardless of the DCB parameter. PROG2 again issues a LINK
for PROG2. This time the copy of PROG2 in the Job Pack Area is marked not
reusable and PROG2 is loaded using the DCB parameter and given control.
The problem encountered in the example above could be avoided by any one of the
following sequences:
v PROG1 links to PROG2 and PROG2 links to PROG2
v PROG1 loads and branches to PROG2. PROG2 loads and branches to PROG2
v PROG1 links to PROG2 and PROG2 loads and branches to PROG2
Once a module has been loaded from a task library, step library, or job library, the
module name is known to all tasks in the address space and may be used as long
as the module is considered usable. Generally speaking, reenterable modules are
always usable. Serially reusable modules are usable when they are currently in use.
Non-reentrant, non-serially reusable modules are considered usable for LOAD if the
use count is zero. A module is considered usable for ATTACH, LINK, or XCTL if it
has not been marked NOT REUSABLE by a previous ATTACH, LINK, or XCTL. The
use count is not considered.
If you know that the load module you are requesting is a member of one of the
private libraries, you can still use the EP or EPLOC parameter, this time in
conjunction with the DCB parameter. Specify the address of the data control block
for the private library in the DCB parameter. The order of the search for EP or
EPLOC with the DCB parameter (when the DCB parameter is not 0) is shown in
Figure 4-13.

The control program searches:

1. The requesting tasks load list for an available copy.
2. The job pack area for an available copy.
3. The specified library.
Figure 4-13. Search for Module, EP or EPLOC Parameters With DCB Parameter Specifying
Private Library

Searching a job or step library slows the retrieval of load modules from the link
library; to speed this retrieval, you should limit the size of the job and step libraries.
You can best do this by eliminating the job library altogether and providing step
libraries where required. You can limit each step library to the data sets required by
a single step. Some steps (such as compilation) do not require a step library and
therefore do not require searching and retrieving modules from the link library. For
maximum efficiency, you should define a job library only when a step library would
be required for every step, and every step library would be the same.
The DE parameter requires more work than the EP and EPLOC parameters, but it
can reduce the amount of time spent searching for a load module. Before you can

4-18

z/OS V1R4.0 MVS Assembler Services Guide

use this parameter, you must use the BLDL macro to obtain the directory entry for
the module. The directory entry is part of the library that contains the module. See
z/OS DFSMS Macro Instructions for Data Sets for more information about the BLDL
macro.
To save time, the BLDL macro must obtain directory entries for more than one entry
name. Specify the names of the load modules and the address of the data control
block for the library when using the BLDL macro; the control program places a copy
of the directory entry for each entry name requested in a designated location in
virtual storage. If you specify the link library and the job or step library by specifying
DCB=0, the directory information indicates from which library the directory entry was
taken. The directory entry always indicates the relative track and block location of
the load module in the library. If the load module is not located on the library you
indicate, a return code is given. You can then issue another BLDL macro specifying
a different library.
To use the DE parameter, provide the address of the directory entry and code or
omit the DCB parameter to indicate the same library specified in the BLDL macro.
The task using the DE parameter should be the same as the one which issued the
BLDL or one which has the same job, step, and task library structure as the task
issuing the BLDL. The order of the search when the DE parameter is used is shown
in Figure 4-14 for the link, job, step, and private libraries.
The preceding discussion of the search is based on the premise that the entry
name you specified is the member name. The control program checks for an alias
entry point name when the load module is found in a library. If the name is an alias,
the control program obtains the corresponding member name from the library
directory, and then searches to determine if a usable copy of the load module exists
in the job pack area. If a usable copy does not exist in a pack area, a new copy is
brought into the job pack area. Otherwise, the existing copy is used, conserving
virtual storage and eliminating the loading time.
Directory Entry Indicates Link Library and DCB=0 or DCB Parameter Omitted.
1.
2.
3.
4.

The
The
The
The

requesting tasks load list is searched for an available copy.

job pack area is searched for an available copy.
link pack area is searched.
module is obtained from the link library.

Directory Entry Indicates Job, Step, or Task Library and DCB=0 or DCB Parameter
Omitted.
1. The job pack area is searched for an available copy.
2. The module is obtained from the task library designated by the Z byte of the
DE operand.
DCB Parameter Indicates Private Library
1. The job pack area is searched for an available copy.
2. The module is obtained from the specified private library.
Figure 4-14. Search for Module Using DE Parameter

As the discussion of the search indicates, you should choose the parameters for the
macro that provide the shortest search time. The search of a library actually
involves a search of the directory, followed by copying the directory entry into virtual
storage, followed by loading the load module into virtual storage. If you know the
Chapter 4. Program Management

4-19

location of the load module, you should use the parameters that eliminate as many
of these unnecessary searches as possible, as indicated in Figure 4-12,
Figure 4-13, and Figure 4-14. Examples of the use of these figures are shown in the
following discussion of passing control.

Using an Existing Copy

The control program uses a copy of the load module already in the requesting
tasks load list or the job pack area if the copy can be used. Whether the copy can
be used or not depends on the reusability and current status of the load module,
that is, the load module attributes, as designated using linkage editor control
statements, and whether the load module has already been used or is in use. The
status information is available to the control program only when you specify the load
module entry name on an EXEC statement, or when you use ATTACH, ATTACHX,
LINK, LINKX, XCTL, or XCTLX macros to transfer control to the load module. The
control program protects you from obtaining an unusable copy of a load module if
you always formally request a copy using these macros (or the EXEC statement).
If you pass control in any other manner (for instance, a branch or a CALL macro),
the control program, because it is not informed, cannot protect your copy. If your
program is in AR mode, and the SYSSTATE ASCENV=AR macro has been issued,
use the ATTACHX, LINKX, and XCTLX macros instead of ATTACH, LINK, and
XCTL. The macros whose names end with X generate code and addresses that
are appropriate for AR mode.
All reenterable modules (modules designated as reenterable using the linkage
editor) from any library are completely reusable. Only one copy is ever placed in the
link pack area or brought into your job pack area, and you get immediate control of
the load module. If the module is serially reusable, only one copy is ever placed in
the job pack area; this copy is always used for a LOAD macro. If the copy is in use,
however, and the request is made using a LINK, LINKX, ATTACH, ATTACHX,
XCTL, or XCTLX macro, the task requiring the load module is placed in a wait
condition until the copy is available. You should not issue a LINK or LINKX macro
for a serially reusable load module currently in use for the same task; the task will
be abnormally terminated. (This could occur if an exit routine issued a LINK or
LINKX macro for a load module in use by the main program.)
If the load module is not reusable, a LOAD macro will always bring in a new copy
of the load module; an existing copy is used only if you issued a LINK, LINKX,
ATTACH, ATTACHX XCTL or XCTLX macro and the copy has not been used
previously. Remember, the control program can determine if a load module has
been used or is in use only if all of your requests are made using LINK, LINKX,
ATTACH, ATTACHX, XCTL or XCTLX macros.

Using the LOAD Macro

|
|
|
|
|
|

If a copy of the specified load module is not already in the link pack area, use the
LOAD macro to place a copy in the address space. When you issue a LOAD
macro, the control program searches for the load module as discussed previously
and brings a copy of the load module into the address space if required. Normally,
you should use the LOAD macro only for a reenterable or serially reusable load
module, because the load module is retained even though it is not in use.

|
|
|
|
|

The control program places the copy of the load module in subpool 244 or subpool
251, unless the following three conditions are true:
v The module is reentrant
v The library is authorized
v You are not running under TSO/E test

4-20

z/OS V1R4.0 MVS Assembler Services Guide

|
|
|
|
|

In this case, the control program places the module in subpool 252. When choosing
between subpools 244 and 251. the control program uses:
v subpool 244 only when within a task that was created by ATTACHX with the
KEY=NINE parameter
v subpool 251 in all other cases.

|
|
|

Subpool 244 is not fetch protected and has a storage key equal to your PSW key.
Subpool 251 is fetch protected and has a storage key equal to your PSW key.
Subpool 252 is not fetch protected and has storage key 0.
The use count for the copy is lowered by one when you issue a DELETE macro
during the task which was active when the LOAD macro was issued. When a task
is terminated, the count is lowered by the number of LOAD macros issued for the
copy when the task was active minus the number of deletions. When the use count
for a copy in a job pack area reaches zero, the virtual storage area containing the
copy is made available.

Passing Control with Return

Use the LINK or LINKX macro to pass control between load modules and to provide
for return of control. You can also pass control using branch, branch and link,
branch and save, or branch and save and set mode instructions or the CALL
macro. However, when you pass control in this manner, you must protect against
multiple uses of non-reusable or serially reusable modules. You must also be
careful to enter the routine in the proper addressing mode. The following
paragraphs discuss the requirements for passing control with return in each case.

Using the LINK or LINKX Macro

When you use the LINK or LINKX macro, you are requesting the system to assist
you in passing control to another load module. There is some similarity between
passing control using a LINK or LINKX macro and passing control using a CALL
macro in a simple structure. These similarities are discussed first.
The convention regarding registers 2-12 still applies; the control program does not
change the contents of these registers, and the called load module should restore
them before control is returned. Unless you are an AR mode program calling an AR
mode program that uses the linkage stack, you must provide the address in register
13 of the save area for use by the called load module; the system does not use this
save area. You can pass address parameters in a parameter list to the load module
using register 1. The LINK or LINKX macro provides the same facility for
constructing this list as the CALL macro. Register 0 is used by the control program
and the contents may be modified. In certain cases, the contents of register 1 may
be altered by the LINK or LINKX macro.
There is also some difference between passing control using a LINK or LINKX
macro and passing control using a CALL macro. When you pass control in a simple
structure, register 15 contains the entry address and register 14 contains the return
address. When the called load module gets control, that is still what registers 14
and 15 contain, but when you use the LINK or LINKX macro, it is the control
program that establishes these addresses. When you code the LINK or LINKX
macro, you provide the entry name and possibly some library information using the
EP, EPLOC, or DE, and DCB parameters, but you have to get this entry name and
library information to the control program. The expansion of the LINK or LINKX
macro does this by creating a control program parameter list (the information
required by the control program) and passing its address to the control program.
After the control program finds the entry name, it places the address in register 15.

Chapter 4. Program Management

4-21

The return address in your control section is always the instruction following the
LINK or LINKX; that is not, however, the address that the called load module
receives in register 14. The control program saves the address of the location in
your program in its own save area, and places in register 14 the address of a
routine within the control program that will receive control. Because control was
passed using the control program, return must also be made using the control
program. The control program also handles all switching of addressing mode when
processing the LINK or LINKX macro.
Note: A program that is LINKed to will get control with the callers Floating Point
Registers and Floating Point Control register. The S/390 linkage convention
applies. For more information, see Chapter 2, Linkage Conventions.
The control program establishes a use count for a load module when control is
passed using the LINK or LINKX macro. This is a separate use count from the
count established for LOAD macros, but it is used in the same manner. The count
is increased by one when a LINK or LINKX macro is issued and decreased by one
when return is made to the control program or when the called load module issues
an XCTL or XCTLX macro.
Figure 4-15 and Figure 4-16 show the coding of a LINK or LINKX macro used to
pass control to an entry point in a load module. In Figure 4-15, the load module is
from the link, job, or step library; in Figure 4-16, the module is from a private library.
Except for the method used to pass control, this example is similar to Figures 10
and 11. A problem program parameter list containing the addresses INDCB,
OUTDCB, and AREA is passed to the called load module; the return point is the
instruction following the LINK or LINKX macro. A V-type address constant is not
generated, because the load module containing the entry point NEXT is not to be
edited into the calling load module. Note that the EP parameter is chosen, since the
search begins with the job pack area and the appropriate library as shown in
Figure 4-12.

RETURNPT
AREA

LINK
...
DC

EP=NEXT,PARAM=(INDCB,OUTDCB,AREA),VL=1
12F0

Figure 4-15. Use of the LINK Macro with the Job or Link Library

PVTLIB

OPEN
.
.
LINK
.
.
DCB

(PVTLIB)
EP=NEXT,DCB=PVTLIB,PARAM=(INDCB,OUTDCB,AREA),VL=1
DDNAME=PVTLIBDD,DSORG=PO,MACRF=(R)

Figure 4-16. Use of the LINK Macro with a Private Library

Figure 4-17 and Figure 4-18 show the use of the BLDL and LINK macros to pass
control. Assuming that control is to be passed to an entry point in a load module
from the link library, a BLDL macro is issued to bring the directory entry for the
member into virtual storage. (Remember, however, that time is saved only if more
than one directory entry is requested in a BLDL macro. Only one is requested here
for simplicity.)

4-22

z/OS V1R4.0 MVS Assembler Services Guide

LISTADDR
NAMEADDR

BLDL
.
.
DS
DC
DC
DC
DS

0,LISTADDR
0H
H01
H60
CL8NEXT
26H

List description field:

Number of list entries
Length of each entry
Member name
Area required for directory information

Figure 4-17. Use of the BLDL Macro

The first parameter of the BLDL macro is a zero, which indicates that the directory
entry is on the link, job, step, or task library. The second parameter is the address
in virtual storage of the list description field for the directory entry. The second two
bytes at LISTADDR indicate the length of each entry. A character constant is
established to contain the directory information to be placed there by the control
program as a result of the BLDL macro. The LINK macro in Figure 4-18 can now be
written. Note that the DE parameter refers to the name field, not the list description
field, of the directory entry.
LINK

DE=NAMEADDR,DCB=0,PARAM=(INDCB,OUTDCB,AREA),VL=1

Figure 4-18. The LINK Macro with a DE Parameter

Using CALL, BALR, BASR, or BASSM

When a module is reenterable, you can save time by passing control to a load
module without using the control program. Pass control without using the control
program as follows.
v Issue a LOAD macro to obtain a copy of the load module, preceded by a BLDL
macro if you can shorten the search time by using it.
The control program returns the address of the entry point and the addressing
mode in register 0 and the length in doublewords in register 1.
v Load this address into register 15.
The linkage requirements are the same when passing control between load
modules as when passing control between control sections in the same load
module: register 13 must contain a save area address, register 14 must contain
the return address, and register 1 is used to pass parameters in a parameter list.
A branch instruction, a branch and link instruction (BALR), a branch and save
instruction (BASR), a branch and save and set mode instruction (BASSM), or a
CALL macro can be used to pass control, using register 15. Use BASSM (or the
CALL macro with the LINKINST=BASSM parameter specified) only if there is to
be an addressing mode switch. The return will be made directly to your program.
Notes:
1. You must use a branch and save and set mode instruction (or the CALL macro
with the LINKINST=BASSM parameter specified) if passing control to a module
in a different addressing mode.
2. When control is passed to a load module without using the control program, you
must check the load module attributes and current status of the copy yourself,
and you must check the status in all succeeding uses of that load module
during the job step, even when the control program is used to pass control.
The reason you have to keep track of the usability of the load module has been
discussed previously; you are not allowing the control program to determine
whether you can use a particular copy of the load module. The following
paragraphs discuss your responsibilities when using load modules with various
Chapter 4. Program Management

4-23

attributes. You must always know what the reusability attribute of the load module
is. If you do not know, you should not attempt to pass control yourself.
If the load module is reenterable, one copy of the load module is all that is ever
required for a job step. You do not have to determine the status of the copy; it can
always be used. You can pass control by using a CALL macro, a branch, a branch
and link instruction, a branch and save instruction, or a branch and save and set
mode instruction (BASSM). Use BASSM (or the CALL macro with the
LINKINST=BASSM parameter specified) only if there is to be an addressing mode
switch.
If the load module is serially reusable, one use of the copy must be completed
before the next use begins. If your job step consists of only one task, make sure
that the logic of your program does not require a second use of the same load
module before completion of the first use. This prevents simultaneous use of the
same copy. An exit routine must not require the use of a serially reusable load
module also required in the main program.
Preventing simultaneous use of the same copy when you have more than one task
in the job step requires more effort on your part. You must still be sure that the logic
of the program for each task does not require a second use of the same load
module before completion of the first use. You must also be sure that no more than
one task requires the use of the same copy of the load module at one time. You
can use the ENQ macro for this purpose. Properly used, the ENQ macro prevents
the use of a serially reusable resource, in this case a load module, by more than
one task at a time. For information on the ENQ macro, see Chapter 6, Resource
Control on page 6-1 You can also use a conditional ENQ macro to check for
simultaneous use of a serially reusable resource within one task.
If the load module is non-reusable, each copy can only be used once; you must be
sure that you use a new copy each time you require the load module. You can
ensure that you always get a new copy by using a LINK macro or by doing the
following:
1. Issue a LOAD macro before you pass control.
2. Pass control using a branch, branch and link, branch and save, branch and
save and set mode instruction, or a CALL macro.
3. Issue a DELETE macro as soon as you are through with the copy.

How Control is Returned

The return of control between load modules is the same as return of control
between two control sections in the same load module. The program in the load
module returning control is responsible for restoring registers 2-14, possibly loading
a return code in register 15, passing control using the address in register 14 and
possibly setting the correct addressing mode. The program in the load module to
which control is returned can expect registers 2-13 to be unchanged, register 14 to
contain the return address, and optionally, register 15 to contain a return code.
Control can be returned using a branch instruction, a branch and set mode
instruction or the RETURN macro. If control was passed without using the control
program, control returns directly to the calling program. However, if control was
originally passed using the control program, control returns first to the control
program, then to the calling program.

Passing Control without Return

Use the XCTL or XCTLX macro to pass control to a target load module when return
of control is not required. You can also pass control using a branch instruction.

4-24

z/OS V1R4.0 MVS Assembler Services Guide

However, when you pass control in this manner, you must ensure that multiple uses
of non-reusable or serially reusable modules does not occur. The following
paragraphs discuss the requirements for passing control without return in each
case.

Passing Control Using a Branch Instruction

The same requirements and procedures for protecting against reuse of a
non-reusable copy of a load module apply when passing control without return as
were stated under Passing Control With Return. The procedures for passing
control are as follows.
Issue a LOAD macro to obtain a copy of the load module. The entry address and
addressing mode returned in register 0 are loaded into register 15. The linkage
requirements are the same when passing control between load modules as when
passing control between control sections in the same load module; register 13 must
be reloaded with the old save area address, then registers 14 and 2-12 restored
from that old save area. Register 1 is used to pass parameters in a parameter list.
If the addressing mode does not change, a branch instruction is issued to pass
control to the address in register 15; if the addressing mode does change, a branch
and save and set mode macro is used.
Note: Mixing branch instructions and XCTL or XCTLX macros is hazardous. The
next topic explains why.

Using the XCTL or XCTLX Macro

The XCTL or XCTLX macro, in addition to being used to pass control, is used to
indicate to the control program that this use of the load module containing the XCTL
or XCTLX macro is completed. Because control will not be returned, the XCTL
issuer must load the address of the old save area into register 13 prior to issuing
the XCTL. The return address must be loaded into register 14 from the old save
area, as must the contents of registers 2-12. The XCTL or XCTLX macro can be
written to request the loading of registers 2-12, or you can do it yourself. If you
restore all registers yourself, do not use the EP parameter. This creates an inline
parameter list that can only be addressed using your base register, and your base
register is no longer valid. If EP is used, you must have XCTL or XCTLX restore the
base register for you.
Note: A program that is XCTLed to will get control with the callers Floating Point
Registers and Floating Point Control register. The program that issued the
XCTL macro is not returned to, instead the XCTLed program will return to
the program that caused the issuer of the XCTL macro to run. The S/390
linkage convention applies except that the non-volatile FPRs and FPC
register that must be restored are different. The issuer of the XCTL macro
must restore its callers non-volatile FPRs and FPC register before issuing
the XCTL (just as if it were returning to its caller). For more information on
linkage conventions, please refer to Chapter 2, Linkage Conventions.
When using the XCTL or XCTLX macro, pass parameters to the target module in a
parameter list. In this case, however, the parameter list (or the parameter data)
must be established in remote storage, a portion of virtual storage outside the
current load module containing the XCTL or XCTLX macro. This is because the
copy of the current load module may be deleted before the called load module can
use the parameters, as explained in more detail below.
The XCTL or XCTLX macro is similar to the LINK macro in the method used to
pass control: control is passed by the control program using a control parameter
Chapter 4. Program Management

4-25

list. The control program loads a copy of the target load module, if necessary, loads
the entry address in register 15, saves the address passed in register 14, and
passes control to the address in register 15. The control program adds one to the
use count for the copy of the target load module and subtracts one from the use
count for the current load module. The current load module in this case is the load
module last given control using the control program in the performance of the active
task. If you have been passing control between load modules without using the
control program, chances are the use count will be lowered for the wrong load
module copy. And remember, when the use count of a copy reaches zero, that copy
may be deleted, causing unpredictable results if you try to return control to it.
Figure 4-19 shows how this could happen. Control is given to load module A, which
passes control to the load module B (step 1) using a LOAD macro and a branch
and link instruction. Register 14 at this time contains the address of the instruction
following the branch and link. Load module B then executes, independently of how
control was passed, and issues an XCTL or XCTLX macro when it is finished (step
2) to pass control to target load module C. The control program knowing only of
load module A, lowers the use count of A by one, resulting in its deletion. Load
module C is executed and returns to the address which used to follow the branch
and link instruction. Step 3 of Figure 4-19 indicates the result.

4-26

z/OS V1R4.0 MVS Assembler Services Guide

Control Program

A
Step 1

B
LOAD B
BALR B

Control
Program

Control
Program
A

BALR

Step 2

XCTL C

Control
Program
B

C
Step 3

XCTL C

RETURN

To routine which
last issued a BALR
instruction.

Figure 4-19. Misusing Control Program Facilities Causes Unpredictable Results

Two methods are available for ensuring that the proper use count is lowered. One
way is to always use the control program to pass control with or without return. The
other method is to use only LOAD and DELETE macros to determine whether or
not a copy of a load module should remain in virtual storage.
Note: The control program abnormally terminates the task if the XCTL issuer
added entries to the linkage stack and did not remove them before issuing
the XCTL.

APF-authorized Programs and Libraries

The authorized program facility (APF) helps your installation protect the system.
APF-authorized programs can access system functions that can affect the security
and integrity of the system. APF-authorized programs must reside in
APF-authorized libraries, which are defined in an APF list.
Unauthorized programs can issue the CSVAPF macro to:
v Determine whether or not a library is in the APF list
Chapter 4. Program Management

4-27

v Determine the current format (dynamic or static) of the APF list

v Obtain a list of all library entries in the APF list.
APF also prevents authorized programs (supervisor state, APF-authorized, PSW
key 0-7, or PKM 0-7) from accessing a load module that is not in an
APF-authorized library. The application development books for programmers who
use authorized programs provide more information about APF authorization.

Additional Entry Points

Through the use of linkage editor facilities you can specify as many as 17 different
names (a member name and 16 aliases) and associated entry points within a load
module. Take note that all names are expected to be unique across all possible
libraries where a module may be retrieved from; and all aliases are expected to
have the related primary module name in the same library. It is only through the use
of the member name or the aliases that a copy of the load module can be brought
into virtual storage. Once a copy has been brought into virtual storage, however,
additional entry points can be provided for the load module, subject to one
restriction. The load module copy to which the entry point is to be added must be
one of the following:
v A copy that satisfied the requirements of a LOAD macro issued during the same
task
v The copy of the load module most recently given control through the control
program in performance of the same task.
Add the entry point by using the IDENTIFY macro. The IDENTIFY macro cannot be
issued by supervisor call routines, SRBs, or asynchronous exit routines established
using other supervisor macros.
When you use the IDENTIFY macro, you specify the name to be used to identify
the entry point, and the virtual storage address of the entry point in the copy of the
load module. The address must be within a copy of a load module that meets the
requirements listed above; if it is not, the entry point will not be added, and you will
be given a return code of 0C (hexadecimal). The name can be any valid symbol of
up to eight characters, and does not have to correspond to a name or symbol within
the load module. You are responsible for not duplicating a member name or an
alias in any of the libraries. Duplicate names cause the system to return a return
code of 8.
The IDENTIFY service sets the addressing mode of the alias entry point equal to
the addressing mode of the major entry point.
If an authorized program creates an alias for a module in the pageable link pack
area or active link pack area, the IDENTIFY service places an entry for the alias on
the active link pack area queue. If an unauthorized user creates an alias for a
module in the pageable link pack area or active link pack area, the IDENTIFY
service places an entry for the alias on the job pack queue of the requesting job.

Entry Point and Calling Sequence Identifiers as Debugging Aids

An entry point identifier is a character string of up to 70 characters that can be
specified in a SAVE macro. The character string is created as part of the SAVE
macro expansion.

4-28

z/OS V1R4.0 MVS Assembler Services Guide

A calling sequence identifier is a 16-bit binary number that can be specified in a

CALL, LINK, or LINKX macro. When coded in a CALL, LINK, or LINKX macro, the
calling sequence identifier is located in the two low-order bytes of the fullword at the
return address. The high-order two bytes of the fullword form a NOP instruction.

Retrieving Information About Loaded Modules

Both the CSVINFO and CSVQUERY macros return information about loaded
modules. A loaded module is a load module that has been loaded into storage.
Use CSVQUERY if you need information about a particular loaded module or if your
program is running in access register (AR) mode. Use CSVINFO to obtain
information about a group of loaded modules or when you want information about
the loaded module associated with a particular program request block (PRB) or
information that the CSVQUERY macro does not provide.
The following information is available only through the CSVINFO macro:
v Whether the entry point is an alias created using the IDENTIFY macro.
v The starting address of every extent and the number of extents for loaded
modules with multiple extents. (CSVQUERY provides only the entry point
address and the total module length.)
v The load count, system count, and total use count for the loaded module.
v The name of the major entry point, if the entry point is an alias.
v The full entry point name for modules with names longer than 8 characters.
In addition to the information you request, the CSVINFO macro returns the file
name for modules in the OpenMVS file system.

Using the CSVINFO Macro

The CSVINFO macro provides information about loaded modules associated with a
job step or a task. You can invoke CSVINFO from a program or an IPCS exit.
Note: IBM recommends that you use the CSVINFO macro rather than write your
own program to scan control blocks for information about loaded modules.
Using the CSVINFO macro enables you to retrieve module information
without depending on the details or structures of data areas.
The CSVINFO service requires a user-written module information processing
routine (MIPR). The CSVINFO service obtains information about loaded modules
and uses the CSVMODI data area to pass that information to the MIPR. The MIPR
examines this data and returns control to CSVINFO, either requesting information
about an additional loaded module or indicating that no more information is needed.
This loop continues until the CSVINFO service has returned to the MIPR all
requested information or all available information.
For example, if you request information about all loaded modules in your job pack
area (JPA), the CSVINFO service uses the CSVMODI data area to pass information
about the first loaded module to the MIPR. The MIPR processes the information
and returns control to CSVINFO to obtain information about the next loaded module
in the JPA. Processing continues until CSVINFO indicates that all information has
been obtained or until the MIPR determines that no more information is required.
When you issue the CSVINFO macro, use the FUNC parameter to specify the
information you want, and the ENV parameter to specify whether CSVINFO is being
issued from a program or from an IPCS exit. Use the MIPR parameter to pass the
Chapter 4. Program Management

4-29

address of your MIPR. You can pass 16 bytes of information to the MIPR using the
USERDATA parameter. Information could include register contents, parameter list
addresses, or other information your MIPR requires. CSVINFO places your user
data into the CSVMODI data area.

References
The CSVMODI data area serves as the interface between the CSVINFO
service and the MIPR. For more information about the CSVMODI mapping
macro, see z/OS MVS Data Areas, Vol 1 (ABEP-DALT).

z/OS MVS IPCS Commands explains how to verify the correct use of the
CSVINFO macro in an IPCS exit. See the TRAPON, TRAPOFF, and
TRAPLIST subcommand descriptions.
z/OS MVS IPCS Customization provides information about writing IPCS exits.
Figure 4-20 on page 4-31 shows the processing that occurs when your program or
exit issues the CSVINFO macro. The numbered steps are explained below:
1. The application or IPCS exit invokes the CSVINFO macro.
2. CSVINFO retrieves the module information you want.
3. CSVINFO places the information into the CSVMODI data area.
4. CSVINFO passes control to your MIPR.
5. The MIPR reads the information that is in the CSVMODI data area.
6. The MIPR places the information into your storage or otherwise processes the
information.
7. The MIPR sets a return code for CSVINFO:
v A return code of zero to request information about another loaded module
v A nonzero return code to indicate that no more information is needed.
8. The MIPR returns control to CSVINFO.
9. Steps 2 through 8 are repeated until the MIPR indicates to CSVINFO that no
more information is needed, or CSVINFO indicates to the MIPR that all
information has been retrieved.
10. CSVINFO sets a return code and returns control to your program when the
MIPR passes CSVINFO a return code indicating that no more information is
needed, or when CSVINFO has passed all the information to the MIPR.
11. The application or IPCS exit continues processing.

4-30

z/OS V1R4.0 MVS Assembler Services Guide

Application or
IPCS Exit Code
Some processing
CSVINFO
1. Call CSVINFO

2. Retrieve requested
information
3. Place information
into CSVMODI
data area
4. Pass control to the
MIPR

MIPR

5. Obtain information
from CSVMODI
data area
6. Process the
information from
CSVMODI

9. Repeat steps 2
through 8 until the
MIPR indicates no
more information
is needed or all
information has
been passed to
the MIPR.
11. Check the
return code
and continue
processing

7. Set return code

8. Return control to
CSVINFO

10. Return control

to the caller.

Figure 4-20. Processing Flow for the CSVINFO Macro and the Callers MIPR

Serialization
Information about loaded modules in common storage is serialized by the LOCAL
and CMS locks. Information about other loaded modules is serialized by the LOCAL
lock. When the CSVINFO service runs with serialization, you are guaranteed that
the information CSVINFO obtains is not in the process of being updated.
If your program runs in problem state and invokes the CSVINFO macro, your
program cannot hold the appropriate locks and the CSVINFO service does not
obtain them. Thus, the CSVINFO service retrieves information without serializing on
it. If you are requesting information about loaded modules in common storage or if
multi-tasking is taking place in your address space, the module information you
request might be changing while the CSVINFO service is retrieving information. In
rare instances, the CSVINFO service could return incorrect information or end
abnormally.
If your program runs in supervisor state and invokes the CSVINFO macro, the
CSVINFO service obtains the appropriate locks if your program does not already
hold them.

Coding a MIPR for the CSVINFO Macro

This section contains information about coding a MIPR.

Chapter 4. Program Management

4-31

Installing the MIPR

You can either link-edit your MIPR with the program that invokes the CSVINFO
macro or include the MIPR in mainline code.

MIPR Environment
The MIPR receives control running under the unit of work that invoked the
CSVINFO macro, in the following environment:
Minimum authorization:
Dispatchable unit mode:
Cross memory mode:
AMODE:
ASC mode:
Interrupt status:
Control parameters:

Problem state and any PSW key.

Task or SRB
PASN=SASN=HASN
31-bit
Primary
Enabled for I/O and external interrupts
Control parameters must be in the primary address space.

Recovery for MIPR Provided by CSVINFO

Table 4-2 shows the recovery environment that the CSVINFO service establishes
for itself and the MIPR.
Table 4-2. CSVINFO Recovery
ENV Keyword

Caller State/Key

Recovery Provided

ENV=MVS

Supervisor state

The callers MIPR gets control with

CSVINFOs FRR in effect.

Problem state

The callers MIPR gets control with

CSVINFOs ESTAE routine in effect.

ENV=IPCS

Problem or supervisor No recovery provided

state

Entry Specifications
The MIPR gets control through standard branch entry linkage. Input to the MIPR is
the address of the CSVMODI data area, containing information from the CSVINFO
service.

Registers at Entry
When the MIPR receives control, the general purpose registers (GPRs) contain the
following information:
GPR

Contents

Does not contain any information for use by the routine

Address of the CSVMODI data area

2 - 12

Does not contain any information for use by the routine

13

Address of a standard 72-byte save area

14

Return address to the CSVINFO service

15

Entry point address of MIPR

Return Specifications
Upon return from MIPR processing, you must ensure that the register contents are
as follows:

Registers at Exit
GPR

4-32

Contents

z/OS V1R4.0 MVS Assembler Services Guide

0-1

The MIPR does not have to place any information into these
registers, and does not have to restore their contents to what they
were when the MIPR received control.

2-13

The MIPR must restore the register contents to what they were
when the MIPR received control.

14

Return address to the CSVINFO service

15

Return code from the MIPR

Note: The CSVINFO service continues processing until either of the following
occurs:
v It receives a non-zero return code from the MIPR.
v It has returned all available data
When CSVINFO receives a non-zero return code, it returns control to the program
that invoked the CSVINFO macro.

CSVINFO Service Coding Example

The CSVSMIPR member of SAMPLIB contains a coded example of the use of the
CSVINFO service and its associated MIPR. The sample program is a reentrant
program that has its MIPR included within the same module.

Using CSVRTLS to Request Run-Time Library Services (RTLS)

Run-time library services (RTLS) enables you to eliminate STEPLIBs from the JCL
that runs your applications. By eliminating STEPLIBs, you reduce the installation
management your applications require, as well as the system overhead involved in
searching STEPLIB data sets when loading modules into storage. In place of
STEPLIBs, the CSVRTLS macro connects to and loads from a given RTLS logical
library.
Both authorized and unauthorized programs can use CSVRTLS, but only authorized
programs can use the TCBADDR parameter or connect to more than 32 libraries
per address space. See the minimum authorization requirements listed in z/OS
MVS Programming: Assembler Services Reference ABE-HSP for options available
to authorized programs.
Language Environment applications currently can exploit RTLS by using the
Language Environment run-time options RTLS(ON), LIBRARY(le_run-time_lib), and
VERSION(version), which identify the RTLS logical library to be connected. During
application startup, the Language Environment element connects to the specified
library using the macro CSVRTLS REQUEST=CONNECT, loads from the specified
library using CSVRTLS REQUEST=LOAD, and disconnects from the logical library
using CSVRTLS REQUEST=DISCONNECT. Language Environment runs as an
extension to the application, allowing it to load from any library the application is
authorized to access.
An operator command, SET RTLS=xx, allows dynamic configuration of the RTLS
library definitions. Each of these library definitions, or logical libraries, identifies a
load library search order that is to be used when an application connects to and
loads from a specific logical library. Each logical library search order definition
contains one or more physical library definitions that can consist of one or more
load library data sets. Caching to common storage is performed on a physical
library basis to provide optimal performance for commonly used libraries. Each

Chapter 4. Program Management

4-33

physical library is either authorized or unauthorized. This determination is made

when the library is added or replaced; it is not changed or affected by changes to
the APF status of individual data sets.
The SET RTLS=xx command, like the RTLS system parameter at IPL, uses the
CSVRTLxx parmlib members. The SET command allows for the introduction of new
physical and logical libraries, removal of physical and logical libraries, or the
replacement of libraries. The DISPLAY RTLS command displays the current status
of the RTLS environment. The information supplied through DISPLAY RTLS
optionally includes the physical and logical libraries in use, the users of the logical
libraries, and the cache utilization for a given library or for all libraries.
The contents supervision services XCTL, LINK, ATTACH, IDENTIFY, CSVQUERY,
and CSVINFO all work with modules loaded through the CSVRTLS
REQUEST=LOAD service.
For more information about the CSVRTLS macro, see z/OS MVS Programming:
Assembler Services Reference ABE-HSP.

4-34

z/OS V1R4.0 MVS Assembler Services Guide

Chapter 5. Understanding 31-Bit Addressing

Note
This chapter documents the programming considerations for running 31-bit
addressing mode programs on previous versions and releases of MVS.
Because this information might be useful for programmers who maintain or
update legacy programs, the chapter is preserved to reflect the programming
environment of previous MVS versions. If you intend to design and code a
new program to run on OS/390 MVS releases, consider the following:
v Always design a program to run in 31-bit addressing mode, to take full
advantage of the virtual storage capacity of MVS.
v Use the IBM High Level Assembler, instead of Assembler H, to assemble
the new program. As of MVS/SP 5.2, Assembler H is not supported.
v Use the DFSMS/MVS program management binder, instead of the
MVS/DFP linkage editor and loader, to prepare the program for execution.

Enterprise Systems Architecture, like 370/Extended Architecture, supports 31-bit

real and virtual addresses, which provide a maximum real and virtual address of
two gigabytes minus one. For compatibility with existing programs, MVS/ESA and
MVS/XA also support 24-bit real and virtual addresses. The basic changes in the
system that provide for both 31-bit addresses and the continued use of 24-bit
addresses are:
v A virtual storage map of two gigabytes with MVS services to support programs
executing or residing anywhere in virtual storage.
v Two program attributes that specify expected address length on entry and
intended location in virtual storage.
v Bimodal operation, a capability of the processor that permits the execution of
programs with 24-bit addresses as well as programs with 31-bit addresses.
v Instructions that are sensitive to addressing mode.

Virtual Storage
In the MVS virtual storage map:
v Each address space has its own two gigabytes of virtual storage.
v Each private area has a portion below 16 megabytes and an extended portion
above 16 megabytes but, logically, these areas can be thought of as one area.
Figure 5-1 shows the virtual storage map.

Addressing Mode and Residency Mode

In MVS/ESA and MVS/XA, the processor can treat addresses as having either 24 or
31 bits. Addressing mode (AMODE) describes whether the processor is using 24-bit
or 31-bit addresses. In MVS/ESA and MVS/XA, programs can reside in 24-bit
addressable areas or beyond the 24-bit addressable area (above 16 megabytes).
Residency mode (RMODE) specifies whether the program must reside in the 24-bit
addressable area or can reside anywhere in 31-bit addressable storage.
Addressing mode (AMODE) and residency mode (RMODE) are program
attributes specified (or defaulted) for each CSECT, load module, and load module

Copyright IBM Corp. 1988, 2002

5-1

alias. These attributes are the programmers specification of the addressing mode in
which the program is expected to get control and where the program is expected to
reside in virtual storage.
AMODE defines the addressing mode (24, 31, or ANY) in which a program expects
to receive control. Addressing mode refers to the address length that a program is
prepared to handle on entry: 24-bit addresses, 31-bit addresses, or both (ANY).
Programs with an addressing mode of ANY have been designed to receive control
in either 24- or 31-bit addressing mode.

2 gigabytes
ELSQA/ESWA 229/230

Extended
Private

ECSA
Extended

EPLPA/EFLPA/EMLPA

Common

ESQA
Extended Nucleus

31-Bit
Addressing
Range

Nucleus
SQA
Common

PLPA/FLPA/MLPA/BLDL
CSA
LSQA/SWA/229/230

24-Bit
Addressing
Range

Private

Common

PSA
0

Figure 5-1. Two Gigabyte Virtual Storage Map

A 370-XA or 370-ESA processor can operate with either 24-bit addresses (16
megabytes of addressability) or 31-bit addresses (2 gigabytes of addressability).
This ability of the processor to permit the execution of programs in 24-bit
addressing mode as well as programs in 31-bit addressing mode is called bimodal
operation. A programs AMODE attribute determines whether the program is to
receive control with 24-bit or 31-bit addresses. Once a program gets control, the
program can change the AMODE if necessary.
In 24-bit addressing mode, the processor treats all virtual addresses as 24-bit
values. This makes it impossible for a program in 24-bit addressing mode to
address virtual storage with an address greater than 16,777,215 (16 megabytes)
because that is the largest number that a 24-bit binary field can contain.

5-2

z/OS V1R4.0 MVS Assembler Services Guide

In 31-bit addressing mode, the processor treats all virtual addresses as 31-bit
values.
The processor supports bimodal operation so that both new programs and most old
programs can execute correctly. Bimodal operation is necessary because certain
coding practices in existing programs depend on 24-bit addresses. For example:
v Some programs use a 4-byte field for a 24-bit address and place flags in the
high-order byte.
v Some programs use the LA instruction to clear the high-order byte of a register.
(In 24-bit addressing mode, LA clears the high-order byte; in 31-bit addressing
mode, it clears only the high-order bit.)
v Some programs depend on BAL and BALR to return the ILC (instruction length
code), the CC (condition code), and the program mask. (BAL and BALR return
this information in 24-bit addressing mode. In 31-bit addressing mode they do
not.)
Each load module and each alias entry has an AMODE attribute.
A CSECT can have only one AMODE, which applies to all its entry points. Different
CSECTs in a load module can have different AMODEs.
RMODE specifies where a program is expected to reside in virtual storage. The
RMODE attribute is not related to central storage requirements. (RMODE 24
indicates that a program is coded to reside in virtual storage below 16 megabytes.
RMODE ANY indicates that a program is coded to reside anywhere in virtual
storage.)
Each load module and each alias entry has an RMODE attribute. The alias entry is
assigned the same RMODE as the main entry.
The following kinds of programs must reside in the range of addresses below 16
megabytes (addressable by 24-bit callers):
v Programs that have the AMODE 24 attribute
v Programs that have the AMODE ANY attribute
v Programs that use system services that require their callers to be AMODE 24
v Programs that use system services that require their callers to be RMODE 24
v Programs that must be addressable by 24-bit addressing mode callers
Programs without these characteristics can reside anywhere in virtual storage.
Addressing Mode and Residency Mode on page 5-12 describes AMODE and
RMODE processing and 31-bit addressing support of AMODE and RMODE in
detail.

Requirements for Execution in 31-Bit Addressing Mode

In general, to execute in 31-bit addressing mode a program must:
v Be assembled using Assembler H Version 2 or an assembler that provides
equivalent function, and the MVS/XA or MVS/ESA macro library.
v Be link edited using the linkage editor supplied with Data Facility Product (DFP)
or be loaded using the loader supplied with DFP.
v Execute on an MVS/XA or MVS/ESA system.

Chapter 5. Understanding 31-Bit Addressing

5-3

Rules and Conventions for 31-Bit Addressing

It is important to distinguish the rules from the conventions when describing 31-bit
addressing. There are only two rules, and they are associated with hardware:
1. The length of address fields is controlled by the A-mode bit (bit 32) in the PSW.
When bit 32=1, addresses are treated as 31-bit values. When bit 32=0,
addresses are treated as 24-bit values.
Any data passed from a 31-bit addressing mode program to a 24-bit addressing
mode program must reside in virtual storage below 16 megabytes. (A 24-bit
addressing mode program cannot reference data above 16 megabytes without
changing addressing mode.)
2. The A-mode bit affects the way some instructions work.
The conventions, on the other hand, are more extensive. Programs using system
services must follow these conventions.
v A program must return control in the same addressing mode in which it received
control.
v A program expects 24-bit addresses from 24-bit addressing mode programs and
31-bit addresses from 31-bit addressing mode programs.
v A program should validate the high-order byte of any address passed by a 24-bit
addressing mode program before using it as an address in 31-bit addressing
mode.

Mode Sensitive Instructions

The processor is sensitive to the addressing mode that is in effect (the setting of
the PSW A-mode bit). The current PSW controls instruction sequencing. The
instruction address field in the current PSW contains either a 24-bit address or a
31-bit address depending on the current setting of the PSW A-mode bit. For those
instructions that develop or use addresses, the addressing mode in effect in the
current PSW determines whether the addresses are 24 or 31 bits long.

Principles of Operation contains a complete description of the 370-XA and 370-ESA

instructions. The following topics provide an overview of the mode sensitive
instructions.

BAL and BALR

BAL and BALR are addressing-mode sensitive. In 24-bit addressing mode, BAL and
BALR work the same way as they do when executed on a processor running in 370
mode. BAL and BALR put link information into the high-order byte of the first
operand register and put the return address into the remaining three bytes before
branching.
First operand register (24-bit addressing mode)
ILC

CC

PGM
Mask
4

next sequential instruction address

31

ILC - instruction length code

CC - condition code
PGM Mask - program mask

In 31-bit addressing mode, BAL and BALR put the return address into bits 1
through 31 of the first operand register and save the current addressing mode in
the high-order bit. Because the addressing mode is 31-bit, the high-order bit is

5-4

z/OS V1R4.0 MVS Assembler Services Guide

always a 1.
First operand register (31-bit addressing mode)
1
0

next sequential instruction address

1

31

When executing in 31-bit addressing mode, BAL and BALR do not save the
instruction length code, the condition code, or the program mask. IPM (insert
program mask) can be used to save the program mask and the condition code.

LA: The LA (load address) instruction, when executed in 31-bit addressing mode,
loads a 31-bit value and clears the high-order bit. When executed in 24-bit
addressing mode, it loads a 24-bit value and clears the high-order byte (as in
MVS/370 mode).
LRA: The LRA (load real address) instruction always results in a 31-bit real
address regardless of the issuing programs AMODE. The virtual address specified
is treated as a 24-bit or 31-bit address based on the value of the PSW A-mode bit
at the time the LRA instruction is executed.

Branching Instructions
BASSM (branch and save and set mode) and BSM (branch and set mode) are
branching instructions that manipulate the PSW A-mode bit (bit 32). Programs can
use BASSM when branching to modules that might have different addressing
modes. Programs invoked through a BASSM instruction can use a BSM instruction
to return in the callers addressing mode. BASSM and BSM are described in more
detail in Establishing Linkage on page 5-21.
BAS (branch and save) and BASR:
v Save the return address and the current addressing mode in the first operand.
v Replace the PSW instruction address with the branch address.
The high-order bit of the return address indicates the addressing mode. BAS and
BASR perform the same function that BAL and BALR perform in 31-bit addressing
mode. In 24-bit mode, BAS and BASR put zeroes into the high-order byte of the
return address register.

Use of 31-Bit Addressing

In addition to providing support for the use of 31-bit addresses by user programs,
MVS includes many system services that use 31-bit addresses.
Some system services are independent of the addressing mode of their callers.
These services accept callers in either 24-bit or 31-bit addressing mode and use
31-bit parameter address fields. They assume 24-bit addresses from 24-bit
addressing mode callers and 31-bit addresses from 31-bit addressing mode callers.
Most supervisor macros are in this category.
Other services have restrictions with respect to address parameter values. Some of
these services accept SVC callers and allow them to be in either 24-bit or 31-bit
addressing mode. However, the same services might require branch entry callers to
be in 24-bit addressing mode or might require one or more parameter addresses to
be less than 16 megabytes.

Chapter 5. Understanding 31-Bit Addressing

5-5

Some services do not support 31-bit addressing at all. To determine a services

addressing mode requirements, see the documentation that explains how to invoke
the service. (VSAM accepts entry by a program that executes in either 24-bit or
31-bit addressing mode.)
MVS provides instructions that support 31-bit addressing mode and bimodal
operation. These instructions are supported only by Assembler H Version 2 installed
with the ADV or UNIV instruction set specified. The linkage editor functions that
support MVS are provided in Data Facility Storage Management (DFSMSdfp).

Planning for 31-Bit Addressing

Most programs that run on MVS/370 will run on MVS/XA or MVS/ESA in 24-bit
addressing mode without change. Some programs need to be modified to execute
in 31-bit addressing mode to provide the same function. Still other programs need
to be modified to run in 24-bit addressing mode.
The MVS conversion notebook helps you identify programs that need to be
changed. You will need to consult one or more versions of the MVS conversion
notebook. The versions you need depend on your current version of MVS and the
version of MVS to which you are migrating. See the appropriate version of the MVS
conversion notebook for your migration.
Planning for 31-Bit Addressing helps you determine what changes to make to a
module you are converting to 31-bit addressing and indicates 31-bit address
considerations when writing new code.
Some reasons for converting to 31-bit addressing mode are:
v The program can use more virtual storage for tables, arrays, or additional logic.
v The program needs to reference control blocks that have been moved above 16
megabytes.
v The program is invoked by other 31-bit addressing mode programs.
v The program must run in 31-bit addressing mode because it is a user exit routine
that the system invokes in 31-bit mode.
v The program needs to invoke services that expect to get control in 31-bit
addressing mode.

Converting Existing Programs

Keeping in mind that 31-bit addressing mode programs can reside either below or
above 16 megabytes, you can convert existing programs as follows:
1. Converting the program to use 31-bit addresses - a change in addressing
mode only.
v You can change the entire module to use 31-bit addressing.
v You can change only that portion that requires 31-bit addressing mode
execution.
Be sure to consider whether or not the code has any dependencies on 24-bit
addresses. Such code does not produce the same results in 31-bit mode as it
did in 24-bit mode. See Mode Sensitive Instructions on page 5-4 for an
overview of instructions that function differently depending on addressing mode.

5-6

z/OS V1R4.0 MVS Assembler Services Guide

Figure 5-2 summarizes the things that you need to do to maintain the proper
interface with a program that you plan to change to 31-bit addressing mode.
Calling Module

Invoked Module

AMODE 24
RMODE 24

AMODE 24 (intends to switch to AMODE 31)

RMODE 24

Parameters are passed

Requires indicated changes:

CALL or BALR
to another CSECT

Minor recoding at the source

level to switch addressing
modes and to zero bits 1-7 of
the high-order bytes of
addresses used by AMODE 31
module that point to locations
below 16 megabytes.

AMODE 31
RMODE 24

AMODE 24
RMODE 24
LINKX, XCTLX, ATTACHX,
LINK, XCTL, or ATTACH

Minor recoding at the source

level to zero bits 1-7 of the
high-order bytes of addresses
used by AMODE 31 module
that point to locations below
16 megabytes.

Figure 5-2. Maintaining Correct Interfaces to Modules that Change to AMODE 31

2. Moving the program above 16 megabytes - a change in both addressing

mode and residency mode
In general, you move an existing program above 16 megabytes because there is
not enough room for it below 16 megabytes. For example:
v An existing program or application is growing so large that soon it will not fit
below 16 megabytes.
v An existing application that now runs as a series of separate programs, or that
executes in an overlay structure, would be easier to manage as one large
program.
v Code is in the system area, and moving it would provide more room for the
private area below 16 megabytes.
The techniques used to establish proper interfaces to modules that move above 16
megabytes depend on the number of callers and the ways they invoke the module.
Table 5-1 summarizes the techniques for passing control. The programs involved
must ensure that any addresses passed as parameters are treated correctly.
(High-order bytes of addresses to be used by a 31-bit addressing mode program
must be validated or zeroed.)

Chapter 5. Understanding 31-Bit Addressing

5-7

Table 5-1. Establishing Correct Interfaces to Modules That Move Above 16 Megabytes
Means of Entry to Moved Module
(AMODE 31,RMODE ANY)
LOAD macro and BALR

Few AMODE 24,RMODE 24 Callers

Many AMODE 24,RMODE 24 Callers

v Have caller use LINK OR LINKX

Create a linkage assist routine (described

in Establishing Linkage on page 5-21).
Give the linkage assist routine the name of
the moved module.

or
v Have caller use LOAD macro and
BASSM (invoked program returns via
BSM)
or
v Change caller to AMODE 31,RMODE
24 before BALR
BALR using an address in a common
control block

v Have caller switch to AMODE 31 when

invoking

Create a linkage assist routine (described

in Establishing Linkage on page 5-21).

or
v Change the address in the control block
to a pointer-defined value (described in
Establishing Linkage on page 5-21)
and use BASSM. (The moved module
will use BSM to return.)
ATTACH, ATTACHX, LINK, LINKX, XCTL,
or XCTLX

No changes required.

No changes required.

SYNCH or SYNCHX in AMODE 24

v Have caller use SYNCH or SYNCHX

with AMODE=31 parameter

Create a linkage assist routine (described

in Establishing Linkage on page 5-21).

or
v Have caller switch to AMODE 31 before
issuing SYNCH or SYNCHX.
v Change address in the control block to
a pointer-defined value and use SYNCH
or SYNCHX with AMODE=DEFINED.

In deciding whether or not to modify a program to execute in 31-bit addressing

mode either below or above 16 megabytes, there are several considerations:
1. How and by what is the module entered?
2. What system and user services does the module use that do not support 31-bit
callers or parameters?
3. What kinds of coding practices does the module use that do not produce the
same results in 31-bit mode as in 24-bit mode?
4. How are parameters passed? Can they reside above 16 megabytes?
Among the specific practices to check for are:
1. Does the module depend on the instruction length code, condition code, or
program mask placed in the high order byte of the return address register by a
24-bit mode BAL or BALR instruction? One way to determine some of the
dependencies is by checking all uses of the SPM (set program mask)
instruction. SPM might indicate places where BAL or BALR were used to save
the old program mask, which SPM might then have reset. The IPM (insert
program mask) instruction can be used to save the condition code and the
program mask.
2. Does the module use an LA instruction to clear the high-order byte of a
register? This practice will not clear the high-order byte in 31-bit addressing
mode.

5-8

z/OS V1R4.0 MVS Assembler Services Guide

3. Are any address fields that are less than 4 bytes still appropriate? Make sure
that a load instruction does not pick up a 4-byte field containing a 3-byte
address with extraneous data in the high-order byte. Make sure that bits 1-7 are
zero.
4. Does the program use the ICM (insert characters under mask) instruction? The
use of this instruction is sometimes a problem because it can put data into the
high-order byte of a register containing an address, or it can put a 3-byte
address into a register without first zeroing the register. If the register is then
used as a base, index, or branch address register in 31-bit addressing mode, it
might not indicate the proper address.
5. Does the program invoke 24-bit addressing mode programs? If so, shared data
must be below 16 megabytes.
6. Is the program invoked by 24-bit or 31-bit addressing mode programs? Is the
data in an area addressable by the programs that need to use it? (The data
must be below 16 megabytes if used by a 24-bit addressing mode program.)

Writing New Programs That Use 31-Bit Addressing

You can write programs that execute in either 24-bit or 31-bit addressing mode.
However, to maintain an interface with existing programs and with some system
services, your 31-bit addressing mode programs need subroutines or portions of
code that execute in 24-bit addressing mode. If your program resides below 16
megabytes, it can change to 24-bit addressing mode when necessary.
If your program resides above 16 megabytes, it needs a separate load module to
perform the linkage to an unchanged 24-bit addressing mode program or service.
Such load modules are called linkage assist routines and are described in
Establishing Linkage on page 5-21.
When writing new programs, there are some things you can do to simplify the
passing of parameters between programs that might be in different addressing
modes. In addition, there are functions that you should consider and that you might
need to accomplish your programs objectives. Following is a list of suggestions for
coding programs to run on MVS/XA or MVS/ESA:
v Use fullword fields for addresses even if the addresses are only 24 bits in length.
v When obtaining addresses from 3-byte fields in existing areas, use SR (subtract
register) to zero the register followed by ICM (insert characters under mask) in
place of the load instruction to clear the high-order byte. For example:
Rather than:
use:

1,A

SR
ICM

1,1
1,7,A+1

The 7 specifies a 4-bit mask of 0111. The ICM instruction shown inserts bytes
beginning at location A+1 into register 1 under control of the mask. The bytes to
be filled correspond to the 1 bits in the mask. Because the high-order byte in
register 1 corresponds to the 0 bit in the mask, it is not filled.
v If the program needs storage above 16 megabytes, obtain the storage using the
STORAGE macro or the VRU, VRC, RU, and RC forms of GETMAIN and
FREEMAIN, or the corresponding functions on STORAGE. In addition, you can
obtain storage above 16 megabytes by using CPOOL services. These are the
only forms that allow you to obtain and free storage above 16 megabytes. Do not
use storage areas above 16 megabytes for save areas and parameters passed
to other programs.

Chapter 5. Understanding 31-Bit Addressing

5-9

v Do not use the STAE macro; use ESTAE or ESTAEX. STAE has 24-bit
addressing mode dependencies.
v Do not use SPIE; use ESPIE. SPIE has 24-bit addressing mode dependencies.
v Do not use previous paging services macros; use PGSER.
v To make debugging easier, switch addressing modes only when necessary.
v Identify the intended AMODE and RMODE for the program in a prologue.
v 31-bit addressing mode programs should use ESTAE, ESTAEX or the ESTAI
parameter on the ATTACH, or ATTACHX macro rather than STAE or STAI. STAI
has 24-bit addressing mode dependencies. When recovery routines refer to the
SDWA for PSW-related information, they should refer to SDWAEC1 (EC mode
PSW at the time of error) and SDWAEC2 (EC mode PSW of the program
request block (PRB) that established the ESTAE-type recovery.
When writing new programs, you need to decide whether to use 24-bit
addressing mode or 31-bit addressing mode.
The following are examples of kinds of programs that you should write in 24-bit
addressing mode:
Programs that must execute on MVS/370 as well as MVS/XA or MVS/ESA
and do not require any new MVS functions.
Service routines, even those in the common area, that use system services
requiring entry in 24-bit addressing mode or that must accept control directly
from unchanged 24-bit addressing mode programs.
When you use 31-bit addressing mode, you must decide whether the new
program should reside above or below 16 megabytes (unless it is so large that it
will not fit below). Your decision depends on what programs and system services
the new program invokes and what programs invoke it.

New Programs Below 16 Megabytes

The main reason for writing new 31-bit addressing mode programs that reside
below 16 megabytes is to be able to address areas above 16 megabytes or to
invoke 31-bit addressing mode programs while, at the same time, simplifying
communication with existing 24-bit addressing mode programs or system services,
particularly data management. For example, VSAM macros accept callers in 24-bit
or 31-bit addressing mode.
Even though your program resides below 16 megabytes, you must be concerned
about dealing with programs that require entry in 24-bit addressing mode or that
require parameters to be below 16 megabytes. Figure 5-7 in Establishing Linkage
on page 5-21 contains more information about parameter requirements.

New Programs Above 16 Megabytes

When you write new programs that reside above 16 megabytes, your main
concerns are:
v Dealing with programs that require entry in 24-bit addressing mode or that
require parameters to be below 16 megabytes. Note that these are concerns of
any 31-bit addressing mode program no matter where it resides.
v How routines that remain below 16 megabytes invoke the new program.

Writing Programs for MVS/370 and MVS Systems with 31-Bit

Addressing
You can write new programs that will run on both MVS/370 and MVS systems that
use 31-bit addressing. If these programs do not need to use any new MVS
functions, the best way to avoid errors is to assemble the programs on MVS/370

5-10

z/OS V1R4.0 MVS Assembler Services Guide

with macro libraries from a 31-bit addressing system (MVS/XA or MVS/ESA). You
can also assemble these programs on 31-bit addressing systems with macro
libraries from MVS/370, but you must generate MVS/370-compatible macro
expansions by specifying the SPLEVEL macro at the beginning of the programs.
If the program needs to use new MVS functions, your programming task is more
difficult because most MVS/XA functions are not supported on MVS/370. You need
to use dual paths in your program so that on each system your program uses the
services or macros that are supported on that system.
Programs designed to execute on either 24 or 31-bit addressing systems must use
fullword addresses where possible and use no new functions on macros except the
LOC parameter on GETMAIN. These programs must also be aware of downward
incompatible macros and use SPLEVEL as needed.

SPLEVEL Macro
Some macros are downward incompatible. The level of the macro expansion
generated during assembly depends on the value of an assembler language global
SET symbol. When the SET symbol value is 1, the system generates MVS/370
expansions. When the SET symbol value is 2 or greater, the system generates
MVS/XA or MVS/ESA expansions.
The SPLEVEL macro allows programmers to change the value of the SET symbol.
The SPLEVEL macro shipped with OS/390 MVS sets a default value of 5 for the
SET symbol. Therefore, unless a program or installation specifically changes the
default value, the macros generated are MVS/ESA macro expansions.
You can, within a program, issue the SPLEVEL SET=1 macro to obtain MVS/370
(MVS/System Product Version 1 Release 3.0) expansions, or SPLEVEL SET=2 to
obtain MVS/XA expansions, or SPLEVEL=3, 4, or 5 to obtain MVS/ESA expansions.
The SPLEVEL macro sets the SET symbol value for that programs assembly only
and affects only the expansions within the program being assembled. A single
program can include multiple SPLEVEL macros to generate different macro
expansions. The following example shows how to obtain different macro expansions
within the same program by assembling both expansions and making a test at
execution time to determine which expansion to execute.
*

DETERMINE WHICH SYSTEM IS EXECUTING

TM
CVTDCB,CVTMVSE (CVTMVSE is bit 0 in the
BO
SP2
CVTDCB field. If bit 0=1,
it indicates that MVS/XA
is executing.)
* INVOKE THE MVS/370 VERSION OF THE WTOR MACRO
SPLEVEL SET=1
WTOR
.....
B
CONTINUE
SP2
EQU
*
* INVOKE THE MVS/XA VERSION OF THE WTOR MACRO
SPLEVEL SET=2
WTOR
......
CONTINUE EQU
*

z/OS MVS Programming: Assembler Services Guide and z/OS MVS Programming:
Assembler Services Reference IAR-XCT describe the SPLEVEL macro.
Certain macros produce a map of control blocks or parameter lists. These
mapping macros do not support the SPLEVEL macro. Mapping macros for different

Chapter 5. Understanding 31-Bit Addressing

5-11

levels of MVS systems are available only in the macro libraries for each system.
When programs use mapping macros, a different version of the program may be
needed for each system.

Dual Programs
Sometimes two programs may be required, one for each system. In this case, use
one of the following approaches:
v Keep each in a separate library
v Keep both in the same library but under different names

Addressing Mode and Residency Mode

Every program that executes in MVS/XA or MVS/ESA is assigned two program
attributes: an addressing mode (AMODE) and a residency mode (RMODE).
Programmers can specify these attributes for new programs. Programmers can also
specify these attributes for old programs through reassembly, linkage editor PARM
values, linkage editor MODE control statements, or loader PARM values. MVS
assigns default attributes to any program that does not have AMODE and RMODE
specified.

Addressing Mode - AMODE

AMODE is a program attribute that can be specified (or defaulted) for each CSECT,
load module, and load module alias. AMODE states the addressing mode that is
expected to be in effect when the program is entered. AMODE can have one of the
following values:
v AMODE 24 - The program is designed to receive control in 24-bit addressing
mode.
v AMODE 31 - The program is designed to receive control in 31-bit addressing
mode.
v AMODE ANY - The program is designed to receive control in either 24-bit or
31-bit addressing mode.

Residency Mode - RMODE

RMODE is a program attribute that can be specified (or defaulted) for each CSECT,
load module, and load module alias. RMODE states the virtual storage location
(either above 16 megabytes or anywhere in virtual storage) where the program
should reside. RMODE can have the following values:
v RMODE 24 - The program is designed to reside below 16 megabytes in virtual
storage. MVS places the program below 16 megabytes.
v RMODE ANY - The program is designed to reside at any virtual storage location,
either above or below 16 megabytes. MVS places the program above 16
megabytes unless there is no suitable virtual storage above 16 megabytes.

AMODE and RMODE Combinations

Figure 5-3 shows all possible AMODE and RMODE combinations and indicates
which are valid.

AMODE and RMODE Combinations at Execution Time

At
1.
2.
3.

5-12

execution time, there are only three valid AMODE/RMODE combinations:

AMODE 24, RMODE 24, which is the default
AMODE 31, RMODE 24
AMODE 31, RMODE ANY

z/OS V1R4.0 MVS Assembler Services Guide

The ATTACH, ATTACHX, LINK, LINKX, XCTL, and XCTLX macros give the invoked
module control in the AMODE previously specified. However, specifying a particular
AMODE does not guarantee that a module that gets control by other means will
receive control in that AMODE. For example, an AMODE 24 module can issue a
BALR to an AMODE 31, RMODE 24 module. The AMODE 31 module will get
control in 24-bit addressing mode.

RMODE 24

RMODE ANY

AMODE 24

Valid

Invalid

AMODE 31

Valid

Valid

AMODE ANY

Valid

It Depends

1.

This combination is invalid because an AMODE 24 module cannot reside

above 16 megabytes.

2.

This is a valid combination in that the assembler, linkage editor, and loader
accept it from all sources. However, the combination is not used at
execution time. Specifying ANY is a way of deferring a decision about the
actual AMODE until the last possible moment before execution. At
execution time, however, the module must execute in either 24-bit or 31-bit
addressing mode.

3.

The attributes AMODE ANY/RMODE ANY take on a special meaning when

used together. (This meaning might seem to disagree with the meaning of
either taken alone.) A module with the AMODE ANY/RMODE ANY attributes
will execute on either an MVS/370 or a system that uses 31-bit addressing
(MVS/XA or MVS/ESA) if the module is designed to:
v Use no facilities that are unique to MVS/XA or MVS/ESA.
v Execute entirely in 31-bit addressing mode on a system that uses 31-bit
addressing and return control to its caller in 31-bit addressing mode.
(The AMODE could be different from invocation to invocation.)
v Execute entirely in 24-bit addressing mode on an MVS/370 system.
The linkage editor and loader accept this combination from the object
module or load module but not from the PARM field of the linkage editor
EXEC statement or the linkage editor MODE control statement. The linkage
editor converts AMODE ANY/RMODE ANY to AMODE 31/RMODE ANY.

Figure 5-3. AMODE and RMODE Combinations

Determining the AMODE and RMODE of a Load Module

Use the AMBLIST service aid to find out the AMODE and RMODE of a load
module. The module summary produced by the LISTLOAD control statement
contains the AMODE of the main entry point and the AMODE of each alias, as well
as the RMODE specified for the load module. Refer to z/OS MVS Diagnosis: Tools
and Service Aids for information about AMBLIST.
You can look at the source code to determine the AMODE and RMODE that the
programmer intended for the program. However, the linkage editor or the loader can
override these specifications.

Chapter 5. Understanding 31-Bit Addressing

5-13

Assembler H Support of AMODE and RMODE

Assembler H Version 2 supports AMODE and RMODE assembler instructions.
Using AMODE and RMODE assembler instructions, you can specify an AMODE
and an RMODE to be associated with a control section, an unnamed control
section, or a named common control section.

AMODE and RMODE in the Object Module

The only combination of AMODE and RMODE that is not valid is AMODE 24/
RMODE ANY.
The following errors will keep your program from assembling:
v Multiple AMODE/RMODE statements for a single control section
v An AMODE/RMODE statement with an incorrect or missing value
v An AMODE/RMODE statement whose name field is not that of a valid control
section in the assembly.

AMODE and RMODE Assembler Instructions

The AMODE instruction specifies the addressing mode to be associated with a
CSECT in an object module. The format of the AMODE instruction is:
Name

Operation

Operand

Any symbol or blank

AMODE

24/31/ANY

The name field associates the addressing mode with a control section. If there is a
symbol in the name field of an AMODE statement, that symbol must also appear in
the name field of a START, CSECT, or COM statement in the assembly. If the name
field is blank, there must be an unnamed control section in the assembly.
Similarly, the name field associates the residency mode with a control section. The
RMODE statement specifies the residency mode to be associated with a control
section. The format of the RMODE instruction is:
Name

Operation

Operand

Any symbol or blank

RMODE

24/ANY

Both the RMODE and AMODE instructions can appear anywhere in the assembly.
Their appearance does not initiate an unnamed CSECT. There can be more than
one RMODE (or AMODE) instruction per assembly, but they must have different
name fields.
The defaults when AMODE, RMODE, or both are not specified are:

5-14

Specified

Defaulted

Neither

AMODE 24 RMODE 24

AMODE 24

RMODE 24

AMODE 31

RMODE 24

AMODE ANY

RMODE 24

RMODE 24

AMODE 24

RMODE ANY

AMODE 31

z/OS V1R4.0 MVS Assembler Services Guide

DFP Linkage Editor Support of AMODE and RMODE

The linkage editor accepts AMODE and RMODE specifications from any or all of
the following:
v Object modules.
v Load modules.
v PARM field of the linkage editor EXEC statement. For example:
//LKED EXEC PGM=name,PARM=AMODE=31,RMODE=ANY,.....

PARM field input overrides object module and load module input.
v Linkage editor MODE control statements in the SYSLIN data set. For example:
MODE AMODE(31),RMODE(24)

MODE control statement input overrides object module, load module and PARM
input.
Linkage editor processing results in two sets of AMODE and RMODE indicators
located in:
v The load module
v The PDS entry for the member name and any PDS entries for alternate names
or alternate entry points that were constructed using the linkage editor ALIAS
control statement.
These two sets of indicators might differ because they can be created from different
input. The linkage editor creates indicators in the load module based on input from
the input object module and load module. The linkage editor creates indicators in
the PDS directory based not only on input from the object module and load module
but also on the PARM field of the linkage editor EXEC statement, and the MODE
control statements in the SYSLIN data set. The last two sources of input override
indicators from the object module and load module. Figure 5-4 shows linkage editor
processing of AMODE and RMODE.

Chapter 5. Understanding 31-Bit Addressing

5-15

Assemble Input

Linkage Editor Input

For each CSECT,

AMODE/RMODE
specified by
assembler statements
or defaulted to
24/24

Optional AMODE/
RMODE PARM
values from JCL
EXEC statement
and/or MODE
control statement.

Assembler H
Version 2
Linkage Editor Processing

Object module contains AMODE/

RMODE.

Processes AMODE/RMODE
values from object module
and load [Link]
AMODE/RMODE into output
load module.(The linkage
editor does not use
AMODE/RMODE values from
the PDS.)

Processes optional PARM values

and/or MODE control statements
that override object module and
load module values. Puts
AMODE/RMODE in the PDS.

Load Module:
Contains AMODE/RMODE of each
executable control section and
named common control second
(derived from object module and
load module input values.)
PDS contains AMODE/RMODE
value from object module or
load module or from overriding
PARM values or MODE control
statements.
PARM values or MODE control
statements.

System obtains AMODE and RMODE

from PDS.

Figure 5-4. AMODE and RMODE Processing by the Linkage Editor

The linkage editor uses default values of AMODE 24/RMODE 24 for:

v Object modules produced by assemblers other than Assembler H Version 2
v Object modules produced by Assembler H Version 2 where source statements
did not specify AMODE or RMODE
v Load modules produced by linkage editors other than the DFP linkage editor
v Load modules produced by the DFP linkage editor that did not have AMODE or
RMODE specified from any input source
v Load modules in overlay structure.

5-16

z/OS V1R4.0 MVS Assembler Services Guide

MVS/XA and MVS/ESA treat programs in overlay structure as AMODE 24, RMODE
24 programs. Putting a program into overlay structure destroys any AMODE and
RMODE specifications contained in the load module.
The linkage editor recognizes as valid the following combinations of AMODE and
RMODE:
AMODE 24

RMODE 24

AMODE 31

RMODE 24

AMODE 31

RMODE ANY

AMODE ANY

RMODE 24

AMODE ANY

RMODE ANY

The linkage editor accepts the ANY/ANY combination from the object module or
load module and places AMODE 31, RMODE ANY into the PDS (unless overridden
by PARM values or MODE control statements). The linkage editor does not accept
ANY/ANY from the PARM value or MODE control statement.
Any AMODE value specified alone in the PARM field or MODE control statement
implies an RMODE of 24. Likewise, an RMODE of ANY specified alone implies an
AMODE of 31. However, for RMODE 24 specified alone, the linkage editor does not
assume an AMODE value. Instead, it uses the AMODE value specified in the
CSECT in generating the entry or entries in the PDS.
When the linkage editor creates an overlay structure, it assigns AMODE 24,
RMODE 24 to the resulting program.

Linkage Editor RMODE Processing

In constructing a load module, the linkage editor frequently is requested to combine
multiple CSECTs, or it may process an existing load module as input, combining it
with additional CSECTs or performing a CSECT replacement.
The linkage editor determines the RMODE of each CSECT. If the RMODEs are all
the same, the linkage editor assigns that RMODE to the load module. If the
RMODEs are not the same (ignoring the RMODE specification on common
sections), the more restrictive value, RMODE 24, is chosen as the load modules
RMODE.
The RMODE chosen can be overridden by the RMODE specified in the PARM field
of the linkage editor EXEC statement. Likewise, the PARM field RMODE can be
overridden by the RMODE value specified on the linkage editor MODE control
statement.
The linkage editor does not alter the RMODE values obtained from the object
module or load module when constructing the new load module. Any choice that the
linkage editor makes or any override processing that it performs affects only the
PDS.

DFP Loader Support for AMODE and RMODE

The loaders processing of AMODE and RMODE is similar to the linkage editors.
The loader accepts AMODE and RMODE specifications from:
Object modules
Load modules
PARM field of the JCL EXEC statement
Chapter 5. Understanding 31-Bit Addressing

5-17

Unlike the linkage editor, the loader does not accept MODE control statements from
the SYSLIN data set, but it does base its loading sequence on the sequence of
items in SYSLIN.
The loader passes the AMODE value to MVS. The loader processes the RMODE
value as follows. If the user specifies an RMODE value in the PARM field, that
value overrides any previous RMODE value. Using the value of the first RMODE it
finds in the first object module or load module it encounters that is not for a
common section, the loader obtains virtual storage for its output. As the loading
process continues, the loader may encounter a more restrictive RMODE value. If,
for example, the loader begins loading based on an RMODE ANY indicator and
later finds an RMODE 24 indicator in a section other than a common section, it
issues a message and starts over based on the more restrictive RMODE value.
Figure 5-5 shows loader processing of AMODE and RMODE.
Assembler Input

Loader Input

For each CSECT,

AMODE/RMODE
specified by
assembler
statements or
defaulted to 24/24.

Optional AMODE/
RMODE PARM
values from JCL
EXEC statement.

Assembler H
Version 2

Loader Processing

Processes object module and

load module AMODE/RMODE
values.

Object module contains AMODE/

RMODE.

Processes optional AMODE/

RMODE PARM values that
override object module
and load module values.
Load Module:
Contains AMODE/RMODE
of each CSECT (derived
from object module or load
module input values.)
PDS information is not
used.
Loader constructs program in virtual
storage with AMODE/RMODE from object
module, load module, or overriding
PARM values.

Figure 5-5. AMODE and RMODE Processing by the Loader

MVS Support of AMODE and RMODE

The following are examples of MVS support of AMODE and RMODE:
v MVS obtains storage for the module as indicated by RMODE.

5-18

z/OS V1R4.0 MVS Assembler Services Guide

v ATTACH, ATTACHX, LINK, LINKX, XCTL, and XCTLX give the invoked module
control in the addressing mode specified by its AMODE.
v LOAD brings a module into storage based on its RMODE and sets bit 0 in
register 0 to indicate its AMODE.
v CALL passes control in the AMODE of the caller.
v SYNCH or SYNCHX has an AMODE parameter that you can use to specify the
AMODE of the invoked module.
v For SVCs, the system saves and sets the addressing mode.
v SRBs are dispatched in the addressing mode indicated by the SRB specified to
the SCHEDULE macro.
v The cross memory instructions PC and PT establish the addressing mode for the
target program.
v DFP access methods, except VSAM macros and OPEN and CLOSE macros,
support AMODE 24 RMODE 24 callers only. VSAM macros and OPEN and
CLOSE macros support all addressing and residency mode callers.
v Dumping is based on the AMODE specified in the error-related PSW.
Program Fetch
The system uses RMODE information from the PDS to determine whether to
obtain storage above or below 16 megabytes.
ATTACH, ATTACHX, LINK, LINKX, XCTL, and XCTLX
Issuing an ATTACH or ATTACHX macro causes the control program to create a
new task and indicates the entry point to be given control when the new task
becomes active. If the entry point is a member name or an alias in the PDS.
ATTACH or ATTACHX gives it control in the addressing mode specified in the
PDS or in the mode specified by the loader. If the invoked program has the
AMODE ANY attribute, it gets control in the AMODE of its caller.
The LINK, LINKX, XCTL, and XCTLX macros also give the invoked program
control in the addressing mode indicated by its PDS for programs brought in by
fetch or in the AMODE specified by the loader. The entry point specified must
be a member name or an alias in the PDS passed by the loader, or specified in
an IDENTIFY macro. If the entry point is an entry name specified in an
IDENTIFY macro, IDENTIFY sets the addressing mode of the entry name equal
to the addressing mode of the main entry point.
LOAD
Issuing the LOAD macro causes MVS to bring the load module containing the
specified entry point name into virtual storage (if a usable copy is not already
there). LOAD sets the high-order bit of the entry point address in register 0 to
indicate the modules AMODE (0 for 24, 1 for 31), which LOAD obtains from the
modules PDS entry. If the modules AMODE is ANY, LOAD sets the high-order
bit in register 0 to correspond to the callers AMODE.
LOAD places the module in virtual storage either above or below 16 megabytes
as indicated by the modules RMODE, which is specified in the PDS for the
module.
Specifying the ADDR parameter indicates that you want the module loaded at a
particular location. If you specify an address above 16 megabytes, be sure that
the module being loaded has the RMODE ANY attribute. If you do not know the
AMODE and RMODE attributes of the module, specify an address below 16
megabytes or omit the ADDR parameter.

Chapter 5. Understanding 31-Bit Addressing

5-19

CALL
The CALL macro passes control to an entry point via BALR. Thus control is
transferred in the AMODE of the caller. CALL does not change AMODE.
SYNCH or SYNCHX
Using the AMODE parameter on the SYNCH or SYNCHX macro, you can
specify the addressing mode in which the invoked module is to get control.
Otherwise, SYNCH or SYNCHX passes control in the callers addressing mode.
SVC
For SVCs (supervisor calls), MVS saves and restores the issuers addressing
mode and makes sure that the invoked service gets control in the specified
addressing mode.
SRB
When an SRB (service request block) is dispatched, MVS sets the addressing
mode based on the high-order bit of the SRBEP field. This bit, set by the issuer
of the SCHEDULE macro, indicates the addressing mode of the routine
operating under the dispatched SRB.
PC and PT
For a program call (PC), the entry table indicates the target programs
addressing mode. The address field in the entry table must be initialized by
setting the high-order bit to 0 for 24-bit addressing mode or to 1 for 31-bit
addressing mode.
The PC instruction sets up register 14 with the return address and AMODE for
use with the PT (program transfer) instruction. If PT is not preceded by a PC
instruction, the PT issuer must set the high-order bit of the second operand
register to indicate the AMODE of the program being entered (0 for 24-bit
addressing mode or 1 for 31-bit addressing mode).
Data Management Access Methods
User programs must be in AMODE 24, RMODE 24 when invoking DFP access
methods other than VSAM. All non-VSAM access methods require parameter
lists, control blocks, buffers, and user exit routines to reside in virtual storage
below 16 megabytes.
VSAM request macros accept callers in AMODE 31, RMODE ANY. VSAM
allows parameter lists and control blocks to reside above 16 megabytes; for
details on addressing and residence requirements for VSAM parameter lists,
control blocks, buffers, and exit routines, see z/OS DFSMS: Using Data Sets.
AMODEs Effect on Dumps
The only time AMODE has an effect on dumps is when data on either side of
the address in each register is dumped. If the addresses in registers are treated
as 24-bit addresses, the data dumped may come from a different storage
location than when the addresses are treated as 31-bit addresses. If a dump
occurs shortly after an addressing mode switch, some registers may contain
31-bit addresses and some may contain 24 bit addresses, but dumping services
does not distinguish among them. Dumping services uses the AMODE from the
error-related PSW. For example, in dumping the area related to the registers
saved in the SDWA, dumping services uses the AMODE from the error PSW
stored in the SDWA.

How to Change Addressing Mode

To change addressing mode you must change the value of the PSW A-mode bit.
The following list includes all the ways to change addressing mode.
v The mode setting instructions BASSM and BSM.

5-20

z/OS V1R4.0 MVS Assembler Services Guide

v Macros (ATTACH, ATTACHX, LINK, LINKX, XCTL, or XCTLX). The system

makes sure that routines get control in the specified addressing mode. Users
need only ensure that parameter requirements are met. MVS restores the
invokers mode on return from LINK or LINKX.
v SVCs. The supervisor saves and restores the issuers addressing mode and
ensures that the service routine receives control in the addressing mode
specified in its SVC table entry.
v SYNCH or SYNCHX with the AMODE parameter to specify the addressing mode
in which the invoked routine is to get control.
v The CIRB macro and the stage 2 exit effector. The CIRB macro is described in
z/OS MVS Programming: Authorized Assembler Services Guide and z/OS MVS
Programming: Authorized Assembler Services Reference ALE-DYN.
v A PC, PT, or PR instruction. These three instructions establish the specified
addressing mode.
v An LPSW instruction (not recommended).
The example in Figure 5-6 illustrates how a change in addressing mode in a 24-bit
addressing mode program enables the program to retrieve data from the ACTLB
control block, which might reside above 16 megabytes. The example works
correctly whether or not the control block is actually above 16 megabytes. The
example uses the BSM instruction to change addressing mode. In the example, the
instruction L 2,4(,15) must be executed in 31-bit addressing mode. Mode setting
code (BSM) before the instruction establishes 31-bit addressing mode and code
following the instruction establishes 24-bit addressing mode.
USER
USER
USER

LABEL1
LABEL2

LABEL3

CSECT
RMODE 24
AMODE 24
L 15,ACTLB
L 1,LABEL1
BSM
DC
DS
L
LA
BSM
DS

SET HIGH-ORDER BIT OF REGISTER 1 TO 1

AND PUT ADDRESS INTO BITS 1-31
0,1
SET AMODE 31 (DOES NOT PRESERVE AMODE)
A(LABEL2 + X80000000)
0H
2,4(,15)
OBTAIN DATA FROM ABOVE 16 MEGABYTES
1,LABEL3
SET HIGH-ORDER BIT OF REGISTER 1 TO 0
AND PUT ADDRESS INTO BITS 1-31
0,1
SET AMODE 24 (DOES NOT PRESERVE AMODE)
0H

Figure 5-6. Mode Switching to Retrieve Data from Above 16 Megabytes

Establishing Linkage
This section describes the mechanics of correct linkage in 31-bit addressing mode.
Keep in mind that there are considerations other than linkage, such as locations of
areas that both the calling module and the invoked module need to address.
Linkage in MVS systems that use 31-bit addressing (MVS/XA, MVS/ESA and
OS/390) is the same as in MVS/370 for modules whose addressing modes are the
same. As shown in Figure 5-7, it is the linkage between modules whose addressing
modes are different that is an area of concern. The areas of concern that appear in
Figure 5-7 fall into two basic categories:
v Addresses passed as parameters from one routine to another must be addresses
that both routines can use.

Chapter 5. Understanding 31-Bit Addressing

5-21

 High-order bytes of addresses must contain zeroes or data that the receiving
routine is programmed to expect.
Addresses must be less than 16 megabytes if they could be passed to a
24-bit addressing mode program.
v On transfers of control between programs with different AMODEs, the receiving
routine must get control in the AMODE it needs and return control to the calling
routine in the AMODE the calling routine needs.
There are a number of ways of dealing with the areas of concern that appear in
Figure 5-7:
v Use the branching instructions (BASSM and BSM)
v Use pointer-defined linkage
v Use supervisor-assisted linkage (ATTACH, ATTACHX, LINK, LINKX, XCTL, and
XCTLX)
v Use linkage assist routines
v Use capping.

5-22

z/OS V1R4.0 MVS Assembler Services Guide

AMODE 31

AMODE 31

ok

AMODE 31

AMODE 31

16 megabytes

ok

Possible
of
1

Area
Concern

Definite
2 of

AMODE 24

AMODE 24
Possible
3 of

AMODE 31

ok

1.

Area
Concern

AMODE 31

AMODE 24

Area
Concern

ok

AMODE 24

When an AMODE 31 module that resides above 16 megabytes invokes an AMODE 24 module, the concerns are:
The AMODE 24 program needs to receive control 24-bit mode.
The location of shared data (including control blocks, register save areas, and parameters). Can the AMODE 24
module address the data?
The AMODE 24 module cannot return control unless an addressing mode change occurs.

2.

An AMODE 24 module cannot invoke an AMODE 31 module that resides above the line unless the AMODE 24
module changes its addressing mode either directly or using supervisor-assisted linkage.

3.

When both modules are below 16 megabytes the concerns are:

Which module cleans out bits 1-7 of the high-order bytes of 24-bit values used as addresses?
Can both modules address shared data?

4.

While there are no restrictions on the mechanics of linkage between two AMODE 31 modules, there might be
restrictions on parameter values.

Figure 5-7. Linkage Between Modules with Different AMODEs and RMODEs

Using the BASSM and BSM Instructions

The BASSM (branch and save and set mode) and the BSM (branch and set mode)
instructions are branching instructions that set the addressing mode. They are
designed to complement each other. (BASSM is used to call and BSM is used to
return, but they are not limited to such use.)

Chapter 5. Understanding 31-Bit Addressing

5-23

The description of BASSM appears in Figure 5-8. (See Principles of Operation for
more information.)

BASSM R ,R
1 2
'0C'
0

R1
8

RR
R2

12

15

Bits 32-63 of the current PSW, including the updated instruction address, are
saved as link information in the general register designated by R1. Subsequently,
the addressing mode and instruction address in the current PSW are replaced
from the second operand. The action associated with the second operand is not
performed if the R2 field is zero.
The contents of the general register designated by the R2 field specify the new
addressing mode and branch address; however when the R2 field is zero, the
operation is performed without branching and without setting the addressing
mode.
When the contents of the general register designated by the R2 field are used,
bit 0 of the register specifies the new addressing mode and replaces bit 32 of the
current PSW, and the branch address is generated from the contents of the
register under the control of the new addressing mode. The new value for the
PSW is computed before the register designated by R1 is changed.
Condition Code: The code remains unchanged.
Program Exceptions: Trace (R2 field is not zero).
Figure 5-8. BRANCH and SAVE and Set Mode Description

The description of BSM appears in Figure 5-9. (See Principles of Operation for
more information.)

5-24

z/OS V1R4.0 MVS Assembler Services Guide

BSM

R ,R
1 2

RR

R1

R2

'0B'
0

12

15

Bit 32 of the current PSW, the addressing mode, is inserted into the first
operand. Subsequently the addressing mode and instruction address in the
current PSW are replaced from the second operand. The action associated with
an operand is not performed if the associated R field is zero.
The value of bit 32 of the PSW is placed in bit position 0 of the general register
designated by R1, and bits 1-31 of the register remain unchanged; however,
when the R1 field is zero, the bit is not inserted, and the contents of general
register 0 are not changed.
The contents of the general register designated by the R2 field specify the new
addressing mode and branch address; however, when the R2 field is zero, the
operation is performed without branching and without setting the addressing
mode.
When the contents of the general register designated by the R2 field are used,
bit 0 of the register specifies the new addressing mode and replaces bit 32 of the
current PSW, and the branch address is generated from the contents of the
register under the control of the new addressing mode. The new value for the
PSW is computed before the register designated by R1 is changed.
Condition Code: The code remains unchanged.
Program Exceptions: None.
Figure 5-9. Branch and Set Mode Description

Calling and Returning with BASSM and BSM

In the following example, a module named BELOW has the attributes AMODE 24,
RMODE 24. BELOW uses a LOAD macro to obtain the address of module ABOVE.
The LOAD macro returns the address in register 0 with the addressing mode
indicated in bit 0 (a pointer-defined value). BELOW stores this address in location
EPABOVE. When BELOW is ready to branch to ABOVE, BELOW loads ABOVEs
entry point address from EPABOVE into register 15 and branches using BASSM
14,15. BASSM places the address of the next instruction into register 14 and sets
bit 0 in register 14 to 0 to correspond to BELOWs addressing mode. BASSM
replaces the PSW A-mode bit with bit 0 of register 15 (a 1 in this example) and
replaces the PSW instruction address with the branch address (bits 1-31 of register
15) causing the branch.
ABOVE uses a BSM 0,14 to return. BSM 0,14 does not save ABOVEs addressing
mode because 0 is specified as the first operand register. It replaces the PSW
A-mode bit with bit 0 of register 14 (BELOWs addressing mode set by BASSM)
and branches.

Chapter 5. Understanding 31-Bit Addressing

5-25

ABOVE CSECT
ABOVE AMODE 31
ABOVE RMODE ANY
.
.
.
.
.
BSM 0, 14
16 megabytes

BELOW CSECT
BELOW AMODE 24
BELOW RMODE 24
.
.
LOAD
ST
.

EP=ABOVE
0,EPABOVE

.
L
15,EPABOVE
BASSM 14,15

Figure 5-10. Using BASSM and BSM

Using Pointer-Defined Linkage

Pointer-defined linkage is a convention whereby programs can transfer control
back and forth without having to know each others AMODEs. Pointer-defined
linkage is simple and efficient. You should use it in new or modified modules where
there might be mode switching between modules.
Pointer-defined linkage uses a pointer-defined value, which is a 4-byte area that
contains both an AMODE indicator and an address. The high-order bit contains the
AMODE; the remainder of the word contains the address. To use pointer-defined
linkage, you must:
v Use a pointer-defined value to indicate the entry point address and the entry
points AMODE. (The LOAD macro provides a pointer-defined value.)
v Use the BASSM instruction specifying a register that contains the pointer-defined
value. BASSM saves the callers AMODE and next the address of the next
sequential instruction, sets the AMODE of the target routine, and branches to the
specified location.
v Have the target routine save the full contents of the return register and use it in
the BSM instruction to return to the caller.

Using an ADCON to Obtain a Pointer-Defined Value

The following method is useful when you need to construct pointer-defined values
to use in pointer-defined linkages between control sections or modules that will be
link edited into a single load module. You can also use this method when the
executable program is prepared in storage using the loader.

5-26

z/OS V1R4.0 MVS Assembler Services Guide

The method requires the use of an externally-defined address constant in the

routine to be invoked that identifies its entry mode and address. The address
constant must contain a pointer-defined value. The calling program loads the
pointer-defined value and uses it in a BASSM instruction. The invoked routine
returns using a BSM instruction.
In Figure 5-11, RTN1 obtains pointer-defined values from RTN2 and RTN3. RTN1,
the invoking routine does not have to know the addressing modes of RTN2 and
RTN3. Later, RTN2 or RTN3 could be changed to use different addressing modes,
and at that time their address constants would be changed to correspond to their
new addressing mode. RTN1, however, would not have to change the sequence of
code it uses to invoke RTN2 and RTN3.
You can use the techniques that the previous example illustrates to handle routines
that have multiple entry points (possibly with different AMODE attributes). You need
to construct a table of address constants, one for each entry point to be handled.
As with all forms of linkage, there are considerations in addition to the linkage
mechanism. These include:
v Both routines must have addressability to any parameters passed.
v Both routines must agree which of them will clean up any 24-bit addresses that
might have extraneous information bits 1-7 of the high-order byte. (This is a
consideration only for AMODE 31 programs.)
When a 24-bit addressing mode program invokes a module that is to execute in
31-bit addressing mode, the calling program must ensure that register 13 contains a
valid 31-bit address of the register save area with no extraneous data in bits 1-7 of
the high-order byte. In addition, when any program invokes a 24-bit addressing
mode program, register 13 must point to a register save area located below 16
megabytes.

Chapter 5. Understanding 31-Bit Addressing

5-27

RTN1

CSECT
EXTRN
EXTRN
.
.
L
L
BASSM
.
.
L
L
BASSM
.

RTN2AD
RTN3AD
15,=A(RTN2AD)
15,0(,15)
14,15

LOAD ADDRESS OF POINTER-DEFINED VALUE

LOAD POINTER-DEFINED VALUE
GO TO RTN2 VIA BASSM

15,=A(RTN3AD)
15,0(,15)
14,15

LOAD ADDRESS OF POINTER-DEFINED VALUE

LOAD POINTER DEFINED-VALUE
GO TO RTN3 VIA BASSM

__________________________________________________________________
RTN2 CSECT
RTN2 AMODE 24
ENTRY RTN2AD
.
BSM
0,14
RETURN TO CALLER IN CALLERS MODE
RTN2AD DC
A(RTN2)
WHEN USED AS A POINTER-DEFINED VALUE,
INDICATES AMODE 24 BECAUSE BIT 0 IS 0
__________________________________________________________________
RTN3 CSECT
RTN3 AMODE 31
ENTRY RTN3AD
.
BSM
0,14
RETURN TO CALLER IN CALLERS MODE
RTN3AD DC
A(X80000000+RTN3) WHEN USED AS A POINTER-DEFINED VALUE
INDICATES AMODE 31 BECAUSE BIT 0 IS 1

Figure 5-11. Example of Pointer-Defined Linkage

Using the LOAD Macro to Obtain a Pointer-Defined Value

LOAD returns a pointer-defined value in register 0. You can preserve this
pointer-defined value and use it with a BASSM instruction to pass control without
having to know the target routines AMODE.

Using Supervisor-Assisted Linkage

Figure 5-12 shows a before and after situation involving two modules, MOD1 and
MOD2. In the BEFORE part of the figure both modules execute in 24-bit addressing
mode. MOD1 invokes MOD2 using the LINK or LINKX macro. The AFTER part of
the figure shows MOD2 moving above 16 megabytes and outlines the steps that
were necessary to make sure both modules continue to perform their previous
function.

5-28

z/OS V1R4.0 MVS Assembler Services Guide

BEFORE

MOD1 links to MOD2. Both MOD1 and MOD2 reside below 16 megabytes and have the
attributes AMODE 24, RMODE 24 by default.

MOD1 CSECT

MOD2 CSECT

LINK EP=MOD2

MOD2 moves above 16 megabytes.

AFTER

When MOD2 moves above 16 megabytes, you must make sure it will execute
correctly. Specifically, you must:

MOD2 CSECT

1.

Review any mode-sensitive instructions to be sure they perform as intended in

AMODE 31, RMODE ANY.

MOD2 AMODE 31

2.

Review system services used to be sure they can be invoked in AMODE 31,
RMODE ANY and make the any necessary changed. (For example, change SPIE
to ESPIE). Review the Conversion Notebook chapters on incompatibilities,
coexistence considerations, and programming considerations. Move any services
that do not permit callers to be in 31-bit mode to modules residing below 16
megabytes.

3.

Make sure all parameters and control blocks needed by MOD1 reside below 16
megabytes.

4.

Make sure all addresses passed by MOD1 have high-order bytes that are free of
extraneous data or code MOD2 to clean up the high-order bytes to any address
shared with MOD1.

5.

Make sure that all fields containing addresses of areas above 16 megabytes are
fullword fields.

MOD2 RMODE ANY

16 megabytes

line

MOD1 CSECT

LINK EP=MOD2

AMODE 24

by default

LINK or LINKX handles the mode switching between MOD1 and MOD2 as
follows:
1. LINK or LINKX obtains MOD2's AMODE from the PDS directory entry.
2. LINK or LINKX ensures that MOD2 is entered in the specified AMODE.
3. On completion, LINK or LINKX restores MOD1's AMODE by default and
returns control.

RMODE 24

Figure 5-12. Example of Supervisor-Assisted Linkage

Linkage Assist Routines

A linkage assist routine, sometimes called an addressing mode interface routine,
is a module that performs linkage for modules executing in different addressing or
Chapter 5. Understanding 31-Bit Addressing

5-29

residency modes. Using a linkage assist routine, a 24-bit addressing mode module
can invoke a 31-bit addressing mode module without having to make any changes.
The invocation results in an entry to a linkage assist routine that resides below 16
megabytes and invokes the 31-bit addressing mode module in the specified
addressing mode.
Conversely, a 31-bit addressing mode module, such as a new user module, can
use a linkage assist routine to communicate with other user modules that execute in
24-bit addressing mode. The caller appears to be making a direct branch to the
target module, but branches instead to a linkage assist routine that changes modes
and performs the branch to the target routine.
The main advantage of using a linkage assist routine is to insulate a module from
addressing mode changes that are occurring around it.
The main disadvantage of using a linkage assist routine is that it adds overhead to
the interface. In addition, it takes time to develop and test the linkage assist routine.
Some alternatives to using linkage assist routines are:
v Changing the modules to use pointer-defined linkage (described in Using
Pointer-Defined Linkage on page 5-26).
v Adding a prologue and epilogue to a module to handle entry and exit mode
switching, as described later in this chapter under Capping.

Example of Using a Linkage Assist Routine

Figure 5-13 shows a before and after situation involving modules USER1 and
USER2. USER1 invokes USER2 by using a LOAD and BALR sequence. The
before part of the figure shows USER1 and USER2 residing below 16 megabytes
and lists the changes necessary if USER2 moves above 16 megabytes. USER1
does not change.
The after part of the figure shows how things look after USER2 moves above 16
megabytes. Note that USER2 is now called USER3 and the newly created linkage
assist routine has taken the name USER2.
The figure continues with a coding example that shows all three routines after the
move.

5-30

z/OS V1R4.0 MVS Assembler Services Guide

BEFORE
Existing Application - USER1 invokes USER2 repeatedly
USER1

USER2

LOAD EP=USER2
BALR
RETURN
Change

Reason
USER1 does not have to change the LOAD
USER2 macro.

Change name of USER2 TO USER3.

Write a linkage assist routine called USER2.
Change USER3 (formerly USER2) as follows:

USER1 remains unchanged; new USER2 switches

AMODEs and branches to USER3 (the former
USER).

- Make sure all control blocks and parameters needed

by USER1 and USER2 are located below
16 megabytes line.

- USER1 and USER2 are AMODE 24; they cannot

access parameters or data above 16 megabytes.

- Check mode-sensitive instructions to be sure they

perform the intended function in AMODE 31,
REMODE ANY.
- Check system services used to be sure they can be
invoked in AMODE 31, RMODE ANY and make any
necessary changes. (For example, change SPIE to
ESPIE.) Review the Conversion Notebook chapters
on incompatibilities, coexistence considerations, and
programming considerations.

- USER3 was moved above 16 megabytes and

has the attributes AMODE 31, REMODE ANY.
- USER3 has the attributes AMODE 31, RMODE
ANY. SPIE and some other system services will
not work in AMODE 31.

- Make sure that all fields containing addresses

of areas above 16 megabytes are fullword fields.
AFTER
Changed Application

USER3 (formerly USER2)

USER3 CSECT
USER3 AMODE 31
USER3 RMODE ANY
RETURN

USER1

USER2 (NEW)

USER1 CSECT
LOAD EP=USER2

USER2 CSECT
USER2 AMODE 24
USER2 RMODE 24
LOAD USER3

BALR

BASSM
BSM TO
NEXT
SEQUENTIAL
INSTRUCTION
RETURN

Figure 5-13. Example of a Linkage Assist Routine (Part 1 of 4)

Chapter 5. Understanding 31-Bit Addressing

5-31

USER1 (This module will not change)

* USER MODULE USER1 CALLS MODULE USER2
USER1
CSECT
BEGIN
SAVE
(14,12),,* (SAVE REGISTER CONTENT, ETC.)
* ESTABLISH BASE REGISTER(S) AND NEW SAVE AREA (NORMAL
* ENTRY CODING)
.
.
* ISSUE LOAD FOR MODULE USER2
LOAD EP=USER2
ISSUE LOAD FOR MODULE "USER2"
* In the MVS/XA environment, the LOAD macro returns a
* pointer-defined value. However, because module USER1
* has not been changed and executes in AMODE 24, the
* pointer-defined value has no effect on the BALR
* instruction used to branch to module USER2.
ST
0,EPUSER2
PRESERVE ENTRY POINT
.
* MAIN PROCESS BEGINS
PROCESS DS
0H
.
.
.
.
.
.
* PREPARE TO GO TO MODULE USER2
L
15,EPUSER2 LOAD ENTRY POINT
BALR 14,15
.
.
.
.
TM
TEST FOR END
BC
PROCESS
CONTINUE IN LOOP
.
DELETE EP=USER2
L
13,4(13)
RETURN (14,12),T,RC=0 MODULE USER1 COMPLETED
EPUSER2 DC
F0
ADDRESS OF ENTRY POINT TO USER2
END
BEGIN
USER2 (Original application module)
* USER MODULE USER2 (INVOKED FREQUENTLY FROM USER1)
USER2
CSECT
SAVE (14,12),,* SAVE REGISTER CONTENT, ETC.
* ESTABLISH BASE REGISTER(S) AND NEW SAVE AREA (NORMAL
* ENTRY CODING)
.
.
.
.
.
L
13,4(13)
RETURN (14,12),T,RC=0 MODULE USER2 COMPLETED
END
Figure 5-13. Example of a Linkage Assist Routine (Part 2 of 4)

5-32

z/OS V1R4.0 MVS Assembler Services Guide

00000100
00000200
00000300
00000400
00000500
00000700
00000800

00000900
00001000
00001100

00002000
00002100
00002200

00003000
00003100

00005000
00007000
00007100

00000100
00000200
00000300
00000400

00008100
00008200

USER2 (New linkage assist routine)

* THIS IS A NEW LINKAGE ASSIST ROUTINE
0000100
* (IT WAS NAMED USER2 SO THAT MODULE USER1 WOULD NOT
0000200
* HAVE TO BE CHANGED)
0000300
USER2
CSECT
0000400
USER2
AMODE 24
0000500
USER2
RMODE 24
0000600
SAVE (14,12),,* (SAVE REGISTER CONTENT, ETC.)
0000700
* ESTABLISH BASE REGISTER(S) AND NEW SAVE AREA (NORMAL
0000800
* ENTRY CODING)
.
* FIRST TIME LOGIC, PERFORMED ON INITIAL ENTRY ONLY,
0002000
* (AFTER INITIAL ENTRY, BRANCH TO PROCESS (SHOWN BELOW))
0002100
.
GETMAIN
NEW REGISTER SAVE AREA
0003000
.
LOAD EP=USER3
0004000
* USER2 LOADS USER3 BUT DOES NOT DELETE IT. USER2 CANNOT
* DELETE USER3 BECAUSE USER2 DOES NOT KNOW WHICH OF ITS USES
* OF USER3 IS THE LAST ONE.
ST
0,EPUSER3 PRESERVE POINTER DEFINED VALUE
0004100
.
* PROCESS (PREPARE FOR ENTRY TO PROCESSING MODULE)
0005000
.
(FOR EXAMPLE, VALIDITY CHECK REGISTER CONTENTS)
.
.
* PRESERVE AMODE FOR USE DURING RETURN SEQUENCE
0007000
LA
1,XRETURN
SET RETURN ADDRESS
0008000
BSM
1,0
PRESERVE CURRENT AMODE
0008100
ST
1,XSAVE
PRESERVE ADDRESS
0008200
L
15,EPUSER3
LOAD POINTER DEFINED VALUE
0009000
* GO TO MODULE USER3
0009100
BASSM 14,15
TO PROCESSING MODULE
0009200
* RESTORE AMODE THAT WAS IN EFFECT
0009300
L
1,XSAVE
LOAD POINTER DEFINED VALUE
0009400
BSM
0,1
SET ADDRESSING MODE
0009500
XRETURN DS
0H
0009600
L
13,4(13)
.
RETURN (14,12),T,RC=0
MODULE USER2 HAS COMPLETED
0010000
EPUSER3 DC
F0
POINTER DEFINED VALUE
0010100
XSAVE
DC
F0
ORIGINAL AMODE AT ENTRY
0010200
END
0010500
_________________________________________________________________________

v Statements 8000 through 8200: These instructions preserve the AMODE in effect at the time of entry
into module USER2.
v Statement 9200: This use of the BASSM instruction:
Causes the USER3 module to be entered in the specified AMODE (AMODE 31 in this example).
This occurs because the LOAD macro returns a pointer-defined value that contains the entry point of
the loaded routine, and the specified AMODE of the module.
Puts a pointer-defined value for use as the return address into Register 14.
v Statement 9400: Module USER3 returns to this point.
v Statement 9500: Module USER2 re-establishes the AMODE that was in effect at the time the BASSM
instruction was issued (STATEMENT 9200).
Figure 5-13. Example of a Linkage Assist Routine (Part 3 of 4)

Chapter 5. Understanding 31-Bit Addressing

5-33

USER3 (New Application Module)

* MODULE USER3
(PERFORMS FUNCTIONS OF OLD MODULE USER2)
00000100
USER3
CSECT
00000200
USER3
AMODE 31
00000300
USER3
RMODE ANY
00000400
SAVE
(14,12),,* (SAVE REGISTER CONTENT, ETC.)
00000500
* ESTABLISH BASE REGISTER(S) AND NEW SAVE AREA
00000600
.
.
.
.
.
.
* RESTORE REGISTERS AND RETURN
00008000
.
RETURN (14,12),T,RC=0
00008100
END
00008200
_________________________________________________________________________

v Statements 300 and 400 establish the AMODE and RMODE values for this module. Unless they are
over-ridden by linkage editor PARM values or MODE control statements, these are the values that will
be placed in the PDS for this module.
v Statement 8100 returns to the invoking module.
Figure 5-13. Example of a Linkage Assist Routine (Part 4 of 4)

Using Capping - Linkage Using a Prologue and Epilogue

An alternative to linkage assist routines is a technique called capping. You can add
a cap (prologue and epilogue) to a module to handle entry and exit addressing
mode switching. The cap accepts control in either 24-bit or 31-bit addressing mode,
saves the callers registers, and switches to the addressing mode in which the
module is designed to run. After the module has completed its function, the
epilogue portion of the cap restores the callers registers and addressing mode
before returning control.
For example, when capping is used, a module in 24-bit addressing mode can be
invoked by modules whose addressing mode is either 24-bit or 31-bit; it can
perform its function in 24-bit addressing mode and can return to its caller in the
callers addressing mode. Capped modules must be able to accept callers in either
addressing mode. Modules that reside above 16 megabytes cannot be invoked in
24-bit addressing mode. Capping, therefore, can be done only for programs that
reside below 16 megabytes.
Figure 5-14 shows a cap for a 24-bit addressing mode module.

5-34

z/OS V1R4.0 MVS Assembler Services Guide

MYPROG
MYPROG
MYPROG

CSECT
AMODE ANY
RMODE 24
USING *,15
STM 14,12,12(13) SAVE CALLERS REGISTERS BEFORE SETTING AMODE
LA 10,SAVE
SET FORWARD ADDRESS POINTER IN CALLERS
ST 10,8(13)
SAVE AREA
LA 12,MYMODE
SET AMODE BIT TO 0 AND ESTABLISH BASE
LA 11,RESETM
GET ADDRESS OF EXIT CODE
BSM 11,12
SAVE CALLERS AMODE AND SET IT TO AMODE 24
USING *,12
MYMODE
DS
0H
DROP 15
ST 13,SAVE+4
SAVE CALLERS SAVE AREA
LR 13,10
ESTABLISH OWN SAVE AREA
_______________________________________________________________________
This is the functional part of the original module.
This example assumes that register 11 retains its
original contents throughout this portion of the program.
_______________________________________________________________________
L
13,4(13)
GET ADDRESS OF CALLERS SAVE AREA
BSM 0,11
RESET CALLERS AMODE
RESETM
DS 0H
LM 14,12,12(13) RESTORE CALLERS REGISTERS IN CALLERS AMODE
BR 14
RETURN
SAVE
DS 0F
DC 18F0

Figure 5-14. Cap for an AMODE 24 Module

Performing I/O in 31-Bit Addressing Mode

Programs in 31-bit addressing mode sometimes need to use 24-bit addressing
mode programs to perform an I/O operation.
A 31-bit addressing mode program can perform an I/O operation by:
v Using VSAM, QSAM, BSAM, BPAM and BDAM services that accept callers in
either 24-bit or 31-bit addressing mode. (z/OS DFSMS: Using Data Sets
describes these services and shows examples. The functions that require. 24-bit
mode are ISAM, some BDAM functions and BSAM and QSAM with a TSO
terminal or IBM 3886 or 3890 Document Processor.)
v Using the EXCP macro. All parameter lists, control blocks, CCWs, virtual IDAWs,
and EXCP appendage routines must reside in virtual storage below 16
megabytes. See Using the EXCP Macro on page 5-36 for a description of using
EXCP to perform I/O.
v Using the EXCPVR macro. All parameter lists, control blocks, CCWs, IDALs
(indirect data address lists), and appendage routines must reside in virtual
storage below 16 megabytes. See Using EXCPVR on page 5-36 for a
description of using EXCPVR to perform I/O.
v Invoking a routine that executes in 24-bit addressing mode as an interface to the
24-bit access methods, which accept callers executing in 24-bit addressing mode
only. See Establishing Linkage on page 5-21 for more information about this
method.
v Using the method shown in Figure 5-15 on page 5-38.

Chapter 5. Understanding 31-Bit Addressing

5-35

Using the EXCP Macro

EXCP macro users can perform I/O to virtual storage areas above 16 megabytes.
By using virtual IDAW support, CCWs in the EXCP channel program can, using a
24-bit address, point to a virtual IDAW that contains the 31-bit virtual address of an
I/O buffer. The CCWs and IDAWs themselves must reside in virtual storage below
16 megabytes. The EXCP service routine supports only format 0 CCWs, the CCW
format used in MVS/370.
CCW (Format 0)
Address of
an IDAW

IDAW
Virtual address of
an I/O buffer

Any CCW that causes data to be transferred can point to a virtual IDAW. Virtual
IDAW support is limited to non-VIO data sets.
Although the I/O buffer can be in virtual storage above 16 megabytes, the virtual
IDAW that contains the pointer to the I/O buffer and all the other areas related to
the I/O operation (CCWs, IOBs, DEBs, and appendages) must reside in virtual
storage below 16 megabytes.
Note: EXCP can translate your virtual channel program to a real channel program
that uses 64-bit IDAWs if you are running in z/Architecture mode and the
device support code allows them.
For more EXCP information, see z/OS DFSMSdfp Advanced Services.

Using EXCPVR
The EXCPVR interface supports only format 0 CCWs. Format 0 CCWs support only
24-bit addresses. All CCWs and IDAWs used with EXCPVR must reside in virtual or
central storage below 16 megabytes. The largest virtual or central storage address
you can specify directly in your channel program is 16 megabytes minus one.
However, using IDAWs (indirect data address words) you can specify any central
storage address and therefore you can perform I/O to any location in real or virtual
storage. EXCPVR channel programs must use IDAWs to specify buffer addresses
above 16 megabytes in central storage.
The format 0 CCW may contain the address of an IDAL (indirect address list),
which is a list of IDAWs (indirect data address words).

5-36

z/OS V1R4.0 MVS Assembler Services Guide

CCW (Format 0)
Address of
IDAL

0 8

32 48

63
IDAL

IDAW

I/O buffer
address

IDAW

IDAW

You must assume that buffers obtained by data management access methods have
real storage addresses above 16 megabytes.
For more EXCPVR information, see z/OS DFSMSdfp Advanced Services.

Example of Performing I/O While Residing Above 16 Megabytes

Figure 5-15 shows a before and after situation that involves two functions,
USER1 and USER2. In the BEFORE part of the example, USER1 contains both
functions and resides below 16 megabytes. In the AFTER part of the example
USER1 has moved above 16 megabytes. The portion of USER1 that requests data
management services has been removed and remains below 16 megabytes.
The figure includes a detailed coding example that shows both USER1 and USER2.

Chapter 5. Understanding 31-Bit Addressing

5-37

BEFORE

Data management
services

USER1

USER1 is an application program that occasionally requests data management services to

perform data base I/O. USER1 and data management services reside below 16 megabytes.

AFTER

USER1 CSECT
USER1 AMODE 31
USER1 RMODE ANY

16 megabytes

USER2 CSECT
USER2 AMODE 24
USER2 RMODE 24

Data management
services
(AMODE 24, RMODE 24
by default)

USER1 moves above 16 megabytes and moves its interface to data management into a new module, USER2.
USER2 remains below 16 megabtyes because some data management services must be invoked 24-bit
addressing mode. The following coding example shows USER1 and USER2 after USER1 has moved.

Figure 5-15. Performing I/O While Residing Above 16 Megabytes (Part 1 of 10)

5-38

z/OS V1R4.0 MVS Assembler Services Guide

USER1 Application Module

*Module USER1 receives control in 31-bit addressing mode, resides in
*storage above 16 megabytes, and calls module USER2 to perform data
*management services.
*In this example, note that no linkage assist routine is needed.
USER1
CSECT
USER1
AMODE 31
USER1
RMODE ANY
*
*
Save the callers registers in save area provided
*
#100
SAVE (14,12)
Save registers
BASR 12,0
Establish base
USING *,12
Addressability
Storage will be obtained via GETMAIN for USER2s work area (which will also contain the save area
that module USER2 will store into as well as parameter areas in which information will be passed.)
Since module USER2 must access data in the work area, the work area must be obtained below 16
megabytes.
LA
0,WORKLNTH
Length of the work area
*
required for USER2
#200
GETMAIN RU,LV=(0),LOC=BELOW
Obtain work area storage
LR
6,1
Save address of obtained
*
storage to be used for
*
a work area for module
*
USER2
USING WORKAREA,6
Work area addressability
The SAVE operation at statement #100 may save registers into a save area that exists in storage either
below or above 16 megabytes. If the save area supplied by the caller of module USER1 is in storage
below 16 megabytes, it is assumed that the high-order byte of register 13 is zero.
The GETMAIN at statement #200 must request storage below 16 megabytes for the following reasons:
1. The area obtained via GETMAIN will contain the register save area in which module USER2 will save
registers. Because module USER2 runs in 24-bit addressing mode, it must be able to access the save
area.
2. Because module USER2 will extract data from the work area to determine what function to perform,
the area must be below 16 megabytes, otherwise, USER2 would be unable to access the parameter
area.
LA
0,GMLNTH
Get dynamic storage for
*
module USER1 (USER1 resides
*
above 16 megabytes)
#300
GETMAIN RU,LV=(0),LOC=RES
Get storage above 16
*
megabytes
LR
8,1
Copy address of storage
*
obtained via GETMAIN
USING DYNAREA,8
Base register for dynamic
*
work area
#400
ST
13,SAVEBKWD
Save address of callers
*
save area
LR
9,13
Save callers save area
*
address
LA
13,SAVEAREA
USER1s save area address
*
Note - save area is below
*
16 megabytes
Figure 5-15. Performing I/O While Residing Above 16 Megabytes (Part 2 of 10)
Chapter 5. Understanding 31-Bit Addressing

5-39

*
*
*
*
*

ST

13,8(9)

LOAD

EP=IOSERV

ST

0,EPA

Have callers save area

point to my save area
Load address of data
management service
Entry point address
returned will be pointer-defined
Save address of loaded
routine.

The GETMAIN at statement #300 requests that the storage to be obtained match the current residency
mode of module USER1. Because the module resides above 16 megabytes, the storage obtained will be
above 16 megabytes.
At statement #400, the address of the callers save area is saved in storage below 16 megabytes.
Prepare to open input and output data base files
MVC
FUNCTION,OPEN1
Indicate open file 1
*
for input
LA
1,COMMAREA
Set up register 1 to
*
point to the parameter
*
area
#500
L
15,EPA
Get pointer-defined address
*
of the I/O service
*
routine
#600
BASSM 14,15
Call the service routine
*
Note: AMODE will change
#650
MVC FUNCTION,OPEN2
Indicate open file 2
*
for output
LA
1,COMMAREA
Setup register 1 to
*
point to the parameter
*
area
#700
L
15,EPA
Get pointer-defined address
*
of the I/O service
*
routine
BASSM 14,15
Call the service routine
*
Note: AMODE will change
The entry point address loaded at statements #500 and #700 is pointer-defined, as returned by the LOAD
service routine. That is, the low-order three bytes of the symbolic field EPA will contain the virtual address
of the loaded routine while the high order bit (bit 0) will be zero to indicate the loaded module is to receive
control in 24-bit addressing mode. The remaining bits (1-7) will also be zero in the symbolic field EPA.
The BASSM at statement #600 does the following:
v Places into bit positions 1-31 of register 14 the address of statement #650.
v Sets the high-order bit of register 14 to one to indicate the current addressing mode.
v Replaces bit positions 32-63 of the current PSW with the contents of register 15 (explained above)
The BSM instruction used by the called service routine USER2 to return to USER1 will reestablish 31-bit
addressing mode.
Figure 5-15. Performing I/O While Residing Above 16 Megabytes (Part 3 of 10)

5-40

z/OS V1R4.0 MVS Assembler Services Guide

Prepare to read a record from data base file 1.

READRTN DS
0H
MVC FUNCTION,READ1
Indicate read to file 1
XC
BUFFER,BUFFER
Clear input buffer
LA
1,COMMAREA
Set up register 1 to
*
point to the parameter area
L
15,EPA
Get pointer-defined address
*
of the I/O service routine
BASSM 14,15
Call the service routine
*
Note: The BASSM will change
*
the AMODE to 24-bit. The
*
BSM issued in the service
*
routine will reestablish
*
31-bit addressing mode.
#900
CLC
STATUS,ENDFILE
End of file encountered
*
by module USER2 ?
BE
EODRTN
Close files and exit
MVC BUFFR31A,BUFFER
Move record returned to
*
storage above 16 megabytes
At statement #900, a check is made to determine if called module USER2 encountered the end of file. The
end of file condition in this example can only be intercepted by USER2 because the EOD exit address
specified on the DCB macro must reside below 16 megabytes. The end of file condition must then be
communicated to module USER1.
Call a record analysis routine that exists above 16 megabytes.

*
*
*

LA
ST
LA

1,BUFFR31A
1,BUFPTR+0
1,UPDATBFR

ST
LA

1,BUFPTR+4
1,BUFPTR

L
15,ANALYZE
BASR 14,15
MVC BUFFER,UPDATBFR

#1000
*
*
*

Get address of first buffer

Store into parameter list
Get address of output
buffer
Store into parameter list
Set up pointers to work
buffers for the analysis
routine
Address of analysis routine
Call analysis routine
Move updated record to
storage below 16 megabytes
so that the updated record can
be written back to the data base

At statement #1000 a BASR instruction is used to call the analysis routine since no AMODE switching is
required. A BALR could also have been used. A BALR executed while in 31-bit addressing mode performs
the same function as a BASR instruction. The topic Mode Sensitive Instructions describes the instruction
differences.
*
*
*
*
*
*
*
*

MVC
LA

FUNCTION,WRITE1
1,COMMAREA

15,EPA

BASSM 14,15

READRTN

Indicate write to file 1

Set up register 1 to
point to the parameter area
Get pointer-defined address
of the I/O service routine
routine
Call the service routine
Note: The BASSM will set
the AMODE to 24-bit. The
BSM issued in the service
routine will reestablish
31-bit addressing mode
Get next record to process

Figure 5-15. Performing I/O While Residing Above 16 Megabytes (Part 4 of 10)
Chapter 5. Understanding 31-Bit Addressing

5-41

Prepare to close input and output data base files

EODRTN
*
*
*
*
*
*
*
*
*
*
*
*
*
*

DS
MVC
LA

0H
FUNCTION,CLOSE1
1,COMMAREA

15,EPA

BASSM 14,15

MVC
LA

FUNCTION,CLOSE2
1,COMMAREA

15,EPA

BASSM 14,15

End of data routine

Indicate close file 1
Set up register 1 to
point to the parameter area
Get pointer-defined address
of the I/O service routine
Call the service routine
Note: The BASSM sets
the AMODE to 24-bit. The
BSM issued in the service
routine will reestablish
31-bit addressing mode
Indicate close file 2
Set up register 1 to
point to the parameter area
Get pointer-defined address
of the I/O service routine
Call the service routine
Note: The BASSM sets
the AMODE to 24-bit. The
BSM issued in the service
routine will reestablish
31-bit addressing mode

Prepare to return to the caller

*
*
*
*

13,SAVEBKWD

LA

0,WORKLNTH

FREEMAIN RC,LV=(0),A=(6)
DROP 6
LA
0,GMLNTH
FREEMAIN RC,LV=(0),A=(8)
DROP 8
XR
15,15
RETURN (14,12),RC=(15)

Restore save area address

of the caller of module
USER1
Length of work area and
parameter area used by
module USER2
Free storage
Length of work area used
by USER1
Free storage
Set return code zero

Figure 5-15. Performing I/O While Residing Above 16 Megabytes (Part 5 of 10)

5-42

z/OS V1R4.0 MVS Assembler Services Guide

Define DSECTs and constants for module to module communication. Define constants used to
communicate the function module USER2 is to perform.
READ1
WRITE1
OPEN1
OPEN2
CLOSE1
CLOSE2
ANALYZE
*
ENDFILE
WORKAREA
SAVEREGS
*
SAVEAREA
SAVERSVD
SAVEBKWD
SAVEFRWD
SAVE1412
COMMAREA
*
*
FUNCTION
*
STATUS
BUFFER
WORKLNTH

DS
DC
DC
DC
DC
DC
DC
DC

0F
CR1
CW1
CO1
CO2
CC1
CC2
V(ANALYSIS)

DC
CEF
DSECT
DS
0F
EQU
DS
DS
DS
DS
DS

SAVEREGS
F
F
F
15F
0F

DS

CL2

DS
DS
EQU

CL2
CL80
*-WORKAREA

Read from file 1 opcode

Write to file 1 opcode
Open file 1 opcode
Open file 2 opcode
Close file 1 opcode
Close file 2 opcode
Address of record
analysis routine
End of file indicator
This storage exists
below 16 megabytes
Reserved
Save area for registers 14-12
Parameter area used to
communicate with module
USER2
Function to be performed
by USER2
Status of read operation
Input/output buffer
Length of this DSECT

Define DSECT work area for module USER1

DYNAREA
*
EPA
BUFFR31A
*
BUFPTR

DSECT
DS
DS

DS
DS
DS
UPDATBFR DS
*
GMLNTH EQU
END

F
CL80
0F
A
A
CL80
*-DYNAREA

This storage exists

above 16 megabytes
Address of loaded routine
Buffer - above 16
megabytes
Address of input buffer
Address of updated buffer
Updated buffer returned
by the analysis routine
Length of dynamic area

Figure 5-15. Performing I/O While Residing Above 16 Megabytes (Part 6 of 10)

Chapter 5. Understanding 31-Bit Addressing

5-43

USER2 Service Routine

*Module USER2 receives control in 24-bit addressing mode, resides below
*16 megabytes, and is called by module USER1 to perform data
*management services.
USER2
USER2
USER2
*
*
*

*
*

CSECT
AMODE 24
RMODE 24
Save the callers registers in save area provided
SAVE
BASR
USING
LR
USING

(14,12)
12,0
*,12
10,1
COMMAREA,10

Save registers
Establish base
Addressability
Save parameter area pointer
around GETMAINs
Establish parameter area
addressability

Storage will be obtained via GETMAIN for a save area that module USER2 can pass to external
routines it calls.
*
*
*
*
*
*
*
*

LA

0,WORKLNTH

GETMAIN RU,LV=(0),LOC=RES
LR

6,1

USING SAVEREGS,6
LA
0,GMLNTH

Length of the work area

required
Obtain save area storage,
which must be below
16 megabytes
Save address of obtained
storage to be used for
a save area for module
USER2
Save area addressability
Get dynamic storage for
module USER2 below
16 megabytes.

Note: This GETMAIN will only be done on the initial call to this module.
#2000
*
*
*
*
*
*
*

GETMAIN RU,LV=(0),LOC=RES
LR

8,1

USING DYNAREA,8
ST

13,SAVEBKWD

LR

9,13

LA

13,SAVEAREA

Obtain storage below

16 megabytes
Copy address of storage
obtained via GETMAIN
Base register for the
dynamic work area
Save address of callers
save area
Save callers save area
address
USER1s save area address
Note - save area is
below 16 megabytes

The GETMAIN at statement #2000 requests that storage be obtained to match the current residency mode
of module USER2. Because the module resides below 16 megabytes, storage obtained will be below 16
megabytes.
Figure 5-15. Performing I/O While Residing Above 16 Megabytes (Part 7 of 10)

5-44

z/OS V1R4.0 MVS Assembler Services Guide

Note: The following store operation is successful because module USER1 obtained save area
storage below 16 megabytes.
*

ST

13,8(9)

.
.
.
.
* Process input requests
.
.
.
.
READ1
DS
0H
.
L
13,SAVEBKWD
LM
14,12,12(13)
BSM
0,14
*
WRITE1 DS
0H
.
L
13,SAVEBKWD
LM
14,12,12(13)
BSM
0,14
*
OPEN1
DS
0H
.
L
13,SAVEBKWD
LM
14,12,12(13)
BSM
0,14
*
CLOSE1 DS
0H
.
L
13,SAVEBKWD
LM
14,12,12(13)
BSM
0,14
*
OPEN2
DS
0H
.
L
13,SAVEBKWD
LM
14,12,12(13)
BSM
0,14
*
CLOSE2 DS
0H
.
L
[Link]
LM
14,12,12(13)
BSM
0,14
*
.
.

Have callers save area

point to my save area

Read a record routine

Reload USER1s registers
Return to caller - this
instruction sets AMODE 31
Write a record routine
Reload USER1s registers
Return to caller - this
instruction sets AMODE 31
Open file 1 for input
Restore callers
Return to caller
instruction sets
Close file 1 for

registers
- this
AMODE 31
input

Restore callers registers

Return to caller - this
instruction sets AMODE 31
Open file 2 for input
Restore callers
Return to caller
instruction sets
Close file 2 for

registers
- this
AMODE 31
input

Restore callers registers

Return to caller - this
instruction sets AMODE 31

Figure 5-15. Performing I/O While Residing Above 16 Megabytes (Part 8 of 10)

Chapter 5. Understanding 31-Bit Addressing

5-45

Note: This FREEMAIN will only be done on the final call to this module.
*

LA

0,GMLNTH

FREEMAIN RC,LV=(0),A=(8)
.
.
.

Length of work area used

by USER2
Free storage

DCB END OF FILE and ERROR ANALYSIS ROUTINES

ENDFILE

*
*

DS
.
.
MVC
.
L
LM
BSM

.
.
.
.
ERREXIT1 DS
.
.
MVC
*
.
L
LM
BSM
*
*
.
.
.
.
ERREXIT2 DS
.
.
MVC
*
.
L
LM
BSM
*
*

0H

End of file encountered

STATUS,ENDFILE

Indicate end of file to

module USER1

13,SAVWBKWD
14,12,12(13)
0,14

Reload USER1s registers

Return to USER1
indicating end of file
has been encountered

0H

SYNAD error exit one

STATUS,IOERROR

Indicate I/O error to

module USER1

13,SAVWBKWD
14,12,12(13)
0,14

Reload USER1s registers

Return to USER1
indicating an I/O error
has been encountered

0H

SYNAD error exit two

STATUS,IOERROR

Indicate I/O error to

module USER1

13,SAVWBKWD
14,12,12(13)
0,14

Reload USER1s registers

Return to USER1
indicating an I/O error
has been encountered

Figure 5-15. Performing I/O While Residing Above 16 Megabytes (Part 9 of 10)

5-46

z/OS V1R4.0 MVS Assembler Services Guide

Note: Define the required DCBs that module USER2 will process. The DCBs exist in storage below
16 megabytes. The END OF DATA and SYNAD exit routines also exist in storage below 16
megabytes.
INDCB

DCB

DDNAME=INPUT1,DSORG=PS,MACRF=(GL),EODAD=ENDFILE, x
SYNAD=ERREXIT1
OUTDCB DCB DDNAME=OUTPUT1,DSORG=PS,MACRF=(PL),SYNAD=ERREXIT2
* Work areas and constants for module USER2
IOERROR DC
CIO
Constant used to indicate
*
an I/O error
ENDFILE DC
CEF
Constant used to indicate
*
end of file encountered
SAVEREGS DSECT
This storage exists
*
below 16 megabytes
SAVEAREA EQU SAVEREGS
SAVERSVD DS
F
Reserved
SAVEBKWD DS
F
SAVEFRWD DS
F
SAVE1412 DS
15F
Save area for registers 14-12
WORKLNTH EQU *-SAVEREGS
Length of dynamic area
.
.
.
.
.
COMMAREA DSECT
Parameter area used to
*
communicate with module
*
USER1
FUNCTION DS
CL2
Function to be performed
*
by USER2
STATUS DS
CL2
Status of read operation
BUFFER DS
CL80
Input/output buffer
.
.
DYNAREA DSECT
This storage exists
*
below 16 megabytes
.
.
.
.
.
.
GMLNTH EQU
*-DYNAREA
Length of dynamic area
.
.
END

Figure 5-15. Performing I/O While Residing Above 16 Megabytes (Part 10 of 10)

Understanding the Use of Central Storage

MVS programs and data reside in virtual storage that, when necessary, is backed
by central storage. Most programs and data do not depend on their real addresses.
Some MVS programs, however, do depend on real addresses and some require
these real addresses to be less than 16 megabytes. MVS reserves as much central
storage below 16 megabytes as it can for such programs and, for the most part,
handles their central storage dependencies without requiring them to make any
changes.
The system uses the area of central storage above 16 megabytes to back virtual
storage with real frames whenever it can. All virtual areas above 16 megabytes can
Chapter 5. Understanding 31-Bit Addressing

5-47

be backed with real frames above 16 megabytes. In addition, the following virtual
areas below 16 megabytes can also be backed with real frames above 16
megabytes:
v SQA
v LSQA
v Nucleus
v Pageable private areas
v Pageable CSA
v PLPA
v MLPA
v Resident BLDL
The following virtual areas are always backed with real frames below 16
megabytes:
v V=R regions
v FLPA
v Subpool 226
v Subpools 227 and 228 (unless specified otherwise by the GETMAIN macro with
the LOC parameter)
When satisfying page-fix requests, MVS backs pageable virtual pages that reside
below 16 megabytes with central storage below 16 megabytes, unless the
GETMAIN macro specifies LOC=(24,31) or the PGSER macro specifies the
ANYWHER parameter. If the GETMAIN or STORAGE macro specifies or implies a
real location of 31, MVS backs pageable virtual pages with real frames above 16
megabytes even when the area is page fixed.

Central Storage Considerations for User Programs

Among the things to think about when dealing with central storage in 31-bit
addressing mode are the use of the load real address (LRA) instruction, the use of
the LOC parameter on the GETMAIN macro, the location of the DAT-off portion of
the nucleus, and using EXCPVR to perform I/O. (EXCPVR was described in the
section Performing I/O in 31-Bit Addressing Mode.)

Load Real Address (LRA) Instruction

The LRA instruction works differently depending on addressing mode you use. In
64-bit mode, the LRA instruction results in a 64-bit real address stored in a 64-bit
GPR. In 24-bit and 31-bit modes, the LRA instruction results in a 31-bit real address
stored in a 32-bit GPR. The LRA instruction cannot be used to obtain the real
address of locations backed by real frames above 2 gigabytes in 24-bit or 31-bit
addressing mode. For those situations, use the STRAG instruction instead of LRA.
All programs that issue an LRA instruction must be prepared to handle a 31-bit
result if the virtual storage address specified could have been backed with central
storage above 16 megabytes, or a 64-bit result if the virtual storage address
specified could have been backed with central storage above 2 gigabytes. Issue
LRA only against areas that are fixed. The TPROT instruction can be used to
replace the LRA instruction when a program is using it to verify that the virtual
address is translatable and the page backing it is in real storage.

GETMAIN Macro
The LOC parameter on the RU, RC, VRU, and VRC forms of the GETMAIN macro
specifies not only the virtual storage location of the area to be obtained, but also
the central storage location when the storage is page fixed.
LOC=24 indicates that the virtual storage is to be located below 16 megabytes.
When the area is page fixed, it is to be backed with central storage below 16
megabytes.

5-48

z/OS V1R4.0 MVS Assembler Services Guide

LOC=(24,31) indicates that virtual storage is to be located below 16 megabytes

but that central storage can be located either above or below 16 megabytes, but
below 2 gigabytes.
LOC=(24,64) indicates that virtual storage is to be located below 16 megabytes
but that central storage can be located anywhere.
LOC=31 and LOC=(31,31) indicate that both virtual and central storage can be
located either above or below 16 megabytes, but below 2 gigabytes in central
storage.
LOC=(31,64) indicates that virtual storage is to be located below 2 gigabytes but
that central storage can be located anywhere.
LOC=RES indicates that the location of virtual and central storage depends on
the location (RMODE) of the GETMAIN issuer. If the issuer has an RMODE of
24, LOC=RES indicates the same thing as LOC=24; if the issuer has an
RMODE of ANY, LOC=RES indicates the same thing as LOC=31.
LOC=(RES,31) indicates that the location of virtual storage depends on the
location of the issuer but that central storage can be located anywhere below 2
gigabytes.
LOC=(RES,64) indicates that the location of virtual storage depends on the
location of the issuer but that central storage can be located anywhere.
Note: There is exception to the meaning of LOC=RES and LOC=(RES,31). A caller
residing below 16 megabytes but running with 31-bit addressing can specify
LOC=RES (either explicitly or by taking the default) or LOC=(RES,31) to
obtain storage from a subpool supported only above 16 megabytes. In this
case, the callers AMODE determines the location of the virtual storage.
LOC is optional except in the following case: A program that resides above 16
megabytes and uses the RU, RC, VRU, and VRC forms of GETMAIN must specify
either LOC=24 or LOC=(24,31) on GETMAIN requests for storage that will be used
by programs running in 24-bit addressing mode. Otherwise, virtual storage would be
assigned above 16 megabytes and 24-bit addressing mode programs could not use
it.
The location of virtual storage can also be specified on the PGSER (page services)
macro. The ANYWHER parameter on PGSER specifies that a particular virtual
storage area can be placed either above or below 16 megabytes on future
page-ins. This parameter applies to virtual storage areas where LOC=(24,31) or
LOC=(31,31) was not specified on GETMAIN.

DAT-Off Routines
The MVS/370 nucleus is mapped so that its virtual storage addresses are equal to
its central storage addresses. MVS/370 has a V=R (virtual=real) nucleus. In
contrast, the MVS/XA, MVS/ESA and OS/390 nucleus is mapped and fixed in
central storage without attempting to make its virtual storage addresses equal to its
real addresses. MVS systems that use 31-bit addressing (MVS/XA, MVS/ESA and
OS/390) save a V=F (virtual=fixed) nucleus.
Because the MVS/370 is V=R, nucleus code can turn DAT off, and the next
instruction executed is the same as it would be if DAT was still on. Because the
MVS/XA, MVS/ESA and OS/390 nucleus is not V=R, their nucleus code cannot turn
DAT-off and expect the next instruction executed to be the same as if DAT was on.

Chapter 5. Understanding 31-Bit Addressing

5-49

To allow for the execution of DAT-off nucleus code, the MVS nucleus consists of
two load modules, one that runs with DAT on and one that runs with DAT off.
Nucleus code that needs to run with DAT off must reside in the DAT-off portion of
the nucleus.
When the system is initialized, the DAT-off portion of the nucleus is loaded into the
highest contiguous central storage. Therefore, you must modify any user modules in
the nucleus that run with DAT off so that they operate correctly above 16
megabytes. Among the things you may have to consider are:
v All modules in the DAT-off portion of the nucleus have the attributes AMODE 31,
RMODE ANY. They may reside above 16 megabytes.
v These modules must return control via a BSM 0,14.
v Register 0 must not be destroyed on return.
To support modules in the DAT-off nucleus:
v Move the DAT-off code to a separate module with AMODE 31, RMODE ANY
attributes. Use as its entry point, IEAVEURn where n is a number from 1 to 4.
(MVS reserves four entry points in the DAT-off nucleus for users.) Use BSM 0,14
as the return instruction. Do not destroy register 0.
v Code a DATOFF macro to invoke the DAT-off module:
DATOFF INDEX=INDUSRn

The value of n in INDUSRn must be the same as the value of n in IEAVEURn,

the DAT-off modules entry point.
v Link edit the DAT-off module (IEAVEURn) into the IEAVEDAT member of
[Link] (the DAT-off nucleus).
See z/OS MVS Programming: Authorized Assembler Services Guide and z/OS MVS
Programming: Authorized Assembler Services Reference ALE-DYN for more
information about modifying the DAT-off portion of the nucleus and the DATOFF
macro.

5-50

z/OS V1R4.0 MVS Assembler Services Guide

Chapter 6. Resource Control

When your program executes, other programs are executing concurrently in the
MVS multiprogramming environment. Each group of programs, including yours, is a
competitor for resources available at execution time. A resource is anything that a
program needs as it executes such as processor time, a data set, another
program, a table, or a hardware device, etc. The competitor for resources is actually
the task that represents the program.
If you subdivide a program into separate logical parts, and code it as several small
programs instead of one large program, you can make the parts execute as
separate tasks and with greater efficiency. However, you must ensure that each part
executes in correct order relative to the others:
v The WAIT, POST, and EVENTS macros introduce a strategic delay in the running
of a program. This delay forces a program to wait using an event control block
(ECB), for a particular event to occur. When the event occurs, the program can
run once again. The event can be the availability of a necessary resource.
v Pause, Release, and Transfer are services you can call, using a pause element
(PE), to synchronize task processing with minimal overhead.
Table 6-1 compares the use of the Pause, Release, and Transfer services with the
WAIT and POST macros.
This chapter also describes how your program can run in an environment in which it
must share resources with other programs.
v The ENQ and DEQ macros allow many programs to serialize use of resources,
such as data sets. The sharing of resources often requires that a program, or
many programs, enter a wait state until a requested resource becomes available.
Under certain circumstances, you might want to use the RESERVE macro
instead of ENQ to serialize use of resources.
v The GQSCAN macro allows you to obtain information about the use of
resources.
Table 6-1. Task Synchronization Techniques
Pause, Release, and Transfer

WAIT and POST

Can change the dispatchability of a task.

Can change the dispatchability of a task.

Can release a task before it is paused.

Can post a task before it waits.

An unauthorized caller can pause and release any task in An unauthorized caller can WAIT and POST any task in
the callers home address space.
the callers home address space.
A task can only pause on a single PE at a time.

A task may wait on multiple ECBs. If the wait count

numbers are posted, the task is made dispatchable.

The Transfer service can simultaneously pause one task

and release another.

There is no single service with comparable capability for

WAIT and POST.

The Transfer service can release a task and immediately

pass control to the released task.

There is no single service with comparable capability for

WAIT and POST.

The system ensures the Pause Elements are not reused

improperly, thus avoiding improper releases caused by
unexpected termination or asynchronous ABENDs.
Ability to pass control directly from one task to another
paused task.
High performance. No local lock contentions effects.
Copyright IBM Corp. 1988, 2002

Lower performance, possible local lock contention.

6-1

Table 6-1. Task Synchronization Techniques (continued)

Pause, Release, and Transfer

WAIT and POST

Callers may use ECBLIST or EVENTS service to wait on
multiple ECBs.

Synchronizing Tasks (WAIT, POST, and EVENTS Macros)

Some planning on your part is required to determine what portions of one task are
dependent on the completion of portions of all other tasks. The POST macro is
used to signal completion of an event; the WAIT and EVENTS macros are used to
indicate that a task cannot proceed until one or more events have occurred. An
event control block (ECB) is used with the WAIT, EVENTS or POST macros; it is a
fullword on a fullword boundary, as shown in Figure 6-1.
An ECB is also used when the ECB parameter is coded in an ATTACH or
ATTACHX macro (see the z/OS MVS Programming: Assembler Services Reference
ABE-HSP for information on how to use the ATTACH or ATTACHX macro create a
new task and indicate the entry point in the program to be given control when the
new task becomes active). In this case, the control program issues the POST
macro for the event (subtask termination). Either the 24-bit (bits 8 to 31) return code
in register 15 (if the task completed normally) or the completion code specified in
the ABEND macro (if the task was abnormally terminated) is placed in the ECB as
shown in Figure 6-1. The originating task can issue a WAIT macro or EVENTS
macro with WAIT=YES parameter specifying the ECB; the task will not regain
control until after the event has taken place and the ECB is posted (except if an
asynchronous event occurs, for example, timer expiration).
0

1
W

2
P

31
completion code

Figure 6-1. Event Control Block (ECB)

When an ECB is originally created, bits 0 (wait bit) and 1 (post bit) must be set to
zero. If an ECB is reused, bits 0 and 1 must be set to zero before a WAIT, EVENTS
ECB= or POST macro can be specified. If, however, the bits are set to zero before
the ECB has been posted, any task waiting for that ECB to be posted will remain in
the wait state. When a WAIT macro is issued, bit 0 of the associated ECB is set to
1. When a POST macro is issued, bit 1 of the associated ECB is set to 1 and bit 0
is set to 0. For an EVENTS type ECB, POST also puts the completed ECB address
in the EVENTS table.
A WAIT macro can specify more than one event by specifying more than one ECB.
(Only one WAIT macro can refer to an ECB at a time, however.) If more than one
ECB is specified in a WAIT macro, the WAIT macro can also specify that all or only
some of the events must occur before the task is taken out of the wait condition.
When a sufficient number of events have taken place (ECBs have been posted) to
satisfy the number of events indicated in the WAIT macro, the task is taken out of
the wait condition.

6-2

z/OS V1R4.0 MVS Assembler Services Guide

An optional parameter, LONG=YES or NO, allows you to indicate whether the task
is entering a long wait or a regular wait. A long wait should never be considered for
I/O activity. However, you might want to use a long wait when waiting for an
operator response to a WTOR macro.
Through the LINKAGE parameter, POST and WAIT allow you to specify how the
macro passes control to the control program. You can specify that control is to be
passed by an SVC or a PC instruction.
When you issue the WAIT or POST macro and specify LINKAGE=SVC (or use the
default), your program must not be in cross memory mode. The primary, secondary,
and home address spaces must be the same, your program must be in primary
ASC mode, and it must not have an enabled unlocked task (EUT) functional
recovery routine (FRR) established. You may use WAIT and POST when the
primary and the home address spaces are different by specifying
LINKAGE=SYSTEM. This option generates a PC interface to the WAIT or POST
service and requires that the program be enabled, unlocked, in primary ASC mode
and, for WAIT only, in task mode. For POST, the control program assumes that the
ECB is in the primary address space. For WAIT, it assumes that the ECB is in the
home address space.
Figure 6-2 shows an example of using LINKAGE=SYSTEM. The program that runs
under TCB1 in ASN1 PCs to a program in ASN2. Now the primary address space is
ASN2 and home address space is ASN1. When the PC routine posts ECB2, it uses
LINKAGE=SYSTEM because home and primary are different. The PC routine waits
on ECB1 using LINKAGE=SYSTEM because home and primary are still different.
Note that ECB1 is in the home address space.
ASN1

ASN2

home address space

TCB1
ECB2

ECB1
PC

POST ECB2,LINKAGE=SYSTEM

WAIT ECB1,LINKAGE=SYSTEM
PR

Figure 6-2. Using LINKAGE=SYSTEM on the WAIT and POST Macros

Synchronizing Tasks (Pause, Release, and Transfer)

Pause, Release, and Transfer (IEAVPSE, IEAVRLS, and IEAVXFR) are callable
services that enable you to synchronize task processing with minimal overhead. If
you have, for example, an application that requires two or more tasks to trade
control back and forth, these services provide efficient transfers of control.

Chapter 6. Resource Control

6-3

These services, which are available to both unauthorized and authorized callers in
Assembler as well as C or C++, use a system-managed object called a pause
element to synchronize processing of tasks. The services provide the following
functions:
v Pause the current task (Pause service IEAVPSE)
v Release a paused task (Release service IEAVRLS)
v Simultaneously release a paused task and pass control to it (Transfer service
IEAVXFR)
v Simultaneously release one paused task and pause the current work unit
(Transfer service IEAVXFR)
The services use a system-managed pause element (PE) rather than an
application-managed control block, such as an event control block (ECB), thus
reducing the possibility of error that might come from improper reuse of the control
block.
As a PE is much like an ECB, the Pause service is much like the WAIT macro, and
the Release service is much like the POST macro. Just as you can use POST to
keep a task from waiting by preposting, you can use Release to keep a task from
pausing by prereleasing.
The Transfer service can both release a paused task and pass control directly to
the released task. The Transfer service can also pause the task that calls the
service. Thus, Transfer enables quick dispatches, saving the overhead of work
search. It also allows two tasks to trade control back and forth with minimal
overhead.
To understand how to use the services, you need to know more about pause
elements, (PEs) and the pause element tokens (PETs) that identify them.

Pause Elements and Pause Element Tokens

A pause element (PE) is a system-managed object used to pause and release a
task. Like an ECB, a PE is used by the system to control whether or not a task is
dispatchable. You can use a PE, like an ECB, to prerelease a task before it is
paused. There are, however, significant differences between an ECB and a PE
Table 6-2 compares the two:
Table 6-2. Pause Element (PE) and Event Control Block (ECB)
Pause Element (PE)

Event Control Block (ECB)

Managed by the system.

Managed by application programs.

Identified by a pause element token (PET).

Identified by a simple address.

Cannot be reused once invalidated by an asynchronous

ABEND.

Can be reused after a task is removed from the wait state

by an asynchronous ABEND, although reuse requires
very complicated programming.

To prevent errors related to reuse, a PET can be used

There is no control on the reuse of an ECB; the same
only once to identify a PE. Once a task is paused and
ECB address can be used over and over.
released, an updated PET is needed to identify the PE.
The system returns the updated PET to the caller through
the Pause or Transfer service.
PEs are allocated and deallocated through calls to
system services.

6-4

z/OS V1R4.0 MVS Assembler Services Guide

ECBs are allocated by application programs.

Table 6-2. Pause Element (PE) and Event Control Block (ECB) (continued)
Pause Element (PE)

Event Control Block (ECB)

The maximum number of PEs available to an

The system imposes no limits on the number of ECBs.
unauthorized program is limited; an unauthorized program
in a single address space can allocate no more than
1024 PEs at any given time
PEs are not directly addressable through PETs. The user
of a PE does not know its actual address and cannot
modify it except through the use of system services.

ECBs can be modified at will by application programs.

A PE allocated with auth_level=IEA_UNAUTHORIZED can be used to pause and

release any task in the callers home address space. A caller specifying
auth_level=IEA_UNAUTHORIZED cannot pause or release using a PE allocated
with auth_level=IEA_AUTHORIZED.
A PE can be used to pause only one task at a time; the system does not allow
more then one dispatchable unit to be paused under a single PE.

Using the Services

There are five callable services available for task synchronization:
v Allocate_Pause_Element IEAVAPE
v
v
v
v

Pause IEAVPSE
Release IEAVRLS
Transfer IEAVXFR
Deallocate_Pause_Element IEAVDPE

To use Pause, Release, and Transfer, a program must first allocate a PE by calling
the Allocate_Pause_Element service. In response, the system allocates a PE and
returns a pause element token (PET) that identifies the pause element (PE).
You use the PET returned from Allocate_Pause_Element to identify the allocated
PE until either:
v The PE has been used to pause (through Pause or Transfer) and release
(through Release or Transfer) a task.
v A paused task has been released through an asynchronous ABEND.
When you are finished with the PE, call the Deallocate_Pause_Element service to
return the PE to the system. If a task is asynchronously ABENDed while it is
paused, the system itself invalidates the PE, and it cannot be reused for pause
requests. Thus, return an invalidated PE to the system as soon as possible by a
call to Deallocate_Pause_Element.
Though the PE remains allocated until you deallocate it, you can use a PET for only
one pair of calls, which result in a pause and a release of a task. When you specify
a PET on a successful call to the Pause service or to pause a task through a
successful call to the Transfer service, the system invalidates the input PET and
returns an updated PET to identify the PE. Use the updated PET to reuse the PE or
to deallocate the PE.
Figure 6-3 on page 6-6 shows, in pseudocode, the sequence of calls to allocate a
PE, pause the current task, release the task, and deallocate the PE.

Chapter 6. Resource Control

6-5

/* Common variables

*/

Dcl PET char(16);

Workunit #1
/* Workunit #1 variables
Dcl Auth1 char(4);
Dcl RC1 fixed(32);
Dcl Updated_pet char(16);
Dcl RetRelCode binary(24);
Auth1 = IEA_UNAUTHORIZED;
.
.
.
/* Allocate a Pause Element
Call IEAVAPE (RC1,Auth1,PET);

*/

*/

/* Pause Workunit #1
*/
Call IEAVPSE (RC1,Auth1,PET,
Updated_PET,RetRelCode);
/*processing pauses until released*/
.
.
.
PET = UPET;
Call IEAVPSE (RC1,Auth1,PET);
Updated_PET,RetRelCode);
/*processing pauses until released*/
.
.
.
/* Deallocate the pause element */
Call IEAVDPE (RC1,Auth1,
Updated_PET)

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

Workunit #2
/* Workunit #2 variables
Dcl Auth2 char(4);
Dcl RC2 fixed(32;
Dcl RelCode binary(24);

*/

Auth2 = IEA_UNAUTHORIZED;
.
.
.

RelCode = 123;
/* Release Workunit #1
Call IEAVRLS (RC2,Auth2,PET,
RelCode);

*/

RelCode = 345;
/* Release Workunit #1
*/
Call IEAVRLS (RC2,Auth2,PET,
RelCode);

Figure 6-3. Pause and Release Example

The Pause, Release, and Transfer services also provide a release code field that
programs can use to communicate, to indicate, for example, the reason for a
release. The program that calls the Release service can set a release code.
The release code is particularly useful when a task might be released before it is
paused (prereleased). When a subsequent call to the Pause service occurs, the
system does not pause the task; instead, it returns control immediately to the calling
program and provides the release code specified on the release call.
Figure 6-4 shows, in pseudocode, the sequence of calls needed to allocate a PE,
prerelease a task, and deallocate the PE

6-6

z/OS V1R4.0 MVS Assembler Services Guide

/* Common variables

*/

Dcl PET char(16);

Workunit #1
/* Workunit #1 variables
Dcl Auth1 fixed(32);
Dcl RC1 fixed(32);
Dcl Updated_PET char(16);
Dcl RetRelCode binary(24);

*/

Auth1 = IEA_UNAUTHORIZED;
/* Allocate a Pause Element
Call IEAVAPE (RC1,Auth1,PET);
.
.
.

*/

/* Pause Workunit #1
*/
Call IEAVPSE (RC1,Auth1,PET,
Updated_PET,RetRelCode);
/*check release code and continue */
.
.
.
/* Deallocate the pause element */
Call IEAVDPE (RC1,Auth1,
Updated_PET);

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

Workunit #2
/* Workunit #2 variables
Dcl Auth2 fixed(32);
Dcl RC2
fixed(32);
Dcl RelCode binary(24);

*/

Auth2 = IEA_UNAUTHORIZED;
RelCode =123;
/* Release Workunit #1
Call IEAVRLS (RC2,Auth2,PET,
RelCode);
.
.
.

*/

Figure 6-4. Release and Pause Example

If you make a release request (through Release or Transfer) specifying a PET that
identifies a PE that has not yet been used to pause a task, the system marks the
PE as a prereleased PE. If a program tries to pause a task using a prereleased PE,
the system returns control immediately to the caller; it does not pause the task.
Instead, it resets the PE. As soon as a PE is reset, it can be reused for another
Pause and Release, but, as stated earlier, you use the returned updated PET for
the next reused PE.
The Pause and Release services are very similar to the WAIT and POST macros,
but the Transfer service provides new function. You can use Transfer to either:
v Release a paused task and transfer control directly to the released task
v Pause the current task, release a paused task, and transfer control directly to the
released task
Figure 6-5 shows an example of using the Transfer service to release a task without
pausing the current task.
Because the Transfer service can affect multiple units of work, using Transfer
requires you to work with three PETs:
1. The current pause element token (CurrentDuPet in Figure 6-5) identifies the
allocated pause element that Transfer is to use to pause the current task (the
caller of the Transfer service). When you do not need to pause the current task,
you set this token to binary zeros, as shown in Figure 6-5.

Chapter 6. Resource Control

6-7

2. The updated pause element token (UPET2 in Figure 6-5), which the system
returns when you specify a current pause element token. You need this updated
token to reuse the pause element on a subsequent Pause or Transfer or to
deallocate the pause element. If you set the current token to binary zeros, as
done in Figure 6-5, the contents of the updated pause element token are not
meaningful.
3. The target token (TargetDuPET in Figure 6-5) identifies the allocated pause
element that Transfer is to use to release a task. In Figure 6-5, it contains the
PET that identifies the PE used to pause Workunit #1.
A current release code and a target release code are also available on the call to
Transfer. Whether or not each code contains valid data depends on conventions set
by the different parts of your program
/* Common variables

*/

Dcl PET char(16);

Workunit #1
/* Workunit #1 variables
Dcl Auth1 char(4);
Dcl RC1
char(4);
Dcl UPET1 char(16);
Dcl RetRelCode binary(24);
.
.
.
Auth1 = IEA_UNAUTHORIZED;
/* Allocate a Pause Element
Call IEAVAPE (RC1,Auth1,PET);

*/

*/

/* Pause Workunit #1
*/
Call IEAVPSE (RC1,Auth1,PET,UPET1,
RetRelCode);
/*processing pauses until transfer*/

/*processing continues

*/

/* Deallocate the Pause Element */

Call IEAVDPE (RC1,Auth1,UPET1);

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

Workunit #2
/* Workunit #2 variables
*/
Dcl Auth2 char(4);
Dcl RC2
char(4);
Dcl CurrentDuRelCode binary(24);
Dcl CurrentDuPET char(16);
Dcl UPET2 char(16);
Dcl TargetDuPET char(16);
Dcl TargetDuRelCode char(3);
Auth2 = IEA_UNAUTHORIZED;
.
.
.
TargetDuRelCode = 123;
/* no pause-set token to zeros
CurrentDuPet =B;
TargetDuPET = PET

*/

/* Transfer to Workunit #1
*/
Call IEAVXFR (RC2,Auth2,
CurrentDuPET,UPET2,
CurrentDuRelCode,
TargetDuPET,
TargetDuRelCode);
.
.
.

Figure 6-5. Transfer without Pause Example

Serializing Access to Resources (ENQ and DEQ Macros)

When one or more programs using a serially reusable resource modify the
resource, they must not use the resource simultaneously with other programs.
Consider a data area in virtual storage that is being used by programs associated
with several tasks of a job step. Some of the programs are only reading records in
the data area; because they are not updating the records, they can access the data
area simultaneously. Other programs using the data area, however, are reading,
updating, and replacing records in the data area. Each of these programs must
serially acquire, update, and replace records by locking out other programs. In

6-8

z/OS V1R4.0 MVS Assembler Services Guide

addition, none of the programs that are only reading the records want to use a
record that another program is updating until after the record has been replaced.
If your program uses a serially reusable resource, you must prevent incorrect use of
the resource. You must ensure that the logic of your program does not require the
second use of the resource before completion of the first use. Be especially careful
when using a serially reusable resource in an exit routine; because exit routines get
control asynchronously with respect to your program logic, the exit routine could
obtain a resource already in use by the main program. When more than one task is
involved, using the ENQ and DEQ macros correctly can prevent simultaneous use
of a serially reusable resource.
The ENQ macro assigns control of a resource to the current task. The control
program determines the status of the resource and does one of the following:
v If the resource is available, the control program grants the request by returning
control to the active task.
v If the resource has been assigned to another task, the control program delays
assignment of control by placing the active task in a wait condition until the
resource becomes available.
v Passes back a return code indicating the status of the resource.
v Abends the caller on unconditional requests that would otherwise result in a
non-zero return code.
When the status of the resource changes so that the waiting task can get control,
the task is taken out of the wait condition and placed in the ready condition.
The ENQ and DEQ macros work together. If used properly, ENQ/DEQ can protect
serially reusable resources. The rules for proper use of ENQ/DEQ are as follows:
v Everyone must use ENQ/DEQ.
v Everyone must use the same names and scope values for the same resources.
v Everyone must use consistent ENQ/DEQ protocol.

Naming the Resource

The ENQ and DEQ macros identify the resource by two names known as the
qname and the rname, and by a scope value. The qname and rname need not
have any relation to any actual name of the resource. The control program does not
associate a name with an actual resource; it merely processes requests having the
same qname, rname, and scope on a first-in, first-out basis. It is up to you to
associate the names with the resource by ensuring that all users of the resource
use the same qname, rname, and scope value to represent the same resource. The
control program treats requests having different qname, rname, and scope
combinations as requests for different resources. Because the control program
cannot determine the actual name of the resource from the qname, rname, and
scope, a task could use the resource by specifying a different qname, rname, and
scope combination or by accessing the resource without using ENQ. In this case,
the control program cannot provide any protection.
Choose qnames and rnames carefully. Because the control program uses SYSZ for
its qnames, the task abends if you use SYSZ as the first four characters of a
qname unless your program is APF-authorized, or in PSW keys 0-7, or in
supervisor state. Avoid using SYSA through SYSY because the control program
sometimes uses these characters for its qnames as well. Either check with your
system programmer to see which of the SYSA through SYSY combinations you can
use or avoid using SYSx (where x is alphabetic) to begin qnames.
Chapter 6. Resource Control

6-9

Defining the Scope of a Resource

You can request a scope of STEP, SYSTEM, or SYSTEMS on the ENQ and DEQ
macros.
v Use a scope of STEP if the resource is used only in your address space. The
control program uses the address space identifier to make your resource unique
in case someone else in another address space uses the same qname and
rname and a scope of STEP.
v Use a scope of SYSTEM if the resource is available to more than one address
space in the same system. All programs on that system that serialize on the
resource must use the same qname and rname and a scope of SYSTEM. For
example, to prevent two jobs from using a named resource simultaneously, use
SYSTEM.
v Use a scope of SYSTEMS if the resource is available to more than one system.
All programs that serialize on the resource must use the same qname and rname
and a scope of SYSTEMS. For example, to prevent two processors from using a
named resource simultaneously, use SYSTEMS. Note that the control program
considers a resource with a SYSTEMS scope to be different from a resource
represented by the same qname and rname but with a scope of STEP or
SYSTEM.

Local and Global Resources

The ENQ and DEQ macros recognize two types of resources: local resources and
global resources.
A local resource is a resource identified on ENQ or DEQ by a scope of STEP or
SYSTEM. A local resource is recognized and serialized only within the requesting
operating system. The local resource queues are updated to reflect each request
for a local resource. If a system is not operating under global resource serialization
(that is, the system is not part of a global resource serialization complex), all
resources requested are treated as local resources.
If a system is part of a global resource serialization complex, a global resource is
identified on the ENQ or DEQ macro by a scope of SYSTEMS. A global resource is
recognized and serialized by all systems in the global resource serialization
complex.
If your system is part of a global resource serialization complex, global resource
serialization might change the scope value during its resource name list (RNL)
processing. If the resource appears in the SYSTEM inclusion RNL, a resource with
a scope of SYSTEM can have its scope converted to SYSTEMS. If the resource
appears in the SYSTEMS exclusion RNL, a scope of SYSTEMS can have its scope
changed to SYSTEM. This important procedure is described in z/OS MVS Planning:
Global Resource Serialization.
Through the RNL parameter on ENQ and DEQ, you can request that global
resource serialization not perform RNL processing and, therefore, not change the
scope value of a resource. It is recommended that you use RNL=YES, the default,
which tells global resource serialization to perform RNL processing. Use RNL=NO
only when you are sure that you never want the scope value to change. An
example of the use of RNL=NO is in a cross-system coupling facility (XCF)
complex, where you can be certain that certain data sets always need a scope
value of SYSTEMS and other data sets always need a scope value of SYSTEM. In
a sense, RNL=NO overrides decisions your system programmer makes when that
programmer places resource names in the RNLs.

6-10

z/OS V1R4.0 MVS Assembler Services Guide

Because the RNL parameter affects the scope value of a resource, be consistent in
specifying the RNL parameter on both ENQ and DEQ. If you use the default value
on ENQ, use the default value also on DEQ.

Requesting Exclusive or Shared Control

On ENQ and DEQ, you specify either exclusive or shared control of a resource.
To request exclusive control of the resource, code E on ENQ. When your program
has exclusive control of a resource, it is the only one that can use that resource; all
other programs that issue ENQs for the resource (either for exclusive or shared
control) must wait until your program issues DEQ to release the resource. If your
program will change the resource, it should request exclusive control.
To request shared control of the resource, code S on the ENQ macro. At the same
time your program has access to the resource, other programs can have concurrent
use of the resource. If another program requests exclusive control over the
resource during the time your program has shared use of the resource, that
program will have to wait until all the current users have issued DEQ to release the
resource. If your program will not change the resource, it should request shared
control.
For an example of how the control program processes requests for exclusive and
shared control of a resource, see Processing the Requests.

Limiting Concurrent Requests for Resources

To prevent any one job, started task, or TSO/E user from generating too many
concurrent requests for resources, the control program counts and limits the
number of ENQs in each address space. When a user issues an ENQ, the control
program increases the count of outstanding requests for that address space by one
and decreases the count by one when the user issues a DEQ.
When the computed count reaches the threshold value or limit, the control program
processes subsequent requests as follows:
v Unconditional requests (ENQs that use the RET=NONE option) are abnormally
ended with a system code of X'538'.
v Conditional requests (ENQs that specify the RET=HAVE or RET=USE option) are
rejected and the user receives a return code of X'18'.

Processing the Requests

The control program constructs a unique list for each qname, rname, and scope
combination it receives. When a task makes a request, the control program
searches the existing lists for a matching qname, rname, and scope. If it finds a
match, the control program adds the tasks request to the end of the existing list;
the list is not ordered by the priority of the tasks on it. If the control program does
not find a match, it creates a new list, and adds the tasks request as the first (and
only) element. The task gets control of the resource based on the following:
v The position of the tasks request on the list
v Whether or not the request was for exclusive or shared control
The best way to describe how the control program processes the list of requests for
a resource is through an example. Figure 6-6 shows the status of a list built for a
qname, rname, and scope combination. The S or E next to the entry indicates that
the request was for either shared or exclusive control. The task represented by the
first entry on the list always gets control of the resource, so the task represented by
Chapter 6. Resource Control

6-11

ENTRY1 (Figure 6-6, Step 1) is assigned the resource. The request that established
ENTRY2 (Figure 6-6, Step 1) was for exclusive control, so the corresponding task is
placed in the wait condition, along with the tasks represented by all the other
entries in the list.
ENTRY1 (S)
ENTRY2 (E)

ENTRY2 (E)

ENTRY3 (S)

ENTRY3 (S)

ENTRY3 (S)

ENTRY4 (S)

ENTRY4 (S)

ENTRY4 (S)

ENTRY5 (E)

ENTRY5 (E)

ENTRY5 (E)

ENTRY6 (S)

ENTRY6 (S)

ENTRY6 (S)

Step 1

Step 2

Step 3

Figure 6-6. ENQ Macro Processing

Eventually, the task represented by ENTRY1 uses DEQ to release control of the
resource, and the ENTRY1 is removed from the list. As shown in Figure 6-6, Step
2, ENTRY2 is now first on the list, and the corresponding task is assigned control of
the resource. Because the request that established ENTRY2 was for exclusive
control, the tasks represented by all the other entries in the list remain in the wait
condition.
Figure 6-6, Step 3, shows the status of the list after the task represented by
ENTRY2 releases the resource. Because ENTRY3 is now at the top of the list, the
task represented by ENTRY3 gets control of the resource. ENTRY3 indicates that
the resource can be shared, and, because ENTRY4 also indicates that the resource
can be shared, ENTRY4 also gets control of the resource. In this case, the task
represented by ENTRY5 does not get control of the resource until both the tasks
represented by ENTRY3 and ENTRY4 release control because ENTRY5 indicates
exclusive use.
The control program uses the following general rules in manipulating the lists:
v The task represented by the first entry in the list always gets control of the
resource.
v If the request is for exclusive control, the task is not given control of the resource
until its request is the first entry in the list.
v If the request is for shared control, the task is given control either when its
request is first in the list or when all the entries before it in the list also indicate a
shared request.
v If the request is for several resources, the task is given control when all of the
entries requesting exclusive control are first in their respective lists and all the
entries requesting shared control are either first in their respective lists or are
preceded only by entries requesting shared control.

Duplicate Requests for a Resource

A duplicate request occurs when a task issues an ENQ macro to request a
resource that the task already controls. With the second request, the system
recognizes the contradiction and returns control to the task with a non-zero return
code (for a conditional request) or abnormally ends the task (for an unconditional
request). You should design your program to ensure that a second request for a
resource made by the same task is not issued as an unconditional request until
control of the resource is released for the first use. Be especially careful when using
an ENQ macro in an exit routine.

6-12

z/OS V1R4.0 MVS Assembler Services Guide

Two specific reasons why the use of ENQ in an exit routine must be carefully
planned are:
v The exit may be entered more than once for the same task.
v An exit routine may request resources already obtained by some other process
associated with the task.
For more information on this topic, see Conditional and Unconditional Requests.

Releasing the Resource

Use the DEQ macro to release a serially reusable resource that you obtained by
using an ENQ macro. If a task tries to release a resource which it does not control,
the control program either returns a non-zero return code or abends the task. The
control program might place many tasks in a wait condition while it assigns control
of the resource to one task. Having many tasks in the wait state might reduce the
amount of work being done by the system, therefore, you should issue a DEQ
macro as soon as possible to release the resource, so that other tasks can use it. If
a task terminates without releasing a resource, the control program releases the
resource automatically.

Conditional and Unconditional Requests

Up to this point, only unconditional requests have been considered. You can,
however, use the ENQ and DEQ macros to make conditional requests by using the
RET parameter. One reason for making a conditional request is to avoid the
abnormal termination that occurs if you issue two ENQ macros for the same
resource within the same task or when a DEQ macro is issued for a resource for
which you do not have control.
The RET parameter of ENQ provides the following options:
RET=TEST

Indicates the availability of the resource is to be tested, but control

of the resource is not requested.

RET=USE

Indicates control of the resource is to be assigned to the active task

only if the resource is immediately available. If any of the resources
are not available, the active task is not placed in a wait condition.

RET=CHNG

Indicates the status of the resource specified is changed from

shared to exclusive control.

RET=HAVE

Indicates that control of the resource is requested conditionally; that

is, control is requested only if the same task does not already have
control of or an outstanding request for the same resource.

For the following descriptions, the term active task means the task issuing the
ENQ macro. No reference is intended to other tasks that might be active in other
processors of a multiprocessor.
Use RET=TEST to test the status of the corresponding qname, rname, and scope
combination, without changing the list in any way or waiting for the resource.
RET=TEST is most useful for determining if the task already has control of the
resource. It is less useful for determining the status of the list and taking action
based on that status. In the interval between the time the control program checks
the status and the time your program checks the return code and issues another
ENQ macro, another task could have been made active, and the status of the list
could have changed.

Chapter 6. Resource Control

6-13

Use RET=USE if you want your task to receive control of the resource only if the
resource is immediately available. If the resource is not immediately available, no
entry will be made on the list and the task will not be made to wait. RET=USE is
most useful when there is other processing that can be done without using the
resource. For example, by issuing a preliminary ENQ with RET=USE in an
interactive task, you can attempt to gain control of a needed resource without
locking your terminal session. If the resource is not available, you can do other
work rather than enter a long wait for the resource.
Use RET=CHNG to change a previous request from shared to exclusive control.
Use RET=HAVE to specify a conditional request for control of a resource when you
do not know whether you have already requested control of that resource. If the
resource is owned by another task, you will be put in a wait condition until the
resource becomes available.
The RET=HAVE parameter on DEQ allows you to release control and prevents the
control program from abnormally ending the active task if a DEQ attempts to
release a resource not held. If ENQ and DEQ are used in an asynchronous exit
routine, code RET=HAVE to avoid possible abnormal termination.

Avoiding Interlock
An interlock condition happens when two tasks are waiting for each others
completion, but neither task can get the resource it needs to complete. Figure 6-7
shows an example of an interlock. Task A has exclusive access to resource M, and
task B has exclusive access to resource N. When task B requests exclusive access
to resource M, B is placed in a wait state because task A has exclusive control of
resource M.
The interlock becomes complete when task A requests exclusive control of resource
N. The same interlock would have occurred if task B issued a single request for
multiple resources M and N prior to task As second request. The interlock would
not have occurred if both tasks had issued single requests for multiple resources.
Other tasks requiring either of the resources are also in a wait condition because of
the interlock, although in this case they did not contribute to the conditions that
caused the interlock.
Task A
ENQ (M,A,E,8,SYSTEM)
ENQ (N,B,E,8,SYSTEM)

Task B
ENQ (N,B,E,8,SYSTEM)
ENQ (M,A,E,8,SYSTEM)

Figure 6-7. Interlock Condition

The above example involving two tasks and two resources is a simple example of
an interlock. The example could be expanded to cover many tasks and many
resources. It is imperative that you avoid interlock. The following procedures
indicate some ways of preventing interlocks.
v Do not request resources that you do not need immediately. If you can use the
serially reusable resources one at a time, request them one at a time and
release one before requesting the next.
v Share resources as much as possible. If the requests in the lists shown in
Figure 6-7 had been for shared control, there would have been no interlock. This
does not mean you should share a resource that you will modify. It does mean

6-14

z/OS V1R4.0 MVS Assembler Services Guide

that you should analyze your requirements for the resources carefully, and not
request exclusive control when shared control is enough.
v If you need concurrent use of more than one resource, use the ENQ macro to
request control of all such resources at the same time. The requesting program
is placed in a wait condition until all of the requested resources are available.
Those resources not being used by any other program immediately become
exclusively available to the waiting program. For example, instead of coding the
two ENQ macros shown in Figure 6-8, you could code the one ENQ macro
shown in Figure 6-9. If all requests were made in this manner, the interlock
shown in Figure 6-7 could not occur. All of the requests from one task would be
processed before any of the requests from the second task. The DEQ macro can
release a resource as soon as it is no longer needed; multiple resources
requested in a single ENQ invocation can be released individually through
separate DEQ instructions.
ENQ (NAME1ADD,NAME2ADD,E,8,SYSTEM)
ENQ (NAME3ADD,NAME4ADD,E,10,SYSTEM)

Figure 6-8. Two Requests For Two Resources

ENQ (NAME1ADD,NAME2ADD,E,8,SYSTEM,NAME3ADD,NAME4ADD,E,10,SYSTEM)

Figure 6-9. One Request For Two Resources

v If the use of one resource always depends on the use of a second resource,
then you can define the pair of resources as one resource. On the ENQ and
DEQ macros, define the pair with a single rname and qname. You can use this
procedure for any number of resources that are always used in combination.
However, the control program cannot then protect these resources if they are
also requested independently. Any requests must always be for the set of
resources.
v If there are many users of a group of resources and some of the users require
control of a second resource while retaining control of the first resource, it is still
possible to avoid interlocks. In this case, each user should request control of the
resources in the same order. For instance, if resources A, B, and C are required
by many tasks, the requests should always be made in the order of A, B, and
then C. An interlock situation will not develop, since requests for resource A will
always precede requests for resource B.

Serializing Access to Resources through the RESERVE Macro

When different systems in your installation access data sets on shared DASD, you
can use the ENQ macro with a scope of SYSTEMS to serialize access to those
resources. However, you might want to use the RESERVE macro to serialize
access when:
v Global resource serialization is not active
v Your installation is not using SMS to manage the shared data sets.
The RESERVE macro provides many of the same functions as ENQ, but can
increase contention for resources and the possibility of interlocks. If you use the
RESERVE macro to serialize access to data sets on shared DASD, use the DEQ
macro to release the resource.

Chapter 6. Resource Control

6-15

Collecting Information about Resources and Their Requestors

(GQSCAN Macro)
Global resource serialization enables an installation to share symbolically named
resources. Programs issue the ENQ and RESERVE macros to request access to
resources; global resource serialization adds information about each requestor to
the appropriate resource queue. The only way you can extract information from the
resource queues is by using the GQSCAN macro.
Using GQSCAN, you can inquire about a particular scope of resources (such as
STEP, SYSTEM, or SYSTEMS), a specific resource by name, a specific systems
resources, a specific address spaces resources, or resources requested through
the RESERVE macro. The system collects the information you request from the
resource queues and consolidates that information before returning it. The
information returned might not reflect changes in the resource queue that occur
while the system collects the information.
The system returns the information you request in an area whose location and size
you specify using the AREA parameter. The size of the area, the scope of the
resource, and whether you code the TOKEN parameter determine the information
you receive from GQSCAN. Use the TOKEN parameter when you design your
program to issue repeated calls to GQSCAN for the same request. For example, if
you request information about a resource that is shared across systems, the
amount of information might be more than will fit in the area that you provide. Using
the TOKEN parameter allows you to issue subsequent calls to receive additional
information about that resource.

How GQSCAN Returns Resource Information

GQSCAN returns the information in the form of resource information blocks (RIB)
and resource information block extensions (RIBE), as shown below. The RIB and
the RIBE are described in z/OS MVS Data Areas, Vol 4 (RD-SRRA).

RIB
A

Resource Information block (RIB) describes a resource

RIB extension (RIBE) describes resource requestor

RIBE
A1
RIBE
A2
RIBE
A3
RIB
B
RIBE
B1
RIBE
B2

In the RIB, the following fields contain information on RIBEs:

v RIBTRIBE contains the total number of RIBEs associated with this RIB.

6-16

z/OS V1R4.0 MVS Assembler Services Guide

v RIBNRIBE contains the total number of RIBEs associated with this RIB that
GQSCAN could fit into the area specified on the AREA parameter.
v RIBEDEVN contains a 4-digit EBCDIC device number for RESERVEs issued on
the system. For RESERVEs issued on other systems, RIBEDEVN contains zero.
If the value in RIBNRIBE is less than the value in RIBTRIBE, you may need to
specify a larger area with the AREA parameter.
The number of RIBs and RIBEs you receive for a particular resource depends on
the size of the area you provide, and the scope and token values you specify on
the GQSCAN macro.

How Area Size Determines the Information GQSCAN Returns

The size of the area you provide must be large enough to hold one RIB and at least
one of its associated RIBEs; otherwise, you might lose information about resource
requestors, or you might have to call GQSCAN repeatedly to receive all of the
information you requested. To determine whether you have received all RIBEs for a
particular RIB, check the values in the RIBTRIBE and RIBNRIBE fields. To
determine whether you have received all of the information on the resource queue,
check the return code from GQSCAN.
IBM recommends that you use a minimum area size of 1024 bytes.
The information that GQSCAN returns in the area also depends on what values you
specify for the SCOPE and TOKEN parameters.

How Scope and Token Values Determine the Information

GQSCAN Returns
Table 6-3 summarizes the possible values and the information returned for a
GQSCAN request.
Table 6-3. GQSCAN Results with a Scope of STEP, SYSTEM, SYSTEMS, or ALL
GQSCAN
Invocation

TOKEN Parameter Information Returned

Coded?

Initial call

No

At least the first RIB that represents the first

requestor on the resource queue, and as many
of that RIBs associated RIBEs as will fit. Any
RIBEs that do not fit are not returned to the
caller.
If all of the RIBEs fit, GQSCAN returns the next
RIB on the resource queue, as long as the
remaining area is large enough to hold that RIB
and at least one of its RIBEs.

Yes; value is zero

At least the first RIB that represents the first

requestor on the resource queue, and as many
of that RIBs associated RIBEs as will fit. Any
RIBEs that do not fit are not returned to the
caller.
If all of the RIBEs fit, GQSCAN returns the next
RIB on the resource queue, as long as the
remaining area is large enough to hold that RIB
and all of its RIBEs.

Chapter 6. Resource Control

6-17

Table 6-3. GQSCAN Results with a Scope of STEP, SYSTEM, SYSTEMS, or

ALL (continued)
GQSCAN
Invocation

TOKEN Parameter Information Returned

Coded?

Subsequent call

No

At least the first RIB that represents the first

requestor on the resource queue, and as many
of that RIBs associated RIBEs as will fit. Any
RIBEs that do not fit are not returned to the
caller.
If all of the RIBEs fit, GQSCAN returns the next
RIB on the resource queue, as long as the
remaining area is large enough to hold that RIB
and at least one of its RIBEs.

Yes; value is the

token value
returned by
GQSCAN on the
preceding call

At least the next RIB on the resource queue, with

as many of that RIBs associated RIBEs as will
fit. Any RIBEs that do not fit are not returned to
the caller.
If all of the RIBEs fit, GQSCAN returns the next
RIB on the resource queue, as long as the
remaining area is large enough to hold that RIB
and all of its RIBEs.

The example in Figure 6-10 shows the area contents for three requests. For each
request, the caller specified the TOKEN parameter and one of the following for the
scope value: STEP, SYSTEM, SYSTEMS, or ALL. Assume that the resource queue
contains information about four resources: A, which has three requestors; B, which
has six; C, which has two; and D, which has one.

First return
RIB

Second return
RIB

Third return
RIB

3 RIBEs total
3 here

6 RIBEs total
5 here

2 RIBEs total
2 here

RIBE A1

RIBE B1

RIBE C1

RIBE A2

RIBE B2

RIBE C2

RIBE A3

RIBE B3

RIB D
1 RIBEs total
1 here

RIBE B4
RIBE B5

RIBE D1

Figure 6-10. Work Area Contents for GQSCAN with a Scope of STEP, SYSTEM, SYSTEMS,
or ALL

Note that, because the specified area is not large enough, the caller cannot receive
all of the RIBEs associated with resource B, even though the caller coded the
TOKEN parameter. To receive all of those RIBEs, the caller has to specify a larger
area and reissue the GQSCAN request.

6-18

z/OS V1R4.0 MVS Assembler Services Guide

When scanning the information returned, you must use the size of the fixed portion
of the RIB and the RIBE that is returned in register 0. The size of the fixed portion
of the RIB (RIBLEN) is in the high-order half of register 0, and the size of the RIBE
(RIBELEN) is in the low-order half.
The first RIB starts at the beginning of the workarea you specify on the AREA
parameter. To find the first RIBE, add the value of RIBLEN and the variable portion
of RIB (as found in the RIBVLEN field of the RIB) to the address of the workarea.
To find the second RIBE, add the value of RIBELEN to the address of the first
RIBE.
To find the second RIB, add the following to the location of the first RIB:
RIBLEN + RIBVLEN + (the number of RIBEs RIBELEN)

Chapter 6. Resource Control

6-19

6-20

z/OS V1R4.0 MVS Assembler Services Guide

Chapter 7. Program Interruption Services

Some conditions encountered in a program cause a program interruption. These
conditions include incorrect parameters and parameter specifications, as well as
exceptional results, and are known generally as program exceptions. The program
status words (PSW) program mask provide bits to control certain program
exceptions. When MVS gives control to programs, these bits are usually off,
disabling the program exceptions. However, MVS also provides the ESPIE and
SPIE services to enable program exceptions and to allow a user exit routine to
receive control when those exceptions occur. This chapter describes the use of
ESPIE and SPIE services.

Specifying User Exit Routines

By issuing the SPIE1 or ESPIE macro, you can specify your own exit routine to be
given control for one or more types of program exceptions. If you issue an ESPIE
macro, you can also pass the address of a parameter list to the exit routine. When
one of the specified program exceptions occurs in a problem state program being
executed in the performance of a task, the exit routine receives control in the key of
the active task and in the addressing mode in effect when the SPIE or ESPIE was
issued. (If a SPIE macro was issued, this is 24-bit addressing mode.) For other
program interruptions, part of the system, the recovery termination manager (RTM),
gets control. If the SPIE or ESPIE macro specifies an exception for which the
interruption has been disabled, the system enables the interruption when the macro
is issued.
If a program interruption occurs, the exit routine receives control on interrupt codes
0 through F. For the SPIE macro, the exit routine receives control only if the
interrupted program is in primary address space control (ASC) mode. For the
ESPIE macro, the exit routine receives control if the interrupted program is in either
primary or access register (AR) ASC mode. For both the SPIE and ESPIE macros,
the exit routine receives control only for interrupts that occur when the primary,
home, and secondary address spaces are the same.
The environment established by an ESPIE macro exists for the entire task, until the
environment is changed by another SPIE/ESPIE macro, or until the program
creating the ESPIE returns. Each succeeding SPIE or ESPIE macro completely
overrides specifications in the previous SPIE or ESPIE macro. You can intermix
SPIE and ESPIE macros in one program. Only one SPIE or ESPIE environment is
active at a time. If an exit routine issues an ESPIE macro, the new ESPIE
environment does not take effect until the exit routine completes.
The system automatically deletes the SPIE/ESPIE exit routine when the request
block (RB) that established the exit terminates. If a caller attempts to delete a
specific SPIE/ESPIE environment established under a previous RB, the caller is
abended with a system completion code of X'46D'. A caller can delete all previous
SPIE and ESPIE environments (regardless of the RB under which they were
established) by specifying a token of zero with the RESET option of the ESPIE
macro or an exit address of zero with the SPIE macro.
A program, executing in either 24-bit or 31-bit addressing mode in the performance
of a task, can issue the ESPIE macro. If your program is executing in 31-bit

1. The ESPIE macro is the preferred programming interface.

Copyright IBM Corp. 1988, 2002

7-1

addressing mode, you cannot issue the SPIE macro. The SPIE macro is restricted
in use to callers executing in 24-bit addressing mode in the performance of a task.
The following topics describe how to use the SPIE and ESPIE macros.

Using the SPIE Macro

The program interruption control area (PICA) and the program interruption element
(PIE) contain the information that enables the system to intercept user-specified
program interruptions established using the SPIE macro. You can modify the
contents of the active PICA to change the active SPIE environment. The PICA and
the PIE are described in the following topics.

Program Interruption Control Area

The expansion of each standard or list form of the SPIE macro contains a system
parameter list called the program interruption control area (PICA). The PICA
contains the new program mask for the interruption types that can be disabled in
the PSW, the address of the exit routine to be given control when one of the
specified interruptions occurs, and a code for interruption types (exceptions)
specified in the SPIE macro. See PICA in z/OS MVS Data Areas, Vol 3 (IVT-RCWK)
for the mapping provided by the IHAPICA mapping macro.
The system maintains a pointer (in the PIE) to the PICA referred to by the last SPIE
macro executed. This PICA might have been created by the last SPIE or might
have been created previously and referred to by the last SPIE. Before returning
control to the calling program or passing control to another program through an
XCTL or XCTLX macro, each program that issues a SPIE macro must cause the
system to adjust the SPIE environment to the condition that existed previously or to
eliminate the SPIE environment if one did not exist on entry to the program. When
you issue the standard or execute form of the SPIE macro to establish a new SPIE
environment, the system returns the address of the previous PICA in register 1. If
no SPIE/ESPIE environment existed when the program was entered, the system
returns zeroes in register 1.
You can cancel the effect of the last SPIE macro by issuing a SPIE macro with no
parameters. This action does not reestablish the effect of the previous SPIE; it does
create a new PICA that contains zeroes, thus indicating that you do not want an exit
routine to process interruptions. You can reestablish any previous SPIE
environment, regardless of the number or type of subsequent SPIE macros issued,
by using the execute form of the SPIE specifying the PICA address that the system
returned in register 1. The PICA whose address you specify must still be valid (not
overlaid). If you specify zeroes as the PICA address, the SPIE environment is
eliminated.
Figure 7-1 shows how to restore a previous PICA. The first SPIE macro designates
an exit routine called FIXUP that is to be given control if fixed-point overflow occurs.
The address returned in register 1 is stored in the fullword called HOLD. At the end
of the program, the execute form of the SPIE macro is used to restore the previous
PICA.

7-2

z/OS V1R4.0 MVS Assembler Services Guide

HOLD

.
.
SPIE
ST
.
.
L
SPIE
.
.
DC

FIXUP,(8)
1,HOLD

Provide exit routine for fixed-point overflow

Save address returned in register 1

5,HOLD
Reload returned address
MF=(E,(5)) Use execute form and old PICA address
F0

Figure 7-1. Using the SPIE Macro

Program Interruption Element

The first time you issue a SPIE macro during the performance of a task, the system
creates a program interruption element (PIE) in the virtual storage area assigned to
your job step. The system also creates a PIE whenever you issue a SPIE macro
and no PIE exists. See PIE in z/OS MVS Data Areas, Vol 3 (IVT-RCWK) for the
format of the PIE.
The PICA address in the PIE is the address of the program interruption control area
used in the last execution of the SPIE macro for the task. When control is passed
to the routine indicated in the PICA, the BC (basic control) mode old program status
word contains the interruption code in bits 16-31 (the first byte is the exception
extension code and the second is the exception code); you can test these bits to
determine the cause of the program interruption. See z/Architecture Principles of
Operations SA227832 for an explanation of the format of the old program status
word. The system stores the contents of registers 14, 15, 0, 1, and 2 at the time of
the interruption as indicated.

Using the ESPIE Macro

The ESPIE macro extends the functions of the SPIE macro to callers in 31-bit
addressing mode. The options that you can specify using the ESPIE macro are:
v SET to establish an ESPIE environment (that is, specify the interruptions for
which the user-exit routine will receive control)
v RESET to delete the current ESPIE environment and restore the SPIE/ESPIE
environment specified
v TEST to determine the active SPIE/ESPIE environment
If
v
v
v

you specify ESPIE SET, you pass the following information to the system:
A list of the program interruptions to be handled by the exit routine
The location of the exit routine
The location of a user-defined parameter list

The system returns either a token representing the previously active SPIE or ESPIE
environment, or a token of zeroes if there was none.
If you code ESPIE RESET, you pass the token, which was returned when the
ESPIE environment was established, back to the system. The SPIE or ESPIE
environment corresponding to the token is restored. If you pass a token of zero with
RESET, all SPIE and ESPIE environments are deleted.

Chapter 7. Program Interruption Services

7-3

If you specify ESPIE TEST, you will be able to determine the active SPIE or ESPIE
environment. ESPIE TEST sets return codes to indicate which type of exit is active,
if any, and if one or the other is active, provides information about the exit in a
parameter list. Refer to the TEST parameter on the ESPIE macro for a description
of the return codes, and the information that is returned in the parameter list.
If an ESPIE environment is active and you issue a SPIE macro to specify
interruptions for which a SPIE exit routine is to receive control, the system returns
the address of a system-generated PICA in register 1. Do not modify the contents
of the system-generated PICA; use the address to restore the previous ESPIE
environment.
For a data exception,an ESPIE routine will receive the DXC value in its parameter
area, and should use this value rather than the value in the Floating Point Control
(FPC) register.
If a retry is to be done, an ESPIE routine can manually change the value(s) of the
FPR(s) and FPC register. Changes to the non-volatile fields (i.e., the IEEE settings)
in the FPC register must be made carefully since this could affect the processing of
the rest of the current program, and possibly subsequent programs.

The Extended Program Interruption Element (EPIE)

The system creates an EPIE the first time you issue an ESPIE macro during the
performance of a task or whenever you issue an ESPIE macro and no EPIE exists.
The EPIE is freed when you eliminate the ESPIE environment.
The EPIE contains the information that the system passes to the ESPIE exit routine
when it receives control after a program interrupt. When the exit routine receives
control, register 1 contains the address of the EPIE. (See the topic Environment
Upon Entry to Users Exit Routine for the contents of the other registers.) The
format of the EPIE is shown in z/OS MVS Data Areas, Vol 2 (DCCB-ITZYRETC).

Environment Upon Entry to Users Exit Routine

When control is passed to your routine, the register contents are as follows:
Register 0:

Used as a work register by the system.

Register 1:

Address of the PIE or EPIE for the task that caused

the interruption.

Registers 2-13:

Unchanged.

Register 14:

Return address.

Register 15:

Address of the exit routine.

The access registers and linkage stack have the values that were current at the
time of the program interruption. Both SPIE and ESPIE exits always receive control
in primary ASC mode.

Functions Performed in User Exit Routines

Your exit routine must determine the type of interruption that occurred before taking
corrective action. Determining the type of interruption depends on whether the exit
is associated with an ESPIE or a SPIE macro.
v For an ESPIE, your exit routine can check the two-byte interruption code (the first
byte is the exception extension code and the second is the exception code) in
the second halfword of the EPIEINT field in the EPIE.

7-4

z/OS V1R4.0 MVS Assembler Services Guide

v For a SPIE, your exit routine can test bits 16 through 31 (the first byte is the
exception extension code and the second is the exception code) of the old
program status word (OPSW in BC mode)in the PIE.
Note: For both ESPIE and SPIE If you are using vector instructions and an
exception of 8, 12, 13, 14, or 15 occurs, your exit 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.
For more information about the exception extension code, see IBM System/370
Vector Operations.
Your exit routine can alter the contents of the registers when control is returned to
the interrupted program. The procedure for altering the registers also depends on
whether the exit is associated with an ESPIE or a SPIE.
v For an ESPIE exit, the exit routine can alter the contents of general purpose and
access registers 0 through 15 in the save area in the EPIE.
v For a SPIE exit, the exit routine can alter general purpose registers 14 through 2
in the register save area in the PIE. To change registers 3 through 13, the exit
routine must alter the contents of the registers themselves.
The exit routine can also alter the last four bytes of the OPSW in the PIE or EPIE.
For an ESPIE, the exit routine alters the condition code and program mask starting
at the third byte in the OPSW. By changing the OPSW, the routine can select any
return point in the interrupted program. In addition, for ESPIE exits, the routine must
set the AMODE bit of this four-byte address to indicate the addressing mode of the
interrupted program.
ESPIE exit routines can alter the ASC mode when control is returned to the
interrupted program if the EPIEVERS field in the EPIE contains a value greater than
zero. This value is set by the system. To alter the ASC mode of the interrupted
program, the exit must do the following:
v Set bit 17 of the EPIEPSW field in the EPIE. If this bit is 0 when control is
returned to the interrupted program, the program receives control in primary ASC
mode. If this bit is 1 when control is returned to the interrupted program, the
program receives control in AR ASC mode.
v Set the EPIERCTL bit in the EPIE to indicate that the ASC mode for the
interrupted program has been set by the exit routine.

Chapter 7. Program Interruption Services

7-5

7-6

z/OS V1R4.0 MVS Assembler Services Guide

Chapter 8. Providing Recovery

In an ideal world, the programs you write would run perfectly, and never encounter
an error, either software or hardware. In the real world, programs do encounter
errors that can result in the premature end of the programs processing. These
errors could be caused by something your program does, or they could be beyond
your programs control.
MVS allows you to provide something called recovery for your programs; that
means you can anticipate and possibly recover from software errors that could
prematurely end a program. To recover from these errors, you must have one or
more user-written routines called recovery routines. The general idea is that, when
something goes wrong, you have a recovery routine standing by to take over, fix the
problem, and return control to your program so that processing can complete
normally; if the problem cannot be fixed, the recovery routine would provide
information about what went wrong. If correctly set up, your recovery should, at the
very least, provide you with more information about what went wrong with your
program than you would have had otherwise.
Part of recovery is also the cleaning up of any resources your program might
have acquired. By clean up of resources, we mean that programs might need to
release storage that was obtained, release ENQs, close data sets, and so on. If
your program encounters an error before it has the opportunity to clean up
resources, your recovery routine can do the clean up.
MVS provides the recovery termination manager (RTM) to handle the process by
which recovery routines and resource managers receive control.
This chapter is devoted to explaining why you might want to provide recovery for
your programs in anticipation of encountering one or more errors, and how you go
about doing that. An important point to note is that providing recovery is something
to be considered at the design stage of your program. You should make the
decision about whether to provide recovery before you begin designing the
program. Trying to provide recovery for an existing program is much more difficult
because recovery must be an integral part of your program.
The following table provides a roadmap to the information in this chapter. If you
already understand recovery concepts you might want to skip directly to those
sections of specific interest to you.

Copyright IBM Corp. 1988, 2002

8-1

To find out about:

Consult the following section:

Understanding General Recovery

General recovery concepts, including:
v Why you would want to provide recovery. Concepts.
v What software errors result in your
recovery getting control.
v What we mean when we say a program
abnormally ends.
v The different states for a recovery routine.
v The different types of routines in a
recovery environment, and how to choose,
define, and activate the right recovery
routine.
v The basic options available to a recovery
routine.
v How routines in a recovery environment
interact.
How to write a recovery routine, including:
v What recovery routines do.
v How recovery routines communicate with
other routines and with the system.
v Special considerations when writing
different types of recovery routines.

Writing Recovery Routines on page 8-10.

The recovery environment, including:

v Register contents at various times during
recovery processing.
v Other environmental factors such as
program authorization, dispatchable unit
mode, ASC mode, and so on.

Understanding the Recovery Environment

on page 8-27.

Coding the various routines in a typical

recovery environment.

Understanding Recovery through a Coded

Example on page 8-37.

Advanced recovery topics, including:

v Intentionally invoking RTM.
v Providing multiple recovery routines.
v Providing recovery for recovery routines.
v Providing recovery for multitasking
programs

Understanding Advanced Recovery Topics

on page 8-39.

Understanding General Recovery Concepts

This section provides a general overview of recovery concepts. After reading this
section, you should understand the following:
v Why you would want to provide recovery for your programs.
v What software errors result in your recovery getting control, if you provide
recovery.
v What we mean when we say a program abnormally ends.
v The different states for a recovery routine.
v The difference between a mainline routine, a recovery routine, and a retry
routine.
v What an extended specify task abnormal exit (ESTAE-type)recovery routine
is and how to choose, define, and activate the appropriate one.
v The difference between what it means to retry and what it means to percolate.
v How routines in a recovery environment interact.

8-2

z/OS V1R4.0 MVS Assembler Services Guide

Deciding Whether to Provide Recovery

MVS does all that it can to ensure the availability of programs, and to protect the
integrity of system resources. However, MVS cannot provide effective recovery for
every individual application program, so programs need recovery routines of their
own.
To decide whether you need to provide recovery for a particular program, and the
amount of recovery to provide, you should:
v Determine what the consequences will be if the program encounters an error and
ends.
v Compare the cost of tolerating those consequences to the cost of providing
recovery.
In general, if you have a large, complex program upon which a great number of
users depend, such as a subsystem, a database manager, or any application that
provides an important service to many other programs or end users, you will almost
certainly want to provide recovery. For small, simple programs upon which very few
users depend, you might not get enough return on your investment. Between these
two extremes is a whole spectrum of possibilities.
Consider the following points in making your decision. Providing recovery:
v Increases your programs availability.
Depending on the nature of the error, your recovery routine might successfully
correct the error and allow your program to continue processing normally.
Maintaining maximum availability is one of the major objectives of providing
recovery.
v Is a way to protect both system and application resources.
In general, recovery routines should clean up any resources your program is
holding that might be requested by another program, or another user of your
program. The purpose of clean up is to:
Allow your program to run again successfully without requiring a re-IPL
Allow the system to continue to run other work (consider especially other work
related to the failing program).
Virtual storage and ENQs are examples of important resources shared by other
programs. A program should provide for the release of these resources if an error
occurs so that other programs can access them.
Note: ENQs are used for serialization. See Chapter 6, Resource Control on
page 6-1 for more information about serialization.
Recovery routines should also ensure the integrity of any data being accessed.
Consider the case of a database application that is responsible for protecting its
database resources. The application must ensure the integrity and consistency of
the data in the event an error occurs. Data changes that were made prior to the
error might have to be backed out from the database.
v Provides for communication between different processes.
An example of this would be a task that sends a request to another task. If the
second task encounters an error, a recovery routine could inform the first task
that its request will not be fulfilled.

Chapter 8. Providing Recovery

8-3

When dealing with a multi-tasking environment, you must plan your recovery in
terms of the multiple tasks involved. You must have a cohesive scheme that
provides recovery for the set of tasks rather than thinking only in terms of a
single task.
v Is a way to help you determine what went wrong when an error occurs in
your program.
Recovery routines can do such things as save serviceability data and request
dumps to help determine what went wrong in your program. These actions are
explained in greater detail later in this chapter.
v Facilitates validity checking of user parameters.
Consider the case of a program that must verify input from its callers. The
program does parameter validation, but might not catch all variations. For
example, the caller might pass the address of an input data area that appears to
be valid; however, the caller did not have access to that storage. When the
program attempts to update the data area, a protection exception occurs. A
recovery routine could intercept this error, and allow the program to pass back a
return code to the caller indicating the input was not valid.
Providing recovery in a case like this improves the reliability of your program.
If you do not provide recovery for your program, and your program encounters an
error, MVS handles the problem to some extent, but the result is that your program
ends before you expected it to, and application resources might not be cleaned up.

Understanding Errors in MVS

Certain errors, which your program or the system can detect, trigger the system to
interrupt your program and pass control to your recovery routine (or routines) if you
have any; if you do not have any recovery routines, the system abnormally ends
your program. This chapter uses the term abnormal end when your program ends
for either of the following reasons:
v Your program encounters an error for which it has no recovery routines
v Your program encounters an error for which its recovery routines are not
successful.
The errors for which you, or the system, might want to interrupt your program are
generally those that might degrade the system or destroy data.
The following are some examples of errors that would cause your recovery routine
(if you have one) to get control:
v Unanticipated program checks (except those resolved by SPIE or ESPIE
routines; see Chapter 7, Program Interruption Services on page 7-1 for
information about SPIE and ESPIE routines.)
v Machine checks (such as a storage error that occurs while your program is
running)
v Various types of CANCEL (such as operator or time out)
v An error when issuing an MVS macro or callable service (for example, specifying
parameters that are not valid)
Each of the above errors has associated with it one or more system completion
codes. All system completion codes are described in z/OS MVS System Codes.
You can write your recovery routine to specifically handle one or more of these
system completion codes, or define your own user completion codes and handle
one or more of them. Completion codes associated with errors are also referred to
as abend codes.

8-4

z/OS V1R4.0 MVS Assembler Services Guide

As stated earlier, the system can detect errors, but your program also can detect
errors and request that the system pass control to recovery routines. To do so, your
program can issue the ABEND macro.
Use the ABEND macro to request recovery processing on behalf of the current unit
of work. Your program might choose to issue the ABEND macro if it detects an
impossible or illogical situation and cannot proceed further. For example, your
program might be passed parameters that are not valid, or might detect something
in the environment that is not valid. Your program might also choose to issue the
ABEND macro so that its recovery routine can get control to save serviceability
information.

Understanding Recovery Routine States

In this chapter we talk about recovery routines being in one of the following states:
v Defined
A recovery routine is defined when you make it known to the system. For
example, you might issue a macro on which you specify a particular recovery
routine. At the point of issuing that macro, the recovery routine is defined to the
system.
v Activated
A recovery routine is activated when it is available to receive control; if an error
occurs, the system can pass control to an activated recovery routine. Depending
on the type of recovery routine, it might be defined to the system but not yet
activated. Some recovery routines are both defined and activated by issuing a
single macro.
v In control
A recovery routine is in control when it is running; an error has occurred and the
system passed control to the recovery routine.
v No longer in control
A recovery routine is no longer in control when it returns control to the system.
The recovery routine returns control either by requesting to percolate or retry
(terms defined later in this chapter) and issuing a BR 14 instruction, or by
encountering an error itself.
v Deactivated
A recovery routine is deactivated when it is no longer available to receive
control; if an error occurs, the system will not pass control to a deactivated
recovery routine. Depending on the type of recovery routine, it might be
deactivated but still defined to the system. For some recovery routines, issuing a
single macro results in the routine becoming both deactivated and no longer
defined.
v No longer defined
A recovery routine is no longer defined when it is no longer known to the
system. The routine might still exist and be in virtual storage, but the system no
longer recognizes it as a recovery routine.

Understanding the Various Routines in a Recovery Environment

This chapter discusses the following different types of routines that interact in a
recovery environment:
v Mainline routine
v Recovery routine
v Retry routine (also known as a retry point)

Chapter 8. Providing Recovery

8-5

All of these routines are user-written routines. The following section provides you
with a description of each of these routines.

Mainline Routine
The mainline routine is that portion of your program that does the work, or provides
the required function. In general, the mainline routine defines and activates the
recovery routine. Before returning to its caller, the mainline should also deactivate
the recovery routine and request that it be no longer defined. When an error occurs
in the mainline routine, the system passes control to the recovery routine.

Recovery Routine
A recovery routine is the routine to which the system passes control when an error
occurs in the mainline routine. The recovery routines objective is to intercept the
error and potentially perform one or more of the following tasks:
v Eliminate or minimize the effects of the error
v Allow the mainline routine to resume normal processing
v Clean up resources
v Communicate with other programs as appropriate
v Provide serviceability data
v Request a dump
v Validate user parameters
v Provide one or more recovery routines for itself.
The recovery routine can be an entry point in your program that processes only
when an error occurs, or it can be a separate routine that gets control when the
error occurs.

Retry Routine
A retry routine is essentially an extension of the mainline routine. When an error
occurs, the system passes control to your recovery routine, which can then request
the system to pass control back to the mainline routine to resume processing. That
portion of the mainline that gets control back is referred to as the retry routine.
When the retry routine gets control, it is as if the mainline routine branched there
after encountering the error; to the mainline routine, it appears as though the error
never occurred.
The retry routine does whatever processing your mainline routine would continue
doing at that point.
Once the retry routine is running, if another error occurs, the system again passes
control to your recovery routine, just as it did when the mainline routine
encountered an error.

Choosing the Appropriate Recovery Routine

The recovery routines you can provide are called ESTAE-type recovery routines.
This section describes the different types of ESTAE-type recovery routines, and for
each type, describes how you define it, activate it, deactivate it, and request that it
no longer be defined. A summary of this information is in Table 8-1 on page 8-8.
When you provide one or more recovery routines for your program, you have the
opportunity to identify a user parameter area for the system to pass from the
mainline routine to the recovery routine. Creating such a parameter area with
information for the recovery routine is a very important part of providing recovery.
See Setting Up, Passing, and Accessing the Parameter Area on page 8-17 for
more information about what this parameter area should contain, and how to pass
it.

8-6

z/OS V1R4.0 MVS Assembler Services Guide

Define ESTAE-type recovery routines in the following ways:

v STAE, ESTAE, and ESTAEX macros
v ATTACH and ATTACHX macros with STAI and ESTAI parameters
The following describes the recovery routines you can define with each of the
above macros:
v STAE, ESTAE, and ESTAEX macros
To provide recovery to protect itself and any other programs running under the
same task, a program can issue either the STAE, ESTAE, or ESTAEX macro with
the CT parameter. Each of these macros both defines and activates the recovery
routine. The recovery routine is defined and activated until one of the following
events occurs:
You deactivate it and request that it be no longer defined (issue STAE 0,
ESTAE 0, or ESTAEX 0).
The recovery routine fails to or chooses not to retry (explained under
Understanding Recovery Routine Options on page 8-8).
The request block (RB) under which the caller of the macro is running
terminates.
A program cannot protect other tasks with recovery routines defined through
these macros.
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. ESTAE and ESTAEX provide the same function, except that ESTAEX
can be issued in AR ASC mode. STAE is the pre-MVS/XA version of ESTAE.
The remainder of this chapter refers to the recovery routines you define and
activate through the ESTAE and ESTAEX macros as ESTAE routines or
ESTAEX routines, respectively.
v ATTACH and ATTACHX macros with STAI and ESTAI parameters
To attach a task and provide recovery to protect the attached task and all of its
subtasks, a program can issue either the ATTACH or the ATTACHX macro with
either the STAI or the ESTAI parameter. You define the recovery routine when
you issue the macro. The recovery routine is not activated until the attached task
gets control. The recovery routine remains activated as long as the attached task
is still running, or until the recovery routine fails to or chooses not to retry. The
system deactivates the recovery routine when the attached task ends. At that
point, the recovery routine is no longer defined.
The program attaching the task is not protected by the recovery defined in this
manner. Only the attached task and its subtasks are protected.
IBM recommends you always use the ESTAI, rather than the STAI, parameter
on ATTACHX, rather than ATTACH. ATTACH and ATTACHX provide the same
function, except that ATTACHX can be issued in AR ASC mode. STAI is the
pre-MVS/XA version of ESTAI.
The remainder of this chapter refers to the recovery routines you define through
ATTACHX with ESTAI as ESTAI routines. All references to the ATTACHX macro
apply also to the ATTACH macro.
In summary, ESTAE-type recovery routines include ESTAE and ESTAEX
routines, and ESTAI routines.
Note: Another ESTAE-type recovery routine that you can write is the associated
recovery routine (ARR). ARRs are associated with stacking PC routines.
Chapter 8. Providing Recovery

8-7

Only authorized programs can create the environment required to use

these routines. For information about coding ARRs, see the application
development books that are available to the programmers in your
installation that use authorized macros.

Floating Point Implications

When working under the FRR recovery routine state, the first recovery routine will
normally see the time-of-error Floating Point Registers (FPRs) and the Floating
Point Control (FPC) register. The DXC value is provided in the SDWA. It is this
value that should be used rather than the copy in the Floating Point Control register.
If control can pass to other recovery routines, and the first recovery routine modifies
any of the FPRs or FPC register, it is responsible to save and restore the
time-of-error FPRs and FPC register.
If retry is to be done, a recovery routine can (manually) change the value(s) of the
FPR(s) and FPC register. Changes to the non-volatile fields (i.e., the IEEE settings)
in the FPC register must be made carefully since this could affect the processing of
the rest of the current program, and possibly subsequent programs.

Summary of Recovery Routine States

The following table summarizes, for each type of recovery routine, when the
recovery routine is defined, activated, deactivated, and no longer defined.
Table 8-1. Summary of Recovery Routine States
Recovery routine

Defined

Activated

Deactivated

No longer defined

ESTAE

ESTAE CT

ESTAE CT

ESTAE 0

ESTAE 0

ESTAEX

ESTAEX CT

ESTAEX CT

ESTAEX 0

ESTAEX 0

ESTAI

ATTACHX ESTAI

Attached task gets

control

Attached task ends Attached task ends

Understanding Recovery Routine Options

A recovery routine has two basic options: the routine can either retry or it can
percolate.
Retry is the attempt to resume processing at some point in the unit of work that
encountered the error. The recovery routine does something to circumvent or repair
the error, and requests that the system pass control to a retry routine to attempt to
continue with normal processing.
Percolate is the opposite of retry. To percolate means to continue with error
processing. A recovery routine percolates under one of the following circumstances:
v The system does not allow a retry
v The recovery routine chooses not to retry, perhaps because the environment is
so damaged that the routine cannot circumvent or repair the error, or perhaps
because the recovery routine was designed only to capture serviceability data,
and is not intended to retry.
When a recovery routine percolates, the system checks to see if any other recovery
routines are activated. If so, the system passes control to that recovery routine,
which then has the option to either retry or percolate. Think of the process of
percolation, then, as the system passing control to one recovery routine after
another.
The system gives control to ESTAE-type recovery routines in the following order:

8-8

z/OS V1R4.0 MVS Assembler Services Guide

1. ESTAE-type recovery routines that are not ESTAI routines, in last-in-first-out

(LIFO) order, which means the most recently activated routine gets control first
2. ESTAI routines, in LIFO order.
Once all routines have percolated, the system proceeds to abnormally end your
program. See Providing Multiple Recovery Routines on page 8-40 for more
information about having multiple recovery routines.

Understanding How Routines in a Recovery Environment Interact

Figure 8-1 is a very simplified illustration of how routines in a recovery environment
interact. In this figure, only one recovery routine exists, and it is an ESTAE-type
recovery routine. The following sequence of events might occur:
1. The mainline routine encounters an error.
2. The system gets control.
3. The system looks for recovery routines and finds an ESTAE-type recovery
routine called ESTAEX.
4. The ESTAEX routine either retries or percolates.
a. If the ESTAEX routine retries, it returns control to a retry point in the
mainline routine. The mainline routine continues processing.
b. If the ESTAEX routine percolates, the system gets control and abnormally
ends the mainline routine.

Mainline
Routine

Error occurs The system gets control

Retry Point

End
Normally

Retry

ESTAEX
Routine
Percolate
The system abnormally
ends the mainline routine

Figure 8-1. Mainline Routine with One Recovery Routine

Figure 8-2 on page 8-10 shows a more complex situation. Several recovery routines
exist, and each one that is entered has the opportunity to retry or to percolate. The
following sequence of events might occur if all recovery routines percolate:
1. The mainline routine encounters an error.
2. The system looks for recovery routines, and finds that ESTAEX(3) was the last
one created.
3. The system gives control to ESTAEX(3) first.
4. ESTAEX(3) percolates to ESTAE(2), which percolates to ESTAI(1).

Chapter 8. Providing Recovery

8-9

5. ESTAI(1) also percolates, and no other recovery routines are activated, so the
system abnormally ends the mainline routine.
Had any of the recovery routines decided to retry, the system would have returned
control to the retry point, and the mainline routine might have ended normally.

Mainline
Routine
.
.
Retry Point
.
.
End
Normally

Error occurs
The system gets control
ESTAI(1)

ESTAI(1)
ESTAE(2)
ESTAI(1)
ESTAEX(3)
Retry

The system
gives control
to ESTAE-type
routines

All ESTAE-type routines percolate The system abnormally ends the mainline routine

Figure 8-2. Mainline Routine with Several Recovery Routines

Writing Recovery Routines

So far, this chapter has discussed general recovery concepts, including how to
decide what type of recovery you need, and how to provide that recovery. But you
have to write the recovery routines that you provide. To do so, you must understand
all of the following. Each item is described in greater detail in the sections that
follow.
v What a recovery routine is supposed to do.
So far we talked about how recovery routines can either retry or percolate. But,
they do a lot more than that. We also talked about recovery routines correcting or
repairing errors, but we have not said how exactly they go about doing that.
v How the recovery routine communicates with the mainline routine, the retry
routine, and the system.
The means of communication available to a recovery routine are:
A user parameter area, built by the mainline routine and passed to the
recovery routine.
A data area called the system diagnostic work area (SDWA), which is
provided by the system. The recovery routine communicates with the system,
with other recovery routines, and with the retry routine through the SDWA.
The recovery routine uses the SETRP macro to update information in the
SDWA.
Registers, when no SDWA is provided.

8-10

z/OS V1R4.0 MVS Assembler Services Guide

v The special considerations you must make when writing an ESTAE-type

recovery routine.
One important consideration is the presence of an SDWA. The case where an
SDWA is not provided is rare; nevertheless, when you design an ESTAE-type
recovery routine, you must allow for the possibility of not receiving an SDWA.
Special considerations for ESTAE-type recovery routines also include RB
considerations, linkage stack considerations, and outstanding I/Os at time of
failure.
Note: When an error occurs for which the system passes control to your recovery
routine, the recovery routine must be in virtual storage. It can either be an
entry point in your program, or a separate routine. You are responsible for
ensuring that the recovery routine is in virtual storage when needed.

Understanding What Recovery Routines Do

The following is a list of some of the things a recovery routine should do if the
recovery is to be effective. Each item is explained in greater detail in the sections
that follow.
The items are arranged in a way that suggests the order in which you might do
them; however, you must decide yourself the order that would work best for your
particular routine.
v Preserve the return address to the system.
v Check for the presence of an SDWA.
v Establish addressability to the parameter area passed by the mainline routine.
How you do that depends on whether an SDWA is present.
v Check the contents of important fields in the SDWA.
Determine the location of the parameter area.
Determine why the routine was entered.
Determine if this is the first recovery routine to get control.
v Check the contents of the parameter area passed by the mainline.
Determine if this is a repeated error (to avoid recursion).
Determine when and where the error occurred.
v Provide information to help determine the cause of the error:
Save serviceability data in the SDWA.
Request a dump of storage.
v Try to correct or minimize the effects of the error.
v Determine whether the recovery routine can retry, decide whether to retry or
percolate, and take the appropriate actions (such as cleaning up resources).

Saving the Return Address to the System

When writing a recovery routine, you must save the return address to the system,
which you find in general purpose register (GPR) 14. The system sets up the return
address so that the recovery routine can return, at the appropriate time, using a BR
14 instruction.

Checking for the SDWA

For an ESTAE-type recovery routine, if the system cannot obtain storage for an
SDWA, the system does not provide one. The case where an SDWA is not provided
is rare. Nevertheless, when you design an ESTAE-type recovery routine, you must
allow for the possibility of not receiving an SDWA; almost every action an
ESTAE-type recovery routine takes must be set up differently to handle the two
possibilities.
Chapter 8. Providing Recovery

8-11

To check for the presence of the SDWA, the recovery routine checks the contents
of GPR 0. If GPR 0 contains 12 (X'0C') the system could not obtain an SDWA.
When GPR 0 contains any value other than 12, an SDWA is present, and its
address is in GPR 1. When the system provides an SDWA, the system also
provides a register save area whose address is in GPR 13.
If an SDWA was not provided GPR 13 does not point to a save area, and your
routine must not use the area pointed to by GPR 13.

Establishing Addressability to the Parameter Area

The recovery routine also must establish addressability to the parameter area
passed by the mainline routine. To determine the location of the parameter area:
v If an SDWA is present, the recovery routine checks either the contents of
SDWAPARM or the contents of GPR/AR 2. GPR 2 contains the address of the
parameter area, and for AR-mode callers, AR 2 contains the ALET.
v If no SDWA is present, the recovery routine checks the contents of GPR/AR 2.
GPR 2 contains the address of the parameter area, and for AR-mode callers, AR
2 contains the ALET.
The following are examples of information a mainline routine can pass to a recovery
routine through the parameter area:
v A dynamic storage area
v An input parameter list (that is, a parameter list that might have been passed to
the mainline routine)
v The addresses of important data areas.

Checking Important Fields in the SDWA

Assuming an SDWA is present, your routine can obtain a great deal of information
from this data area. Some of the key information a recovery routine can check for in
the SDWA includes:
v Why the routine was entered.
The routine can check the SDWACMPC field, which contains the completion
code that existed when the system gave control to the routine, and the
SDWACRC field, which contains the reason code associated with the completion
code. SDWACRC contains a reason code only if the SDWARCF bit is on.
v The location of the parameter area that was passed by the mainline.
The routine can check the SDWAPARM field, which provides the information the
routine needs to locate the parameter area. The contents of this field vary
depending on the way in which the recovery was defined.
v Whether this is the first recovery routine to get control.
If the SDWAPERC bit is off, this recovery routine is the first to get control. If the
SDWAPERC bit is on, percolation has occurred.
The first recovery routine to get control usually has a more direct relationship
with the error; being the first recovery routine to get control for an error can be
an indication that the error occurred in the mainline routine that activated this
particular recovery routine, rather than in a routine that was subsequently called.
This information can be useful in determining what action the recovery routine
should take. A recovery routine is more likely to take corrective action or capture
serviceability data if it is the first to get control for an error. Subsequent recovery
routines are further removed from the error, and might limit their activities to
releasing resources, or attempting a retry if possible.

8-12

z/OS V1R4.0 MVS Assembler Services Guide

See Important Fields in the SDWA on page 8-20 for a list of some of the fields in
the SDWA, and an explanation of their contents.

Checking the Contents of the Parameter Area

Generally the mainline routine sets up a parameter area containing information for
use by the recovery routine. Key information that a recovery routine might
determine from the parameter area includes:
v When and where the error occurred
v Whether this is a repeated error.
The recovery routine can tell when and where the error occurred through
footprints, a technique explained under Deciding What to Include in the
Parameter Area on page 8-17. Footprints can help the recovery routine to avoid
getting into a loop in which the routine requests a retry, and the same error occurs
again (recursion). For example, if the recovery routine supplies a bad retry address
to the system, and the processing of the first instruction at the given address
causes a program check, the first recovery routine to get control is the one that just
requested the retry. If the recovery routine requests another retry at the same
address, the loop is created.
See Setting Up, Passing, and Accessing the Parameter Area on page 8-17 for
more information about what the parameter area can contain, and the techniques
you can use to provide the most useful information to the recovery routine.

Saving Serviceability Data

One of the objectives of providing recovery is to obtain as much information as
possible to help you determine what went wrong. The SDWA has certain areas
where the recovery routine can save such information. Your recovery routine can
update the SDWA with serviceability information in three different ways:
v By issuing the SETRP macro with the RECPARM parameter. Use the RECPARM
parameter to supply the load module name, the active CSECT name, and the
recovery routine CSECT name. See Using the SETRP Macro to Update the
SDWA on page 8-19 for more information about using SETRP.
v By issuing the VRADATA macro to update the SDWA variable recording area.
See the VRADATA macro in z/OS MVS Programming: Assembler Services
Reference IAR-XCT for more information.
v By directly manipulating other fields in the SDWA. Important fields to fill in are
SDWACID, SDWASC, SDWAMLVL, and SDWARRL. See Important Fields in the
SDWA on page 8-20 for a description of each of these fields.
Part of saving serviceability data includes providing information for dump analysis
and elimination (DAE). DAE depends on information that users provide in recovery
routines to construct symptom strings needed to describe software failures. DAE
uses these symptom strings to analyze dumps and suppress duplicate dumps as
requested. You should provide information for DAE prior to requesting a dump of
storage. See Suppressing Dumps That Duplicate Previous Dumps on page 9-2 for
more information about DAE and dump suppression.

Requesting a Dump
Your recovery routine can also request a dump of storage to help determine the
cause of the error. In most cases, the system does not automatically request dumps
on behalf of your program. To request an ABEND dump, the recovery routine can
issue the SETRP macro with the DUMP=YES parameter.
For more information about requesting dumps, see Chapter 9, Dumping Virtual
Storage (ABEND, SNAPX, SNAP, and IEATDUMP Macros) on page 9-1.
Chapter 8. Providing Recovery

8-13

Before requesting a dump of storage, the recovery routine should check the
SDWAEAS bit. The SDWAEAS bit is on when a previous recovery routine has
provided sufficient diagnostic data related to this error. The recovery routine that
analyzes the problem and captures sufficient diagnostic data is responsible for
setting the SDWAEAS bit so that subsequent recovery routines know they do not
have to capture any further data.
Note that if your program calls a system service (by issuing a macro or callable
service), that system service might encounter a user-induced error and end
abnormally. Generally, the system does not take dumps for user-induced errors. If
you require such a dump, then it is your responsibility to request one in your
recovery routine.

Correcting or Minimizing the Error

Another important activity for a recovery routine is to attempt to correct or minimize
the error. What the recovery routine actually does to correct or minimize the error
depends on what the mainline routine is doing and what the error is. Some
examples of possible situations where the recovery routine could take action are the
following:
v The mainline routine might be working with a queue of data areas. The recovery
routine might be able to scan the queue and determine if one or more of the data
areas contains information that is not valid.
For example, one of the data areas might contain an address that is not valid.
Or, the mainline routine might have set up the data areas with some sort of
validating information that could be checked, and possibly corrected. Certain data
areas might have to be deleted from the queue, or the entire queue might have
to be deleted and rebuilt.
v The mainline routine might be running under a task that is communicating with
another task when an error occurs. The recovery routine might then take the
action of alerting the other task that a problem exists, so the other task does not
wait for any further communication.
v The mainline routine might have initiated I/O, and the recovery routine might
have to ensure that the I/O completes to protect the integrity of the I/O
resources.
v The recovery routine might back out changes made to a database to ensure its
integrity.

Deciding to Retry or Percolate

Under certain circumstances (such as CANCEL), the system does not allow a retry.
The SDWACLUP bit is on when the system prohibits a retry, and off when the
system allows a retry.
If a recovery routine requests retry when it is not allowed, the system ignores the
request and continues with percolation.
A recovery routine must determine whether it will attempt a retry. The determination
might be very simple: if the SDWACLUP bit is on, retry is not even an option. But if
retry is an option, the routine must make the decision based on the information it
has gathered in the preceding steps.
By no means is a recovery routine required to attempt a retry, even when one is
permitted. The recovery routine might decide not to retry if no SDWA is present,
going on the assumption that serious problems probably exist. The routine might
make the decision based on the particular completion code it finds in SDWACMPC,
or based on information in the parameter area, or based on how successful the

8-14

z/OS V1R4.0 MVS Assembler Services Guide

routine was in determining the cause of the error and fixing it. Perhaps the
environment is so badly damaged that repair is beyond the scope of the recovery
routine.
Once the decision is made, the recovery routine now does different things
depending on whether it will retry or percolate.
Note: If the recovery routine does not specify retry or percolate, the default is to
percolate.

Recovery Routines that Retry: When a recovery routine decides to retry, it

should do the following:
v Eliminate or minimize the cause of the error with complete or partial repair, as
explained above under Correcting or Minimizing the Error on page 8-14.
v Ensure that the retry routines environment is restored. For example, restore
registers and re-establish addressability to mainline resources. See Register
Contents on Entry to a Retry Routine on page 8-30 for details about how a
recovery routine can control the register contents on entry to the retry routine.
v Know the condition of resources being held by the mainline. For example, the
routine might have to repair data structures, back out changes to data sets, and
so on.
v Indicate to the system that a retry is to be attempted. If an SDWA is present, the
recovery routine issues the SETRP macro with the RC=4 parameter to indicate
retry, and the RETADDR parameter to specify the address of the retry routine.
You can specify RC=4 even when the SDWACLUP bit is on, indicating that retry
is not allowed. If you do so, however, the system ignores the retry request.
If no SDWA is present, the recovery routine has to set a return code of 4 in GPR
15, and place the address of the retry routine in GPR 0.
v Decide whether to pass the SDWA to the retry routine, and so indicate on the
SETRP macro with the FRESDWA parameter.
What the Retry Routine Does: Once the retry routine gets control, it continues
with mainline processing, and can free resources, deactivate recovery routines, and
so on. As stated earlier, the retry routine is really an extension of the mainline
routine, and its purpose is to re-establish the mainline environment.
When the retry routine gets control, the following are true:
v The retry routine runs under the same unit of work that activated the recovery
routine. See Special Considerations for ESTAE-Type Recovery Routines on
page 8-23 for further details related to ESTAE-type recovery routines.
v The retry routine might or might not have access to the SDWA, and the recovery
routine might or might not have directed that register contents be restored for the
retry routine.
For ESTAE-type recovery routines that specify FRESDWA=YES on SETRP, the
system frees the SDWA before entering the retry routine. For ESTAE-type
recovery routines that specify RETREGS=YES, the system restores the registers
from the SDWA.
For ESTAE-type recovery routines that specify FRESDWA=NO on SETRP, the
system does not free the SDWA, and the retry routine can access it. In that
case, the retry routine also has the responsibility of freeing the storage for
the SDWA when it is no longer needed. The subpool number and length to use
to free the storage are in the SDWA, in fields SDWASPID and SDWALNTH,
respectively.

Chapter 8. Providing Recovery

8-15

Note: IBM recommends that the recovery routine use FRESDWA=YES on the
SETRP macro, thus alleviating the retry routines responsibility to free the
SDWA. If your recovery routine retries multiple times and the SDWA is not
freed, out-of-storage failures can result.
The retry routine can determine what action the recovery routine took in regard to
freeing the SDWA and restoring registers by examining the contents of GPR 0:
Table 8-2. Contents of GPR 0 on Entry to a Retry Routine
GPR 0 Contents

Meaning

The system provided an SDWA. The recovery routine specified

RETREGS=NO and FRESDWA=NO. Registers are not restored from the
SDWA, and the retry routine must free the SDWA. GPR 1 contains the
address of the SDWA.

12 (X'0C')

The system did not provide an SDWA.

20 (X'14')

The system provided an SDWA. The recovery routine specified

RETREGS=NO and FRESDWA=YES. Registers are not restored from the
SDWA, and the retry routine does not have to free the SDWA.

Value restored from

SDWA (field
SDWASR00)

The system provided an SDWA. The recovery routine specified

RETREGS=YES, and either FRESDWA=NO or FRESDWA=YES. If the
recovery routine specifies FRESDWA=NO, the recovery routine must alert
the retry routine to free the SDWA. Some sort of protocol must be
established between the recovery routine and the retry routine. For example,
the recovery routine can set a unique value in SDWASR00 (the field that
represents GPR 0 in SDWASRSV) to distinguish this case from those above
where GPR 0 contains either 0, 12, or 20. The recovery routine can pass
the address of the SDWA to the retry routine in a parameter area (use the
parameter area pointed to by SDWAPARM) or in a register (consider using
register 0).

For complete details about register contents see Understanding the Recovery
Environment on page 8-27.
v The recovery routine that requested the retry is still activated and can be entered
again, so be aware of the possibility of looping back to the same recovery
routine. That recovery routine remains activated and can be entered again unless
the recovery routine issued SETRP with REMREC=YES. If the recovery routine
specified REMREC=YES, the system deactivated that recovery routine before
giving control to the retry routine.
v Any previous recovery routines (those that percolated to the recovery routine that
requested the retry) are deactivated.
Notes:
1. You can have as many retry points in your program as needed, and you can
change the designated retry point as your mainline processing continues.
2. The retry routine can be a separate routine. The only requirement is that it must
be in virtual storage. You are responsible for ensuring that the retry routine is in
virtual storage when needed.

Recovery Routines that Percolate: When a recovery routine decides to percolate

(or takes the default), it should do the following:
v Release resources that were acquired by the mainline, such as ENQs.
v Repair the cause of the error, if possible.
v Indicate the percolate option to the system. If an SDWA is present, the recovery
routine issues the SETRP macro with the RC=0 parameter to indicate
percolation. If no SDWA is present, the recovery routine has to set a return code
of 0 in register 15.

8-16

z/OS V1R4.0 MVS Assembler Services Guide

Notes:
1. Once a recovery routine percolates, it is no longer activated; it cannot receive
control again for this error.
2. An ESTAI routine can request that the system not give control to any further
ESTAI routines by specifying RC=16 on the SETRP macro. The system then
abnormally ends the task.

Understanding the Means of Communication

An important aspect of writing a recovery routine is understanding how the recovery
routine communicates with the mainline routine, the retry routine, and the system.
This section discusses the following means of communication:
v Parameter area
The parameter area is set up by the mainline routine and passed to the recovery
routine. See Setting Up, Passing, and Accessing the Parameter Area.
v SDWA
The SDWA provides information to the recovery routine, and the recovery routine
can communicate with the system, and with subsequent recovery routines, by
placing information into the SDWA. See Using the SDWA on page 8-19.
v Registers
When a recovery routine gets control, GPR 0 indicates whether an SDWA is
available. When an SDWA is not available, the recovery routine can
communicate its recovery options to the system only through registers. Aside
from this circumstance, the recovery routine cannot use registers to
communicate with the system; the routine must use the SDWA. Also, the
mainline routine should not place information in registers and expect that
information to be in the registers when the recovery routine gets control.
Complete details about registers are in the section entitled Understanding the
Recovery Environment on page 8-27.
You should understand that communications are handled differently depending on
the following circumstances:
v Whether your recovery routine received an SDWA
v Whether the communication is with the recovery routine or with the retry routine.

Setting Up, Passing, and Accessing the Parameter Area

The primary means of communication between the mainline routine and the
recovery routine is the parameter area that the mainline sets up and passes to the
recovery routine. This section discusses:
v What your mainline routine should put into the parameter area
v How your mainline passes the parameter area to the recovery routine
v How your recovery routine accesses the parameter area.

Deciding What to Include in the Parameter Area: Your mainline routine can put
whatever information it wants in the parameter area. Remember that the object is to
provide the recovery routine with as much useful information as possible so the
recovery routine can be effective. Here are some suggestions for important
information to place in the parameter area:
v The base registers for the mainline. The recovery routine must be able to
establish addressability to whatever resources the mainline is holding.
v The addresses of all dynamically acquired storage.
v The location of a workarea for use by the recovery routine.

Chapter 8. Providing Recovery

8-17

v Indications of what resources are held or serialized, such as ENQs, data sets,
and so on.
v Footprints indicating the processing being performed by the mainline when the
error occurred. Using footprints is a technique whereby the mainline sets bits as
it goes through its processing. When the recovery routine gets control, it can
check the parameter area to see which bits have been turned on, and thus can
tell how far along the mainline was. The recovery routine can pinpoint what the
mainline was doing at the time of error. If the mainline was done with its
processing when the error occurred, the recovery routine might not need to retry,
but might just clean up resources.
v An indication of whether a retry is desired.
v The input parameter list to the mainline. When the mainline received control, it
might have received an input parameter list. The mainline can preserve this in
the parameter area intended for use by the recovery routine. The recovery
routine can then inspect the input parameter list to determine if the mainline
received input that was not valid.
v Whatever register contents (both GPRs and ARs) the mainline wants to save
(they might need to be restored upon retry).
v The location of important data areas used by the mainline. Errors often occur
because of damage to information in a data area. The recovery routine might
need to repair one or more of these data areas, and so must be able to access
them. The recovery routine might also want to include these data areas when it
specifies the areas of storage to dump.
v The addresses of any user-written routines available to repair damage. You might
have separate routines designed to scan and repair queues, repair data areas,
and so on. The recovery routine might want to call these other routines for
assistance.

Passing the Parameter Area: When you provide a recovery routine, you have the
opportunity to identify to the system the parameter area you want passed to the
recovery routine. Here are the ways to accomplish that:
v ESTAE and ESTAEX routines
Use the PARAM parameter on the ESTAE or ESTAEX macro to specify the
address of the parameter area you have constructed.
v ESTAI routines
Use the ESTAI parameter on the ATTACHX macro to specify both the address of
the recovery routine to get control, and the address of the parameter area you
have constructed.
Accessing the Parameter Area: Once the recovery routine gets control, the
routine must know how to access the parameter area. That varies according to
whether the system provided an SDWA, and according to how the recovery routine
was defined:
v SDWA is present
ESTAE macro
SDWAPARM and GPR 2 contain the address of the parameter area you
specified on the PARAM parameter on ESTAE.
ESTAEX macro
SDWAPARM contains the address of an 8-byte field, which contains the
address and ALET of the parameter area you specified on the PARAM

8-18

z/OS V1R4.0 MVS Assembler Services Guide

parameter on ESTAEX, and GPR 2 contains the address of the parameter

area you specified on the PARAM parameter on ESTAEX. AR 2 contains the
ALET qualifying the address in GPR 2.
ATTACHX macro with ESTAI parameter
SDWAPARM and GPR 2 contain the address of the parameter area you
specified on the ESTAI parameter on ATTACHX. The parameter area specified
on ATTACHX is always assumed to be in the primary address space, so for
AR-mode callers, the ALET is always zero.
v SDWA is not present
ESTAE macro
GPR 2 contains the address of the parameter area you specified on the
PARAM parameter on ESTAE.
ESTAEX macro
GPR 2 contains the address of the parameter area you specified on the
PARAM parameter on ESTAEX. AR 2 contains the ALET qualifying the
address in GPR 2.
ATTACHX macro with ESTAI parameter
GPR 2 contains the address of the parameter area you specified on the
ESTAI parameter on ATTACHX. The parameter area specified on ATTACHX is
always assumed to be in the primary address space, so for AR-mode callers,
the ALET is always zero.

Using the SDWA

The SDWA is both a means by which the recovery routine can provide information
to the system and to subsequent recovery routines, and a provider of information to
the recovery routine. To access and update the SDWA, the recovery routine must
include the IHASDWA mapping macro as a DSECT. For complete information about
the SDWA, see SDWA in z/OS MVS Data Areas, Vol 4 (RD-SRRA). The SDWA is
always in the primary address space.

Updating the SDWA: A recovery routine can update the SDWA in various ways:
v By issuing the SETRP macro (See Using the SETRP Macro to Update the
SDWA.)
v By issuing the VRADATA macro (See the VRADATA macro in z/OS MVS
Programming: Assembler Services Reference IAR-XCT and use of the VRADATA
macro in Symptoms Provided by a Recovery Routine on page 9-5.)
v By directly updating specific fields (see Important Fields in the SDWA on
page 8-20).
Using the SETRP Macro to Update the SDWA: Recovery routines issue the
SETRP macro to communicate recovery options to the system, and to save
serviceability data. The routine must have an SDWA to issue SETRP. The following
are some of the things a recovery routine can do using the SETRP macro:
v Indicate retry or percolate
Use the RC parameter on SETRP to let the system know whether the recovery
routine wants to percolate (RC=0) or retry (RC=4). If attempting a retry, the
routine must also specify a retry address on the RETADDR parameter.
For ESTAI routines, you can also specify RC=16 to ask the system not to give
control to any further ESTAI routines.
v Specify register contents for the retry routine and free the SDWA
ESTAE-type recovery routines can use parameters on the SETRP macro to
restore registers from the SDWA (RETREGS=YES), and to free the SDWA before
Chapter 8. Providing Recovery

8-19

control is given to the retry routine (FRESDWA=YES). See Register Contents on

Entry to a Retry Routine on page 8-30 for information about using the
RETREGS and FRESDWA parameters.
v Save serviceability data
Use the RECPARM parameter to supply the load module name, the active
CSECT name, and the recovery routine CSECT name.
v Change the completion and reason codes
You can specify both completion and reason code values on the ABEND macro.
The system passes these values to recovery routines in the SDWA. Recovery
routines can change the values of the completion code and the reason code by
using the SETRP macro. The COMPCOD parameter allows you to specify a new
completion code; the REASON parameter allows you to specify a new reason
code.
The reason code has no meaning by itself, but must be used together with a
completion code. To maintain meaningful completion and reason codes, the
system propagates changes to these values according to the following rules:
If a user changes both the completion code and the reason code, the system
accepts both new values.
If a user changes the reason code but not the completion code, the system
accepts the new reason code and uses the unchanged completion code.
If a user changes the completion code but not the reason code, the system
accepts the new completion code and uses a zero for the reason code.

Symptom Data Required in the SDWA for Dump Suppression: If the

installation is using DAE to suppress duplicate dumps, the recovery routine must
provide the following minimum data to enable dump suppression. See Suppressing
Dumps That Duplicate Previous Dumps on page 9-2 for more information about
dump suppression.
SDWA Field
SDWAMODN
SDWACSCT
SDWACID
SDWACIB
SDWACIDB
SDWAREXN
SDWASC

Data
Failing module name
Failing CSECT name
Product or component identifier

Example
IEAVTCXX
IEAVTC22
SCDMP

Component identifier base

Recovery routine name
Subcomponent or module subfunction

5655
IEAVTC2R
RSM-PGFIX

Important Fields in the SDWA: The following table summarizes some of the key
fields in the SDWA. Note that certain fields are in an extension of the SDWA called
SDWARC1, which is a different DSECT. Here is how to access SDWARC1:
v SDWAXPAD in the SDWA contains the address of SDWAPTRS.
v SDWAPTRS is a DSECT which contains SDWASRVP.
v SDWASRVP contains the address of SDWARC1.
The fields described below that are in SDWARC1 are:
v SDWACRC
v SDWAARER
v SDWAARSV
v SDWACID
v SDWASC
v SDWAMLVL
v SDWARRL

8-20

z/OS V1R4.0 MVS Assembler Services Guide

Table 8-3. Key Fields in the SDWA

Field Name

Use

SDWAPARM

This 4-byte field contains the address of the user parameter area that
you supply for an ESTAE-type recovery routine.
For routines defined by the ESTAEX macro, this field contains the
address of an 8-byte area. The first four bytes of this 8-byte area
contain the address of the parameter area you specified on the ESTAEX
macro; the next four bytes contain the ALET for the parameter area.

SDWACMPC

This 3-byte field contains the completion code that existed when the
system gave control to the recovery routine. The recovery routine can
change the completion code by issuing the SETRP macro with the
COMPCOD parameter. The system completion code appears in the first
twelve bits, and the user completion code appears in the second twelve
bits.

SDWARPIV

This bit tells the recovery routine that the registers and PSW at the time
of error are not available. When this bit is on, the contents of
SDWAGRSV, SDWAARER, and SDWAEC1 are unpredictable.

SDWACRC

This 4-byte field contains the reason code associated with the
completion code in SDWACMPC. The reason code is set through the
REASON parameter of the ABEND macro, and is valid only when bit
SDWARCF is on. The recovery routine may change this reason code by
specifying a new value for the REASON parameter of the SETRP
macro.
Note: This reason code is not the same as the return code that
programs may set in GPR 15 before they issue the ABEND macro.

SDWARCF

If on, this bit indicates that SDWACRC contains a reason code.

SDWAGRSV

This field contains the contents of the general purpose registers (GPRs)
0-15 as they were at the time of the error.

SDWAARER

This field contains the contents of the access registers (ARs) 0-15 as
they were at the time of the error.

SDWAEC1

This field contains the PSW that existed at the time of the error.

SDWAEC2

The contents of this field vary according to the type of recovery routine:
v For ESTAE-type recovery routines (except for ESTAI routines): If a
program establishes an ESTAE routine, and subsequently performs a
stacking operation while running under the same RB as when it
established the ESTAE routine, SDWAEC2 contains the PSW from
the linkage stack entry immediately following the entry that was
current when the ESTAE routine was established. Otherwise,
SDWAEC2 contains the current RBOPSW from the RB that activated
the recovery routine, and the PSW is the one from the time of the last
interruption of that RB that occurred while the RB was unlocked and
enabled. Bit SDWAINTF in SDWAXFLG indicates whether the
contents of SDWAEC2 are from the linkage stack (SDWAINTF is 1)
or from an RB (SDWAINTF is 0).
v For an ESTAI routine, this field contains zero.

Chapter 8. Providing Recovery

8-21

Table 8-3. Key Fields in the SDWA (continued)

Field Name
SDWASRSV

Use
The contents of this field vary according to the type of recovery routine:
v For ESTAE-type recovery routines (except for ESTAI routines): If a
program establishes an ESTAE routine, and subsequently performs a
stacking operation while running under the same RB as when it
established the ESTAE routine, SDWASRSV contains GPRs 0-15
from the linkage stack entry immediately following the entry that was
current when the ESTAE routine was established. Otherwise,
SDWASRSV contains GPRs 0-15 from the RB that activated the
recovery routine, and the GPRs are the same as they were at the
time of the last interruption of that RB that occurred while the RB was
unlocked and enabled. Bit SDWAINTF in SDWAXFLG indicates
whether the contents of SDWASRSV are from the linkage stack
(SDWAINTF is 1) or from an RB (SDWAINTF is 0).
v For an ESTAI routine, this field contains zeros.
If the recovery routine requests a retry, the system might use the
contents of this field to load the GPRs for the retry routine. See the
RETREGS parameter description in the SETRP macro in z/OS MVS
Programming: Assembler Services Reference IAR-XCT for details. To
change the contents of the GPRs for the retry routine, you must make
the changes to SDWASRSV and then issue SETRP with
RETREGS=YES. You can update the registers directly or with the RUB
parameter on SETRP.

SDWAARSV

The contents of this field depend on the type of recovery routine:

v For ESTAE-type recovery routines (except for ESTAI routines): If a
program establishes an ESTAE routine, and subsequently performs a
stacking operation while running under the same RB as when it
established the ESTAE routine, SDWAARSV contains ARs 0-15 from
the linkage stack entry immediately following the entry that was
current when the ESTAE routine was established. Otherwise,
SDWAARSV contains ARs 0-15 from the RB that activated the
recovery routine, and the ARs are the same as they were at the time
of the last interruption of that RB that occurred while the RB was
unlocked and enabled. Bit SDWAINTF in SDWAXFLG indicates
whether the contents of SDWAARSV are from the linkage stack
(SDWAINTF is 1) or from an RB (SDWAINTF is 0).
v For an ESTAI routine, this field contains zeros.
If the recovery routine requests a retry, the system might use the
contents of this field to load the ARs for the retry routine. See the
RETREGS parameter description in the SETRP macro in z/OS MVS
Programming: Assembler Services Reference IAR-XCT for details. To
change the contents of the ARs for the retry routine, you must make the
changes in SDWAARSV, and then issue SETRP with RETREGS=YES.

8-22

SDWASPID

This field contains the subpool ID of the storage used to obtain the
SDWA, for use whenever the retry routine is responsible for freeing the
SDWA.

SDWALNTH

This field contains the length, in bytes, of this SDWA, the SDWA
extensions, and the variable recording area, for use whenever the retry
routine is responsible for freeing the SDWA. (This allows the retry
routine to free the extensions along with the SDWA.)

z/OS V1R4.0 MVS Assembler Services Guide

Table 8-3. Key Fields in the SDWA (continued)

Field Name

Use

SDWACOMU

The recovery routines can use this 8-byte field to communicate with
each other when percolation occurs. The system copies this field from
one SDWA to the next on all percolations. When the field contains all
zeros, either no information is passed or the system has not been able
to pass the information.

SDWATRAN

This field contains one of the following if a translation exception

occurred:
v The valid translation exception address if the SDWATEAV bit is 1.
v The ASID of the address space in which the translation exception
occurred if the SDWATEIV bit is 1.
If both the SDWATEAV and SDWATEIV bits are 0, ignore the
SDWATRAN field.

SDWATEAR

For translation exceptions that occur in AR mode, this 1-byte field

identifies the number of the AR that the program was using when the
translation exception occurred.

SDWACLUP

If on, this bit indicates that the recovery routine cannot retry.

SDWAPERC

If on, this bit indicates that a recovery routine has already percolated for
this error.

SDWAEAS

If on, this bit indicates that a previous recovery routine provided

sufficient diagnostic information pertaining to this error. The recovery
routine providing the information is responsible for setting the bit.

SDWACID

The recovery routine can use this 5-byte field to provide the component
ID of the component involved in the error.

SDWASC

The recovery routine can use this 23-byte field to provide the name of
the component and a description of the function or subfunction involved
in the error.

SDWAMLVL

The recovery routine can use this 16-byte field to indicate the level of
the module involved in the error. The first 8 bytes contains the date
(SDWAMDAT) and the second 8 bytes contains the version
(SDWAMVRS).

SDWARRL

The recovery routine can use this 8-byte field to indicate the recovery
routines entry point label.

SDWALSLV

The recovery routine can use this 2-byte field to control the linkage
stack state upon retry. See Linkage Stack at Time of Retry on
page 8-35 for additional information.

Special Considerations for ESTAE-Type Recovery Routines

This section discusses some special considerations for writing ESTAE-type recovery
routines:
v RB considerations
v Linkage stack considerations
v Outstanding I/Os at time of failure
v Other considerations for ESTAE-type recovery routines

RB Considerations
A program must activate and deactivate ESTAE-type recovery routines under the
same RB level. If you try to deactivate an ESTAE-type recovery routine that is not
associated with your RB, you get a return code that indicates your request is not
valid.
Chapter 8. Providing Recovery

8-23

ESTAE-type recovery routines are deactivated when their associated RBs

terminate. This is important because a program expects one of its own ESTAE-type
recovery routines to get control rather than one left behind by a called program. A
program might, however, invoke a service routine that does not create an RB. If that
routine then issues an ESTAEX or ESTAE macro and fails to deactivate the
resulting ESTAE-type recovery routine, a problem could develop if the original
program encounters an error. The ESTAE-type recovery routine left behind by the
service routine would receive control rather than the ESTAE-type recovery routine
associated with the program, because the recovery routine specified by the most
recently issued ESTAE or ESTAEX macro gets control.
IBM recommends that every program that activates an ESTAE-type recovery
routine also deactivate it.
For retry from an ESTAE-type recovery routine, the retry routine runs as a
continuation of the code that activated the recovery routine. That is, the retry routine
runs under the same RB that defined the ESTAE-type recovery routine, and the
system purges all RBs created after the retry RB before giving control to the retry
routine.
Note that ESTAI is an exception; a retry request from a recovery routine defined by
the ESTAI parameter of the ATTACHX macro must run under a program request
block (PRB). The retry routine cannot run under the PRB of the routine that defined
the ESTAI routine, because that PRB is associated with a different task. The system
scans the RB queue associated with the task under which the retry is to occur,
starting with the RB that was interrupted (the newest RB). The system then uses
the following rules to select a PRB for the retry routine:
v If one or more PRBs exist that represent an ESTAE-type recovery routine, use
the newest one.
v If no PRBs exist that represent ESTAE-type recovery routines, use the newest
PRB that does not have any non-PRBs (such as SVRBs) that are older.
If the RB queue contains no PRBs at all, retry is suppressed.

Linkage Stack Considerations

Consider the following information about the linkage stack when writing an
ESTAE-type recovery routine or a retry routine, or when deactivating an
ESTAE-type recovery routine:

Recovery Routine: IBM recommends that your recovery routine not modify or
extract from the linkage stack entry that is current when the routine is entered. In
some cases, the system might prevent an ESTAE-type recovery routine from
modifying or extracting from that linkage stack entry. If your recovery routine
attempts to modify or extract from the linkage stack entry when the system does not
allow it, the result is a linkage stack exception.
IBM recommends that if your recovery routine adds entries to the linkage stack,
through a stacking PC or BAKR instruction, it should also remove them. If the
recovery routine adds entries to the stack and does not remove them, the system
recognizes an error when the recovery routine returns control. If the recovery
routine retries, the additional entries are not given to the retry routine. If the
recovery routine percolates, subsequent recovery routines receive a linkage stack
with entries more recent than the entry that was current at the time of error.

8-24

z/OS V1R4.0 MVS Assembler Services Guide

Retry Routine: When the system gives control to your retry routine, the linkage
stack level is set to the level that was current when your program activated the
recovery routine, unless the recovery routine sets the SDWALSLV field.
Deactivating an ESTAE-Type Recovery Routine: A program may deactivate an
ESTAE-type recovery routine only under the same linkage stack level as the level
that existed when the program activated the recovery routine. This rule affects
programs that add entries to the linkage stack either through the BAKR or PC
instruction. Failure to follow this rule results in an error return code of 36 from the
ESTAE or ESTAEX macro.
When you issue a PR, the system automatically deactivates all ESTAE-type
recovery routines that were previously activated under that current linkage stack
entry.

Outstanding I/Os at the Time of Failure

Before the most recently activated ESTAE-type recovery routine receives control,
the system can handle outstanding I/Os at the time of the failure. You request this
through the macro that defines the routine (that is, through the PURGE parameter
on ESTAE, ESTAEX, or ATTACHX). The system performs the requested I/O
processing only for the first ESTAE-type recovery routine that gets control.
Subsequent routines that get control receive an indication of the I/O processing
previously done, but no additional processing is performed.
Note: You should understand PURGE processing before using this parameter. For
information on where PURGE processing is documented, see z/OS DFSMS
Introduction for the version of DFP you have installed.
If there are quiesced restorable I/O operations (because you specified
PURGE=QUIESCE on the macro for the most recently defined ESTAE-type
recovery routine), the retry routine can restore them as follows:
v If the recovery routine specified FRESDWA=YES and RETREGS=NO on the
SETRP macro, or the system did not provide an SDWA, the system supplies the
address of the purged I/O restore list in GPR 2 on entry to the retry routine.
v If the recovery routine specified FRESDWA=NO and RETREGS=NO on the
SETRP macro, GPR 1 contains the address of the SDWA, and the address of
the purged I/O restore list is in the SDWAFIOB field on entry to the retry routine.
v If the recovery routine specified FRESDWA=NO and RETREGS=YES on the
SETRP macro, the recovery routine must pass the address of the SDWA to the
retry routine (in the user parameter area, or in GPR 0). The address of the
purged I/O restore list is in the SDWAFIOB field on entry to the retry routine.
v If the recovery routine specified FRESDWA=YES and RETREGS=YES on the
SETRP macro, the retry routine cannot access the purged I/O restore list, unless
the recovery routine saves the address of the purged I/O restore list from
SDWAFIOB, and passes the address to the retry routine.
The following table provides a summary of how the retry routine can access
quiesced restorable I/O operations:

Chapter 8. Providing Recovery

8-25

Table 8-4. Restoring Quiesced Restorable I/O Operations

Parameter on SETRP Macro

RETREGS=NO

RETREGS=YES

FRESDWA=YES

GPR 2 contains the address of

the purged I/O restore list (see
note below)

Retry routine cannot access the

purged I/O restore list, unless the
recovery routine saves the
address from SDWAFIOB and
passes the address to the retry
routine

FRESDWA=NO

GPR 1 contains the address of

the SDWA; SDWAFIOB contains
the address of the purged I/O
restore list

The recovery routine must pass

the address of the SDWA to the
retry routine; SDWAFIOB
contains the address of the
purged I/O restore list.

Note: If the system did not provide an SDWA and RETREGS=NO, then GPR 2 contains the address of
the purged I/O restore list.

You can use the RESTORE macro to have the system restore all I/O requests on
the list. For information about where the RESTORE macro is documented, see
z/OS DFSMS Introduction for the version of DFP you have installed.

Additional Considerations Specific to ESTAE-Type Recovery

Routines
The following are additional things you should consider that are specific to
ESTAE-type recovery routines:
v During processing of the first and all subsequent recovery routines, the system
allows or disallows asynchronous processing (such as a timer exit) depending on
how you specify the ASYNCH parameter when you define the routine (that is,
through the ASYNCH parameter on ESTAE, ESTAEX, and ATTACHX).
v The following list describes what the system does when it is done processing a
particular recovery routine (either because the recovery routine percolates, or
because the recovery routine itself encounters an error and has no recovery
routine of its own that retries):
Accumulates dump options
Resets the asynchronous exit indicator according to the request of the next
recovery routine
Ignores the I/O options for the next recovery routine
Initializes a new SDWA
Gives control to the next recovery routine.
If all recovery routines fail or percolate, the task is terminated.
v If a non-job step task issues an ABEND macro with the STEP parameter, the
system gives control to recovery routines for the non-job step task. If the
recovery routines do not request a retry, the job step is terminated with the
specified completion code. Subsequent recovery routines for the job step task get
control only when you specify TERM=YES on the macros that defined those
recovery routines. You can specify TERM=YES on ESTAE, ESTAEX, and
ATTACHX.
If the recovery routines for the job step task do not retry, subsequent recovery
routines for any other non-job step tasks get control in the same way they would
if the job step task itself encountered the error and then did not retry.
v For some situations, the system gives control to ESTAE-type recovery routines
only when the TERM=YES parameter was specified. The situations are:
System-initiated logoff

8-26

z/OS V1R4.0 MVS Assembler Services Guide

 Job step timer expiration

Wait time limit for job step exceeded
DETACH macro was issued from a higher level task (possibly by the system if
the higher level task encountered an error)
Operator cancel
Error occurred on a higher level task
Error in the job step task when a non-job step task issued the ABEND macro
with the STEP parameter
OpenMVS is canceled and the users task is in a wait in the OpenMVS kernel.
When the system gives control to the recovery routines defined with the
TERM=YES parameter as a result of the above errors, the system takes the
following actions:
Sets the SDWACLUP bit
Gives control to all such routines in LIFO order
Does not enter any ESTAI routine previously suppressed by a return code of
16, or any previously entered recovery routine that requested percolation
Ignores any request for retry.

Understanding the Recovery Environment

When you write a recovery routine, you must take into consideration a number of
environmental factors that are present when the recovery routine gets control, and
that are present when a retry routine gets control. This section discusses
environmental factors in two broad categories, distinguishing register contents from
all other environmental factors:
v Register contents.
Recovery routines are interested in register contents at the following times:
When the error occurs
When the recovery routine gets control, certain fields in the SDWA contain the
register contents at the time the error occurs. SDWAGRSV contains the
contents of the GPRs; SDWAARER contains the contents of the ARs.
On entry to and return from the recovery routine
See Register Contents on Entry to a Recovery Routine on page 8-28 and
Register Contents on Return from a Recovery Routine on page 8-29 for
details.
On entry to the retry routine
See Register Contents on Entry to a Retry Routine on page 8-30 for details.
v All other environmental factors.
The other environmental factors important in a recovery environment are:
Authorization: problem state or supervisor state, PSW key, and PSW key
mask (PKM)
SDWA storage key
Dispatchable unit mode
AMODE
ASC mode

Interrupt status
DU-AL
Program mask
Condition of the linkage stack
Chapter 8. Providing Recovery

8-27

This section discusses each of the environmental factors, and makes distinctions,
where necessary, that depend on the following:
v Whether the system provided an SDWA
v Whether you are dealing with the recovery routine or the retry routine.

Register Contents
This section describes register contents for the following:
v On entry to a recovery routine
v On return from a recovery routine (see Register Contents on Return from a
Recovery Routine on page 8-29)
v On entry to a retry routine.
The following table provides a roadmap to all the tables containing register content
information on entry to a recovery routine or on entry to a retry routine:
Table 8-5. Where to Find Register Content Information
Registers Described For:

Table and Page

Number:

ESTAE-type recovery routine with an SDWA

Table 8-6

ESTAE-type recovery routine without an SDWA

Table 8-7 on
page 8-29

Retry from an ESTAE-type recovery routine without an SDWA

Table 8-8 on
page 8-30

Retry from an ESTAE-type recovery routine with an SDWA,

RETREGS=NO, and FRESDWA=NO

Table 8-9 on
page 8-31

Retry from an ESTAE-type recovery routine with an SDWA,

RETREGS=NO, and FRESDWA=YES

Table 8-10 on
page 8-31

Retry from an ESTAE-type recovery routine with an SDWA and

RETREGS=YES

Table 8-11 on
page 8-32

Register Contents on Entry to a Recovery Routine

The register contents on entry to an ESTAE-type recovery routine are different
depending on whether the system supplied and SDWA. The following tables
describe the register contents on entry to the recovery routine for both situations.
Table 8-6. Register ContentsESTAE-Type Recovery Routine With an SDWA
Register

Contents

General Purpose Registers

GPR 0

GPR 1
GPR 2

A code indicating the type of I/O processing performed:

0

Active I/O has been quiesced and is restorable.

Active I/O has been halted and is not restorable.

No I/O was active when the abend occurred.

16 (X'10')

No I/O processing was performed.

Address of the SDWA.

One of the following:
v If you specified the PARAM parameter on ESTAE, ESTAEX, or
ATTACHX, the address of the user-supplied parameter area
v If you issued ESTAE, ESTAEX, or ATTACHX without the PARAM
parameter, zero.

8-28

z/OS V1R4.0 MVS Assembler Services Guide

Table 8-6. Register ContentsESTAE-Type Recovery Routine With an SDWA (continued)

Register

Contents

GPRs 3 - 12

Do not contain any information for use by the routine.

GPR 13

Address of a 72-byte register save area.

GPR 14

Return address to the system.

GPR 15

Entry point address of the ESTAE-type recovery routine.

Access Registers
ARs 0 - 1
AR 2

Zero
One of the following:
v If you issued the ESTAEX macro in AR ASC mode, an ALET that
qualifies the address in GPR 2.
v Otherwise, this register does not contain any information for use by the
routine.

ARs 3 - 15

Zero.

Table 8-7. Register ContentsESTAE-Type Recovery Routine Without an SDWA

Register

Contents

General Purpose Registers

GPR 0

12 (X'0C'). The system could not obtain an SDWA.

GPR 1

Completion code in bytes 1-3. The system completion code appears in the
first 12 bits, and the user completion code appears in the second 12 bits.

GPR 2

One of the following:

v If you specified the PARAM parameter on ESTAE, ESTAEX, or
ATTACHX, the address of the user-supplied parameter area
v If you issued ESTAE, ESTAEX, or ATTACHX without the PARAM
parameter, zero.

GPRs 3 - 13

Do not contain any information for use by the routine.

Note: When the system does not provide an SDWA, GPR 13 does not
contain the address of a standard 72-byte save area. In this case, your
ESTAE-type recovery routine must save the address from GPR 14 and use
it as the return address to the system.

GPR 14

Return address to the system.

GPR 15

Entry point address of the ESTAE-type recovery routine.

Access Registers
ARs 0 - 1
AR 2

Zero
One of the following:
v If you issued the ESTAEX macro in AR ASC mode, an ALET that
qualifies the address in GPR 2.
v Otherwise, this register does not contain any information for use by the
routine.

ARs 3 - 15

Zero.

Register Contents on Return from a Recovery Routine

The register contents on return from a recovery routine depend on whether the
system provided an SDWA. ESTAE-type recovery routines that receive an SDWA
can use any register without saving its contents, except GPR 14. The routines must
maintain the return address supplied in GPR 14. The routines do not have to place
any information in the registers for use by the system.
Chapter 8. Providing Recovery

8-29

ESTAE-type recovery routines that do not receive an SDWA must set one of the
following return codes in GPR 15:
Return Code

Meaning

The recovery routine requests percolation.

The recovery routine requests a retry. The recovery routine must

then place the address of the retry routine in GPR 0.

16 (X'10')

Valid only for an ESTAI recovery routine. The system should not
give control to any further ESTAI routines, and should abnormally
end the task.

Register Contents on Entry to a Retry Routine

The register contents on entry to a retry routine vary according to the following:
v Whether an SDWA is present.
v If an SDWA is present, what the recovery routine specifies on the SETRP macro.
The parameters on SETRP that affect register contents on entry to the retry routine
from an ESTAE-type recovery routine are the following:
v The RETREGS parameter controls whether registers are restored from the
SDWA. If you specify RETREGS=NO, registers are not restored from the SDWA.
If you specify RETREGS=YES, GPRs are restored from SDWASRSV, and ARs
are restored from SDWAARSV. If you specify RETREGS=YES,RUB, you can
manipulate the contents of SDWASRSV to whatever you wish the GPRs to be
before they are restored. Or, you can directly manipulate the contents of both
SDWASRSV and SDWAARSV.
See the description of the SETRP macro in z/OS MVS Programming: Assembler
Services Reference IAR-XCT for complete details.
v The FRESDWA parameter controls whether the system frees the SDWA before
giving control to the retry routine. FRESDWA=YES instructs the system to free
the SDWA; FRESDWA=NO instructs the system not to free the SDWA. This has
an affect on the register contents on entry to the retry routine.
The following tables describe the register contents under various circumstances on
entry to a retry routine from an ESTAE-type recovery routine:
Table 8-8. Register ContentsRetry from an ESTAE-Type Recovery Routine Without an
SDWA
Register

Contents

General Purpose Registers

GPR 0

12 (X'0C').

GPR 1

Address of the user parameter area.

GPR 2

Address of the purged I/O restore list if I/O was quiesced and is restorable;
otherwise, zero.

GPRs 3 - 14

Do not contain any information for use by the routine.

GPR 15

Entry point address of the retry routine.

Access Registers
AR 0

8-30

Zero.

z/OS V1R4.0 MVS Assembler Services Guide

Table 8-8. Register ContentsRetry from an ESTAE-Type Recovery Routine Without an

SDWA (continued)
Register
AR 1

Contents
One of the following:
v If the recovery routine was defined using ESTAEX and the caller was in
AR ASC mode, the ALET of the user parameter area.
v Otherwise, this register does not contain any information for use by the
routine.

ARs 2 - 13

Do not contain any information for use by the routine.

ARs 14 - 15

Zero.

Table 8-9. Register ContentsRetry from an ESTAE-Type Recovery Routine With an

SDWA, RETREGS=NO, and FRESDWA=NO
Register

Contents

General Purpose Registers

GPR 0

Zero.

GPR 1

Address of the SDWA.

GPRs 2 - 14

Do not contain any information for use by the routine.

GPR 15

Entry point address of the retry routine.

Access Registers
ARs 0 - 1

Zero.

ARs 2 - 13

Do not contain any information for use by the routine.

ARs 14 - 15

Zero.

Table 8-10. Register ContentsRetry from an ESTAE-Type Recovery Routine With an

SDWA, RETREGS=NO, and FRESDWA=YES
Register

Contents

General Purpose Registers

GPR 0

20 (X'14').

GPR 1

Address of the user parameter area.

GPR 2

Address of the purged I/O restore list, if I/O was quiesced and is
restorable; otherwise, zero.

GPRs 3 - 14

Do not contain any information for use by the routine.

GPR 15

Entry point address of the retry routine.

Access Registers
AR 0

Zero.

AR 1

One of the following:

v If the recovery routine was defined using ESTAEX and the caller was in
AR ASC mode, the ALET of the user parameter area.
v Otherwise, this register does not contain any information for use by the
routine.

ARs 2 - 13

Do not contain any information for use by the routine.

ARs 14 - 15

Zero.

Chapter 8. Providing Recovery

8-31

Table 8-11. Register ContentsRetry from an ESTAE-Type Recovery Routine With an

SDWA and RETREGS=YES
Register

Contents

General Purpose Registers

GPRs 0 - 15

Restored from SDWASRSV, regardless of whether the recovery routine

specified FRESDWA=NO or FRESDWA=YES.
Note that register 15 does not contain the entry point address of the retry
routine unless the recovery routine sets it up that way.

Access Registers
ARs 0 - 15

Restored from SDWAARSV, regardless of whether the recovery routine

specified FRESDWA=NO or FRESDWA=YES.

Other Environmental Factors in Recovery

As mentioned previously, the other environmental factors to be concerned about in
a recovery environment are:
v Authorization: problem state or supervisor state, PSW key, and PKM
v SDWA storage key
v Dispatchable unit mode
v AMODE
v ASC mode
v Interrupt status
v DU-AL
v Program mask
v Condition of the linkage stack
These environmental factors differ depending on whether you are dealing with the
recovery routine or the retry routine.

Environment on Entry to an ESTAE-Type Recovery Routine

The following is a description of each environmental factor on entry to an
ESTAE-type recovery routine.

Authorization:
v Problem or supervisor state
The ESTAE-type recovery routines you can write are entered in problem state.
v PSW key
An ESTAE-type recovery routine is entered with the PSW key that existed at the
time the recovery routine was defined.
v PKM
An ESTAE-type recovery routine is entered with the PKM that existed at the time
the recovery routine was defined.
SDWA Storage Key: An ESTAE-type recovery routine receives an SDWA in the
same storage key as the TCB key at the time the related task made the first
storage request from subpool 0.
Dispatchable Unit Mode: All ESTAE-type recovery routines receive control in task
mode.

8-32

z/OS V1R4.0 MVS Assembler Services Guide

AMODE: A recovery routine defined through the ESTAE macro, or the ESTAI
parameter on ATTACHX, has the addressing mode of the caller at the time the
macro was issued. ESTAEX routines are always entered in 31-bit addressing mode.
ASC Mode: A recovery routine defined through the ESTAE macro is entered in
primary ASC mode. A recovery routine defined through the ESTAEX macro or the
ESTAI parameter on ATTACHX is entered in the ASC mode that existed at the time
the macro was issued.
Interrupt Status: All ESTAE-type recovery routines are entered enabled for I/O
and external interrupts.
DU-AL: ESTAE-type recovery routines receive control with the DU-AL that was
current at the time of the error, as modified by any previous recovery routines, with
the following exception. For an ESTAE-type recovery routine activated by an IRB, or
activated by an IRBs ESTAE-type recovery routine, the ESTAE-type recovery
routine receives the IRBs DU-AL (IRBs get control with their own DU-AL). The
system does not modify the contents of the DU-AL during recovery processing.
Program Mask: The program mask on entry to an ESTAE-type recovery routine is
the same as the program mask at the time of error.
Condition of the Linkage Stack: On entry to an ESTAE-type recovery routine,
the current linkage stack entry is the same as it was at the time of the error, unless
a previous recovery routine added entries to the linkage stack through a PC or
BAKR instruction and did not remove them. In such a case, when percolation
occurs and the recovery routine gets control, the linkage stack contains additional
entries beyond what was the current entry at the time of the error for which the
recovery routine received control. IBM recommends that any recovery routines that
add entries to the linkage stack also remove them.
Restricted Environments: During normal task termination, a resource manager
might end abnormally; its own recovery routines, if any exist, will receive control. If
they do not retry, or if the resource manager has no recovery routines, the system
now considers this situation to be an abnormal termination, and passes control to
the newest ESTAI routine. Because the abending resource manager, and any
previous resource managers, might have completed some processing, the ESTAI
routine will run in an unpredictable environment. In this situation, IBM recommends
that you restrict the ESTAI routines processing. For the ESTAI routine to run in this
environment, design it to:
1. Check the STCBRMET field in the STCB; if the bit is on, the ESTAI routine is
running after a resource manager has ended abnormally and its recovery
routines have not retried. In this situation, the ESTAI routine does not need to
hold a lock to check the STCBRMET field. See z/OS MVS Data Areas, Vol 5
(SSAG-XTLST) for the mapping of the STCB.
2. Do as little processing as possible, and nothing that might depend on a
resource that might have been cleaned up already.
3. Do not request to retry. The system will not allow a retry in this situation.
Note that no other ESTAE-type routines receive control in this situation; only those
established through the ATTACHX macro still exist at this point in termination
processing.

Chapter 8. Providing Recovery

8-33

Environment on Entry to a Retry Routine from an ESTAE-Type

Recovery Routine
The following is a description of each environmental factor on entry to a retry
routine that was specified by an ESTAE-type recovery routine.

Authorization:
v Problem or supervisor state
The retry routine from an ESTAE-type recovery routine that you can write is
entered in problem state.
v PSW key
If the recovery routine was defined by an ESTAE or ESTAEX macro, the retry
routine is entered with the same PSW key that existed when the macro was
issued.
If the recovery routine was defined by the ESTAI parameter of the ATTACHX
macro, the retry routine is entered with the same PSW key as the one in
RBOPSW of the retry RB, if the RBOPSW of the retry RB has a key greater than
or equal to 8 and is in problem state, and the PKM of that RB does not have
authority to keys less than 8. Otherwise, the PSW key of the retry routine is that
of the task in error.
v PKM
If the recovery routine was defined through the ESTAE or ESTAEX macro, the
retry routine is entered with the PKM that existed when the macro was issued.
If the recovery routine was defined through the ESTAI parameter of the
ATTACHX macro, the retry routine is entered with the PKM from the retry RB if
the RBOPSW of the retry RB has a key greater that or equal to 8 and is in
problem state, and the PKM of that RB does not have authority to keys less than
8. Otherwise, the PKM of the retry routine has authority that is equivalent to that
of the task in error.
SDWA Storage Key: If the recovery routine does not request that the system free
the SDWA, the retry routine receives the SDWA in the same storage key as that
which the recovery routine received.
Dispatchable Unit Mode: The retry routine is always entered in task mode.
AMODE: Retry routines are entered in the same addressing mode that existed
when the recovery routine was entered. Remember that ESTAEX routines are
always entered in 31-bit addressing mode. The recovery routine cannot change the
addressing mode of the retry routine.
ASC Mode: For recovery routines defined through the ESTAE macro, the retry
routine is entered in primary ASC mode. For recovery routines defined through the
ESTAEX macro or through the ESTAI parameter on ATTACHX, the retry routine is
entered with the ASC mode of the caller when the macro was issued.
Interrupt Status: The retry routine is always entered enabled for I/O and external
interrupts.
DU-AL: The retry routine is entered with the same DU-AL that the ESTAE-type
recovery routine received, as modified by the ESTAE-type recovery routine. The
system does not modify the contents of the DU-AL during recovery processing.
Program Mask: When the retry routine receives control, the program mask is the
one in the RBOPSW for the retry RB, saved at the time of the last interruption of
that RB that occurred while the RB was unlocked and enabled.

8-34

z/OS V1R4.0 MVS Assembler Services Guide

Condition of the Linkage Stack: For recovery routines defined through the
ESTAE or ESTAEX macro, on entry to the retry routine, the current linkage stack
entry is the same as it was at the time the macro was issued, unless the recovery
routine has set the SDWALSLV field.
For recovery routines defined through the ESTAI parameter on ATTACHX, on entry
to the retry routine, the current linkage stack entry is the same as it was at the time
the selected retry RB was entered, unless the recovery routine has set the
SDWALSLV field.

Summary of Environment on Entry to an ESTAE-Type Recovery

Routine and Its Retry Routine
Table 8-12 summarizes some of the environmental factors for ESTAE-type recovery
routines under different conditions. Specifically, the table lists the status information
of:
v The caller at the time of issuing the macro
v The recovery routine at entry
v The retry routine at entry.
Table 8-12. Environments of ESTAE-type Recovery Routines and their Retry Routines
Type of
Recovery
ESTAE

ESTAEX

Environment
When macro was issued

At entry to recovery routine

At entry to retry routine

ASC mode=primary

ASC mode=primary

ASC mode=primary

Linkage stack at time of error (see

Note 1)

Linkage stack at time macro was

issued (see Note 2)

PKM at time macro was issued

PKM at time macro was issued

ASC mode=primary or AR

ESTAI (through ASC mode=primary or AR

ATTACHX)

ASC mode at time macro was issued ASC mode at time macro was issued
Linkage stack at time of error (see
Note 1)

Linkage stack at time macro was

issued (see Note 2)

PKM at time macro was issued

PKM at time macro was issued

ASC mode at time macro was issued ASC mode at time macro was issued
Linkage stack at time of error (see
Note 1)

Linkage stack at time the retry RB

was entered (see Note 2)

PKM at time macro was issued

For PKM, see the complete

description 8-34

For possible environment

restrictions, see Restricted
Environments on page 8-33.
Notes:
1. The linkage stack presented to the recovery routine might have additional entries, beyond what was the current entry at the time
of the error, if a previous recovery routine added entries through a PC or BAKR instruction and did not remove them.
2. The linkage stack presented to the retry routine might have additional entries, beyond what was current at the time that the
routine was activated, when the recovery routine set the SDWALSLV field.
3. At time of entry to the recovery routine, the AMODE will be the same as the time of invocation, except for ESTAEX routines,
which are always given control in AMODE 31.
4. The AMODE at the retry point will be the same as the AMODE on entry to the recovery routine.
5. An ESTAE-type recovery routine is entered with the PSW key that existed at the time it was defined.

Linkage Stack at Time of Retry

There is one retry situation you must avoid: the situation where the retry routine
runs with a linkage stack entry that is inappropriate. Consider the following

Chapter 8. Providing Recovery

8-35

example, where PGM1 activates an ESTAEX routine that handles recovery for
PGM1, PGM2, and PGM3.
caller ---> PGM1
BAKR
:
ESTAEX
:
BALR -------->

PGM2
BAKR
:
BALR -------->

PGM3
BAKR
***abend***
:
retry point
:
<-------- PR

Both PGM2 and PGM3 use the BAKR instruction to save status; each BAKR adds
an entry to the linkage stack. Within PGM3, retry point indicates the location
where the ESTAEX routine is to retry. After PGM3 issues the BAKR instruction, the
last entries in the linkage stack are:
v Entry 1 -- caused by PGM1s BAKR
v Entry 2 -- caused by PGM2s BAKR
v Entry 3 -- caused by PGM3s BAKR
When the abend occurs in PGM3, unless you take special measures, the linkage
stack level is reset to the level that was current when PGM1 activated the ESTAEX
recovery routine. However, retry from the abend in PGM3 occurs within PGM3. The
linkage stack level and the retry routine are not in synch. Measures you take to
avoid this situation involve:
1. Passing the recovery routine a value that represents the difference between the
level of the linkage stack that the retry routine in PGM3 needs and the level of
the stack at the time PGM1 activated the ESTAEX routine. (In our example, the
difference is 2 entries.)
2. Having the recovery routine set the value 2 in the SDWALSLV field in the
SDWA.
At a retry, the system uses the value in SDWALSLV to adjust the linkage stack. In
this way, the retry routine has the appropriate current linkage stack entry.
Two ways your program can track the entries in the linkage stack are:
v Count the number of entries added to the stack through BAKRs since PGM1
activated the ESTAEX routine. Subtract from that total the number of entries
taken from the stack through corresponding PRs.
v Issue the IEALSQRY macro, which returns the number as output.
In either case, the recovery routine must receive the value and must place it in
SDWALSLV. In summary, the value in SDWALSLV is the difference between the
number of linkage stack entries present when the retry routine gets control and the
number that were present when the recovery routine was activated. The system
preserves the additional entries on the linkage stack for use by the retry routine.
These linkage stack entries must exist at the time of the error; the system does not
create any new entries.

8-36

z/OS V1R4.0 MVS Assembler Services Guide

The following rules apply to the value in SDWALSLV, as it pertains to linkage stack
entries:
v The system ignores the SDWALSLV field when retry is from a STAE or STAI
recovery routine.
v The value must not reflect entries that were placed on the linkage stack through
a PC instruction.
v The value must reflect only those entries associated with programs that are
problem state and running with the same PSW key as the program that activated
the ESTAE-type recovery routine.
v For ESTAE-type routines, the value must reflect only those entries associated
with programs that have been established by a program running under the RB of
the retry routine. See RB Considerations on page 8-23.
If any of these rules are broken, retry still occurs but the system ignores the entry
that did not conform and all subsequent entries.

Understanding Recovery through a Coded Example

This section provides a coded example illustrating a mainline routine with both a
recovery routine and a retry routine as entry points in the mainline code.
The code in this example does not contain any real function. The mainline code
does little more than save status, establish addressability, obtain a dynamic area
(making the code reentrant), define a recovery routine, and issue the ABEND macro
to pass control to the system.
The purpose of the example is just to illustrate how you might code a program that
contains both a recovery routine and a retry routine, and how the three routines
interact. The example also illustrates how you design an ESTAE-type recovery
routine to allow for the possibility that the system might not provide an SDWA.
EXAMPLE
EXAMPLE
EXAMPLE

CSECT
* SAMPLE PROGRAM THAT USES ESTAEX
AMODE 31
RMODE ANY
USING EXAMPLE,15
* ESTABLISH TEMPORARY ADDRESSABILITY
B
@PROLOG
* BRANCH AROUND EYE CATCHER
DC CL24EXAMPLE 04/10/92.01 * EYE CATCHER

*
* USE THE LINKAGE STACK TO SAVE STATUS ON ENTRY TO THE PROGRAM.
*
@PROLOG BAKR 14,0
* SAVE REGISTER/PSW STATUS
*
* ESTABLISH ADDRESSABILITY FOR THIS PROGRAM.
*
LR 12,15
* REG 12 BECOMES BASE REGISTER
DROP 15
*
USING EXAMPLE,12
* ESTABLISH ADDRESSABILITY
*
* OBTAIN DYNAMIC STORAGE AREA FOR THIS REENTRANT PROGRAM.
*
L
2,DYNSIZE
* LENGTH TO OBTAIN
STORAGE OBTAIN,ADDR=(1),SP=0,LENGTH=(2)
LR 13,1
* SAVE DYNAMIC AREA ADDRESS
USING DYNAREA,13
* ADDRESSABILITY TO DYNAMIC AREA
*
* SET UP THE REMOTE PARAMETER LIST FOR THE ESTAEX MACRO.
*
MVC RMTESTAEX(@LSTSIZE),LSTESTAEX
*
* DEFINE AND ACTIVATE AN ESTAEX RECOVERY ROUTINE AT LABEL RECOVERY.
*
Chapter 8. Providing Recovery

8-37

ESTAEX RECOVERY,PARAM=DYNAREA,MF=(E,RMTESTAEX)
***********************************************************************
*
* CODE FOR THE MAINLINE ROUTINE FUNCTION CAN BE INSERTED HERE
*
*
IF AN ERROR OCCURS IN THE MAINLINE ROUTINE, THEN THE SYSTEM WILL
*
PASS CONTROL TO RECOVERY.
*
***********************************************************************
*
RETRYPT DS 0H
***********************************************************************
*
* CODE FOR THE RETRY ROUTINE FUNCTION CAN BE INSERTED HERE
*
***********************************************************************
ESTAEX 0
* DELETE THE ESTAEX
LR 1,13
* FREE DYNAMIC AREA, ADDRESS TO FREE
L
2,DYNSIZE
* LENGTH TO FREE
STORAGE RELEASE,ADDR=(1),SP=0,LENGTH=(2)
PR
* RESTORE STATUS & RETURN TO CALLER
***********************************************************************
*
* RECOVERY ROUTINE
*
***********************************************************************
RECOVERY DS
0H
* ENTRY POINT FOR ESTAEX RECOVERY ROUTINE
*
* HANDLE INPUT FROM THE SYSTEM AND RE-ESTABLISH ADDRESSABILITY FOR
* BASE REGISTER (12) AND DYNAMIC AREA REGISTER (13)
*
PUSH USING
DROP ,
* ENSURE NO SPURIOUS USING REFERENCES
USING RECOVERY,15
* TEMPORARY ADDRESSABILITY
L
12,#BASE
* RELOAD THE BASE REGISTER
DROP 15
* RELEASE TEMPORARY ADDRESSABILITY
USING EXAMPLE,12
* USE THE BASE REGISTER
USING DYNAREA,13
* DYNAMIC AREA ADDRESSABILITY
C
0,TESTNOSDWA
* IS THERE AN SDWA PRESENT?
BE NOSDWA
* NO, DO NOT USE THE SDWA
HAVESDWA DS 0H
USING SDWA,1
* ADDRESSABILITY TO SDWA
L
13,SDWAPARM
* ADDRESS OF PARAMETER ADDRESS
L
13,0(13)
* PARAMETER ADDRESS (DYNAREA)
MVC SAVE_ABCC,SDWAABCC * SAVE THE COMPLETION CODE
B
RECOV1
* CONTINUE WITH COMMON RECOVERY
NOSDWA
LR 13,2
* PARAMETER ADDRESS (DYNAREA)
ST 1,SAVE_ABCC
* SAVE THE COMPLETION CODE
SR 1,1
* NO SDWA IS AVAILABLE, CLEAR REGISTER
*
* COMMON RECOVERY PROCESSING
*
RECOV1
DS 0H
* COMMON RECOVERY PROCESSING
ST 1,SAVE_SDWA
* SAVE THE SDWA ADDRESS
ST 14,SAVE_RETURNR14 * RETURN ADDRESS TO THE SYSTEM
*
***********************************************************************
*
* CODE FOR THE RECOVERY ROUTINE FUNCTION SHOULD BE INSERTED HERE
*
***********************************************************************
*
* IF THERE IS NO SDWA, THEN SET UP FOR PERCOLATION
*
L
1,SAVE_SDWA
* RESTORE SDWA REGISTER (1)
LTR 1,1
* IS THERE AN SDWA?
BZ NORETRY
* NO, DO NOT ATTEMPT TO RETRY

8-38

z/OS V1R4.0 MVS Assembler Services Guide

*
* CHECK SDWACLUP TO SEE IF RETRY IS ALLOWED
*
TM SDWAERRD,SDWACLUP * IS RETRY ALLOWED?
BNZ NORETRY
* NO, DO NOT ATTEMPT TO RETRY
*
* SET UP THE RETURN PARAMETERS TO THE SYSTEM. THE SETRP MACRO UPDATES
* THE SDWA. NOTE: THE WKAREA PARAMETER DEFAULTS TO REGISTER 1, WHICH
* HAS THE ADDRESS OF THE SDWA. ALSO NOTE THAT OTHER REGISTERS MIGHT
* NEED TO BE UPDATED TO MEET THE NEEDS OF DIFFERENT PROGRAMS.
*
ST
12,SDWASR12
* BASE REGISTER 12 FOR RETRY
ST
13,SDWASR13
* DYNAMIC AREA REGISTER 13 FOR RETRY
SETRP RETREGS=YES,RC=4,RETADDR=RETRYPT,FRESDWA=YES
B
RECOV2
* CONTINUE WITH COMMON RECOVERY
NORETRY DS 0H
* BRANCH HERE WHEN NOT GOING TO RETRY
LA 15,0
* RETURN CODE TO INDICATE PERCOLATION
RECOV2
DS 0H
* COMPLETE THE RETURN TO THE SYSTEM
L 14,SAVE_RETURNR14 * SET THE RETURN ADDRESS TO THE SYSTEM
BR 14
* RETURN TO THE SYSTEM
*
* STATIC STORAGE AREA
*
TESTNOSDWA DC F12
* TEST FOR NO SDWA CONDITION
#BASE
DC A(EXAMPLE)
* BASE REGISTER VALUE
DYNSIZE DC AL4(@DYNSIZE)
* DYNAMIC AREA SIZE
LSTESTAEX ESTAEX RECOVERY,MF=L * LIST FORM OF ESTAEX PARAMETER LIST
@LSTSIZE EQU *-LSTESTAEX
* SIZE OF ESTAEX PARAMETER LIST
*
* DYNAMIC AREA STORAGE FOR REENTRANT PROGRAM
*
DYNAREA DSECT
* DYNAMIC STORAGE
SAVEAREA DS 18F
* REGISTER SAVE AREA
SAVE_SDWA DS F
* SDWA ADDRESS ON ENTRY TO RECOVERY
SAVE_ABCC DS F
* COMPLETION CODE
SAVE_RETURNR14 DS F
* RETURN ADDR. TO SYSTEM FROM RECOVERY
RMTESTAEX DS CL(@LSTSIZE)
* REMOTE ESTAEX PARAMETER LIST
STATUS
DS F
* MAINLINE STATUS INDICATOR
@ENDDYN DS 0X
* USED TO CALCULATE DYNAMIC AREA SIZE
@DYNSIZE EQU ((@ENDDYN-DYNAREA+7)/8)*8 * DYNAMIC AREA SIZE
*
* INCLUDE MACROS
*
IHASDWA
END

Understanding Advanced Recovery Topics

This section contains information about the following advanced recovery topics:
v Invoking RTM (ABEND Macro)
v Providing Multiple Recovery Routines on page 8-40
v Providing Recovery for Recovery Routines on page 8-41
v Providing Recovery for Multitasking Programs on page 8-41.

Invoking RTM (ABEND Macro)

Any routine can issue the ABEND macro to direct the recovery termination services
to itself (cause entry into its recovery routine) or to its callers. The issuer of ABEND
should remove its own recovery routine if it wishes its caller to be ended abnormally
or to enter recovery. Control does not return to the issuer of the macro (except as a
result of a retry).
The position within the job step hierarchy of the task for which the ABEND macro is
issued determines the exact function of the abnormal termination routine. If an
Chapter 8. Providing Recovery

8-39

ABEND macro is issued when the job step task (the highest level or only task) is
active, or if the STEP parameter is coded in an ABEND macro issued during the
performance of any task in the job step, all the tasks in the job step are terminated.
For example, if the STEP parameter is coded in an ABEND macro under TSO/E,
the TSO/E job is terminated. An ABEND macro (without a STEP parameter) that is
issued in performance of any task in the job step task usually causes only that task
and its subtasks to be abnormally terminated. However, if the abnormal termination
cannot be fulfilled as requested, it might be necessary for the system to end the job
step task abnormally.
If you have provided a recovery routine for your program, the system passes control
to your routine. If you have not provided a recovery routine, the system handles the
problem. The action the system takes depends on whether the job step is going to
be terminated.
If the job step is not going to be terminated, the system:
v Releases the resources owned by the terminating task and all of its subtasks,
starting with the lowest level task.
v Places the system or user completion code specified in the ABEND macro in the
task control block (TCB) of the active task (the task for which the ABEND macro
was issued).
v Posts the event control block (ECB) with the completion code specified in the
ABEND macro, if the ECB parameter was coded in the ATTACHX macro issued
to create the active task.
v Schedules the end-of-task exit routine to be given control when the originating
task becomes active, if the ETXR parameter was coded in the ATTACHX macro
issued to create the active task.
v Calls a routine to free the storage of the terminating tasks TCB, if neither the
ECB nor ETXR parameter were specified by the ATTACHX macro.
If the job step is to be terminated, the system:
v Releases the resources owned by each task, starting with the lowest level task,
for all tasks in the job step. The system does not give control to any end-of-task
exit.
v Writes the system or user completion code specified in the ABEND macro on the
system output device.
The remaining steps in the job are skipped unless you can define your own
recovery routine to perform similar functions and any other functions that your
program requires. Use either the ESTAE or ESTAEX macro, or the ATTACHX
macro with the ESTAI option to provide a recovery routine that gets control
whenever your program issues an ABEND macro. If your program is running in AR
ASC mode, use the ESTAEX or ATTACHX macro.

Providing Multiple Recovery Routines

A single program can activate more than one ESTAE-type recovery routine by
issuing the ESTAE or ESTAEX macro more than once with the CT parameter. The
program can also overlay recovery routines by issuing ESTAE or ESTAEX with the
OV parameter, or deactivate recovery routines by issuing ESTAE or ESTAEX with
an address of zero.
ESTAE-type recovery routines get control in LIFO order, so the last ESTAE-type
recovery routine activated is the first to get control. Remember that ESTAE-type
recovery routines include ESTAE and ESTAEX routines, and ESTAI routines. ESTAI

8-40

z/OS V1R4.0 MVS Assembler Services Guide

routines are entered after all other ESTAE-type recovery routines that exist for a
given task have received control and have either failed or percolated.
MVS functions provide their own recovery routines; thus, percolation can pass
control to both installation-written and system-provided recovery routines. If all
recovery routines percolate -- that is, no recovery routine can recover from the error
-- then the task is terminated.
When a recovery routine gets control and cannot recover from the error (that is, it
does not retry), it must free the resources held by the mainline routine and request
that the system continue with error processing (percolate). Note that a recovery
routine entered with the SDWACLUP bit set to one, indicating that retry is not
permitted, has no choice but to percolate. When the recovery routine requests
percolation, the previously activated recovery routine gets control. When a retry is
not requested and the system has entered all possible recovery routines, the task
ends abnormally.
When a recovery routine requests percolation, it is deactivated; that is, it can no
longer get control for this error. A deactivated recovery routine is not entered again
unless that recovery routine is activated again after a retry.

Providing Recovery for Recovery Routines

In some situations, the function a recovery routine performs is so essential that you
should provide a recovery routine to recover from errors in the recovery routine.
Two examples of such situations are:
1. The availability of some resources can be so critical to continued system or
subsystem operation that it might be necessary to provide a recovery routine for
the recovery routine, thus ensuring the availability of the critical resources.
2. A recovery routine might perform a function that is, in effect, an extension of the
mainline routines processing. For example, a system service might elect to
check a callers parameter list for fetch or store protection. The service
references the users data in the users key and, as a result of protection,
suffers a program check. The recovery routine gets control and requests a retry
to pass a particular return code to the mainline routine. If this recovery routine
ends abnormally and does not provide its own recovery, then the callers
recovery routine gets control, and the caller does not get an opportunity to
check the return code that it was expecting.
You can activate an ESTAE-type recovery routine from another ESTAE-type
recovery routine. Any recovery routine activated from a recovery routine is called a
nested recovery routine. Nested ESTAE or ESTAEX routines can retry; the retry
routine runs under the RB of the ESTAE-type recovery routine that activated the
nested recovery routine.

Providing Recovery for Multitasking Programs

There are situations where the system does not provide serialization between
recovery routines for different TCBs in an address space. When possible you
should write your recovery routines so that serialization is not required.
When a recovery routine requires serialization with other TCBs in the address
space then the recovery routine must provide its own serialization. Serialization
must be carefully designed to avoid causing deadlock situations.

Chapter 8. Providing Recovery

8-41

One serialization technique to ensure the order of termination processing is to use

the DETACH macro. Issuing DETACH ensures that the detached task and its
recovery routines complete before processing for the issuing task proceeds.
DETACH can only be used for tasks that were directly attached by the recovery
routines TCB.
Another important aspect of recovery is releasing resources. Releasing serialization
resources (locks, ENQs, latches) in ESTAE-type recovery routines, rather than
leaving them to be released by a resource manager, helps avoid deadlocks in
recovery processing.

Using STAE/STAI Routines

Notes:
1. IBM recommends you use the ESTAEX or ESTAE macro, or the ESTAI
parameter on ATTACHX.
2. Under certain circumstances, STAE or STAI routines might receive control in a
restricted environment. See Restricted Environments on page 8-33 for more
information.
The STAE macro causes a recovery routine address to be made known to the
system. This recovery routine is associated with the task and the RB that issued
STAE. Use of the STAI option on the ATTACH macro also causes a recovery
routine to be made known to the system, but the routine is associated with the
subtask created through ATTACH. Furthermore, STAI recovery routines are
propagated to all lower-level subtasks of the subtask created with ATTACH that
specified the STAI parameter.
If a task is scheduled for abnormal termination, the recovery routine specified by the
most recently issued STAE macro gets control and runs under a program request
block created by the SYNCH service routine. Only one STAE routine receives
control. The STAE routine must specify, by a return code in register 15, whether a
retry routine is to be scheduled. If no retry routine is to be scheduled (return code =
0) and this is a subtask with STAI recovery routines, the STAI recovery routine is
given control. If there is no STAI recovery routine, abnormal termination continues.
If there is more than one STAI recovery routine existing for a task, the newest one
receives control first. If it requests that termination continue (return code = 0), the
next STAI routine receives control. This continues until either all STAI routines have
received control and requested that the termination continue, a STAI routine
requests retry (return code = 4 or 12), or a STAI routine requests that the
termination continue but no further STAI routines receive control (return code = 16).
Programs running under a single TCB can issue more than one STAE macro with
the CT parameter to define more than one STAE routine. Each issuance temporarily
deactivates the previous STAE routine. The previous STAE routine becomes active
when the current STAE routine is deactivated.
A STAE routine is deactivated (it cannot receive control again for this error) under
any of the following circumstances:
v When the RB that activated it goes away (unless it issued XCTL and specified
the XCTL=YES parameter on the STAE macro)
v When the STAE macro is issued with an address of 0
v When the STAE routine receives control.

8-42

z/OS V1R4.0 MVS Assembler Services Guide

If a STAE routine receives control and requests retry, the retry routine reissues the
STAE macro if it wants continued STAE protection.
A STAI routine is deactivated if the task completes or if the STAI routine requests
that termination continue and no further STAI processing be done. In the latter
case, all STAI recovery routines for the task are deactivated.

STAE and STAI Routine Environment:

Prior to entering a STAE or STAI recovery routine, the system attempts to obtain
and initialize a work area that contains information about the error. The first 4 bytes
of the SDWA contains the address of the user parameter area specified on the
STAE macro or the STAI parameter on the ATTACH macro.
Upon entry to the STAE or STAI routine, the GPRs contain the following:
If an SDWA was obtained:
GPR
0

Contents
A code indicating the type of I/O processing performed:

0
Active I/O has been quiesced and is restorable.
4
Active I/O has been halted and is not restorable.
8
No active I/O at abend time.
16 (X'10')
Active I/O, if any, was allowed to continue.
1
Address of the SDWA.
2
Address of the parameter area you specified on the PARAM parameter.
3 - 12 Do not contain any information for use by the routine.
13
Save area address.
14
Return address.
15
Address of STAE recovery routine.
If no SDWA was available:
GPR
0
1
2
3 - 13
14
15

Contents
12 (X'0C') to indicate that no SDWA was obtained.
Completion code.
Address of user-supplied parameter list.
Do not contain any information for use by the routine.
Return address.
Address of STAE recovery routine.

When the STAE or STAI routine has completed, it should return to the system
through the contents of GPR 14. GPR 15 should contain one of the following return
codes:
Return Code

Action

Continue the termination. The next STAI, ESTAI, or ESTAE routine

will be given control. No other STAE routines will receive control.

4,8,12

A retry routine is to be scheduled.

Note: These values are not valid for STAI/ESTAI routines that
receive control when a resource manager fails during
normal termination of a task. See Restricted Environments
on page 8-33 for more information.
Chapter 8. Providing Recovery

8-43

16

No further STAI/ESTAI processing is to occur. This code may be

issued only by a STAI/ESTAI routine

For the following situations, STAE/STAI routines are not entered:

v If the abnormal termination is caused by an operators CANCEL command, job
step timer expiration, or the detaching of an incomplete task without the
STAE=YES option.
v If the failing task has been in a wait state for more than 30 minutes.
v If the STAE macro was issued by a subtask and the attaching task abnormally
terminates.
v If the recovery routine was specified for a subtask, through the STAI parameter
of the ATTACH macro, and the attaching task abnormally terminates.
v If a problem other than those above arises while the system is preparing to give
control to the STAE routine.
v If another task in the job step terminates without the step option.

STAE and STAI Retry Routines:

If the STAE retry routine is scheduled, the system automatically deactivates the
active STAE routine; the preceding STAE routine, if one exists, then becomes
activated. Users wanting to maintain STAE protection during retry must reactivate a
STAE routine within the retry routine, or must issue multiple STAE requests prior to
the time that the retry routine gains control.
Like the STAE/STAI recovery routine, the STAE/STAI retry routine must be in
storage when the recovery routine determines that retry is to be attempted. If not
already resident in your program, the retry routine may be brought into storage
through the LOAD macro by either the mainline routine or the recovery routine.
If the STAE/STAI routine indicates that a retry routine has been provided (return
code = 4, 8, or 12), register 0 must contain the address of the retry routine. The
STAE routine that requested retry is deactivated and the request block queue is
purged up to, but not including, the RB of the program that issued the STAE macro.
In addition, open DCBs that can be associated with the purged RBs are closed and
queued I/O requests associated with the DCBs being closed are purged.
The RB purge is an attempt to cancel the effects of partially run programs that are
at a lower level in the program hierarchy than the program under which the retry
occurs. However, certain effects on the system are not canceled by this RB purge.
Generally, these effects are TCB-related and are not identifiable at the RB level.
Examples of these effects are as follows:
v Subtasks created by a program to be purged. Subtasks cannot be associated
with an RB; the structure is defined through TCBs.
v Resources allocated by the ENQ macro. ENQ resources are associated with the
TCB and are not identifiable at the RB level.
v DCBs that exist in dynamically acquired virtual storage. Only DCBs in the
program, as defined by the RB through the CDE itself, are closed.
If there are quiesced restorable input/output operations (as specified by
PURGE=QUIESCE on the macro invocation), the retry routine can restore them in
the same manner as the retry routine from an ESTAE routine. See Outstanding
I/Os at the Time of Failure on page 8-25.

8-44

z/OS V1R4.0 MVS Assembler Services Guide

If an SDWA was obtained upon entry to the STAE/STAI retry routine, the contents
of the GPRs are as follows:
GPR
0
1
2 - 14
15

Contents
0
Address of the first 104 bytes of the SDWA.
Do not contain any information for use by the routine.
Address of the STAE/STAI retry routine.

When the storage is no longer needed, the retry routine should use the FREEMAIN
macro with the default subpool to free the first 104 bytes of the SDWA.
If the system was not able to obtain storage for the work area, GPR contents are as
follows:
GPR
0
1
2
3 - 14
15

Contents
12 (X'0C')
Completion code.
Address of purged I/O restore list or 0 if I/O is not restorable.
Do not contain any information for use by the routine.
Address of the STAE/STAI retry routine.

The retry routine is entered with the same PSW key as the one in the RBOPSW of
the retry RB if the RBOPSW of the retry RB has a key greater than or equal to 8
and is in problem program state, and the PKM of that RB does not have authority to
keys less than 8.
Otherwise, the PSW key of the retry routine is that of the task in error.

Chapter 8. Providing Recovery

8-45

8-46

z/OS V1R4.0 MVS Assembler Services Guide

Chapter 9. Dumping Virtual Storage (ABEND, SNAPX, SNAP,

and IEATDUMP Macros)
A problem-state and PSW key 8-15 program can request three types of storage
dumps:
v An ABEND dump obtained through the DUMP parameter in the ABEND macro,
or the DUMP=YES parameter on the SETRP macro in a recovery exit
v A SNAP dump obtained through the SNAPX macro.
v A Transaction dump obtained througfh the IEATDUMP macro.
Table 9-1 summarizes reasons for selecting an ABEND, SNAP, or Transaction
dump.
Table 9-1. Reasons for Selecting the Type of Dump
Type of Dump

Reasons for Selecting the Type of Dump

ABEND dumps

Use an ABEND dump when abnormally ending a program because of an unpredictable

error. The DD statement in the programs job step determines the type of ABEND dump and
the dump contents, as follows:
SYSUDUMP ABEND dumps
These are the smallest of the ABEND dumps, containing data and areas only about the
failing program. You can either print or view the dump if its in a SYSOUT data set or on
a tape or direct access data set (DASD).
SYSABEND ABEND dumps
These are the largest of the ABEND dumps, containing all the areas in a SYSUDUMP
dump and system areas that are used to analyze the processing in the failing program.
You can either print or view the dump if its in a SYSOUT data set or on a tape or DASD.
SYSMDUMP ABEND dumps
These contain data and areas in the failing program, plus some system areas. The
SYSMDUMP dumps can be more useful for diagnosis than other ABEND dumps
because you can use IPCS to gather diagnostic information. Use IPCS to format, view,
and print dumps.

SNAP dumps

Use a SNAP dump to show one or more user-specified areas in the problem-state program
while it is running. A series of SNAP dumps can show a storage area at different stages to
display a programs processing. For example, you can use SNAP dumps to show fields
holding calculations and the counter in a loop to check processing in the loop.

Transaction dumps
(IEATDUMP)

Use Transaction dump to show one or more user-specified areas in the problem-state
program while it is running. Transaction dump can be more useful for diagnosis than SNAP
dumps because you can use IPCS to gather diagnostic information. Use IPCS to format,
view, and print dumps.

z/OS MVS Diagnosis: Tools and Service Aids shows, in detail, the contents of
dumps. z/OS MVS IPCS Users Guide describes how to use IPCS. z/OS MVS
Programming: Authorized Assembler Services Guide describes macros that
authorized programs can use to dump virtual storage.

ABEND Dumps
An ABEND macro initiates error processing for a task. The DUMP option of ABEND
requests a dump of storage and the DUMPOPT or DUMPOPX option may be used
to specify the areas to be displayed. These dump options may be expanded by an
ESTAE or ESTAI routine. The system usually requests a dump for you when it
issues an ABEND macro. However, the system can provide an ABEND dump only if
Copyright IBM Corp. 1988, 2002

9-1

you include a DD statement (SYSABEND, SYSMDUMP, or SYSUDUMP) in the job

step. The DD statement determines the type of dump provided and the system
dump options that are used. When the dump is taken, the dump options that you
requested (specified in the ABEND macro or by recovery routines) are added to the
installation-selected options.
When writing an ESTAE-type recovery routine, note that the system accumulates
the SYSABEND/SYSUDUMP/SYSMDUMP dump options specified by means of the
SETRP macro and places them in the SDWA. During percolation, these options are
merged with any dump options specified on an ABEND or CALLRTM macro or by
other recovery routines. Also, the CHNGDUMP operator command can add to or
override the options. The system takes one dump as specified by the accumulated
options. If the recovery routine requests a retry, the system processes the dump
before the retry. If the recovery routine does not request a retry, the system
percolates through all recovery routines before processing the dump.
Note: If your program calls a system service (by issuing a macro or callable
service), that system service might encounter a user-induced error and end
abnormally. Generally, the system does not take dumps for user-induced
errors. If you require such a dump, then it is your responsibility to request
one in your recovery routine. See Chapter 8, Providing Recovery on
page 8-1 for information about writing recovery routines.

Obtaining a Symptom Dump

With all ABEND dumps, you will automatically receive a symptom dump through
message IEA995I. This symptom dump provides a summary of error information,
which will help you to identify duplicate problems.
You will receive this dump even without a DD statement unless your installation
changes the default via the CHNGDUMP operator command or the dump parmlib
member for SYSUDUMP.

Suppressing Dumps That Duplicate Previous Dumps

If your installation is using dump analysis and elimination (DAE), code your program
to provide symptom data that DAE can compare with the symptom data from
previous dumps. Through this comparison, DAE can reduce the number of duplicate
dumps. Another benefit is that the symptom data, which is stored in the DAE data
set, provides a consistent set of data for identifying a failure.
DAE suppresses dumps that match a dump you already have. Each time DAE
suppresses a duplicate dump, the system does not collect data for the duplicate or
write the duplicate to a data set. In this way, DAE can improve dump management
by only dumping unique situations and by minimizing the number of dumps.
To perform dump suppression, DAE builds a symptom string, if the data for it is
available. If the symptom string contains the minimum problem data, DAE uses the
symptom string to recognize a duplicate SVC dump, SYSMDUMP dump, or
Transaction dump requested for a software error. When installation parameters
request suppression, DAE suppresses the duplicate dump. The following describes
DAE processing.
1. DAE obtains problem data. DAE receives the data in the system diagnostic
work area (SDWA) or from values in a SYMREC parameter on the SDUMP,
SDUMPX or IEATDUMP macro that requested the dump.

9-2

z/OS V1R4.0 MVS Assembler Services Guide

v The system supplies system-level data, such as the abend and reason
codes, the failing instruction, and the register/PSW difference.
v The ESTAE routine or the functional recovery routine (FRR) of the failing
program supplies module-level information, such as the failing load module
name and the failing CSECT name.
2. DAE forms a symptom string. DAE adds a descriptive keyword to each field
of problem data to form a symptom. DAE forms MVS symptoms, rather than
RETAIN symptoms. DAE combines the symptoms for a requested dump into a
symptom string.
The following tables show the required and optional symptoms. SDWA field
names are given for the symptoms the failing program must provide to enable
dump suppression. The tables have both MVS and RETAIN symptoms so that
you can relate the MVS symptoms DAE uses to the RETAIN symptoms you
might use to search the RETAIN data base. An MVS symptom string must
contain at least five symptoms that are not null. DAE places symptoms into
strings in the order shown in the tables.
Required symptoms are first and must be present.
Symptom

SDWA Field

MVS Keyword

RETAIN Keyword

Name of the failing load module

SDWAMODN

MOD/name

RIDS/name#L

Name of the failing CSECT

SDWACSCT

CSECT/name

RIDS/name

Optional symptoms must follow the required symptoms. DAE needs at least
three of these optional symptoms to make a useful symptom string.
Symptom

SDWA Field

MVS Keyword

RETAIN Keyword

Product/component identifier with the component

identifier base

SDWACID,
SDWACIDB

PIDS/name

PIDS/name

System completion (abend) code

AB/S0hhh

AB/S0hhh

User completion (abend) code

AB/Udddd

AB/Udddd

REXN/name

RIDS/name#R

Failing instruction area

FI/area

VALU/Harea

PSW/register difference

REGS/hhhhh

REGS/hhhhh

Reason code, accompanying the abend code or from

the REASON parameter of the macro that requests the
dump

HRC1/nnnn

PRCS/nnnn

SUB1/name

VALU/Cname

Recovery routine name

SDWAREXN

Subcomponent or module subfunction

SDWASC

3. DAE tries to match the symptom string from the dump to a symptom
string for a previous dump of the same type, that is, SVC dumps, with SVC
dumps and SYSMDUMP, or Transaction dumps with a previous SYSMDUMP or
Transaction dump. When DAE finds a match, DAE considers the dump to be a
duplicate.
Previous symptom strings are kept by DAE in virtual storage. When DAE is
started, usually during IPL, DAE selects from the DAE data set symptom strings
that were active in the last 180 days; either the string was created for a unique
dump within the last 180 days or its dump count was updated within the last
180 days. The selected symptom strings are placed in virtual storage.

Chapter 9. Dumping Virtual Storage (ABEND, SNAPX, SNAP, and IEATDUMP Macros)

9-3

The systems in a sysplex can share the DAE data set to suppress duplicate
dumps across the sysplex. While each system in a sysplex can use its own
DAE data set, IBM recommends that systems in a sysplex share a DAE data
set so that:
v DAE can write a dump on one system and suppress duplicates on other
systems in the sysplex.
v Only one DAE data set is required, rather than a data set for each system.
4. DAE updates the symptom strings in storage and, later, in the DAE data
set, if updating is requested.
v For a unique symptom string, DAE adds a new record. The record contains
the symptom string, the dates of the first and last occurrences, the incidence
count for the number of occurrences, and the name of the system that
provided the string.
v For a duplicate symptom string, DAE updates the incidence count for the
string, the last-occurrence date, and the name of the last system that found
the string.
In a sysplex, changes to the in-storage strings are propagated to the in-storage
strings throughout the sysplex.
5. DAE suppresses a duplicate dump, if DAE is enabled for dump suppression.
Note that, if you specify an ACTION of SVCD, TRDUMP, NOSUP, or
RECOVERY on a SLIP command, the command overrides DAE suppression
and the system writes the dump. Also, dumps requested by the DUMP operator
command are not eligible for suppression.
When DAE does not suppress a dump, the symptom string is in the dump
header; you can view it with the IPCS VERBEXIT DAEDATA subcommand. DAE
also issues informational messages to indicate why the dump was not
suppressed.
DAE suppresses a dump when all of the following are true:
v DAE located in the dump the minimum set of symptoms.
v The symptom string for the dump matches a symptom string for a previous
dump of the same type.
v Either of the following is true:
The current ADYSETxx parmlib member specifies SUPPRESS for the type
of dump being requested and the VRADAE key is present in the SDWA.
To set the VRADAE key, a recovery routine issues the following macro:
VRADATA KEY=VRADAE

A VRADATA VRAINIT must be done prior to any VRADATA KEY= request

in order for the VRA data to be properly processed by both DAE and the
SDWA formatter.
The current ADYSETxx parmlib member specifies SUPPRESSALL for the
type of dump being requested and the VRANODAE key is absent from the
SDWA. The VRANODAE key specifies that the dump is not to be
suppressed.
The following table shows the effect of the VRADAE and VRANODAE keys on
dump suppression when SUPPRESS and SUPPRESSALL keywords are
specified in the ADYSETxx parmlib member. For SUPPRESS, the VRANODAE
key can be present or absent; the system does not check it. The table assumes
that the symptom string from the dump has matched a previous symptom string.

9-4

z/OS V1R4.0 MVS Assembler Services Guide

ADYSETxx Option

VRADAE Key in
SDWA

VRANODAE Key in
SDWA

Dump Suppressed?

SUPPRESS

Yes

N/A

Yes

SUPPRESS

No

N/A

No

SUPPRESSALL

Yes

No

Yes

SUPPRESSALL

No

Yes

No

SUPPRESSALL

No

No

Yes

SUPPRESSALL

Yes

Yes

No

The only way to ensure that a dump is not suppressed, regardless of the
contents of the ADYSETxx parmlib member, is to specify the VRANODAE key in
the SDWA, or DAE=NO on SYMRBLD used to build a symptom record passed
to the SDUMPX or IEATDUMP macro with the SYMREC keyword.

References:
v See z/OS MVS Diagnosis: Reference for symptoms and symptom strings.
v See z/OS MVS Initialization and Tuning Reference for the ADYSETxx and
IEACMD00 parmlib members.
v See z/OS MVS IPCS Commands for the VERBEXIT DAEDATA subcommand.

Symptoms Provided by a Recovery Routine

DAE attempts to construct a unique symptom string using specific data that your
recovery routine can provide in the SDWA or through a symptom record. For an
SVC dump, or a Transaction dump, the symptom record is passed in the SDUMPX
or IEATDUMP macro. For a SYSMDUMP, place the symptom record in the
ABDUMP symptom area.
To provide symptoms for an SVC dump, do one or more of the following in a
recovery routine:
v Place data in the SDWA, which is mapped by the IHASDWA mapping macro.
v In an authorized program, provide a symptom record through a SYMREC
parameter on the SDUMPX or SDUMP macro. The symptom record is built using
SYMRBLD and mapped by the ADSR mapping macro.
v In an authorized or unauthorized program, provide a symptom record through a
SYMREC parameter on the IEATDUMP macro. The symptom record is built
using SYMRBLD and mapped by the ADSR mapping macro.
v Use a VRADATA macro to place information in the SDWA variable recording area
(VRA), which is mapped by the IHAVRA mapping macro. The VRA is used:
To supply additional symptoms for the symptom string.
To provide secondary symptoms that give problem data not given in the
SDWA; for example, the identity of the caller of a service.
Use VRADATA when the standard symptom data is insufficient to determine if a
dump for the program is a duplicate.
For information about coding the VRADATA macro to add data to the SDWA, see
z/OS MVS Programming: Assembler Services Reference IAR-XCT. For more
information about symptom records, see Chapter 10, Reporting Symptom Records
(SYMRBLD and SYMREC Macros). For more information about recovery routines,
see Writing Recovery Routines on page 8-10.

Chapter 9. Dumping Virtual Storage (ABEND, SNAPX, SNAP, and IEATDUMP Macros)

9-5

VRADATA Macro: Use the VRAREQ key to tell DAE that the symptom is required
and the VRAOPT key to tell DAE that the symptom is optional.
A VRADATA macro with VRAREQ adds a symptom following the two required
symptoms (see the previous table). For example, to add a symptom, in this case
the name of a data set, and to define the symptom as required:
VRADATA KEY=VRAREQ,DATA=TAG1,LEN=LTAG1
VRADATA
KEY=VRADSN,DATA=MYDSN,LEN=LMYDSN
.
.
.
TAG1 DC AL2(VRADSN)
MYDSN DC [Link]

A VRADATA macro with VRAOPT adds an optional symptom following the optional
symptoms (see the previous table). For example, to add an optional symptom with
the data at the address in register 5, and to define the symptom as optional:
LA R5,VRAOPTKEY
VRADATA KEY=VRAOPT,LEN=2,DATA=(5)
VRADAYA
KEY=VRACA,DATA=PGMCALLR
.
.
.
VRAOPTKEY DC AL2(VRACA)
PGMCALLR DS A

If the symptom is to be the callers address, the data pointed to would consist of
X'003C', which represents the key VRACA.
See z/OS MVS Diagnosis: Reference for the VRADATA keys.

Required Symptom Data: The recovery routine must provide the following
minimum data to enable dump suppression by DAE:
SDWA Field
SDWAMODN
SDWACSCT
SDWACID
SDWACIB
SDWAREXN
SDWASC

Data
Failing module name
Failing CSECT name
Product or component identifier
Component identifier base
Recovery routine name
Subcomponent or module subfunction

Example
IEAVTCXX
IEAVTC22
SCDMP
5655
IEAVTC2R
RSM-PGFIX

To obtain the failing module name, the failing CSECT name, and the recovery
module name, the recovery routine can set up a RECPARM parameter list and
specify it on a SETRP macro. For information, see the RECPARM parameter of the
SETRP macro in z/OS MVS Programming: Authorized Assembler Services
Reference SET-WTO.

Correct Module and CSECT Names: Obtaining the correct module and CSECT
names may be difficult, especially when the PSW does not point within the program
areas. Problems can also occur when the program uses the following:
v User exits: When the program calls a user exit, which in turn invokes system
services, such as getting a lock, the recovery routine often cannot identify the
exit as the failing module and CSECT. To avoid this problem, the program should
save the name of the user exit, so that the recovery routine can use the saved
name.
v Common recovery routines: The program should maintain footprints or require
that all modules using a common recovery routine update a common parameter

9-6

z/OS V1R4.0 MVS Assembler Services Guide

list with the name of the current module, CSECT, subfunction, and so on. The
recovery routine can obtain data from the common parameter list when filling in
the SDWA.

Symptoms: When you provide symptom information, select each symptom

carefully. If a symptom is too precise, no other failure will have that symptom; if the
symptom is too general, many failures will have the same symptom. For example,
do not use addresses as symptoms; instead, use names of modules and
components.
DAE accumulates up to 20 specified required and optional symptoms and up to 20
additional symptoms, if specified. The maximum string length is 150, so that not all
of the additional symptoms may appear in the string. A recovery routine can change
the minimum number of symptoms and the minimum string lengths that DAE is to
use for symptom matching for a particular dump. To make these changes, code the
following VRADATA macro keys in the recovery routine:
v The VRAMINSC key controls the minimum number of symptoms.
v The VRAMINSL key controls the minimum string length.

Control of Suppression: When the ADYSETxx parmlib member being used by the
installation contains SUPPRESS, a recovery routine must indicate that enough data
is available to suppress a duplicate dump. To indicate to DAE that the SDWA
contains enough data, set the VRADAE indicator in the SDWA variable recording
area by issuing the following:
VRADATA KEY=VRADAE

If the recovery routine cannot provide enough data in the SDWA suppression, the
recovery routine should indicate that its dump is not eligible for suppression, even
when the ADYSETxx member contains SUPPRESSALL. The routine should set the
VRANODAE indicator by issuing the following:
VRADATA KEY=VRANODAE

The VRANODAE key is useful for error environments that generate identical
symptoms but represent different problems.

When a Dump is Not Suppressed

When DAE is active but does not suppress a dump, DAE adds the reason that the
dump is not suppressed to the dump header record. When viewing a dump online
or printing a dump, specify the IPCS VERBEXIT DAEDATA subcommand to see the
reason that a dump was not suppressed.
Some reasons for not suppressing a dump are:
v The dump is unique. DAE found no match for the symptom string.
v The current ADYSETxx member does not specify SUPPRESS or
SUPPRESSALL for the type of dump being requested.
v A SLIP operator command specifies that the dump is not to be suppressed. A
SLIP command with ACTION=SVCD, ACTION=SYNCSVCD, ACTION=STDUMP,
ACTION=RECOVERY, or ACTION=TRDUMP always produces a dump.
ACTION=NOSUP stops suppression.
v
v
v
v

DAE could not find all required symptoms.

DAE could not find the minimum number of symptoms.
The symptom string built by DAE was shorter than the minimum length.
DAE found certain errors. For example, a required symptom had a key that was
not valid.
Chapter 9. Dumping Virtual Storage (ABEND, SNAPX, SNAP, and IEATDUMP Macros)

9-7

v The VRADAE key in the SDWA is absent, signifying that the dump should not be
suppressed, and the DAE parameter of the ADYSETxx parmlib member does not
specify SUPPRESSALL.
v The VRANODAE key is present in the SDWA, specifying that the dump should
not be suppressed.

SNAP Dumps
A program can request a SNAP dump at any time during its processing by issuing a
SNAPX or SNAP macro. For a SNAP dump, the DD statement can have any name
except SYSABEND, SYSMDUMP, and SYSUDUMP.
If your program is in AR ASC mode, use the SNAPX macro instead of SNAP.
Ensure that the SYSSTATE ASCENV=AR macro has been issued to tell the macro
to generate code and addresses appropriate for callers in AR mode.
Like the ABEND dump, the data set containing the dump can reside on any device
that is supported by BSAM. The dump is placed in the data set described by the
DD statement you provide. If you select a printer, the dump is printed immediately.
However, if you select a direct access or tape device, you must schedule a
separate job to obtain a listing of the dump, and to release the space on the device.
To obtain a dump using the SNAP macro, you must provide a data control block
(DCB) and issue an OPEN macro for the data set before issuing any SNAP
macros. If the standard dump format is requested, 120 characters per line are
printed. The DCB must contain the following parameters: DSORG=PS,
RECFM=VBA, MACRF=W, BLKSIZE=882 or 1632, and LRECL=125. (The DCB is
described in z/OS DFSMS: Using Data Sets, and z/OS DFSMS Macro Instructions
for Data Sets). If a high-density dump is to be printed on a 3800 Printing
Subsystem, 204 characters per line are printed. To obtain a high-density dump,
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.
CHARS=DUMP can also be coded on the DD statement describing a dump data
set that will not be printed immediately. If CHARS=DUMP is specified and the
output device is not a 3800, print lines are truncated and print data is lost. If your
program is to be processed by the loader, you should also issue a CLOSE macro
for the SNAP DCB.

Finding Information in a SNAP Dump

You will obtain a dump index with each SNAP dump. The index will help you find
information in the dump more quickly. Included in the information in the dump index
is an alphabetical list of the active load modules in the dump along with the page
number in the dump where each starts.

Obtaining a Summary Dump for an ABEND or SNAP Dump

You can request a summary dump for an abending task by coding the SUM option
of the SNAP macro. You can also obtain a summary dump by coding the
DUMPOPT option on the ABEND or SETRP macro and specifying a list form of
SNAP that contains the SUM option. Use the DUMPOPX parameter on ABEND or
SETRP to obtain an ABEND dump that contains data space storage. When you use
DUMPOPX, specify a list form of SNAPX that contains the SUM option.
If SUM is the only option that you specify, the dump will contain a dump header,
control blocks, and certain other areas. The contents of the summary dump are
described in z/OS MVS Recovery and Reconfiguration Guide.

9-8

z/OS V1R4.0 MVS Assembler Services Guide

Transaction Dumps
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. You can request that the dump be written
to a data set that is either pre- allocated or automatically allocated. To request a
pre-allocated data set, specify an open MACRF=W DCB that contains sufficient
space in one or more extents for the entire dump to be written. If you dont provide
a large enough data set, you will receive a partial dump. To request automatic
allocation, ensure a dump will not be truncated due to space constraints and specify
a data set name pattern. Automatic allocation is done to SYSALLDA.
When a Transaction dump is written, a dump directory record describing the dump
may be written. Specify the dump directory to be used with the IDX keyword on the
dump request. If you do not specify a dump directory, 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 you provide a
symptom string, 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.
Authorized users may specify the REMOTE keyword on the IEATDUMP macro to
request other address spaces on the current or other MVS images (in the same
sysplex) be dumped. When you request remote dumps, automatic allocation must
also be used.
Transaction dump uses an incident token to associate this dump with other
diagnostic information. Automatic allocation also uses this incident token for symbol
substitution in the data set name pattern. You can generate an incident token using
the IEAINTKN macro and providing the INTOKEN keyword on the dump request. If
you do not provide an incident token, one will be generated and used internally.
While an incident token may always be specified, it may be especially important
when remote dumps are requested.
An asynchronous dump may be requested by specifying ASYNC=YES on the dump
request. It is recommended that an ECB be specified for asynchronous dumps to
ensure that any volatile resources are captured before being freed.

Chapter 9. Dumping Virtual Storage (ABEND, SNAPX, SNAP, and IEATDUMP Macros)

9-9

9-10

z/OS V1R4.0 MVS Assembler Services Guide

Chapter 10. Reporting Symptom Records (SYMRBLD and

SYMREC Macros)
An installations programmers can write authorized or unauthorized applications that
detect and collect information about errors in their processing. Through the
SYMRBLD or SYMREC macro, the applications can write a symptom record for
each error to the logrec data set, the online repository where MVS collects error
information. Programmers can analyze the records in the logrec data set to
diagnose and debug problems in the installations applications.
The unit of information stored in the logrec data set is called a symptom record.
The data in the symptom record is a description of some programming failure
combined with a description of the environment where the failure occurred. Some of
the information in the symptom record is in a special format called the structured
data base (SDB) format.
An installations programmers can do the following:
v Build the symptom records using the SYMRBLD macro.
v Record the symptom records on the logrec data set using SYMRBLD or
SYMREC.
v Format