Text preview for : GC28-0628-0_OS_VS2_System_Programming_Library_Supervisor_Rel_3_Feb75.pdf part of IBM GC28-0628-0 OS VS2 System Programming Library Supervisor Rel 3 Feb75 IBM 370 OS_VS2 Release_3.0_1975 GC28-0628-0_OS_VS2_System_Programming_Library_Supervisor_Rel_3_Feb75.pdf
Back to : GC28-0628-0_OS_VS2_System | Home
GC28-0628-0
File No. 5370-36
OS/VS2 System Programming
Systems Library: Supervisor
VS2 Release 3
. !)
i tZJ
First Edition (February, 1975)
This edition, with OS/VS2 System Programming Library: Job Management, GC28-0627, and
OS/VS2 System Programming Library: TSO, GC28-0629, obsoletes OS/VS2 System
Programming Library: Job Management. Supervisor, and TSO, GC28-0682-0.
This edition applies to release 3 of OS/VS2 and to all subsequent releases of OS/VS2
until otherwise indicated in new editions or Technical Newsletters. Changes are
continually made to the information herein; before using this publication in connection
with the operation of IBM systems, consult the latest Virtual Storage Supplement to IBM
System/360 and System/370 Bibliography, Ge20-000l, for the editions that are applicable
and current.
Requests for copies of IBM publications should be made to your IBM representative or
to the IBM branch office serving your locality.
A form for readers' comments is provided at the back of this publication. If the form
has been removed, comments may be addressed to IBM Corporation, Programming
Systems Publications, Department ])58, Building 706-2, PO Box 390, Poughkeepsie, N.Y.
12602. Comments become the property of IBM.
@ Copyright International Business Machines Corporation 1974,1975
Preface
This publication describes supervisor facilities that can be influenced by the
system programmer.
Part I: Supervisor Services discusses supervisor functions restricted to
system programmers and installation-approved personnel, and the macro
instructions and parameters used to obtain the functions.
Part I is divided into .seven topics. For convenience and compatability, these
services are grouped in the same manner as in OS/VS2 Supervisor Services
and Macro Instructions, GC28-0683. Accordingly, some of the subjects
discussed are merely continuations of previous coverage, but are extended
to include discussions of the new functions. However, some subjects
discussed under the topics are completely new, but are restricted in use to
the system programmer.
Part II: Macro Instructions contains the formats and descriptions of the
supervisor macro instructions. It provides system programmers with the
information necessary to code the macro instructions.
Publications referenced:
OS/VS2 System Programming Library: Data Management, GC26-3830.
IBM System/370 Principles of Operation, GA22-7000.
OS/VS2 Supervisor Services and Macro Instructions, GC28-0683.
OS/VS2 Scheduler and Supervisor Logic, SY28-0624,SY28-0625,SY28-0626.
(3 volumes)
OS/VS - DOS/VS - VM/370 Assembler Language, GC33-4010.
OS/VS2 System Programming Library: System Generation Reference,
GC26-3792.
Preface 3
4 OS/VS2 System Programming Library: Supervisor (VS2 Release 3)
Contents
Summary of Amendments ..... . 9
Part I: Supervisor Services ..... 11
Subtask Creation and Control 13
Creating a New Task 13
User Modifications . . . 14
Operator Communication With a Problem Program 15
Providing an EXTRACT Answer Area 16
Program Management 17
Synchronous Exits 17
Resource Control 19
Locking 19
Classes of Locks 20
Types of Locks 20
Locking Hierarchy 21
Locking Considerations 21
SETLOCK Macro Instruction 22
The Must Complete Function 22
Characteristics of the Must Complete Function 23
Programming Notes . . . . . . '. . . . . . 23
Shared Direct Access Storage Devices (Shared DASD) 24
Devices That Can be Shared 24
Volume/Device Status 24
System Configuration . . . 25
Volume Handling 25
Macro Instructions Used With Shared DASD 25
Releasing Devices . 25
Preventing Interlocks 25
Volume Assignment 26
Program Libraries . 26
Finding the UCB Address 26
Authorized Program Facility (APF) 30
Restricting Services/Resources 30
Assigning Authorization 30
Defining Authorized Libraries 31
Changing System Status 32
Generating an SVC . . . . . 32
Generating Inline Code . . . 32
Interprocessor Communications (IPC) 32
Service Classes . 33
Status Conditions 34
Event Completion . 35
Cross Memory POST 35
Bypassing the POST Routine 35
Waiting for Event Completion 36
Interruption, Termination, and Dumping Services 37
Recovery /Termination . . . . . . . . . 37
Task Termination . . . . . . . . . 37
Ad'dress Space Termination . . . . . 38
Processing Functional Recovery Routines 38
SETFRR Macro Instruction 39
SPIE Processing . . . . . . . . . . . 39
Dumping Virtual Storage ..... . 39
Using the SDUMP Macro Instruction 39
SQA Buffer . . . . . . . . . . 40
Using the CHNGDUMP Command 40
Task Recovery . . . . . . . . . . 41
ST AE/ST AI Exit Routines 41
Interface to a ST AE/ST AI Exit 42
ST AE/ST AI Retry Routines . 42
EST AE Extended Capabilities . . 43
Contents 5
The BRANCH Option . . . . . . . . 44
The TERM Option . . . . . . . . . 44
The PURGE and ASYNCH Parameters 44
EST AE/EST AI Exit Routines 45
Interface to an EST AE/EST AI Exit 47
EST AE/EST AI Retry Routines 49
Clean-Up Routines . . . . . . . . . . 50
Support for Installation-Written Clean-Up Routines 50
Programming Considerations . . . . . . . . . . 50
Virtual Storage Management . 53
The BRANCH Parameter 53
The KEY Parameter 53
Real Storage Management . . . . . . . 55
Fixing/Freeing Virtual Storage Contents 55
Completion Considerations 56
Virtual Subarea List (VSL) . . . . . . 56
Miscellaneous Services 59
Writing Operator Messages 59
Routing the Message 59
Writing a Multiple-Line Message 60
Message Routing Exit Routines . . 60
Characteristics of M CS 60
Programming Conventions for WTO/WTOR Routines 61
Messages Not Using Routing Codes . . . . . . . 62
Writing a WTO/WTOR Exit Routine ...... . 62
Adding a WTO/WTOR Exit Routine to the Control Program 62
Service Management ...... . 63
Scheduling Service Requests . . . 64
Service Request Blocks (SRBs) 64
Priorities . . . . . . . . . . 64
Characteristics of Service Requests 65
Purging Service Requests 65
PURGEDQ Parameters 66
Creating Interruption Request Blocks 66
Writing SVC Routines . . . . . . . 67
Characteristics of SVC Routines . 67
Programming Conventions for SVC Routines 67
Inserting SVC Routines Into the Control Program 70
Specifying SVC Routines . . . . . . . . . . 70
Inserting SVC Routines During the System Generation Process 71
Missing Interruption Handler . . . . . . . . . . . 71
Establishing a Time Interval . . . . . . . . . . . . . . 71
Adding Code to the Power Warning Feature Support . . . . 72
Writing Code for the Machine Check Handler Appendage 72
Coding Considerations . . . . . . . . . . . . . . . 73
Writing Code for the Master Scheduler Initialization Routine 74
Coding Considerations 75
Control Track Record . . . . . . . . . . . . . . . . 76
Part II: Reference - Macro Instructions 79
Macro Instruction Forms . . . 80
Coding the Macro Instructions 80
Continuation Lines . . . . . 82
Descriptions of the Macro Instructions ..... . 83
A TT ACH -- Create a New Task . . . . . . 84
CALLRTM -- Call Recovery/Termination Manager 88
CHNGDUMP -- Change Dump Options . . 90
CIRB - Create Interruption Request Block 94
DEQ -- Release a Serially Reusable Resource 96
DEQ (List Form) . . . . . 99
DEQ (Execute Form) . . . . . . . . . . 100
DSGNL -- Issue Direct Signal ..... . 101
ENQ -- Request Control of a Serially Reusable Resource 103
ENQ (List Form) 106
ENQ (Execute Form) 107
EST AE -- Extended ST AE 108
6 ' OS/VS2 System Programming Library: Supervisor (VS2 Release 3)
EST AE (List Form) . . . . . . . . . 110
EST AE (Execute Form) . . . . . . . 111
I EVENTS -- Wait for Events . . . . . 112
EXTRACT -- Extract TCB Information 113
EXTRACT (List Form) . . . . . 115
EXTRACT (Execute Form) 116
FREE MAIN -- Free Virtual Storage 117
FREEMAIN (List Form) . . . . . 119
FREE MAIN (Execute Form) . . . 120
GET MAIN -- Allocate Virtual Storage 121
GETMAIN (List Form) . . . . . . 123
GET MAIN (Execute Form) 124
MODESET -- Change System Status 125
MODESET (List Form) . . . . . . 128
MODESET (Execute Form) 129
NIL -- Provide a Lock Via an AND IMMEDIATE (NI) Instruction 130
OIL -- Provide a Lock Via an OR IMMEDIATE (01) Instruction 132
PGFIX -- Fix Virtual Storage Contents 134
PGFIX (List Form) . . . . . . . . . . 137
PGFREE -- Free Virtual Storage Contents 138
PGFREE (List Form) . . . . . 140
POST -- Signal Event Completion 141
POST (List Form) . . . . . . 142
POST (Execute Form) . . . . 143
RGEDQ -- Purge SRB Activity 144
PURGEDQ (List Form) 145
PURGEDQ (Execute Form) 146
QEDIT -- Link to SVC 34 147
RESERVE -- Reserve a Device 148
RESERVE (List Form) 151
RESERVE (Execute Form) . . 152
RISGNL -- Issue Remote Immediate Signal 153
RPSGNL -- Issue Remote Pendable Signal . 155
SCHEDULE -- Schedule System Services for Asynchronous Execution 157
SDUMP -- Dump Virtual Storage . . . . . . . 158
SDUMP (List Form) ........... . 161
SDUMP (Execute Form) . . . . . . . . . . . 162
SETFRR -- Set Up Functional Recovery Routines 164
SETLOCK -- Control Access to Serially Reusable Resources 166
SETRP -- Set Return Parameters 173
SPIE -- Specify Program Interruption Exit 177
SPIE (List Form) . . . . . 178
SPIE (Execute Form) . . . . . . . 179
SPOST -- Synchronize POST . . . . 180
ST AE -- Specify Task Abnormal Exit 181
ST AE (List Form) ...... . 184
STAE (Execute Form) . . . . . . . 185
ST A TUS -- Change Subtask Status 186
SYNCH -- Take a Synchronous Exit to a Processing Program 190
TEST AUTH -- Test Authorization of Caller 191
WTO -- Write to Operator . . . . . . 193
WTO (List Form) . . . . . . . . . . 196
WTOR -- Write to Operator With Reply 197
WTOR (List Form) 199
Index 201
Contents 7
Figures
Figure 1. EXTRACT ECB and CIB Pointers 15
Figure 2. Command Input Buffer Contents 15
Figure 3. EXTRACT Answer Area Fields 16
Figure 4. Summary of Locking Characteristics 21
Figure 5. Valid Volume Characteristic and Device Status Combinations 24
Figure 6. Example of an Interlock Environment . . . . . . 26
Figure 7. Example of Subroutine Issuing RESERVE and DEQ 29
Figure 8. Assigning Authorization via SETCODE 31
Figure 9. Bypassing the POST Routine 36
Figure 10. EST AE Environment . . . . . . . . 46
Figure 11. Virtual Subarea List Entries . . . . . 56
Figure 12. Programming Conventions for SVC Routines 68
Figure 13. Changing the Missing Interruption Handler Time Interval 71
Figure 14. Logical Placement of Your Code in the Machine Check Handler Appendage 73
Figure 15. Logical Placement of Your Code in the Master Scheduler Initialization Module 75
Figure 16. Control Track Record ..... . 76
Figure 17. Storage Assignments on MP Systems 77
Figure 18. Macro Instruction Coverage . . 79
Figure 19. Sample Macro Instruction . . . 81
Figure 20. Continuation Coding . . . . . 82
Figure 21. Return Code Area Used by DEQ 97
Figure 22. Return Code Area Used by ENQ 104
Figure 23. Return Code Area Used by RESERVE 150
Figure 24. MCSFLAG Fields . . . . . . . . . 194
8 OS/VS2 System Programming Library: Supervisor (VS2 Release 3)
Summary of Amendments
for GC28-0628-0
OS/VS2 Release 3
This edition, with OS/VS2 System Programming Library: Job SPIE Macro Instruction
Management, GC28-0627, and OS/VS2 System Programming
The syntax of the SPIE macro instruction is presented.
Library: TSO, GC28-0629, obsoletes OS/VS2 System
Programming Library: Job Management, Supervisor, and TSO,
GC28-0682-0. Miscellaneous Corrections
EST AE processing
Power Warning Feature Support APF
Locking
This edition incorporates system programmer information MODESET
previously contained in OS/VS Power Warning Feature WTO
(PWF) Support, ICR Guide, GC28-0686-0. Command input buffers
Virtual Storage Management Examples
New Subpools 227 and 228 are discussed. The examples of the standard, list, and execute forms of the
macro instructions are more properly placed at the ends of
their appropriate sections.
Event Completion
The EVENTS macro instruction, and its use, are discussed.
Summary of Amendments 9
10 OS/VS2 System Programming Library: Supervisor (VS2 Release 3)
Part I: Supervisor Services
The supervisor provides the resources that your programs need while assuring that as many of
these resources as possible are being used at a given time. Well designed programs use system
resources efficiently. Knowing the conventions and characteristics of the vs supervisor will
help you design more efficient programs.
This section describes those supervisor services that should be restricted in use to systems
programmers and installation-approved personnel. In most cases, the services correspond to
macro instructions and parameters that are described in part II.
For convenience and compatibility, the services you can request from the supervisor are
grouped in the same manner as in OS/VS2 Supervisor Services and Macro Instructions. The
service groupings may be described as follows:
Subtask Creation and Control: Occasionally, you can have your program executed faster and
more efficiently by dividing parts of it into subtasks that compete with each other and with
other tasks for execution time.
Program Management: The supervisor can be used to aid communication between segments of
a program. Save areas, address ability , and passage of control from one segment of a program
to another are included in this topic.
Resource Control: Portions of some tasks depend on the completion of events in other tasks,
thus requiring planned task synchronization. Planning is also required when more than one
program uses a serially reusable resource.
Interruption, Termination, and Dumping Services: The supervisor provides facilities for writing
exit routines to handle specific types of interruptions. It is not likely, however, that you will be
able to write routines to handle all types of abnormal conditions. The supervisor therefore
provides for termination of your program when you request it by issuing an ABEND macro
instruction, or when the control program detects a condition that will degrade the system or
destroy data.
Virtual Storage Management: While virtual storage allows you to write large programs without
the need for complex overlay structures, virtual storage must be obtained for your job step.
Virtual storage is allocated by both explicit and implicit requests.
Real Storage Management: The supervisor administers the use of real storage and directs the
movement of virtual pages between auxiliary storage and real storage in page size blocks. The
services provided allow you to release virtual storage contents, load virtual storage areas into
real storage, and page out virtual storage areas from real storage.
In addition to the services outlined above, the supervisor provides the facilities for timing
events, extended precision floating-point simulation, and operator communication with both the
system and application programs.
Part I: Supervisor Services 11
12 OS/VS2 System Programming Library: Supervisor (VS2 Release 3)
Subtask Creation and Control
One task is created by the control program as a result of initiating execution of the job step
(the job step task). You can create additional tasks in your program. If you do not, however,
the job step task is the only task in a job 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 jobs 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 than the task in the job you are concerned with. When a wait condition
occurs in one of your tasks, it is not necessarily a task from some other job that gets control;
it may be one of your tasks, a portion of your job.
The general rule is that parallel execution of a job step (that is, more than one task in a job
step) should be chosen only when a significant amount of overlap between two or more tasks
can be achieved. 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 must be taken into account.
Most of the information concerning subtask creation and control appears in OS/VS2
Supervisor Services and Macro Instructions. This chapter continues discussion in the following
areas: