Scanned GY28 2018 3_Time_Sharing_System_System_Service_Routines_PLM_Sep71 3 Time Sharing System Service Routines PLM Sep71
GY28-2018-3_Time_Sharing_System_System_Service_Routines_PLM_Sep71 GY28-2018-3_Time_Sharing_System_System_Service_Routines_PLM_Sep71
User Manual: GY28-2018-3_Time_Sharing_System_System_Service_Routines_PLM_Sep71
Open the PDF directly: View PDF 
.
Page Count: 133
| Download | |
| Open PDF In Browser | View PDF |
File No. S360-31
GY2S-201S-3
--..----. --____
1'_
-- ----
-
-----
Program Logic
Version 8.1
IBM System/360 Time Sharing System
System Service Routines
Describes the internal logic of the system service
routine used in TSS/360. The system service routines
are non-resident programs that can be invoked either
directly by the user, through the use of system commands and macro instructions, or indirectly, in response to requests from other system components.
The system service routines are divided into eight
categories: catalog services; external storage allocation; device management; virtual memory allocation;
small virtual memory allocation; symbolic library
services; control section store; and serviceability
aids. Appendixes describe VAM and SAM OSCB formats
and catalog SBLOCK formats.
This material is intended for persons involved in
program maintenance, and system programmers who are
altering the program design.
It can be used to locate
specific areas of the program, and it enables the
reader to relate these areas to the corresponding program listings. Program logic information is not necessary for the use and operation of the program.
Prerequisite Publications
The reader must be familiar with the information
presented in:
IBM System/360 Time Sharing System:
Programmer's Guide, Ge2S-200S
IBM System/360 Time Sharing s*stem:
Logic Summary PLM, GY2B-20 9
System
System
PREFACE
This book describes the internal logic
of the system service routines used in
TSS/360. The system service routines are
divided into eight categories and each
category is discussed in a separate section
of this book:
1.
Catalog services
2.
External Storage Allocation
3.
Device Management
4.
Virtual Memory Allocation
5.
Small Virtual Memory Allocation
6.
Symbolic Library Services
7.
Control section Store
B.
serviceability Aids
Each of the 8 sections provides a general
description of the catagory and also
individual routine descriptions. Section 9
contains the flowcharts for all the
routines. Appendixes include a module
directory and descriptions of VAM and SAM
DSCB formats and catalog SBLOCK formats.
The material in this book is intended
for persons involved in program
rr.aintenance, and system programmers who are
altering the program design.
It can be
used to locate specific areas of the
program and i t enables the reader to relate
these areas to the corresponding program
listings. Program logic information is not
necessary for the use and operation of the
program.
The reader must be familiar with the
information presented in:
IBM System/360 Time Sharing System:
System Programmers Guide, GC28-2008
IBM System/360 Time Sharing System:
System Logic Summary PLM, GY28-2009
Fourth Edition (September 1971)
This is a major revision of. and makes obsolete,
GY28-2018-2 and Technical Newsletters GN28-312q and
GN28-1152. Changes since the latest Technical
Newsletter include four new catalog Service routines
USERCAT SCAN (CZUFY). CATFLUSB (CZCFX), DSCB/CAT
RECOVERY (CZUFX>. catalog Error Processor (CZCFE), and
a new External Storage Allocation routine, READWRIT
(CZCEM). SHAREUP (CZCFU) and LOCATE (CZCFL) have teen
changed extensively and smaller changes have been made
to INDEX (CZCFI) and MOUNTVOL (CZCAM).
This edition applies to Version 8, Modification 1,
of the IBM System/360 Time Sharing System, and to all
subsequent releases until otherwise indicated in new
editions or Techincal Newsletters. Before using this
publication. please refer to the latest edition of IBM
system/360 Time Sharing System: Addendum. GC28-20Q3,
which lists the current editions of publications.
This publication was prepared for production using an IBM computer to
update the text and to control the page and line format.
Page
impressions for photo-offset printing were obtained from an IBM lQOJ
Printer using a special print chain.
Requests for copies of IBM publications should be made to your IBM
representative or to the IBM branch office serving your locality.
A form is provided at the back of this publication for reader's
comments.
If the form has been removed. comments may be addressed to
IBM Corporation, Dept. 643. Neighborhood Road, Kingston. New York 12401
© Copyright International Business Machines Corporation
1967,1969,1970.1971
CONTENTS
INTRODUCTION
1
SECTION 1: CATALOG SERVICES.
General Description of Catalog Services •
The catalog • . • • • • • •
Catalog Protection
• • • • • • • •
Cataloo Services Routines • • • • • • • • • • • • •
Routines Invoked by the User Program
Routines Invoked by Other Catalog Service Routines
Routines Invoked by Other System Routines for Dynamic Catalog
Operation . . •
• • • • •
• • • •
ADDCAT (CZCFA)
• • • •
• •••••••••••••••
DELCAT {CZCFr:;}
SHARE (CZCFS) •
UNSHARE (CZCFV)
•
Collective Removal
•
Selective Removal •
·
SHAREUP (CZCFU) • .
·
LOCATE (CZCFL)
. • • •
•
CATALOG ERROR PROCESSOR (CZCFE) •
• •
INDEX (CZCFI) • • • . •
•
GETSBLOCK (CZCFG) • • •
•
SEARCHSBLOCK (CZCFH)
• •
USERCAT SCAN (CZUFY)
CATFLUSH (CZCFX)
•
DSCB/CAT RECOVERY (CZUFX) • • • •
2
2
2
SECTION 2: EXTERNAL STORAGE ALLOCATION
External Volumes • • • • • • • • • • •
• • •
Public and Private Volumes • • • • •
••••••••••
Duplexing capability for USER Data Sets • • • • • • • •
SAM Volume Processing • • • • • . • • • • • • •
VAM Volume Processing • • • • • • • • •
Routines Used With SAM Format Volumes
ALLOCATE (CZCEA)
• • • •
SAMSEARCH (CZCEC)
• • • • •
SCRATCH (CZCES) •
• • • • • • • •
EXTEND (CZCEX)
• • • •
GIVBKS -- Give Back SAM Storage (CZCEG)
MERGESAM (CZCEE)
OBTAIN/RETAIN (CZCFO)
OBTAIN Request
· • •
RETAIN Request • • • • •
RENAME (CZCFZ)
••••
Routines Used With VAM Format Volumes •
• • •
FINDEXPG (CZCEL)
ADDDSCB (CZCEK)
VOLSRCH (CZCEH) •
• • •
RELEXPG (CZCEN) • • • •
• • • •
DSCBREC (CZCEF) • • • • • •
WRITDSCB (CZCEW)
• • • •
VAMINIT (CZCEQ) • • • • • •
READWRIT (CZCEM)
•••••
ESA LOCK (CZCEJ)
SECTION 3: DEVICE MANAGEMENT
General Operation • • • • •
MOUNTVOL Routine (CZCAM)
MTREQ Routine (CZCAA) .
BUMP Routine (CZCAB)
RELEAS Routine (CZCAD)
PAUSE Routine (CZCAC> •
4
4
4
5
5
5
9
10
12
14
14
14
15
20
21
23
24
24
26
28
30
30
30
30
31
31
32
32
• 32
•
• 35
• • • 35
36
•
•
•
•
•
• • •
•
•
• • 38
• 38
• • 40
•
.
• • • 41
• 42
• • • • 42
42
•
•
•
43
• 45
• • • 46
· 47
•
•
•
49
• 50
• • • 51
• • 52
• 54
• • • 54
• • • 55
• 57
• • 59
• 60
• 61
iii
SECTION 4: VIRTUAL MEMORY ALLOCATION • • • •
VMA -- Virtual Memory Allocation (CZCGA)
GETMAIN (CZCGA2)
• • • • • • • • • •
Allocation of Packed Virtual Storage
Allocation of Non-Packed Virtual Storage
Allocation of Virtual Storage • •
FREEMAIN (CZCGA3) • • • • . • • •
Release of a Variable Allocation
Releasing Storage •
EXPAND (CZCGA4) •
GETSMAIN (CZCGA6) •
CONNECT (CZCGA7)
DISCONNECT (CZCGA8)
• • • •
•
• • • •
•
• •
• •
•
•
• • • •
63
64
66
67
67
67
67
68
68
68
• 69
• 70
• 71
SECTION 5: SMALL VIRTUAL MEMORY ALLOCATION
General Description • • • • • •
Internal Tables • • • • • • • • • •
Internal Subroutines Available
Small Virtual Memory Allocation (CZCHA) •
• 73
• 73
• 73
SECTION 6: SYMBOLIC LIBRARY SERVICE ROUTINES
Symbolic Library Indexing Routine (SYSINDEX)
Symbolic Library Search Routine (SYSEARCH)
User Subroutine for SYSXBLD • • • • • • • • • •
SYSINDEX -- Symbolic Library Indexing Routine (CGCKA)
SYSXBLD -- Build Symbolic Library Index (CGCKB) • • •
SYSEARCH -- Symbolic Library Search Routine (CGCKC) •
• 77
• 77
•
• •
•
• •
•
SECTION 7: CONTROL SECTION STORE ROUTINE
Control Section Store (CZCKZ)
• 82
• • 82
• 74
74
78
78
78
79
81
SECTION 8: SERVICEABILITY AIDS
• • • •
• 84
Error Information Recording and Retrieval • •
• 84
Error Information Recording •
• • • •
• 84
Error Information Retrieval •
• 84
Virtual Storage I/O Operation Aids
• 84
I/O Request Control Block (IORCB) • • • • •
• 84
I/O Statistical Data Table (SDT)
• • • •
• 85
Virtual Memory Statistical Data Recording (CZCRY)
• 85
Virtual Memory Error Recording (CZCRX)
• 86
Drum Access Module (CZASY)
•••••••••••
• • • • 88
Virtual Memory Environment Recording Edit and Print (CZASE) • • • 89
Environment Recording Edit and Print, Model 67 (CMASN)
90
RTAM Error Recording Interface Module (CZCTR)
• • • •
• 91
Time Conversion • • • • • •
• • • • •
• • 92
SYSTIME Routine (CZCTA) •
• 92
SECTION 9: FLOWCHARTS • • •
APPENDIX A: DATA SET CONTROL BLOCK (OSCB)
APPENDIX B: CATALOG SBLOCK FORMAT • •
SBLOCK Format •
APPENDIX C: MODULE DIRECTORY
INDEX • • •
iv
• • • • 94
FOR~~T
.260
• .272
• .272
.279
• • • • • • 284
IL:;:'USTRP.TIONS
Figure
Figure
Figure
Figure
Figure
Figure
Figure
Figure
Figure
Figure
Figure
Figure
Figure
Figure
.Figure
Figure
Figure
Figure
Figure
Figure
Figure
Figure
SBLOCK
Figure
Figure
Figure
Figure
Figure
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
1-
2.
3.
4.
5.
6.
7.
8.
9.
10.
1112.
13.
11+.
15 .
16.
17 •
18.
19.
20.
2122.
23.
21+.
25.
26.
27.
AA.
AB.
AC.
AD.
AE.
AF.
AG.
AH.
AI.
AJ •
M.
AL.
AM.
BA.
BB.
BC.
BD.
BE.
BF.
BG.
BH.
BI.
BJ •
BK.
BL.
BM.
BN.
BO.
BP.
PQ.
Typical SBLOCK Format
••.••••••••
3
Option Codes for VAM Input Parameter
• • ••
6
Format of SHARE Control field • • • •
• •••
• 11
l'y!=e,; of OBTAIN Requests
•. . • • •
• • • •
• 40
General Diagram of Device Management Operation • • • • • 55
Standard (~efault) Virtual Memory Allocation
• 63
Location of Input Parameters for GETMAIN
• 66
DRAM Condition Code Recovery Procedures
• 88
Format-l OSCB
.261
Format-3 DSCB
.265
Format-I+ DSCB
.265
Format-5 OSCB
• • • • • • • .267
Format-A DSCB
· • • • •
• 268
Format-B OSCB
• • • • •
• • .269
Format-C OSCB
• • • • • • .270
Format-E DSCB
• • • •
.270
Format-F OSCB •
• • • • • • • 271
General SBLOCK Format
• • ••
..272
SBLOCK Format - Data Set Descriptor (First Block)
.273
SBLOCK Format - Data Set Descriptor (Chained SBLOCKs)
.274
SBLOCK Format - Index (Generation Index) -- First SBLOCK 275
SBLOCK Format - Index (Generation Index) - Chained
• . . • • • • • • • • • • • . • . • • • • •
• 276
SELOCK Format - Sharing DescriFtor • • • . • • •
.276
SBLOCK Format - Sharer List (First SBLOCK)
.277
SBLOCK Format - Sharer List (Chained SBLOCKS)
.278
Module Directory, Indexed Alphabetically by Module Title 279
Module Directory, Indexed Alphabetically by Module Name .283
·
·
·
·
·
. . . .
··
AD DCA'T (CZCFA)
DELCAT (CZCFD)
SHARE (CZCFS)
UNSBARE (CZCFV)
SHAREUP (CZCFU)
GETS BLOCK (CZCFG)
SEARCHSBLOCK (CZCFH)
LOCATE (CZCFL)
INDEX (CZCFI)
USERCAT SCAN (CZUFY)
OSCB/CAT RECOVERY (CZUFX)
CATFLUSH (CZCFX) ·
.
Catalog Error Processor (CZCFE)
ALLOCATE (CZCEA) ·
SAMSEARCH (CZCEC)
SCRATCH (CZCES)
EXTEND (CZCEX)
GIVBKSAM (CZCEG)
MERGESAM (CZCEE)
OBTAIN/RETAIN (CZCFO)
REN,\ME (CZC FZ)
FINLEXl'G (CZCEL)
ACDCSCE (CZCEK)
VOL;3RCH (CZCE!j)
RELEXPG (CZCEN)
DSCBREC ( CZCEF)
WRITOSCB (CZCEW)
VAMINIT (CZCEQ)
RIcA[;WRI'I' (CZCEM)
ESA LOCK (CZCEJ)
··.
.
.
. .
· · ·
. · . · ·
· · ·· · · · ·
...
·
·
· · · ·
·
· · · ·
·
· · ·
· · ·
·
·
·
·
·
· · · .
· · · ·
·
95
.102
.105
.106
.108
.109
.111
.112
.123
.126
.130
.141
.145
.146
.147
.149
.150
.151
.152
.155
.157
.158
.160
.163
.168
.172
.181
.188
.189
.191
v
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
Chart
chart
Chart
Chart
Chart
vi
CA.
CE.
CC.
CD.
CEo
DA.
EA.
FA.
FB.
FC.
GA.
HA.
HB.
HC.
HD.
HE.
HF.
HG.
MTREQ (CZCAA)
PAUSE (CZCZC)
RELEAS (CZCAD)
BUMP (CZCAB)
MOUNTVOL (CZCAM)
VMA (CZCGA)
SVMA (CZCHA)
SYSINrEX (CGCKA)
SYSXBLD (CGCKB)
SYSEARCH (CGCKC)
CSECT STORE (CZCKZ) .
VMSDR (CZCRY)
VMER (CZCRX)
DRAM (CZASY)
VMEREP (CZASE)
EREP67 (CMASN)
SYSTIME (CZCTA)
RERIM (CZCTR)
· . · · ·
·
· ·
····
·
····
··
. · · · ·· ·· ·· ·· · · ·
·
· ·
··
· ·
· · · · · · ·
··
·
····
·····
···
·····
····
··
·····
··
· · ·· ·· ..
·
··
···
· · ·
·
·
·
··
·
·
·
·
·
·
.194
.205
.208
.210
.212
.221
.234
.240
.241
.242
.243
.244
.245
.252
.253
.254
.255
.259
INTRODUCTION
IBM System/360 1'ime Sharing System,
hereafter referred to in this publication
as Time Sharing System/360 (TSS/360>, provides eight categories of system service
routines. These rout_ines are invoked ei ther directly by the user through use of system commands and macro i~structions. or
indirectly, in response to requests from
other system components.
The eight categories are:
• Catalog Services: These routines allow
the user to read, write, update, and
share his user catalog and the data
sets contained in it. The catalog is a
hierarchial index structure; each index
level is made up of 64-byte blocks of
storage called SBLOCKs. catalog service routines operate on the index
levels and the SBLOCKs.
• External storage Allocation: These
routines control the storage on direct
access volumes used for data storage.
One group of routines controls the initial allocation of storage to a data
set and the secondary allocation of
storage as it is needed. When storage
is no longer needed, it can be returned
in part, or all the space assigned to
the data set can be returned when the
data set is deleted.
One set of ESA
routines is used for the processing of
SAM format volumes and another for VAM
format.
• Device Management: These routines are
used to allocate, mount, and release
private devices. Mounting messages are
issued to the operator; and his reply
is awaited. Facilities are provided to
mount subsequent volumes of a multivolume physical sequential data set on
the same device as earlier volumes of
the same data set.
• Virtual Nemory Allocation: This routine provides for problem program
requests for dynamic allocation and
release of virtual storage during program execution.
In addition, an existing block of storage can be dynamically
expanded. The storage obtained can be
either private or shared.
• Small Virtual Memory Allocation: This
routine provides the system or user
[rag ram with dynamic allocation of virtual storage by bytes.
SVMA obtains
integral numbers of pages from VMA
which ar~ then segmented to satisfy the
requests.
• Symbolic Library Service Routines: A
symbolic library is composed of two
portions: an index and a symbolic comronent. Each portion may be a distinct
data set, or they may be members of
different partitioned data sets. The
symbolic portion contains source statements; the index portion is used to
locate the desired group of symbolic
statements. Routines are provided to
automatically index and retrieve individual sections from the library.
• Control Section Store Routine: This
routine is invoked by the CSTORE macro
instruction.
It enables the user to
create, during program execution, a
control section that is placed as a
module in the current JOBLIB.
• Serviceability Aids: These aids consist of service programs to record and
retrieve statistical data concerning
system performance and hardware failures, and a routine which converts
time and date from system format to
EBCDIC form.
Introduction
1
GENERAL DESCRIPTION OF CATALOG SERVICES
THE CATALOG
The system catalog (called the scratch
catalog) is a VAM partitioned data set that
exists in virtual storage fr·'m startup to
shutdown. This is a dynamic catalog since
only members (users) that are active during
a session exist in the scratch catalog.
The individual user catalogs are VS data
sets with format U records that reside on
public storage.
When a user logs on, the scratch catalog
is searched for the user's member. and
normal logon procedure follows if it is
found.
If the user's member is not found,
the external VS rr:~mber will be copied into
the scratch catalog. subsequent references
will use the scratch catalog.
When the user logs off (or abends), a
check is made to see if the scratch catalog
member has been changed.
If it has, the
system copies the scratch catalog member
into the external VS data set. At shutdOWII, the scratch catalog is erased. If a
scratch catalog exists at startup (no shutdown), it will be used as the system catalog.
Entries in the catalog contain
infomation about the physical location of
data, a list of users who have access to
the data, and how the data may be accessed.
The catalog is a hierarchical structure of
indexes, each uniquely identifiable by its
symbolic name plus the symbolic name of
each higher-level index in its structure.
The highest level of index in the catalog
contains one entry for each authorized user
of the system. Each entry is the eightcharacter userid, which is concatenatF..!d
automatically by the system to the name
that the user assigns to his data set.
This highest level index is called the
master index, and is actually the partitioped organization directory (POD) of the
catalog data set.
Each index name is referred to as a
simple name; combining the names produces a
qualified name. If the name of each level,
from highest to lowest, is specified, a
0ingle data set is identified by its .fully
qualified name.
If one or more of the lowest levels are not included in the name, a
collection of data sets is identified by
its partially qualified name. Including
all simple names and separating periods
(but excluding the user identification),
the length of a data set name must not
exceed 35 characters. The concatenation of
2
the user identification gives the name a
maximum length of 44 characters for catalog
references.
A data set is cataloged at OPEN time,
using information placed in the JFCB by the
DDEF command. As pages are assigned to
members, they are formatted into 64-byte
blocks called SBLOCKs which are the basic
unit of information in the catalog. Each
SBLOCK contains indexing information and
pointers to related SBLOCKs. Space for
each user catalog is allocated in whole
page units, 64 available SBLOCKs per page.
Related SBLOCKs are chained together in
groups called indexes, each of which correspond to a level of qualification in the
data set name structure adopted by the
user.
A logical entity within the catalog consists of one or more chained SBLOCRs. The
logical entities defined in an SBLOCK are:
• Indexes
• Generation indexes
• Data set descriptors
• Sharing descriptors
• Sharer lists
As pages are assigned to user catalogs,
the fields are zeroed and information is
inserted in groups of 64 bytes. Unused
SBLOCKs are identified by a control field
of binary zeros. The form of a typical
SBLOCK is shown in Figure 1.
(Refer to
Appendix B for a detailed description of
SBLOCKs. )
The SBLOCKs within an index need not be
contiquous. Forward and backward links in
each SBLOCK give the relative location of
the next succeeding and preceding SBLOCKs
in the index level, which may be in the
same or different pages. Within each index
are SBLOCKs containing the name of each
subordinate index, and a pointer to the
beginning of the SBLOCK chain of each subordinate index. For a fully qualified data
set name in SAM, the lowest level index in
the catalog of the data set owner contains
one or more SBLOCKs identifying the volume
or volumes on which the data set resides.
In VAM if the data set is public. the
SBLOCK points to the format E DSCB and
gives the volume type.
If private, it
points to the format E DSCB and the volume
r---" --T''------T--------'------"--- ---,-,- -----"-1
iFIELDI#BYTES\DESCRIPTION
I
,,--,----,-------1
I (CCCFWD> Forward Pointer to I
l i t h e first character of the
I
!
Inext SBLOCK in the chain.
I
IPointer is of the form Pbb: I
I
I
I P is the logical page numbt"r!
~-----+------+---------------"
I
I
I
I
I
I
I
!
i
I
I
I
I
I
I
I
I
I
I
:3
I
2
i
I
I
I
I
I
I
I
Iwithin tne member; bb is thel
Irelative byte within the
I
I page.
I
1
I
3
I
I
I
I
I
I
I
I
I
I
I
3
I
I (CCCCT1) Binary Count of
I SBLOCKs allocated from a
Ipage. This field is mainItained by Catalog Services
lin the first SBLOCK of each
I page.
I
I
I
I
I
I
I
I
I
I(CCCBWD) Backward pointer tol
I the preceding SBLOCK in a
I
Ichain. Pointer is of the
I
Iform Pbb.
!
I
I
I
I 4
1
I , the
data set is treated as new; RC='OO' indicates an old data set. Return codes of
'04' and 'OC' result in SYSERs (minor software) followed by ABEND.
IIft.er return from LOCATE, ADDCAT checks
for the RET option in the parameter list
(word 2). If the option is 1, a branch is
taken to the code for updating the catalog;
if the RET option is not on, ADDCAT
examines the CATVAM option to add a private
VAM data set to the catalog without going
to AtDDSCB (since the data set already has
a DSCB). If the option is on for an old
data set, control is returned to the user
~ith a code of 'OS' indication that the
fully qualified name given by CATVAM was
not unique. The DSD is also returned to
the user.
If the CATVAM option is on for a new
data set ADDCAT checks for a generation
qualifier and calls INDEX if necessary, to
create a generation index.
Processing differs for new nongeneration
data sets, new generation data sets, and
old data sets, as follows:
Section 1:
Catalog Services
7
1. New Nongeneration Data Sets: For a new
data set it is assumed that if the last
index pointer found by LOCATE is not a
generation index (CCCFL1 ~ 02), the new
data set is not generation associated.
Therefore, if the last qualifier is in
absolute GOOOOVOO format, ADDCAT will
return with a code of '08', except in the
case of the CATVAM art ian teing set as mentioned above. ADDDSCB is entered to obtain
a DSCB for the new data set and its pointer. In the event of an error return from
ADDDSCB, r:racessing will be ~. errninated wi t_h
a SYSER (minor software) follOwed by ABEND.
The pointer to the DSCB is inserted into
the JFCB and INDEX is entered to create the
necessary index levels for the FQN in the
catalog. 11 return code of '00' from INDEX
indicates an SBLOCK has been obtained for
the creation of a DSD. GETS BLOCK is
entered with the pointer to the SBLOCK from
INDEX to get the SBLOCKi ADDCAT then gets
the backward pointer to the index SBLOCK
and enters GETSBLOCK to indicate in the
SBLOCK the type of DSD (public or private).
GETS BLOCK is entered to again get the DSD
SBLOCK.
(Returns of '04' or 'Oc' from
INDEX result in SYSER and ABEND; a return
of '08' indicates that the FQN was already
in the catalog and results in a return to
the user with a code af '08'.) ADDCAT then
r:roceeds to construct the DSD using information in the DSD portion of the JFCB and
calls CZCFG4 for PUT/PUTX/STOW. control is
r-eturned to the user with a successful
return code of '00' in general register 15
and an image of the DSD in the user's 64byte return area.
pointer to the Ilew generation data set
descriptor is sorted by qeneration number
into the list of pointers.
INDEX is
entered to find and chain an SBLOCK in
which to construct the DSD for the new data
set.
If the maximum number of generations is
exceeded, the delete options are examined
to calculate the number of generations to
be deleted and erased. DELVAM is entered
with the FQN of the generation to be
deleted.
If DELVAM was unsuccessful, a
message is sent to the user with the reason
for no deletion and the data set name (via
the GATWR macro). The number of generations to be deleted is decremented and proceSSing continues with the next generation.
DELVAM is called for each generation until
the count is zero. ADDCAT then processes
the new generation as above when there are
no deletions to be made.
Old Data Sets: For an old data set, ADDCAT
examines the option code to see if an update is requested. If not, processing is
terminated with a SYSER (minor software)
and an ABEND. To process the update
options, ADDCAT must first determine whether the DSD or the JFCB is to be updated.
(Note: Only bytes 21-55 of either the DSD
or the DSD portion of the JFCB may be
updated at one time. Not both.)
If the JFCB is to be updated from the
DSD, the option code is examined to deterrrine whether a complete or partial update
should be performed. If a complete update
is requested, ADDCAT moves each field of
the DSD into the corresponding field in the
JFCB. A partial update is requested, the
last three bytes of the option are examined
bit by bit to determine which fields are to
be u~dated.
In either case, when updating
TDTAQL, the userid in Task Common is comrared to the userid in the FQN to determine
~hether to move the owner's (CCCFL4) or
sharer's (CCCFL3) access privileges into
the JFCB.
2.
New Generation Data Sets: If ADCAT is
call"f:'d to perform an operation on a generation data set, validity checks are performed on the generation index in the catalog.
If an error is detected, the ERROR
PROCESSOR is called with information
describing the type and location of the
error in the catalog index. The ERROR PROCESSOR issues a SYSER and completion code 1
ABEND. Otherwise ADDCAT checks the sharing
access and only the owner or a sharer with
unlimited access will be allowed to proceed
(ABEND is otherwise invoked). GETSBLOCK is
entered to get the generation index and the
number of pointers to existing generations
is incremented by the one to be added and
compared to the maximum allowed. When a
user requests deletion of generation data
sets, the data sets are autQmatically
scratched by DELVAM as well because once a
data set is deleted from the catalog it is
inaccessible.
If the DSD is to be updated from the
JFCB, GETS BLOCK is entered to obtain the
DSD SBLOCK from the catalog.
The ortion
code is examined to see if a complete or
partial update is requested and the update
is performed the same as the JFCB update.
When the SBLOCK has been updated as
required, CZCFG4 is called.
If the maximum number of generations is
not exceeded, ADDCAT will search through
the pointers to previously existing generation data sets, comparing the new generation name to those already cataloged. The
Uf-Uti completion of the
is returned to the user.
back an image of the DSD,
return code, as indicated
register 15.
8
updating, control
ADDCAT passes
and the proper
under "exits', in
DC:U:AT (CZCFD)
taining pOinters to lower
levels
JELCAT is a reenterable, nonrecursive,
privileged subroutine, residing in virtual
storage.
It deletes index levels from the
catalog structure and recatalogs index
levels under a different fully qualified
name. DELCAT calls LOCATE to get the specified index level and then determines if an
owner's catalog is referred to by checking
the first byte of the 45-byte buffer used
as an entry parameter to LOCATE.
If the
flag is set, the sharer disposition flag in
the 64-byte SBLOCK retrieval buffer is
checked.
(See Chart AB.)
Entry Point:
CZCFDl
Input: Register 1 contains a pointer to
this list..
Word 1
Pointer to fully qualified name
Word 2
Pointer t.O option (if RENAME
option is selected, bits 0-15
contain X' 04 t )
Word 3
Pointer to new fully qualified
name (applicable only if RENAME
option is selected>
output: Register 1 contains a pointer to
the input parameter list.
Modules Called:
LOCATE (CZCFL) -- To locate an index level.
08 - the DELETE fully qualified
name and RENAME fully qualified name refer to different
user catalogs
08 - the RENAME fully qualified
name is not unique
oc -
indicates a sharing error
Operation: The fully qualified name supFlied in the entry parameter list is used
to locate the specified index level,
through use of the LOCATE routine.
If
LOCATE returns with a non-zero return code,
indicating an unsuccessful locate, DELCAT
terminates with an appropriate error return
code.
Upon a successful return from LOCATE,
DELCAT determines if an owner's catalog was
referred to by checking the first byte of
the 45-byte buffer used as an entry parareeter to LOCATE.
If the flag is on, the
sharer disposition flag in the 64-byte
SBLOCK retrieval buffer is checked. In
order to be able to delete from the owner's
catalog, the sharer must have unlimited
sharing privileges.
The fully qualified name can only
describe one of the following:
• An eropty index level
• A data set descriptor
INDEX (CZCFI) -- To construct chained index
levels and create new members in catalog
data sets.
GETSBLOCK (CZCFG1) -- To locate SBLOCK and
calculate virtual storage address.
(CZCFG4) -- To perform PUT/PUTX/STOW
functions.
CATALOG ERROR PROCESSOR (CZCFE) -- To claim
a SYSER and a completion code 1 ABEND when
a catalog structure error is encountered or
an end-of-data-set is detected by
GETSBLOCK.
Exits:
Normal - register 15 contains 00
successful.
Error
- DELCAT
- DELCAT returns one of the following codes:
04 - userid not in the POD
08 - the DELETE fully qualified
name not found by LOCATE
08 - the DELETE fully qualified
name is an index level con-
• A sharing descriptor
Otherwise, DELCAT is terminated with an
error indication.
DELCAT can be entered with one of the
following options: DELETE or RENA~E.
If the delete option is selected, the
entire entity located is zeroed and the
SBLOCK-count for the page is decremented by
one for each SELOCK freed. The deletion
includes extended SBLOCKs and any attached
sharer's lists. Next, the pOinter field
referred to by the back-chain in the first
SBLOCK of the deleted entity, is retrieved
and deleted. If the deleted pOinter was
the sole member of that index level, the
entire index level is. in turn, deleted as
described above. However, if the first
SBLOCK in the user's catalog becomes empty
or if the SBLOCK is a generation index, it
is not deleted.
If the index level is not
emptied, the zeroed pointer entry is left
in the index level for future use.
However, if the deleted member is located in an
extended SBLOCK which has become empty as a
result of the deletion, the extended SELOCK
Section 1:
Catalog Services
9
is removed from the chain. The empty node
SBLOCK is not deleted unless there are no
extended SBLOCKs chained to it.
DELCAT
updates the respective allocated byte
fields and forward and backward chains
involved in the deletion and justification.
When deleting a data set descriptor from
the catalog, the structure of any sharing
lists or volume lists attached to it are
checked for errors.
If an error is encountered the ERROR PROCESSOR is called (with
information describing the type and location of the error in the catalog) to
execute a SYSER and a completion code 1
ABEND.
If the rename option is selected, DELCAT
verifies via LOCATE that the RENAME fully
qualified name and the DELETE fully qualified name refer to the same user's catalog.
If they refer to different user catalogs,
an error return results.
DELCAT then
enters INDEX to construct the new fully
qualified name and transfers the contents
of the last qualified level in the old
fully qual~fied name to the new one.
Once
the data is successfully transferred,
DELCAT proceeds to delete the last qualified level of the old fully qualified name
as described above, except for deleting any
sharer's list or extended SBLOCKs that are
now associated with the new fully qualified
name.
If the last qualified level of a fully
qualified name is a sharing descriptor, the
sharing descriptor is deleted, rather than
the shared index level referred to.
SHII-RE (CZCFS)
SHARE is a reenterable, nonrecursive.
privileged subroutine residing in virtual
storage, that adds sharing privileges to a
catalog level. An unshared level can be
set to shareable, or a shared level can
have its sharing access modified.
Sharing
can be universal (meaning that any user may
share), or selective (meaning that only
those users whose userid is included in the
input parameter list are allowed to share>.
LOCATE is called to retrieve the proper
level for the fully qualified name supplied.
For selective sharing, a sharing
list is created or updated, depending on
the type of request.
(See Chart AC.)
Entry Point:
CZCFSl
qualified name, left-justified
Word 2
Virtual storage address of a fullword control field
word 3
count field - number of sharers
to be added to the sharers list
(used only for universal sharing)
Word 4
Virtual storage address of a list
of sharers
The format of the control field pointed
to by Word 2 is shown in Figure 3.
Notes to Figure 3:
Byte 0:
net used.
Byte 1:
bit 0=0
indicates that a Universal/Selective
sharing parameter is not present.
bit 0=1
indicates that a Universal/Selective
sharing parameter is present in byte
2. This bit is examined only in the
update mode. If it is 0, the sharing
mode is taken from the catalog itself.
bit 1=0
access code is not present in byte 3
of the control word or in the list of
new sharers. The default is unlimited
access for all sharers on the list of
new sharers.
bit 1=1
access code is present.
Byte 2: Universal/Selective parameter
bit 6=1
indicates that the request is for
selective sharing.
bit 7=1
indicates that the request is for
universal sharing.
If this bit is
set, the access code must be specified
in byte 3.
Byte 3: access code
bits 0-7
all zero indicates unlimited sharing.
Input: Register 1 contains a pointer to
this parameter list:
bit 1=1
indicates read/write access.
Word 1
bit 2=1
indicates read-only access.
10
Virtual storage address of a 44byte field containing the fully
Ii
I
Not Used
(must be binary zeros)
b>,te 0
I
I
i
bits
1
--~~+------
I
Un ivpr,a I
Selechve
Parameter
Indi cator
byte 1
I
I
Access
Code
Indicator
Not Used
(must be binary zeros )
I
I
~- . . -- 1..--
1
---
o
bi ts
-----1----
11
f-------------
2
Tl-T------~- r-------~
J31,151
6
7
~_L_ ----- - -- - ------ -- ---- L__ ----r--------------+--------~
i
Not Used
(must be binary zeros)
byte 2
Sel€ctive
Sharing
Indicator
Un iversal
Sharing
lndi calor
I
I
bits
I
----{--i
Read/write
Indicator
byte 3
Read only
Indicator
I
;
bi ts
--~-
3.
2
i
I
Figure
i
1
0
3
I
4
:r
7
6
i
Format of SHARE Control field
The list of sharers pointed to by parameter 4 has a length of 9*N bytes, when N is
the number of sharers indicated in Word 3
of the input parameter list. Each entry
has the following format:
r----------------------T---------,
I
I
Bytes
I
I ACCESS
I CODE
SHARER ID
I
I
•--T--T--T--T--T-~--T-t---------~
11
2
3
4
5
6
7
BI _________
9
I
l __ __ __ __ __ __ __
j
~
~
~
~
~
~
~_~
The access code has the same meaning as
in the control field pointed to by parameter 2 (byte 3>. This list is not meaningful for universal sharing.
output: Register 1 contains a pointer to
the input parameter list.
Restrictions: A user can autho.rize sharing
only if those index levels are in his own
user catalog.
Modules Called:
.LOCATE (CZCFL) -- To locate an index level.
GETSBLOCK (CZCFG1) -- To locate SBLOCK and
calculate virtual storage address.
(CZCFG4) -- to update external storage.
SEARCHSBLOCK (CZCFH) -- To acquire and
chain an empty SBLOCK to an index level •
CATALOG ERROR PROCESSOR (CZCFE) -- To
execute a SYSER and a completion code 1
A~END when a catalog error is encountered
or if an end-of-data-set is detected by
GETSBLOCK.
Exits:
Normal - register 15 contains 00:
successful
Error
SHARE
if SHARE is unsuccessful. register
15 contains one of the following
codes:
section 1:
Catalog Services
11
04 - Owner-id not in the POD
used, in all cases, to update external
storage when necessary.
08 - Fully qualified name not in
cat.alog
Oe - Owner is not allowed
10 - Not used
14 -
re'lu,c,st to ,;hare is
directed to a shdr~ng
descriptor
A
18 - Not used
Ie _. Not used
20 - Request to update from a list
of shares to a universal
shared level or vice versa
Operation:
The owner of a catalog can set
a level in the catalog to "universally
Shareable," meaning that any user can
share, or to "selectively shareable" meaning that only those users whose ID is
included in the input parameter list are
allowed to share.
The user can specify whether the level
for a newly shared data set is to become
universally shared or selectively shared.
If the level is to be universally shareable, the user can supply the access code
(read-only, read/write, or unlimited
access). If the user does not specify any
access code, as indicated by byte 1 of the
control field, unlimited access is assumed.
If a sharer has unlimited access, he can
add to or delete from the shared Fortion of
the cataloy.
SHARE supplies LOCATE with
the fully qualified name to get the proper
index l.eve1.
SHARE sets the sharing flag
in that level to universal and sets the
sharing privileges from the access code in
the parameter list or will default the
access to unlimited if none is given.
If the l.evel is to be selectively
shared, the user must supply a count of the
number of sharers plus a list of these
sharers in the form:
sharer's-id (8 bytes)
followed by his sharing privilege (I-byte
access code).
If the user does not supply
any sharing privilege for the sharers on
the sharing list, each sharer will be given
unlimited access. This is indicated when
bit 1 of byte 1 of the control field is
zero.
After locating and retrieVing the
SBLOCK associated with the fully qualified
name, SHARE sets the sharing flag in the
level to "selective.- A sharing list is
constructed and attached to the level by
filling in the pointer to the sharer list.
SBLOCKs to create the sharer l.ist are
obtained using SEARCHSBLOCK.
CZCFG4 is
12
The user can share a data set which is
already being shared, but a request to
change the sharing mode from selective to
univer~ial, or from universal to selective,
without flrst restricting the data set,
will not be honored and will result in a
return code of 20.
If the sharing mode is universal and the
user wants to leave it as universal. SHARE
simply changes the sharing privileges by
using the access code from the input. If
none is supplied in the input parameter
list, unlimited sharing privilege is
assumed.
When the sharing mode is selective and the user wants it to remain selective, the user must supply a count of the
number of users to be added to the present
sharing list plus a list of new sharers
containing sharerids followed by their
sharing privileges.
Before updating the
selective sharing, SHARE checks the structure of the sharing list for errors. If an
error is encountered the ERROR PROCESSOR is
called (with information describing the
type and loca t.ion of the error in the sharing list) to execute a SYSER and a completion code 1 ABEND.
The sharing privileges
for the new sharers on the sharing list can
be defaulted as indicated by byte 1 of the
control word. When this happens, the new
sharers will be given the sharing privilege
of the last sharer on the present sharing
list.
SHARE checks each userid to ensure
that i t does not already belong to the
user's list.
If it already belongs to the
list, the access code from the input is
inserted in the existing entry; if it does
not already belong to the list, it is
added.
After the list has been completely
updated, the count of sharers in the catalog level is updated by the number of IDs
added.
CZCFG4 is used, in all cases, to update
external storage when necessary.
UNSHARE (CZCFV)
UNSHARE is a reenterable, nonrecursive,
privileged subroutine residing in virtual
storage, that removes sharing privileges
from a catalog level. First the proper
level is located and checks are made to see
that the sharing mode of the level is compatible with the type requested.
If the
sharing mode is universal and the request
is to delete all sharers, the sharing flag
is set to private and the new index level
is updated in the catalog.
If the sharing
Irode is selective and the request is to
delete all sharers, the additional operation of deleting the sharer's list is performed.
When the sharing mode is selective
and the request is not to delete all mem-
b~[~r tne sharer's list is searched and
only the members passed in the parameter
list are delet.ed.
(See Chart AD.)
Entry Point:
1.
Sharing privilege can be removed from
a catalog level only by the owner of
the cdtalog.
2.
To determine the sharing privilege of
a catalog level, UNSHARE examines 0nly
the sharing privilege pointed to by
the fully qualified name.
This means
that for UNSHARE. the sharing ~rivi
lege of any higher level in the cat.alog has no effect on the sharing rrivilege of subordinate levels. The
owner must specifically establish the
sharing rrivilege of a level via SHARE
if any other user is to link to the
sr:cecific level via SHAREUP.
3.
A level is considered private by
UNSHARE until a SH~RE is given for it.
CZCFVl
~~~:
Register 1 contains a pOinter to
this parameter list:
Word 1
Pointer to a 44-byte field containing the fully qualified name,
left-justified.
Word 2
Pointer to a fullword control
field.
Word 3
Pointer to halfword count field.
Word 4
Pointer to a list of sharers.
The control field pointed to by Parameter 2 is aligned on a tullword boundary and
has the following structure.
l-',)dules Called:
LOCATE (CZCFL> -- To locate an index leve1.
GETS BLOCK (CZCFGl) -- To locate SBLOCK and
calculate virtual storage address.
(CZCFG4) -- To effect PUT/PUTX/STOW
functions.
Byte 0 - unused
Byte 1 - unused
CATALOG ERROR PROCESSOR (CZCFE) -- To
execute a SYSER and completion code 1 ABEND
when a catalog structure error is encountered or an end-of-data-set is detected by
CZCFG1.
Byte 2
bits 0-5 -- unused
bit 6=1
delete all sharers
bit 7==1
delete only those sharers
identified in the input parameter list
Exits:
Normal - register 15 contains 00, UNSHARE
successful
Byte 3 - unused
Error
All unused bits must be set to zero.
The count field pointed to by Parameter
3 is a halfword binary count of the number
of sharers to be removed from the sharer
list of a selectively shared level; it is
aligned on a halfword boundary.
This parameter is meaningful cnly for selective
sharing.
04 - Owner-id not in POD
outp~"-ic:
2
~
___
3
~
___
4
~
___
5
~
___
6
~
___
7
~
___
~
8 I _____
9 JI
___
~
Register 1 contains a painter to
the input parameter list.
oc -
Owner is not allowed to share
18 - Level is not now shareable
I 00 I
I (hex) I
lC - Input ids are not in the
sharer's list
t--T---T---T---T---T---T---T---t-----1
Byte 11
l __
Fully qualified name not in
catalog
14 - Request to unshare is
directed to a sharing
descriptor
r------------------------------T-----'
SHARER ID
OS
10 -. A list of sharers was provided for a universally
shared level
The list of sharers pointed to by Parameter 4 has a length of 9*N bytes, where N
is the number of sharers identified in the
count field above.
Each entry in the list
has the following format:
I
I
- register 15 contains one of these
codes:
Operation:
The o·,mer of a catalog can use
one of two options with UNSHARE:
•
~aking
d universally or selectively
shared level in the catalog private.
Section 1:
Catalog Services
13
• Removing sharing privileges from a list
of users for a selectively shared catalog level.
In either case, UNSHARE locat.es the
fully qualified name to get the proper
level in the cataloq.
If the level indicated is a sharing descriptor or if the
level is not already shared, an error
return is made.
viously designated as shareable. The
shared index level is J:"etrieved to determine if the calling program is allowed to
share.
If the calling program or user is
allowed to share and his fully qualified
name is unique, a sharing descriptor is
constructed by the INDEX routine.
(See
Chart AE.)
Entry Point:
Before removing any userii's from a sharing list, the sharing list is checked for
catalog structure errors.
If an error is
encountered, the ERROR PROCESSOR is called
(with information describing the type and
location of the error) to issue a SYSER and
a completion code 1 ABEND.
Collective Removal
If sharing privileges are to be removed
collectively, (that is, the catalog level
is to be made private), UNSHARE checks the
sharing mode of the level to see if it is
universal.
If so, i t resets the sharing
flag to make the level private. The pointer to the sharing list is saved and zeroed;
all SBLOCKs in the sharing list are then
returned to the catalog.
Selective Removal
If the sharing privileges are to be
removed selectively, UNSHARE checks the
sharing flag in the cataluJ level.
If
selective sharing is not indicated, an
error return is made.
Ut,SHARE next
searches the sharing list for the userid.
If the userid is not present, a flag is set
in the access byte following the userid on
the input list and UNSHARE begins to search
for the next userid in the input list.
If
the userid is present, its entry is zeroed
on the sharing list.
If the deletion
results in an empty sharing list SBLOCK
which is not the node sharing list SBLOCK,
the SBLOCK will be removed from the sharing
list chain. Processing is completed when
all the userids on the input list have been
removed from the sharing list.
If any
deletion results in the removal of all of
the members from the sharing list, the
catalog level is set to private.
Note: For both collective and selective
removal, CZCFG4 is used to update external
storage when necessary.
CZCFUl
Input:
Register 1 contains a pointer to
the following parameter list:
~ord
1
Word 2
Pointer to owner's fully qualified name.
Pointer to user's fully qualified
name.
output: Register 1 contains a pointer to
the input parameter list.
Modules Called:
LOCATE (CZCFL) -- To locate an index level.
INDEX (CZCFI) -- To construct a chained
index level and create new ~ernbers in the
catalog data set.
GETS BLOCK (CZCFG1) -- To locate an SBLOCK
and calculate virtual storage address.
(CZCFG4) -- To perform PUTX function.
CATALOG ERROR PROCESSOR (CZCFE) -- To
execute a SYSER and completion code 1 ABEND
when a catalog structure error is encountered or an end-of-data-set is detected by
CZCFGl or an unsuccessful return code is
obtained from INDEX.
Exits:
Normal - register 15 contains 00; SHARE UP
successful
Error
- register 15 contains one of the
following codes:
04 - userid not in POD
08 - user name not unique
OC - index level requested to
share is not shareable
10 - owner FQN nonexistant
SHAREUP (CZCFU)
14 - ownerid not in POD
SHAREUP is a reenteratle, nonrecursive,
privileged subroutine, residing in virtual
storage.
It linkS a user's private catalog
to a level in another user's shareable
catalog by constructing a sharing descriptor in the sharer's catalog that points to
a node in a user's catalog that was pre14
18 - request to add sharing
descriptor with gdg.
lC - user is attempting to share
another catalog in the owners
catalog.
'21!c't_c:tion:
LOCATE is called to retrieve
th~ owner's fully qualified name that is in
the pararreter list.
If a X'04' return code
is returned from LOCATE, it is converted by
SHAREUP to a X'14' return code which is
returned to the caller after the sharing
descriptor is built. Similarly, a X'08'
return code (level to be shared is not in
the catalog) is converted to a x'lO' return
code which is sent to the caller after the
sharing descriptor is built. A X'OC'
return code (level cannot be shared) is
sent to the caller after the sharing
descriptor is built. B~fore processing is
continued, a check is made to see if LOCATE
crossed a catalog boundary.
If it did,
processing is terminated and the sharing
descriptor is not built since sharing
across multiple members is not permitted.
LOCATE is then called with the sharer's
FQN that is in the parameter list.
If a
X'04' return code is received, processing
terminates and a X'04' return code is sent
to the caller.
If a X'OO' return code is
received, a check is made to see if the
user is trying to build a sharing descript.or in a generation index.
If so, processing terminates with a X'18' return code.
A check is made to see if the user has
already shared the data set.
If he has,
the caller is sent a X'OO' return code.
otherwise a X'08' return code, indicating
that the name is not unique, is returned.
A X'OC' return code means that a subset of
the name is the name of a ~reviously
created sharing descriptor and the caller
receives a return code of X·08'.
A X'08' return code means that only a
subset of the name was found. The catalog
entity on which the search terminated could
be either an index or a data set descriptor; the SBLOCK retrieved by LOCATE is
checked to determine which.
If the search
terminated on an index, the name is unique
and SHAREUP continues to build a sharing
descriptor. If the search terminated on a
data set descriptor, there can be no additional subordinate levels; thus the name is
not unique and SHAREUP returns with a
return code of '08'.
If the SBLOCK
returned is a generation index, SHAREUP
returns with a return code of '18'.
If the name is unique, INDEX is called
to construct the necessary levels for
building a sharing descriptor.
INDEX
builds all required levels including the
level that the sharing descriptor occupies.
On return from INDEX, it is necessary to
change the last level created by INDEX into
the completed sharing descriptor.
A nonzero return code causes SYSER to be
invoked. since all conditions causing nonzero return codes should have been discovered by the previous LOCATE.
Before the sharing descriptor is built,
a check is made to see if INDEX added the
new levels to the catalog correctly.
If an
error is detected, the CATALOG ERROR PROCESSOR is called to claim a SYSER and a
camp code 1 ABEND.
If the new levels are
satisfactory, the sharing descriptor is
built and the catalog is updated externally
with a call to CZCFG4.
If the final return code is X'OO', LOCATE is called again with the sharer's name
to see if the sharer is allowed to access
the data set.
If no access is permitted
the caller receives a X'OC' return code.
LOCATE (CZCFL)
LOCATE is a reentrant, privileged routine that resides in public storage. The
first entry pOint (CZCFLl) is called to
retrieve SBLOCKs from the user catalog,
either by fully qualified name (FQN) or
relative address. Conversion of relative
numbers (for example, NAME(+1» to al:;solute
generation numbers (for example, NAME.
GOOOIVOO) is performed when required. The
second entry point (CZCFL2) is called to
locate the catalog level and any lower
levels implied for an FQN.
Catalog inforrration is placed in one or more TBLOCKs
(logical entities containing output catalog
data which are located in a GETMAIN area)
for each terminal level found in the
catalog.
Entry Points:
CZCFL1
for LOCATE
CZCFL2 -- for LOCFQN
Input:
LOCATE has two separate sets of
input parameters. Register 1 contains the
address of the following parameter list:
For LOCATE (CZCFll)
Word 1
Pointer to a fully qualified name
or relative address, depending on
the option code specified in Word
2
word 2
Option pointer
0004 -- locate on fully qualified
name and unlock
0008 -- locate on relative
address and unlock
OOOC -- locate on fully qualified
name and hold interlock
0010 -- locate on relative
address and hold
interlock
0014 -- release interlock
Section 1:
catalog Services
15
Word 3
Pointer to SBLOCK return area
(64-byte buffer>
PUT
To move the user catalog into
SYSCAT.
Word 4
Pointer to owner's name and flag
return area (45-byte buffer)
CLOSE (CZCLB) -- To close the user catalog
DCB.
For LOCFQN (CZCFL2)
Word 1
Pointer to a fully qualified name
Word 2
Pointer to a fullword area for the
return of the numcer of TBLOCK
pages
Word 3
Word 4
CATFLUSH (CZCFX) -- To remove the catalogs
for inactive member from SYSCAT.
INDEX (CZCFI) -- To build the first page of
a catalog for a userid.
Pointer to a fullword area for the
return of the first TBLOCK page
virtual memory address
Exits:
Normal - register 15 contains X'OO'.
Error
- register 15 contains one of the
following hexadecimal codes:
Pointer to a I-byte option code
01 -- cross catalog when
necessary
02
cross catalog implicitly
03
don't cross catalog
Output: Register 1 contains a pointer to
the input parameter list.
Modules Called:
GETSBLOCK (CZCFG1) -- To calculate the
SBLOCK virtual memory address.
(CZCFG3) -- To provide the initial sizing
of the VAM buffer used in processing the
user catalog.
(CZCFG4) -- To effect the necessary PUT/
PUTX/STOW and CLOSE (TYPE T) sequence.
FIND (CZCOJ)
To search the POD or entry.
STOW (CZCOK)
To replace the member
descriptor and to close the member.
ERROR PROCESSOR (CZCFE)
To record a
catalog structure error in SYSLOG and issue
SYSER and/or ABEND.
DSCB/CAT RECOVERY (CZUFX1) -- To rebuild
the catalog in SYSCAT.
GETMAIN (CZCGA2) -- To reserve pages of
virtual storage.
04 - The userid supplied to the FIND macro
instruction is not in the POD of the
catalog data set.
If the owner's
userid is not found, a flag is set in
the first byte of the 45-byte buffer,
and the owner's fully qualified name
is in the remaining 44 bytes.
08 - Not all the qualifiers of the fully
qualified name were located. The last
qualified SBLOCK located is in the
64-byte retrieval area.
If an owner's
catalog was entered, a flag is set in
the first byte of the 45-byte buffer
and the owner's fully qualified name
is in the remaining 44 bytes.
OC - The user is attempting to retrieve an
entity in an owner's catalog that he
is not allowed to share. No SELOCKs
are retrieved in the 64-byte buffer,
nor is the owner's fully qualified
name inserted in the 45-byte buffer.
LOCFQN (CZCFL2).
WRITE (CZCPE) -- To write a record in
SYSSVCT.
LOCATE calls the ERROR PROCESSOR (CZCFE)
to issue a SYSER for any of the following
conditions:
1.
80102501 - The FQN in the parameter
list contains an error (for example,
the userid or qualifier exceeds 8
characters in length).
2.
80102502 - An FQN generation data set
name contains an error (for example,
if there is a non-numeric character
between parentheses).
3.
80102503 - There is an invalid option
cede in the input parameter list.
4.
80102504 - An unexpected return code
is returned from FIND.
FINDJFCB (CZAEB) -- To find a JFCB for the
user catalog.
OPEN (CZCLA) -- To open the USERCAT DCB.
GET -- To bring the user catalog into the
buffer.
Same exits as for CZCFL1.
Same as above.
READ (CZCPE) -- To read a record from
SYSSVCT.
16
LOCATE (CZCFL1)
80102506- Another catalog rrember has
to be opened thus forcing LOCATE to
implicitly release the current member
which has been locked up for an
update.
found in the catalog. Sharing infcrrration
and the type and relative address of the
SELOCK are saved in the table. A flag is
alsc set to indicate that the qualifier was
found in the catalog.
6.
80102507 - The userid is not in the
first SBLOCK of a catalog.
7.
80102508 - A catalog cannot be
accessed (for example, the member cannot be located by FIND or a STOW canDot be issued successfully).
8.
80102509 - A SYNAD was taken on a READ
or WRITE operation on SYSSVCT for a
reason other than that the key was not
found.
9.
80109902 - This is a general SYSER
that CZCFE issues when requested to
issue a SYSER but the parameter list
to CZCFE does not contain a SYSER.
The following conditions in LOCATE
cause this SYSER:
LOCATE calls CZCFG3 after issuing the
FIND against the user's catalog, to initialize the VAM buffer in which the catalog is
rrocessed.
LOCATE must also determine if
the member for which the FIND is to ce
issued is already open. If it is, LOCATE
cypasses issuing the FIND and the call to
CZCFG3.
If a member is open but does not
correspond to the member for which the FIND
is to be issued, CZCFG4 is called to issue
the necessary PUTX, PUT, STOW and CLOSE
Before calling CZCFG4 a
(TYPE=T) sequence.
check is made to see if the catalog is
locked ur.
If it is, a SYSER and ABEND are
claimed and the user receives the message:
LOCATE HAD TO IMPLICITLY RELEASE A MEMBER
LOCKED UP FOR UPDATE.
The number of qualifiers exceeds 19.
The primary catalog cuffer has been
destroyed after processing an owner's
catalog.
There was an error return from last
call to GETSBLOCK (CZCFG1) before
exit.
10.
80109901 - This SYSER is issued by
CZCFE when LOCATE detects a catalog
structure error.
operation:
LOCATE (CZCFL1)
LOCATE is entered with a request to
retrieve an SBLOCK either by its fully
qualified name (FQN) or its relative
address.
After initialization, the option code is
examined. If it is not zero or a multiple
of four a SYSER and ABEND will be issued
informing the user of an invalid option
code.
If the input option requests a LOCATE on an FQN, a trace table is built. A
24-byte entry is made for each qualifier in
the FQN. First, the qualifier is moved
into the table after it is validated. A
flag is set in the entry to indicate that
the level is an explicit one and a second
flag is set if the FQN points to a data set
in an owner's catalog. A third flag is set
for the last qualifier in the FQN. If the
FQN is a relative generation, it is converted to binary and the qualifier for the
current level contains the binary number
followed by a plus or minus sign. A SYSER
and ABEND are claimed if any irregularity
is detected in the FQN. The trace table is
updated when the SBLOCK for the level is
If the return code from FIND indicates
that the userid in the FQN is not in the
SYSCAT POD and if the attempted access is
to his own catalog, the address of the user
catalog is extracted from SYSSVCT with a
READ operation. If a SYNAD is taken on the
READ because the key is not found, a return
Ioiith RC='OI~' is made.
If a SYNAD is taken
on the WRITE oreration or on the READ
operation for any other reason than because
the key can not be found the program will
issue a SYSER and ABEND and the user
receives the message; UNRECOVERABLE ERROR
IN SYSSVCT. A STOW 'N' is issued to create
a member entry in the POD and this is fol10loied by a FIND to open the member of SYSCAT.
If the STOW fails because the POD is
full, CATFLUSH is called to delete inactive
rr,embers from the SYSCAT POD and a branch is
taken to reissue the STOW 'N' again.
If
the CATFLUSH return code is not zero, LOCATE terminates with a '04' return code.
If
the return code from FIND is other than
'00' or '14' (member already open), SYSER
80102508 and an ABEND are issued. The user
receives the message: SYSTEM FAULT:
UNABLE TO ACCESS CATALOG.
If the FIND is
successful and the DCB indicates there are
rages in the SYSCAT member, a branch is
taken to continue normal processing in LOCATE. If there are no pages in the SYSCAT
rrember and SYSSVCT indicates a USERCAT does
not exist, INDEX is called to create the
first fage of a catalog in SYSCAT. The
flag UCTSYNC in SYSSVCT is then set to indicate that the SYSCAT member and the USERCAT are not the same by issuing a WRITE or
SYSSVCT. Then a branch is taken to continue normal processing.
If there is no
is a USERCAT, the
SYSCAT. FINDJFCB
for the USERCAT.
SYSCAT member but there
USERCAT is moved into
is called to get the JFCB
The USERCAT DSCB pointer
Section 1:
catalog Services
17
is moved fron: SYSSVCT to the JFCB, TPTVPY
is set to indicate that the USERCAT is a
",rivileged data set and the LCB tor USERCAT
is opened.
1\ GET moves t.he USERCAT to the
buffer, a PUT moves it to SYSCAT "lnd t.he
DCB is then closed.
A STOW is exec'lt.ed to
close the catalog member.
If the return
code from STOW is not zero, a SYSER and an
ABEND are issued and the user receives the
message:
SYSTEM FAULT:
UNABLE TO /,CCESS
CATALOG.
Before retul:ning to reissue t.he
FIND, SYSCAT is checked to see if it
exceeds 800 pages.
If it doe~, CATFLUSH is
called to delete inact:i ve SY:'CAT member s.
Aft('r the FIND is complete, CZCFGl is
called to obtain the virtual memory address
(VMA) of the first SBLOCK in the catalog.
If the return code from CZCFGl is not zero
or if the FQN userid is not in the first
catalog ;::>BLOCK, a SYSER is claimed dnd the
ERROR PROCESSOR (CZCFE) is requested to
call CZUFX to rebuild the catalog.
CZCFE
then issues a completion code 1 ABEND after
CZUFX returns control.
When the catalog SBLOCK for one of the
FQN qualifiers is found, the corresponding
entry in the trace table is updated as
described above.
If this is the SBLCCK for
the last qualifier in the FQN and it is not
a sharing descriptor, the catalog search is
finished.
If LOCATE is called by LOCFQN,
LOCATE branches back to LOCFQN.
Otherwise
the caller receives a zero return code and
LOCATE exits. Th~ exit procedure consists
of moving the last located SBLOCK into the
calling routine's 64-byte buffer (given as
an entry parameter to LOCATE). This SBLOCK
may be an index, a data set descriptor or a
sharing descriptor.
Sharing information
extracted from the current or a higher
level is returned in the 64-byte buffer (if
a sharing descriptor is not being
returned).
LOCATE also fills in CDSNPT,
CDSCLS and CDSCLC in the catalog common
area (CHBCDS).
If the input option
requests the closing of the catalog member,
CZCFG4 is called to close it before returning to the caller.
If the SBLOCK is an index SBLOCK (and
there are more FQN qualifiers to be
located), a search is made in this index
level for the pointer entry containing the
next FQN qualifier.
If found, CZCFGl is
called to obtain the VMA of the SBLOCK and
a branch is made to update the trace table
as described previously.
If the next FQN
qualifier is not found in the index level,
the caller receives an X'08' return code.
If LOCATE is called by LOCFQN the module
branches to it.
If not the module exits as
described previOUSly.
If the SBLOCK is a sharing descriptor
and proceSSing is already in an owner's
catalog, a x'OC' return code is sent to the
18
caller or LOCFQN.
If LOCATE was called by
CELCAT, the catalog search is complete and
this sharing descriptor is returned to
DELCAT.
Otherwise LOCATE moves the owner's
FQN from the sharing descriptor to the calling routine's 45-cyte buffer. Any remaining qualifiers in the original FQN are then
concatenated with the owner's FQN in the
ruffer.
If adding these qualifiers causes
thf FQN to exceed 44 characters a SYSER and
ABEhL are claimed.
The sharing descriptor
is then moved into the 64-byte buffer in
edse t.he owner userid is not found.
If the
Gwner dnd sharer userids are not the same
thE current catalog member is closed before
branching back to build a new trace table
for the owner's FQN. Before closing the
catalog rrember a check is made to see if
t.he caller requested LOCATE to keep the
catalog locked until it is updated (CDSLOC
flag was set).
If so, a SYSER and ABEND
are claimed and the user receives the message:
LOCATE HAD TO IMPLICITLY RELEASE A
MEMBER LOCKED UP FOR UPDATE.
If the catalog level pointed to by the
owner's FQN is successfully retrieved, and
the user is allowed to share, a flag
(X'04') is set in the first byte of the
45-byte cuffer to indicate that an owner's
catalog was entered and LOCATE will exit
with a zero return code.
If the user is
not allowed to share the owner's data set.
the buffer flag is set to zero and LOCATE
exits with a X'OC' return code.
When LOCATE is given a fully qualified
name containing a relative generation number, the relative generation number is converted to an absolute generation name.
The
last qualifier before the relative number
must point to a generation index, or LOCATE
terminates with an error condition.
When
the absolute name associated with a zero or
negative relative number is located, the
relative number is overlayed in the fully
qualified name by the absolute name.
If a
Fositive number is given, a new absolute
name is generated by adding the last
generation number to the relative number.
The result is put in the fully qualified
name, as with zero or negative numbers.
LOCATE then proceeds as usual, retrieving
the data set descriptor for zero or negative numbers, and returning an error code
for positive numbers.
If the generation
index is in an owner's catalog, the relative number is replaced in the 45-byte
buffer, not in the original fully qualified
narre.
Sharing information is extracted from
the catalog by searching all levels of the
catalog until an access is found. The
search begins at the lowest level (the last
level found) and can continue up to the
highest (userid).
The first access that is
found is returned.
If a level is shared
selectively, the sharing list is searched
for the userid.
If a level is shared
universally. that access is returned.
A request by relative address may be
made only after a LOCATE has been executed
for a fully qualified name and it is necessary to retrieve subsequent chained
SBLOCKs.
However, if any intermediate request causes LOCATE to enter another user's
catalog. a request by relative address is
not valid for any relative address within
the first user's catalog. When this option
is used, no fields in the SBLOCK are
changed.
LOCATE checks for catalog structure
errors when searching through a catalog.
If an error is detected, the CATALOG ERROR
PROCESSOR (CZCFE) is called with an error
code to describe the type of error and with
other data such as the location of the
error in the catalog. If LOCATE is called
by LOCFQN a flag may be set requesting
CZCFE to return after claiming a SYSER and
processing continues in LOCATE. Otherwise
CZCFE issues an ABEND.
Note: LOCATE'S PSECT (CZCFLX) contains a
data control block (DCB) for SYSCAT.
LOCFQN CZCFL2
LOCFQN is entered to find the catalog
level and any lower levels implied for an
FQN. This information will be returned to
the caller in 96-byte blocks called
TBLOCKs.
The TBLOCKs are all chained
together on storage obtained by a GETMAIN
operation. The caller must free this
storage when the TBLOCKs are no longer
required.
LOCFQN calls LOCATE (CZCFLl) with the
FQN in the input parameter list.
Upon
returning from LOCATE the return code is
saved and a switch is set to activate error
recovery if an error is encountered during
a lower level implicit search of the
catalog.
If an error is detected a call is
made to the ERROR PROCESSOR (CZCFE) to
issue a SYSER and ABEND.
If the flag is
set the ERROR PROCESSOR may be requested
for certain recoverable situations to
return to the caller after issuing the
SYSER.
If a zero return code is obtained from
the LOCATE call the virtual memory address
(VMA) of the catalog SELOCK associated with
the last qualifier in the FQN is obtained
by calling GETSBLOCK (CZCFG1).
If a nonzero return code is obtained for GETSBLOCK,
the ERROR PROCESSOR is called to issue a
SYSER and ABEND and the user will get the
n,essage: SOFTWARE ERROR- ERROR RTN ON LAST
GETSBLOCK BEFORE EXIT.
The SBLOCK is then analyzed to determine
its type.
If it is a data set descriptor
SBLOCK and a entry was not made into an
owner's catalog, a TED type TBLOCK will be
built. TBS TBLOCKs containing permissive
information for all qualifier levels of the
FQN will also be built and chained to the
'IBD TBLOCK.
If entry was made into an
owner's catalog a TBD TBLOCK is built only
if the sharer has access to the data set.
lifter building the TBLOCK for t.his level in
the FQN, a check is made to see if this
qualifier level is in the FQN in the parameter list t.o LOCFQN.
If so, it is the end
of the processing in the current catalog
and the catalog is closed. This is the
sa~e proceedure followed when a return code
of X'OS' or X'OC' is received from the initial call to LOCATE.
If the closed catalog
is not an owner's catalog, processing is
complete and a return is made to the
caller.
If processing is in an owner's catalog,
a check is made to see if the sharer'S
catalog was previously closed.
This is the
same procedure to be followed for a return
code of X'04' from t~e initial LOCATE call.
If it was closed the buffer is checked to
see if the first SBLOCK in the catalog contains a userid. If it does not, a SYSER is
clairred and the ERROR PROCESSOR is asked to
return instead of issuing an ABEND.
If
there had been an explicit search into an
owner's cat.alog but no TBLOCKs were built
because of a lack of sharing information,
an initial return code of X'OO' from LOCATE
is changed to x'OC' before exiting from the
module.
If an explicit search into the
owner's catalog yields no output, a TED
TBLOCK is built containing the sharer's
FQN. A TBO TBLDCK is also built containing
the owner's FQN and a flag, which is set to
explain why there is no output.
The module then checks to see if the
current qualifier level is explicit (that
is, the qualifier is in the input FQN).
This procedure is also followed after output of a TBD TBLOCK.
If the level is
explicit, processing in this catalog is
complete and the member is closed as previously described.
If not, a search is
made for the next lowest qualifier.
If
none is found, the entry in the trace table
(see LOCATE for explanation of trace table>
for this qualifier is erased and the module
will back up to the next higher qualifier
to see if it is explicit. When a qualifier
is found a check is made to see if the number of qualifier levels exceeds 19. If so,
a SYSER is claimed, all the lower qualifier
levels are ignored and a TBD TBLOCK is
built as described above.
If the number of
qualifier levels is fewer than 19, a new
trace table entry is built for this qualifier level and the module branches to analyze the type of SBLOC~ in the catalog for
Section 1:
Catalog Services
19
this level as descrlhed after the initial
to LOCAT.E.
(;a11
If the SBLOCK that is returned after the
initi,'ll call to LOCATE is a sharing descriptor, a check is made to see it an owner's
catalog has been entered.
If so, LOCFQN
backs up t.O examine the next higher qualifier as described above.
If an owner's
catalog has not been entered and L~:FQN is
requested not to enter a catalog, a TBD and
TBO TBLOCK are built and LOCFQN backs up
again to ex~mine the next hlgl.er qualifier.
If LOCFQN is requested to implicitly ent.er
d
catalog, a flag is set indicating 2n
owner's catalog has been entered and the
sharer's catalog is closed. Since it will
not be reopened again, each page in the
buffer is aarked as changed so that pageins can be done from the drum or auxiliary
storage instead of external storage which
cOlllcl be changed since the catalog is
closed.
If sharer and owner user.ids are
the same the catalog is not closed.
LOCATE
is now entered for the SEcond time using
the FQN in the sharing descriptor.
Finally, if none of the above options is
requested, LOCFQN enters an owner's catalog
only if the qualifier level which points to
the sharing descriptor is in the input FQN
(that is, is an explicit qualifier level).
Otherwise a TBD and TBO 'TBLOCK are built
before branching back to look at the next
higher qualifier.
If the SBLOCK that is returned after the
initial LOCATE call is an index, LOCFQN
looks for the first member in this index
level.
If none can be found, a TBD TBLOCI<
is built as described previously.
If a
member is found, LOCFQN brnnches to check
if the number of qualifier levels exceeds
19.
A TBD TBLOCK contains an FQN (TBDDSI),
the DSCB pointer if it is a VAM data set
(TBDDSC), the owner's or sharer's access to
the data set (TBDACC), the owner's userid
if the data set is shared (TBDOWN) and data
set organization (TBDORG). The TBLOCK has
room for two volume fields (TBDDVF, TBDDVL)
for a SAM data set.
If the data set exists
on more than two volumes, this information
is stored in TBC TBLOCKs which are chained
to the TBD TBI,oCK.
A TBDFLL flag is also
set if the data set has BULKIO pending for.
i t or if it is a temporary data set.
If a TBD TBLOCK is built for a sharing
descriptor, either because of the input
option, or because of an unsuccessful
search into the owner catalog, a TBO TBLOCK
is also built and chained to the TBD
TBLOCK. The TBO TBLOCK contains the owner
data set name issued by the user at SHARE
time and flags, if applicable, indicating
the reason for the unsuccessful search (for
20
0XamPle! userid not found, data set nonexistent
or non-sharable).
1
Sharing inforrration is stored in TBS
TBLOCKs which are chained to the TED
TBLOCK.
Each entry in the TBLOCK (ten
bytes) consists of a userid, the access,
and t~e FQN level associated with the
access.
If a level is shared universally,
• the userid is set to *ALL.
CATALOG ERROR PROCESSOR (CZCFE)
The CATALOG ERROR PROCESSOR is a reentnonrecursive, privileged subroutine
rec3iding in virtual storage.
Its function
is to execute catalog SYSERs and to take
action when a catalog structure error or a
user format error is discovered by one of
tne catalog service routine modules.
If
the module is called to execute a catalog
SYSER (error codes FO-FF) the SYSER and
ABEND in the parameter list are checked and
then issued from this module. When a
catalog structure error (error codes 00-9F)
is discovered by one of the catalog service
modules, the ERROR PROCESSOR is called with
the type and location of the SYSER in the
catalog. This information is recorded in
the system log and a SYSER and an ABEND are
then issued.
If a user format error (error
codes EO-EF) is detected, the error ~roces
sor is called to issue an ABEND to the
user.
~ratle,
Input:
The farameter list to the module is
in the PSECT CBBCEP.
It contains the following infor~ation:
Word l/Word 2
word 3:
byte
byte
byte
byte
~odule
name of caller
Contains the following:
hexadecimal error code
2 - exit option code
3 - flag byte (not used)
4 - not used
1
Word 4
Address of FQN (44-byte area).
~,ord
Address of qualifier level at
which error occurs (this address
should be in the range of the
FQN) •
5
mino~
SYSER in caller's
Word 6
Address of
PSECT.
Word 7
Address of ABEND message in caller's PSECT (the first byte gives
the length of the text that
follows) .
Wo.rd 8
Primary address of the error.
Word 9
Secondary address associated with
the error.
Word 10
contains the following:
bytes 1,2 - actual count of entries
byte 3 - not used
byte 4 - not used
Modules Called: SYSER (CEAIS) -- system
error routine:
invoked when the error processor is called with ~rrors codes 00 to 9F
and EO-EF.
Exits: Return, to the caller, if specified
by the option code (CEPOPT). Otherwise,
issues an ABEND.
SYSERs:
80109901 This SYSER is issued when CZCFE is
called when one of the catalog
service routines discovers a
catalog structure error (error
code 00-9F)
80109902 This SYSER is issued when CZCFE is
called to issue a SYSER but the
parameter list does not contain
one (error code FO-FF)
80109903 This SYSER is issued if the parameter list contains a SYSER that is
not type 1 (error code FO-FF).
Operation: The CATALOG ERROR PROCESSOR is
called for three types of errors detected
by the Catalog Service Routines:
1.
Type 1 (error codes 10-9F) a catalog
structure error.
2.
Type 2 (error codes EO-EF) a user
input format error with no afpropriate
return code available for returning to
the caller.
3.
Type 3 (error codes FO-FF) other system error conditions for which the
caller supplied a SYSER code and a
comp code 1 ABEND message.
If the parameter list contains a fully
qualified name (FQN), it is added to all
ABEND and WTL messages.
If the name
exceeds 44 characters only the first 44 are
added. If the parameter list contains an
address of a qualifier that is in the FQN
range, the qualifier is also added to the
messages.
When called for a type 1 error, the
CATALOG ERROR PROCESSOR checks to see if
the parameter list contains a SYSER. If it
does not, SYSER 80109902 is executed. If
the SYSER is not a type 1 SYSER, the module
issues a 80109903 SYSER. Otherwise the
SYSER in the parameter list is issued.
If
the ~arameter list contains an ABEND message, the FQN and the calling routine are
added to it before writing the message to
SYSLOG.
If the farameter list does not
contain an ABEND, a standard message is
written in SYSLOG instead. Before issuing
the ABEND (either the one in the pararr,eter
list or the standard ABEND message), the
option code is checked.
If it specifies a
return, the CATAlOG ERROR PROCESSOR returns
to the caller. If it specifies that the
catalog is to be rebuilt, CZUFX is called
to do this before return is made to the
caller. Otherwise the ABEND message is
issued.
When called for a type 2 error the
CATALOG ERROR PROCESSOR checks the parameter list to see if it contains an ABEND
message. If it does, the message is concatenated with the error code, the module
name of CZCFE's calls an FQN. Then a camp
code 1 ABEND is issued.
If the para~eter
list does not contain an ABEND, a standard
message is issued.
If called for a type 3 error, the
CATALOG ERROR PROCESSOR writes a Ir1essage to
SYSLOG describing the type and location of
the error in the user's catalog. The FQN
and the module which discovers the error
are also included in the message. The
option code is again checked.
If a return
is requested, the module returns to the
caller. If it requests that the catalog be
rebuilt, CZCFX is called to do this before
returning to the caller. Otherwise, a comp
code 1 ABEND is issued and the user
receives a standard message along with the
error code, the module which detected the
error and the FQN.
Note: CZCFE8 is the location in CZCFE
where all SYSERs are executed. CZCFER is
the location of the area in CZCFE's PSECT
which contains the write-to-Iog message.
INDEX (CZCFI)
INDEX is a reenterable, nonrecursive.
subroutine residing in virtual
storage, that constructs chained index
levels in the catalog and creates new mem~ers within the catalog data set.
The
fully qualified name input parameter is
inspected to determine if a new member is
~eing created or a new index level is to be
added to the user.
If the FQN consists of
just one component, INDEX will build the
userid SBLOCR in the catalog and exit.
When index levels are to be chained for the
user, the lowest level found is searched
for an empty pointer and a pointer is constructed to the first SBLOCK of the level
~eing created.
(See Chart AI.)
~rivileged
Section 1:
Catalog Services
21
_.t~ntry
Point:
CZeFI1
Input: Register 1 contains a pointer to
the pararreter list:
Word 1
Pointer to fully qualified name
Word 2
Pointer to special parameters
bits
0-7
- generation code 40;
create generation
index
tits
8-15 - maximum generation
nUlT1ber
bits 2u-31 - generation flags
Outpu~:
Register 1 points to the input parameter list.
Modules Called:
GETS BLOCK (CZCFG1) -- To locate SBLOCK and
calculate virtual storage address.
(CZCFG4) -- To update the catalog.
Operation:
INDEX inspects the fully qualified name supplied as an input parameter to
determine whether the name has one component or more than one.
If there is only
one component (the userid), the PUT macro
instruction is issued to acquire a buffer
in which to construct the userid SELOCK.
INDEX returns with a X'OO' return code
after building the userid SELOCK. The STOW
!facre instruction is issued in LOCATE.
If the fully qualified name is composed
of mere than one component, INDEX will
enter l.OCATE to determine if the sarr,e name
already exists.
If LOCATE indicates that
all the components of the fully qualified
name were found (code 0), INDEX will return
a code of '08' to the calling routine.
A
return code cf '04' or 'OC' is passed on as
a return code from INDEX, and no further
processing takes place.
LOCATE (CZCFL) -- To locate an index level.
Upon locating some, but not all of the
levels of the fully qualified name, INDEX
deterrrines, in the case of a sharer, if the
sharer is privileged to update the catalog.
If not, an error code of 'OC' is returned.
If the lcwest level found is a generation
index, the next corr-ponent of the fully
qualified name must have the atsolute
generation name format.
Otherwise, an
errcr code of '08' is returned.
CATALOG ERROR PROCESSOR (CZCFE) -- To claim
a SYSER and a completion code 1 ABEND when
a catalog structure error is detected, or
when an end-of-data-set condition is
detected by CZCFGl. CZCFE is also called
whenever a SYSER is clained tecause the
userid in FQN is not 8 characters in
length.
The lowest level fO~Ld is then searched
fer an empty pointer. If none exists, the
SEARCHSBLOCK routine is entered to acquire
and chain an empty SBLGCK in which a pointer is to be placed. This is a pointer to
the first SBLOCK of the level being added.
1his process is continued until the entire
fully qualified nane has been cataloged.
Lxits:
Normal - register 15 contains 00 - a new
member was successfully added, or
all qualifiers (index levels> not
previously cataloged were added.
If the parameter list indicates that a
generaticn index is teing created, the
~i.eraticn options are put in the SBLOCK of
t~~ lowest level created.
SEARCHSBLOCK (CZCFH) -- To acquire and
chain an ~~pty SBLOCK.
PUT (locate mode) (CZCOS>
To locate a
tuffer to be the next record put in the
data set.
Error
- if INDEX was unsuccessful, register 15 contains one of the following codes:
When the level is being added to an
existing generation index, the pointer to
the new level is sorted by generation nurrter into the list ef pcinters belonging to
that G~n~ration index.
04 - userid not found in POD.
08 - all components of the fully
qualified narees were already
in the catalogs, or the
generaticn name had a format
error.
oc -
22
user is attempting to update
a user catalog for which he
is not authorized.
Validity checks are performed on data in
tne catalog when INDEX is searching the
catalog.
If an error is detected, the
CATALOG EFRCR PROCESSOR is called with
rararreters describinq the type and location
cf the error in the catalog, to claim a
SYSEF and d corrpleticn code 1 ABENC.
A call to CZCFG4 is made to update the
catalog cn external storage.
GETSBLOCK (CZCFG)
GETSBLOCK is a reenterable, nonrecursive, privileged subroutine residing in
virtual storage. ~hen entered at its primary entry point (CZCFGl>, it receives a
pointer containing the relative address of
an SBLOCK and calculates its virtual
storage address for the user. The user
submits the pointer to the desired SBLOCK
in the format OPbb, where P is the page
number relative to the member and bb is the
relative byte within tre page.
If the
requested SBLOCK is in the page buffer, the
virtual storage address is calculated and
returned to the user. If the p value
exceeds the size of the user's catalog,
CZCFG2 is called which returns to the user
with a return code of X·04'.
Entry point CZCFG3 is invoked by LOCATE
to provide initial sizing of the VAM buffer
used in processing the user catalog.
Entry point CZCFG4 is used to perform
the PUT or PUTX functions as indicated by
the bit settings in the CHACDS table.
(See
Chart AF.)
Entry Point:
CZCFG1 - Primary entry point. Used to convert a 'Pbb' address into a 32-bit
Virtual Memory address.
CZCFG2 - EODAD exit.
CZCFG3 - Entry point from LOCATE (CZCFL) to
provide initial sizing of the VAM
buffer used in processing the user
catalog.
CZCFG4 - Used to effect PUTX/PUT/STOW/CLOSE
sequence as indicated by the bit
settings in the CHACDS table
(CDSFLG) .
Input:
Register 1 contains a pOinter to
the relative address of the requested
SBLOCK.
output: Register 1 contains a pointer to
the virtual storage address of the
requested SBLOCK.
Modules called:
SETL (CZCOT) -- To locate the specified
rage of a catalog member.
GET (CZCOR) -- To move the specified page
to the catalog buffer.
STOW (CZCOK) -- To unlock a member in the
POD.
CLOSE (CZCOQ) -- To disconnect a data set
from the system.
PUT (CZCPA) -- To add a record to an output
data set.
PUTX (CZCOU) -- To exchange a record in an
output data set.
READ (CZCPE) -- To read a record of
SYSSVCT.
(CZCPE) -- To write a record of
SYSSVCT.
~RITE
CATALOG ERROR PROCESSOR (CZCFE) -- To issue
any SYSERs and ABENDs claimed by GETSBLOCK.
Exits:
If the return code from STOW is not
zero a SYSER is issued followed by an
ABEND.
If end-of-data set occurs, control
is returned to the user with 04 in register
15; otherwise, control is returned with 00
in register 15.
Operation: CZCFGl - This is the primary
entry point used to convert a 'Pbb' address
into a 32-bit Virtual Memory address. This
is done by multiplying (P-l) by 4096, and
adding the product to the beginning of the
user's catalog buffer. Adding the bb value
yields the required Virtual Memory address.
No physical GET operations are performed.
If the P value exceeds the size of
the user's catalog, CZCFG2 is entered.
CZCFG2 - This is the EODAD exit after a GET
or PUT is issued for a catalog member.
A
SYSER and ABEND will be claimed if the
EODAD occurs.
CZCFG3 - This entry point is invoked by
LOCATE (CZCFL) after the call to FIND
(CZCOJ), to provide initial sizing of the
VAM buffer used in processing the user
catalog. The buffer must be at least one
rage greater than the current size of the
member (CCBDMS).
If the buffer is too
small, a FREEMJ\IN and GETMAIN sequence is
perforrred to release the current buffer and
obtain the required space for the new buffer, storing these parameters in the DCB
Header.
DCBEXL, DCBBCN, DHDDXP, and DHDCPR
are cleared to ensure that paging of the
rrember will te effected on a subsequent GET
operation.
The DHDMRL field is set to one page
greater than the current size of the member. This field is set to ensure proper
execution of CZCFG4 and the edit performed
by SEARCHSBLOCK (CZCFH).
A SETL is issued to the beginning of the
rrember, followed by a GET (locate mode).
The address returned by GET is stored in
EUFFJ\D and used by CZCFG1 to calculate the
Virtual ~emory address requested.
CZCFG4 - This entry point is used to effect
the necessary PUTX/PUT as indicated by the
bit settings in the CHACDS table (CDSFLG).
The CDSFIG bits are then reset, and a STOW
Section 1:
Catalog Services
23
(type R) is issued against the DCB pointed
to by CZCFL2. The CZCFL2 field is reset to
foint to the primary DCB (CDSCOM).
If a t'UTX was issued, a check is made to
see if the flag byte in the SYSSVCT record
indicates that the USERCAT and the SYSCAT
(SCRATCHCAT) members are the same.
(Tbey
should not be the same since the PUTX
changed SYSCAT.) If the flag indicates the
catalogs are the same, the record is reset
and written back into SYSSVCT.
If a SYNAD
is taken on a READ or on a WRITE, the
CATALOG ERROR PROCESSOR is called to issue
d
SYSER and ABEND and the user receives the
message:
UNRECOVERABLE ERROR IN SYSSVCT.
If d PUT is issued against a member due
to an added page, a CLOSE (TYPE=T) is
issued instead of the STOW.
SEARCHSBLOCK (CZCFH)
SEARCHSBLOCK is a reenterable, nonrecursive, privileged subroutine residing in
virtual storage.
It acquires and chains an
empty SBLOCK as either:
maximum), a page containing an available
SBLOCK can be located. When an end-of-data
set condition is encountered while scanning
through the pages, SEARCHSBLOCK appends a
new page to the user's catalog through use
of a simulated PUT (locate mode). SEARCHSBLOCK sets the PUT indicator in the CHACDS
t.able, calculates the VMA of the new page
ty adding the current value of LRECL to
that of DCBBCN, and then increases the
value of LRECL by 4096. The new page is
zeroed out and thereby initialized.
Once the page is retrieved, SEARCHSBLOCK
scans the allocated byte field of each
SBLOCK in the page. If this field is zero,
the SBLOCK is free; if this field is not
zero, the next SBLOCK is examined. This
Frocedure is repeated until an empty SBLOCK
is found.
SEARCHSBLOCK inserts a cackward
Fointer in the new SBLOCK, and retrieves
the parent SBLOCK to which it is chained.
The forward chain in this SBLOCK can be one
of the following:
• Extended SBLOCK pointer.
• Pointer to a list of sharers.
• An extended SBLOCK of a cataloged
entity.
• Pointer field in a member of an index
level.
• The first SBLOCK of a cataloged entity.
The count of SBLOCKs in each page is
checked until an available SBLOCK is found.
The relative address of thE: SBLOCK within
the page is then located by searching for a
control byte of zeros. The new SBLOCK is
retrieved by GETS BLOCK and its virtual
storage address is returned to the user.
The new SBLOCK is linked to the parent
SBLOCK before returning control to the
user.
(See Chart AG.)
Entry Point:
CZCFHl
Input: Register 1 contains a point~r to
the address of the SBLOCK to which the new
SBLOCK is to be chained.
Output:
Same as input
Modules Called:
GETSBLOCK -- locate SBLOCK and calculate
virtual storage address.
CATALOG ERROR PROCESSOR (CZCFE) -- To claim
any SYSERs and camp code 1 ABENDs issued by
SEARCHSBLOCK.
Exits:
Normal - return without return code
Error
- to SYSER without return code
Operation: SEARCHSBLOCK scans the existing
pages of the user's catalog.
By testing
the count of SBLOCKs in the page (64 is the
24
SEARCHSBLOCK determines the proper field
and inserts the forward chain.
The new SBLOCK is retrieved via
GETSBLOCK and control is returned to the
calling program.
USERCAT SCAN (CZUFY)
USERCAT SCAN is a reenterable. nonrecursive, Friviliged subroutine that resides in
virtual storage.
It is called at entry
point CZUFYl when OPEN VAM or DSCB/CAT
RECOVERY discovers an error while reading
the DSCE for the SYSSVCT data set. The
first data page of the data set is examined
to see if it contains records for userids
TSS ••••• , SYSOPERO, and SYSMANGR, and if
the locators at the bottom of the VISAM
page for the records are correct. If all
these conditions are true, the checksum is
computed for the SYSSVCT DSCB, and the DSCB
page is written out before leaving the
module. Otherwise, the first page of SYSSVCT is constructed with records for the
three userids and the page is written onto
a direct access device. The DSCB for SYSSVCT is initialized, the checksum is comFuted, and this page is written out. The
opErator is then prompted with a message
telling him to call CZUFY2 after startup is
complete.
The data set SYSSVCT is rebuilt at entry
point CZUFYI. First, the bSCB pointer for
each record in SYSSVCT is filled ~ith
zeros. The public volumes are then scanned
for usercat DSCBs. When found, the DSCB
pointer is computed and entered into SYSSVCT for the userid.
(See Chart AJ.)
Entry Points:
CZUFYl - To compute checksum for SYSSVCT
DSCB and to construct the first
page of SYSSVCT data set if
necessary.
CZUFY2 - To initialize SYSSVCT and then
rebuild it by noving in the DSCB
pointer for all of the usercat
data sets.
Input:
putput:
None
None
Modules Called:
SETL (CZCOT) - To position to beginning of
SYSUSE data set.
If FINDEXPG could not get a free
page on a direct access device.
If READWRIT could not ~rite out a
~SCB page containing the
corrected DSCB for SYSSVCT.
if READWRIT could not read a DSCB
page containing the OSCB fer
SYSSVCT.
~.f9~i~0:
The entry IJuint CZUF'Yl is
called ~hen OPEFVA~ or DSCB/CATALOG RECOVERY encounters an error in the SYSSVCT
FINDJFCB is called to retrieve the
OSCB.
JFCB.
If one is not found, ODEF is called
to create one.
If a JFCB cannot be
created. an ABEND is issued and the user
receives the following message:
SYSTEM FAUL'r: 001, UNABLE TO ACCESS USERCAT
The LSCB pointer is obtcdned from the JFCB
GET (CZCOR) - To retrieve a record in
SYSUSE.
OPEN (CZCLAO) - To open SYSUSE and SYSSVCT
data sets.
READ (CZCPE) - To read a record in SYSSVCT.
WRITE (CZCPE) - To
SYSSVCT.
~rite
SYSTEM FAULT; 002, UNABLE TO ACCESS USERCAT
a record in
(CZATJ) - To issue a message to user
and operator.
PR~2T
CLOSE (CZCLB) - To close SYSSVCT and SYSUSE
data sets.
READWRIT (CZCEM) - To read and
page.
~rite
a OSCE
ESALOCK (CZCEJ) - To lock and unlock the
SDAT PAT lock.
FINDJFCB (CZAEB) - To find the JFCB for
SYSSVCT.
DDEF (CZAEA) - To build a JFCB for SYSSVCT.
FINDEXPG (CZCEL) - To get a page of storage
on a direct access device.
GETMAIN (CZCGA) - To get a page of virtual
storage.
FREEMAIN (CZCGA) - To free a page of virtual storage.
ABEND (CZCAP) - To abort from a module.
Exits: The module does not set a return
code on normal exit.
ABEND:
and READWRIT is then called to read the
CSCB page into virtual storage.
If no
error is detected in reading the DSCB page.
the module returns to the caller.
If an
error other than checksum is detected, an
ABENC is issued. and the user receives the
follo~ing message:
If ODEF could not create a JFCB for
SYSSVCT.
If a checksum error is detected by REAOWRIT, the first page of the SYSSVCT data
set is read into main storage at CZCOWl by
issuing a SETXP macro instruction. The
page is examined to see if it contains
records for userids TSS ••••• , SYSOPERO, and
SYSMANGR, and to see if the locators at the
bottom of the VISAM page for these userids
are correct.
If these conditions are true,
the checksum for the SYSSVCT DSCB is computed and the DSCB page is ~ritten out by
calling READWRIT before leaving the module.
(ESALOCK has to be called to lock the SOAT
PAT page before ~riting the DSCB page.
When the ~rite is completed, ESALOCK must
te called again to unlock the SCAT PAT
lock.)
If the ~rite operation is unsuccessful, an ABEND is issued, and the user
receives the follo~ing message:
SYSTEM FAULT: UNABLE TO WRITE OSCB OR PAT
PAGE
If the first page of tbe SYSSVCT data
set is not correct, the data set is rebuilt
with records for userids TSS ••••• , SYSOPERO, and SYSMANGR on a page of virtual
storage obtained by a GETMAIN macro call.
The DSCB pointer for the USERCAT of each
userid is computed and put into SYSSVCT.
The page is then ~ritten out to a page on a
direct access device ~hich ~as obtained by
calling FINDEXPG. If FINDEXPG can not
obtain a page of storage an ABEND is issued
Section 1;
catalog Services
25
and the user receives the following
message:
UNABLE TO ACCESS USERCAT FOR THE USERID
~hen
SYSTEM FAULT: EXTERNAL STORAGE EXHAUSTED
The DSCB for SYSSVCT is then initialized, and the page containing the DSCB is
written out as described above. The operator is prompted with a message telling him
to call entry point CZUFY2 after startup is
complete. FREEMAIN is then called to free
the page of storage obtained ty calling
GETMAIN. The corresponding by,~e in the PAT
page table is found and set to indicate
that the page is in use. The PAT page is
then written out by READWRIT.
Entry point CZUFY2 is called to rebuild
the SYSSVCT data sets. First, the SYSUSE
data set is opened if it is not already
open, and a SETL macro instruction is
issued to position the beginning of the
data set. Then, a record is obtained by a
GET. A userid is obtained from the SYSUSE
record, and it is used as the key to read a
record in SYSSVCT after it has been opened.
If the redd is unsuccessful, the DSCB
pointer in the SYSSVCT record will be
filled with zeros, a WRITE UPDATE will be
issued on SYSSVCT, and the program will get
the next record in SYSUSE. If the READ or
WRITE UPDATE results in a SYNAD for a
reason other than because the use rid was
not found, the user is prompted with the
following message:
UNABLE TO ACCESS USERCAT FOR THE USERID
and the program looks at the next record in
SYSUSE.
If a SYNAD is taken because the
userid was not found in SYSSVCT, a WRITE
NEW will be issued on SYSSVCT, and the program will get the next record in S¥SUSE.
If a SYNAD is taken on a WRITE NEW, the
user is prompted with the following
message:
USERID CANNOT BE ADDED TO USERCAT TABLE
dnd again the program tranches back to get
the next SYSUSE record.
When all the records in SYSUSE have been
read, SYSUSE is closed if it was opened in
this module. SYSSVCT is now initialized so
that all of the records have a zero DSCB
pointer. All of the public volumes are
then searched for USERCATs by examining the
PAT page on each public volume for a DSCB
page.
When one is found, READWRIT is
called to read the page into main storage
at CZCOZ1. Each format E DSCB i~ examined
for an FQN of userid.USERCAT.
If found,
the DSCB pointer is computed and moved into
SYSSVCT with a WRITE UPDATE using the
userid in the DSCB as the key.
If the
WRITE results in a SYNAD, the user is prompted with the following message:
26
all of the DSCBs on all of the volumes
have been checked, the module returns.
CATFLUSH (CZCFX)
CATFLUSH is a public, reenterable, privileged subroutine that copies members of
the scratch catalog (SYSCAT) into individual user catalogs at task termination.
deletes closed members from the scratch
catalog when the virtual storage POD becomes full. and erases the scratch catalog at
shutdown.
(See Chart AL.)
Entry Points:
CZCFXl - To copy specific members into the
user catalog.
CZCFX2 - To copy inactive members into the
user catalog and erase them from
the scratch catalog (SYSER if
erase is impossible).
CZCFX3 - To copy all members into the user
catalog and erase the scratch
catalog.
CZCFX4 - To copy SYSOPERO member intc the
user catalog.
CZCFXS - SYSSVCT DCB
CZCFX6 - USERCAT DCB
CZCFX7 - SYNAD entry
CZCFX8 - To copy inactive members into the
user catalog and erase them from
the scratch catalog (no SYSER if
erase is impossible).
Input:
Register 1 points to a userid.
(The parameter list is for entry point
CZCFXl only.)
Output:
None
Modules Called:
READ/wRITE (CZCPE)
record into SYSSVCT.
To read or write a
FINDJFCB (CZAEB) -- To find the SYSCAT and
USERCAT JFCBs.
DDEF (CZAEA) -- To create a USERCAT JFCB if
none is found.
ADDDSCB (CZCEK> -- To allocate a DSCB for a
new USERCAT.
OPEN (CZCLA)
To open a USERCAT DCB.
SETL (CZCOT)
(old USERCAT).
To position the data set
PUT (CZCOS) -- To copy the user catalog
from the scratch catalog.
CLOSE (CZCLB) -- To close the USERCAT DCB.
STOW (CZCOK) -- To unlock a scratch catalog
member (type R), and to erase a scratch
catalog member (type D).
FIND (CZCOJ) -- To lock a member of the
scratch catalog.
GETSBLOCK (CZCFG) -- To set up the scratch
catalog buffer (entry faint CZCFX3).
RELEXPG (CZCEN) -- To give back pages of
the scratch catalog at shutdo~n.
READWRIT (CZCEM) -- To rEad or
scratch catalog DSCE.
DSCBREC (CZCEF)
~rite
the
To handle a OSCE error.
PATLOCK (CZCEJ)
To lock or unlock a PAT
when ~riting a DSCB.
SYSER (CEAIS) -- To indicate an error
condition.
ABEND (CZACP) -- To terminate processing
for an error condition.
Exits:
Normal - register 15 will contain a zero
return code.
CZCFX3 (entry point 3) is called by SHUTDOWN to update all members not already
updated and then erase the scratch catalog.
When entered at CZCFX3. CATFLUSB checks the
RCR Ration Flag for each member and. if it
is set for a member, bypasses that member
and does not erase the scratch catalog.
All successfully updated members are
deleted.
All members in SCRATCHCAT updated
with no RCR ration flag set are also
deleted.
To erase the scratch catalog, RELEXPG
(CZCEN) is called to release all pages from
the scratch catalog except the format E
DSCB slot. Then, the DSCB is read into
CZCOZ by a call to READWRIT (CZCEM). The
follo~ing fields in the format E slot are
filled with zeros:
DSELBP
bytes in last page
r;SENCP
data pages
OSEDOP
directory pages
DSENOP
overflo~
rSETNP
total pages
DSEENT
(38 full words)
DSECHN
chain pointer
pages
Error - SYSER or ABEND
Operation: The input r:arameter list (consisting of a pointer in register 1 to an
eight-character userid) is required for
entry point CZCFX1. All other entry points
~ork on the entire scratch catalog, except
CZCFX4 ~hich works only on SYSOPERO.
Before a member of SCRATCHCAT is copied to
USERCAT, the entry for this user in SYSSVCT
is checked for UCTFLG=X'OO' or '01'.
If
this sync byte is '01', no changes have
been made to SCRATCHCAT and no update is
necessary.
If the sync byte is '00', USERCAT is updated from SCRATCHCAT and UCTFLG
is set to '01'.
(In this description
·sync· means the scratch catalog and the
user catalog for a memter are the same.)
CZCFXl (entry paint 1) is called by
LOGOFF or ABEND to update a user catalog.
'I'his ~ill ensure that a user's catalog contains any changes made to the scratch
catalog. The member is not deleted from
the scratch catalog at this time.
CZCFX2 (entry point 2) is called by LOCATE if it is necessary to add a member to
the scratch catalog and there is no room in
the virtual storage POD to insert the member.
If all me~bers are active, a minor
SYSER is declared and the task is terminated.
Before any member is deleted (by
t.he STOW D macro instruction), the UCTFLG
tyte is checked for the RCR Ration Flag
(UCTFLG=X'02') and if it is set, the member
is skipped and not deleted.
The checksum for the DSCB is then recalculated and written to external storage by
REAm-mIT.
CZCFX4 (entry point 4) is called by MOHR
(STARTUP) to force a refresh of SYSOPERO to
ensure that this particular user catalog is
updated.
CZCFX8 (entry paint 5) is called by LOCATE to reduce the size of the scratch
catalog when it reaches 800 data pages.
If
all rrerr,bers are currently active, a return
is made to the caller.
CAT FLUSH uses the following method to
cory from the scratch catalog to the user
catalog.
If no user catalog exists (no
address in UCTDSCB in SYSSVCT), FIND JFCB
is called to locate the JFCB for this user
catalog.
If no JFCB exists, DDEF is called
to create one. ADDDSCB is then called to
assign a format 'E' OSCE for this user
catalog, the pointer to which is placed in
TOTDSC ~efore the call to OPEN.
Prior to
opening the USERCAT, CATFLUSH ensures that
the member to be copied from the scratch
catalog is write-interlocked and if it is
not, a ~rite interlock is imposed before
the user catalog is opened. Read interlocks are cleared before setting a write
interlock.
Section 1:
catalog Services
27
Also before opening the user catalog,
CATFLUSH sets the RCR Ration Flag in SYSSVCT for this entry.
CATFLUSH then opens
the user catalog for output.
If the OPEN
is successful the OSCB pointer is placed in
UCTDSCB and a WRITE is issued. CATFLUSH
reads pages from the scratch catalog (by
GET macro instruct10ns), writes pages to
the user catalog (by PUT macro instructions), and then closes the user catalog.
When a user catalog exists, CATFLUSH
moves the DSCB pointer for t;.e user catalog
from UCTDSCB to TDTDSC. Before opening the
user catalog. CATFLUSH SETS THE RCR Ration
Flag in SYSSVCT for this entry. A SETL 'B'
is done after the user catalog is opened.
The PUT macro instruction that follows will
truncate any pages no longer needed, or add
pages if necessary. On the successful completion of the PUTs to the user catalog,
the UCTFLG is set to X"Ol' to indicate that
the update is complete and the RCR Ration
Flag is cleared.
Output:
None
~odules Called:
READ/WRITE (CZCPE) -- To read or write a
record in SYSSVCT.
READWRIT (CZCEM) -- To read or write a
DSCE.
VMA (CZCGA) -- To get work and buffer pages
(GETMAIN) •
ADDDSCB (CZCEK) -- To allocate a new DSCB
for a user catalog.
INDEX (CZCFI) -- To create a userid SBLOCK
level when rebuilding the catalog.
GET SBLOCK (CZCFG) -- To set up the scratch
catalog buffer (entry point 3).
--To do
PUT/PUTX/STOW on the scratch catalog member
(entry point 4).
CPEN (CZCLA) -- To open a user catalog DCB.
OSCB/CAT RECOVERY (CZUFX)
DSCB/CAT RECOVERY is a public, reenterable, privileged subroutine that provides
dynamic error recovery for either the
scratch catalog or the user catalogs.
It
updates a user catalog if the current member in the scratch catalog cannot be used,
or rebuilds a user catalog if no member
Exists in the scratch catalog and the user
catalog is unusable.
If the user catalog
is rebuilt, the user must reenter all sharing information because it is lost in
rebuilding from public DSCBs.
(See Chart
AK. )
Entry Point:
CZUFXl
Input: Register 1 contains a pOinter to a
two-word parameter list that is organized
as follows:
Word 1
address of an eight-character
userid
Word 2
address of a one-byte flag field
The flag will be set to the following hexadecimal values:
X'01' - cannot open bhe user catalog for
input
X'02" - cannot open the user catalog for
output
X'04' - the scratch catalog member is
unusable
X'OS' - the user catalog is unusable
X'lO' - user catalog input paging error
X'1l' - user catalog DSCB input paging
error
28
PUT (CZCCS) -- To copy the scratch catalcg
rreITber to the user catalog. --To copy the
user catalog to the scratch catalog.
CLOSE (CZCLB) -- To close the user catalog
DCB.
DELCAT (CZCFD) -- To delete a catalog
entry.
VMA (CZCGA) -- To free the buffer and work
pages (FREEMAIN).
LOCATE (CZCFL) -- To verify data set names
with pULlic DSCBs.
ADDCAT (CZCFA) -- To update DSDs. --To
catalog public data sets during rebuilding
[rocess.
RELEXPG (CZCEN) -- To free up data pages
and r:SCB slots.
GET (CZCOR) -- To copy the scratch catalog
member to a work area.
--To copy the user
catalog into a buffer for copy to the
scratch catalog.
USER PROMPTER (CZATJ) -- To issue diagnostics to the user.
PAT LOCK (CZCEJ) -- To lock or unlock a PAT
when writing a DSCB.
SRCH SDST (CZCQE)
To clean up the SDST
entry when called during the open process.
FIND (CZCOJ) -- To lock a scratch catalog
member.
ABEND (CZACP) -- To terminate processing
when an error occurs.
Exits:
Normal - Return to caller if input code is
X'04' (SCRATCHCAT is unusable>
If the userid is incorrect, the user
catalog is bad and the procedure described
above for a bad OSCB is followed.
Error
If the userid in the first SBLOCK on the
first page of the user catalog is correct,
all catalog chains are searched for ~ublic
OSOs. For this search, the following tests
are made to ensure catalog integrity:
- ABEND (CC1)
Operation: DSCB/CAT RECOVERY assumes upon
ent.ry that the user catalog rr,ember is
locked in the scratch catalog. This lock
~revents multiple users from attempting
recovery of a user catalog.
The userid is used as a key to extract
t.he entry for this user from SYSSVCT. The
pointer to the user catalog (UCTCSCB) is
checked for a nonzero fainter.
If a user catalog exists (UCTDSCB is not
zero), the DSCB is read into CZCOZ by a
call to REAOWRIT (CZCEM). The return code
is tested, and if the data set name agrees,
this OSCE is used to ufdate the catalog.
The return code from REACWRIT is saved for
later use. The DSCE is checked for the
following:
1.
VS organization
2.
(J-format records
3.
Number of pages in OSCB
page entries
4.
LRECL
5.
A checksum error
=a
Number of
multiple of 4096
If any of these checks failS, the OSCB is
declared invalid, and the CSNAME field in
the invalid OSCE, the OSCB pointers in
UCTOSCB and the JFCB for t.his user catalog
are all filled with zeros.
The OSCB is then written back to external storage by REAOWRIT. AOOOSCB is called
to assign a new DSCB slot, and the pointers
in the JFCB and UCTDSCB are updated. The
user catalog is then rebuilt in SCRATCHCAT
by scanning public storage for the user's
data sets and calling AODCAT2 with the CATVAM option to catalog them. Uron completion of the rebuild, SCRATCHCAT is used to
create a new USERCAT.
If the tests on the original OSCB were
successful. a GETMAn~ is done for a Luffer
large enough to hold all pages of the user
catalog. A SETXP is then issued to read
these pages into the buffer and the first
page is checked for an index level SBLOCK
with the correct userid in the name field.
1.
Forward and backward pointers for each
SBLOCK are good.
2.
Number of bytes used in each SBLOCK is
correct.
The count in the above test is corrected
if it is wrong.
If the pointers are wrong,
the user catalog is bad, and it is rebuilt
from the public DSCBs. At the com~letion
of the search and corrections, the buffer
is written (by PUT) into the scratch
catalog for the completion of the recovery
procedure.
Following the copy to the scratch
catalog, all OSCBs on public volu~es are
searched and as each data set for this user
is found, a LOCATE is done.
If the data
set does not exist in the catalog, it is
cataloged by a call to AODCAT2 with the
CATV AM option specified. A dummy JFCB is
used for this call with the data set name
rroved into it from the OSCB. If the data
set does exist in the catalog, the OSCB
painter is compared to the address of the
DSCB on public storage.
If the pointers
agree, the OSCB search is continued. If
the OSCB pointers do not agree, the DSCB
pointed to by the catalog is checked and,
if it is a valid DSCB, the OSCB search is
continued.
If it is an invalid OSCB, the
DSCB just located is checked: if it is
valid, a pointer to it is put in the
catalog; if it is not valid, the data set
is erased. At the completion of the OSCB
search, the scratch catalog member is again
searched for public DSOs and any OSOs that
are not ~arked as public are deleted from
the scratch catalog by a call to DELCAT.
At the completion of the scratch catalog
search. the member is copied to the user
catalog as described in the CATFLUSH module
description.
If UCTDSCB is zero, public storage is
searched for a USERCAT DSCB. If one is
found, both the OSCB and the USERCAT are
validated as described above. If a USERCAT
DseB is not found, the scratch catalog is
rebuilt.
Section 1:
catalog Services
29
SECTION 2:
EXTERNAL STORAGE
A~LOCATION
External storage allocation (ESA)
includes those service routines that allocate storage from direct access volumes
designated as external volumes.
External
volumes are those volumes of secondary
storage used for data, as opposed to
volumes used as auxiliary stc,rage. Auxiliary volumes are used for virtual storage
(paging) and, as such, are controlled by
auxiliary storage allocation (CEAIA).
EXTERNAL VOLUMES
The external storage allocation routines
deal only with direct access volumes (IBM
2311 Disk Pack or IBM 2314 Disk Pack). All
public storage volumes are assumed mounted.
Each volume in the system has a 6-byte
identification associated with it. The
volume identification is included in the
volume label on each volume. When a device
becomes accessible to the system, a unique
2-byte logical (symbolic) device address is
associated with it; this logical address
can then be used to refer to any volume
mounted on that device. The logical device
address is converted to a true physical
address by the supervisor path finding
mechanism whenever the volume is accessed.
The symbolic device allocation table (SDAT)
contains an entry for each on-line device.
Within the entry is control data used by
ESA routines to determine volume type, page
availability information, Page Assignment
Table (PAT) origin, PAT VMA for VAM
volumes, and VTOC space available or gross
space available for SAM volumes.
Each volume is identified by a volume
label located on cylinder 0, track O. The
volufl'(' label points to the Page Assignment
Table (PAT) for VAM volumes, which is used
to indicate the current assignment status
of each page on the volume. The PAT occupies some number of pages on the volume,
the number dependent on device type (1 on
the 2311 Disk Pack; 2 on the 2314 Disk
Pack). The remaining pages can be allocated as Data Set Control Block (DSCB)
pages or data pages. For SAM volumes the
volume label points to the VTOC which is
itself variable in length but composed of
fixed length (140 byte) records (DSCBs).
SAM volumes use format-O, -1, -4, -5,
-A. -B, and -C DSCBs. VAM volumes use
format-E and -F DSCBs. The DSCB formats
are described in detail in Appendix A.
30
There are two types of external volumes,
those containing physical sequential data
sets (SAM volumes) and those containing
virtual storage data sets (VAM volumes).
Each external volume may contain either,
but not both, types on the same volume.
VAM volumes are characterized by the fact
that they are formatted into page-sized
records and space is maintained and allocated in page-oriented extents. SAM
volumes are not pre-formatted and can be
used for interchange with Operating System/
360. Srace is maintained in terms of
tracks and cylinders and can be allocated
in increments of either tracks or
cylinders.
Utility programs are provided with TSS/
360 for volume initialization. Initialization of volumes containing physical sequential data sets is described in the publication IBM System/360 Time Sharing System:
Inderendent Utilities, GC28-2038.
Initialization of volumes containing virtual
storage data sets differs from those containing rhysical sequential data sets in
that VAM volumes are formatted into pagesized segments (to be consistent with page
number conversion algorithms in the resident monitor) and the PAT table is then
formatted and initialized. The PAT table
will be pOinted to by the Volume Label, and
will contain one one-byte entry for each
rage on the volume.
PUBLIC AND PRIVATE VOLUMES
All external volumes can be classified
as either public or private. Space is not
allocated on a private volume unless a user
explicitly declares in a DDEF command or
DDEF macro instruction that he wants srace
cn that volume.
If the user does not
declare a specific volume. space will be
allocated on a public volume. All public
volumes are VAM volumes, and the system
specifies the storage device for the user.
DUPLEXING CAPABILITY FOR USER DATA SETS
Through the DUPOPEN command, the user
has the capability of duplicating his data
set on two separate physical volumes. This
fUnction is transparent to the user and is
available only for public VAM data sets.
The external storage required is exactly
double for this duplicating facility, and
the time required for data output is
approxirr.ately doubled. The routines that
operate on VAM data sets must be aware of
the possibility of the duplicate set.
Note: If either copy of a duplexed data
set. is changed independently of the other,
duplexing is invalidated in a manner which
is transparent to the duplexing mechanism,
and may cause false recoveries.
SA.M VOLUME PROCESSING
ALLOCATE is called to inspect the job
file control block (JFCB) for the size of
the initial allocation. The sFecification
will be in terms of tracks. cylinders. or
records, and only from a single volume having enough space for the entire amount of
requested storage. ALLOCATE returns the
appropriate code if the request cannot be
satisfied, and updates the SDAT and volume
fields of the JFCB.
ALLOCATE calls SA~SEARCH to find the
extents for physical sequential data sets.
During the scan, SAMSEARCH creates a pushdown list of five extents smaller than the
request.
If an extent equal to the request
is found, the scan is terminated and the
extent allocated.
If an extent equal to
the request is not found. the smallest
extent larger than the request is allocated.
If an extent equal to or greater
than the request is not found, space is
allocated from the extents in the push-down
list. up to five separate contiguous
extents as necessary are combined until the
request is satisfied. Requests must be
made for integral numbers of tracks or
cylinders.
When the access method routine detects
that extent limits have been reaChed, and
additional space is required fer a data
set, EXTEND is used to obtain additional
storage.
The secondary allocation field of
the JFCB is used to determine the amount of
storage required.
EXTEND always makes the
total requested allocation froll' one volume.
If there is not sufficient space available,
EXTEND links to the calling program (end of
volume - EOV) for label processing and the
mounting of a new volume. EOV returns to
EXTEND for the allocation from a new
volume.
When a data set is closed, the CLOSE
routine checks the space release flag in
the JFCB to determine whether unused space
is to be returned (that is, made available
for reallocation, and made unavailable to
the data set from which it is released).
GIVBKS is called to merge the returned
extents into the list of extents in the
DADSM-DSCBs of the proper volume.
Adjacent
ext.ents are combined whenever possible.
If
any extents are given back, the DADSM-DSCBs
are updated.
To return the extents to the available
space on the volume, MERGESAM is called by
GIVBKS. It is MERGESAM that adds the
returned extents to the list of extents in
the CADSM-DSCBs, maintaining the order by
location and combining extents whenever
Fossible.
When the user commands the system to
erase a data set., or when any data set
remains on a public volume at the end of a
task, the SCRATCH routine is used to remove
it from the volume or volumes on which it
resides. All the allocated extents are
merged tack into the available extents on
the volume (s) and t.he data set DSCBs are
over-written with zeros to indicate that
the extents are available for reallocation.
The various SAM routines call the
OBTAIN/RETAIN routine for reading and writing DSCBs. The RENAME routine can be used
to change the FQN in the key field of a
format-l DSCB.
VAM VOLUME PROCESSING
VAM volumes may be either public or private.
FiNDEXPG is called to allocate the
number of pages specified in the allocation
fields of the JFCB. The new DSCB will be
constructed using the list of external page
entries returned from FINDEXPG.
To find and commit an unassigned DSCB
slot, ADCDSCB is called. For a format--E
DSCB, ADDDSCB will call VOLSRCH and will
search the PAT of the returned RVN to find
an unused OSCB or a dat.a page which can be
assigned as a DSCB page.
For a format-F
OSCB, ACDDscn will try to assign it from
the fage or volume on which the format-E
OSCB resides.
Failing this, it will call
VOLSRCH as for a forrr~t-E DSCB.
RELEXPG is
used to return data pages and DSCBs for
subsequent reallocation.
DSCBREC is called to recover from a
checksum error.
If the data set has been
opened, the bad format-E DSCB is reflaced
cy a new one.
This is because the call is
assumed to have come from WRITDSCB after
having found a cad format-E DSCB.
All the
data set pOinters are present in the
RESTBL, and the DSCE chain is about to be
updated anyway.
If the data set has not
teen ofened and there is no duplexed copy,
the data set is deleted from the catalog
and all DSCBs associated are released.
If
the data set is not open, but is duplexed.
recovery is made from the duplexed cOfY.
WRITDSCB updates and writes the DSCBs to
external storage, using an in-line subroutine to obtain the DSCBs to be updated.
Sect.ion 2:
External Storage Allocation
31
When private VAM volumes require mounting. the VAMINIT routine is used to read
the volume label record. and set up the
SDAT entry.
ROUTINES USED WITH SAM FORMAT VOLUMES
ALLOCATE (CZCEA)
ALLOCATE is a reentrant. nOIlrecursive,
routine residing in virtual
storage.
This routine is caJ .ed I:;y DATADEF
to provide the initial allocaticn of direct
access external storage for new output data
sets.
ALLOCATE finds a private volume in
the JFCB.
DSCBs describing the extents
allocated are written and the VTOC DSCB,
JFCB, and SDAT entry updated.
(See Chart
BA. )
~rivileged
Entry Points:
CZCEAI
Normal entry via Type I linkage.
CZCEA2
Called by ABEN8 for resetting
interlocks.
Input: Register I contains a pointer to a
one-word parameter list:
Word 1
Address of the JFCB
output: The JFCB, VTOC, and SDAT are
updated.
Restrictions:
1.
Allocation is from one volume only.
2.
There is a maximum of fiVE extents
allocated to one SAM data set.
2p::ratiof!: ALLOCATE searches the volume
fields of the JFCB to find the last nounted
volurr~.
If none are feund, SYSER is
called. followed by ABEND with the followinq ~essage to the user:
NO
~OUNTED
VOLUME INDICATED BY JFCB
If one is iound it is checked to be sure
it i~ d SAM fcrmatted volume on a private
device.
If it is on a public device, SYSER
IS called and return is made with the
return code set to '04'.
If the volume is
not SAM formatted, a return is made with
the return code set to '10'.
If these
checks are succEssful, the VTOC is locked
and the gross space and hole count fields
cf the SDAT are Examined.
Return is made
with a code of '04' if there is not enough
gross space on the volumE.
If there is
space enough, OBTAIN is called to read the
DSCE with the same data set name on the
volume.
It such a DSCB is found, through a
SEARCH KEY EQUAL on DSNAME, a duplicate
data set name exists, and return is made
with a code of 'OC'.
If none is found,
ALLOCATE calls SAMSEARCH to allocate space
for the GSCB. OBTAIN then reads in two
format-O (i.e., unused) DSCBs to become the
data set DSCBs (format-I), sets up all
fixed GSCB fields and fills in the extents
just allocated. The original data set flag
is set in the JFCB; the VTOC is updated.
the lock bytes reset. and return is made
~ith a code of '00'.
An unrecoverable I/O
error will cause the program to return with
a code of 'OS'.
SAMSEARCH (CZCEC)
Modules called:
OBTAIN/RETAIN (CZCFO) -- Read/Write DSCBs
SAMSEARCH is called ty either ALLOCATE
or EXTENC to search the DADSM-DSCBs for
available space to fill a request. The
DADSM-DSCBs are then updated to reflect the
allocation.
(See Chart BB.)
SAMSEARCH (CZCEC> -- Assigns extents
Entry Point:
PAIR (CZCACS) -- Set and delete ABEND table
entry
SYSER (CEAIS)
CZCEC1
lnfut:
General Register 1 contains a
fainter to the following parameter list:
Minor system error
~ord
1
ABEND (CZACP)
End task and return control t.O terminal
Address of either the primary
allocation field (TDTSPO) or the
secondary allocation field
(TDTSP2) of the JFCB
Exits:
Normal - Register 15 contains 00.
Word 2
Address of the VTOC-DSCB
Error
Word 3
Address of the SDAT entry
Word 4
Address of a 12-word output area.
The first byte of the area contains a flag indicating the type
of request.
- Register 15 contains one of the
following codes:,
No space found
08
Unrecoverable I/O error
oc - Duplicate DS name found
10 - Volume not formatted properly
04 -
SYSER and ABEND occur when the JFCB (1u(c's
not indicate any mounted volume.
32
Output: General register 1 contains a
fainter to the input parameter list; the
list is unchanged, but the work area
pointed to by ~ord 4 now describes the
extents allocated.
If a standard user label (SUL) track was
requested, the output area has the following format:
and updates the DSCE.
UPDATE (described
below> ur-dates the DADSM-DSCBs to reflect
the allocation of extents. Return is then
rrade to the calling routine.
SEARCH SUBROUTINE:
Word 1
Count of extents allocated
Word 2
CCHH of SUL track
Word 3
CCHH of lower limit of first
extent
Word 4
CCHH of upper limit of first
extent
Words
CCH of lower and
other extents
up~er
limits of
OBTAIN reads the DADSM-
CSCB~one at a time, into a work area.
UNPACK (described later) examines tile
extents and coroputes the size of the request.
The request can be in terms of
tracks (in whicil case the allocation can
tegin at allY available track) or in tern:s
of cylinders (in which case only full
cylinders can be allocated).
The request
can te satisfied in one of three ways:
• An extent equal to the request.
• An extent larger than the request.
If no SUL track was requested, the output area has the following format:
Word 1
count of extents allocated
Word 2
CCRE of lower limit of first
extent
Word 3
CCRH of upper limit of first
extent
Words
4-11
CCHE of lower and upper limits of
other extents
Word 12
Unused
Modules Called:
OBTAIN/RETAIN (CZCFO) -- read/write formatS DADSM-DSCBs from/to external volume
macro (CZABQ) -- write error- message to
system operator
~TO
SYSER (CEAIS)
minor system error
ABEND CCZACP)
force abnormal end of task
Exits:
Normal - registers 15 contain 0, registers
0-14 are restored
Error
- register 15 contains 04, meaning
request cannot be satisfied; registers 0-14 are restored
Operation: The size of the requested area
is extracted from the JFCB. On a request
for track allocation, the number of tracks
requested is incremented by 1 if a standard
user labeling (SUL) track is requested; if
a SUL track is requested the ·SUL addedflag is set.
The SEARCH routine (described below)
then findS the extent or extents to satisfy
the request. The COMPUT routine (described
below) examines the extents to see if they
fill the request, sets appropriate pages,
•
combination of extents, each af which
is smaller than the request.
A
If an extent equal to the request is
found, the extent is placed in COMPUT's
work area, and. if no SUL track is
requested, exit is made.
If, however, a
SUL track is requested, the extents are
searched for a surplus track to be used as
a SUL track.
If the OSCB is chained,
OBTAIN reads in the continuation DSCBs and
they are searched for an available track.
If a SUL track is found, a successful
return is made.
If no such track is found,
a no-space-available return is made.
If an extent greater than the request is
found, it is saved until an extent equal to
the reqUEst, or a smaller extent that is
larger than the request is found.
If the
CSCB is chained, all continuation DSCBs in
the chain are searched.
If an extent equal
to the request is found, the procedure
described in the preceding paragraph is
followed.
If no ext:ent equal to the request is found during the search, the request is satisfied from the smallest extent
that is larger than the request.
The
excess space is subtracted from the extent
and the result is entered into the DSCB as
an update to the old extent.
If a SUL
track is requested, the procedure described
in the previous r~ragraph is followed.
During the search of the DSCBs, a pushdown list of extents smaller than the request is accumulated.
The list has five
entries, and only extents larger than the
smallest extent in the list are added.
When a new extent is added, the smallest is
deleted from the list. This list is abandoned as soon as an extent equal to or
larger than the request is found.
If no
such extent is found, space is allocated
from the extents in this list, combining
the smaller extents (with a maximum of
five) for the allocation.
;;ection 2:
External Storage Allocation
33
COMPUT SUBROUTINE: COMPUT determines it an
-extent can till the request ano sets the
appropriate flag accordingly.
It also
determines if the entire extent_ is a 110cated and updates the OSCR accordingly.
It a SUL track is req~ested, the output
parameter list pointer is incremented to
include the SUL track.
The requested allocation can be in terms of tracks or
cylinders.
• If a cylinder request al~J includes an
SUL request, COMPUT determines if there
are any available tracks preceding the
cylinder.
If there are, the SUL track
is made the first track of the extent.
If there are no preceding tracks, the
last track on the cylinder is used as
the SUL track.
If the entire extent
was allocated, its entry in the DSCB is
flagged for deletion by UPDATE; if only
part of the extent was allocated, the
DSCB entry is flagged for updating (Ly
UPDATE) to reflect the new limits of
the extent. If space in addition to a
SUL track was allocated, COMPUT places
the upper and lower limit CCHH of the
extent in the output parameter list,
and checks the input parameter list for
additional extent requests.
• If a track request also includes a SUL
track, the first available track in the
extent is used as the SUL track and its
CCHH is placed in the output parameter
list.
If the entire extent was allocated, the extent entry is flagged for
deletion. If the extent allocated was
only a SUL track, COMPUT examines the
next entry in the input list; if the
extent included other tracks in addition to this SUL track, the upper and
lower limit CCHHs are placed in the
output list before examining the next
input entry.
When all entries in the input list have
been processed, a count of extents allocated is placed in the output list, and the
gross available space indicator for the
volume is updated.
Exit is then made.
UPDATE SUBROUTINE:
UPDATE updates the
DADSM-DSCBs as extents are allocated.
OBTAIN is called to read in t.ne DSCBs if
they are not already in storage. The CCHHR
and chain address in the input list are
moved to the output list, if needed; otherwise, they are saved.
If the extent in the LADSM-DSCB equals
zero and UPDATE'S work area list is not
exhausted, SYSER is invoked.
If the extent
in the DADSM-DSCB is not zero, the available tracks in the DSCB extent is compared
to the original request for track allocation of the entry to UPDATE.
If the DSCB
34
extent available tracks is greater, SYSER
is invoked; if it is lesser, PACK is called
to move the DSCB extent to the output list.
If there are more extents in this DSCB, the
DSP [ointer is incremented, and the next
(~xtent in the DSCB is examined, as above.
If there are no more extents in the DSCB,
CBTAIN is called to read in the next DSCB,
and its Extents are examined as previously
described.
If, however, the number of available
tracks in the DSCB extent is equal to the
original request of the UPDATE entry, the
iollowing procedure is used.
PACK is used to move the UPDATE extent
to the output work area, if it is not
flagged "delete extent. W If the next entry
is a new entry to be added to the DSCB,
PACK is called to move it to the output
work areas; otherwise, the pointer to the
next UPDATE entry is incremented.
If there
are Iwre extents in this DSCB or if there
are no more UPDATE entries, the DSCB pointer is incremented, and the next extent in
the DSCB is examined. as described previously.
If there are no more extents in
the DSCB. OBTAIN is called to read in the
next DSCB, and its extents are examined.
If the extent in the DADSM-DSCB equals
zero and the UPDATE work area list finally
becoffies zero Call DSCBs have been
examined>, the output area is zeroed and
the hole count in the VTOC-DSCB is incremented by one, if the OSCB is not the first
in the chain. RETAIN is then used to write
the CADSM-DSCB.
If a hardware error occurs. the WTO
macro instruction is issued to inforrr the
operator; registers are restored, a return
code of 8 is set, and return is made. For
all the errors, SYSER is invoked, the WTO
macro instruction is issued to inform the
operator, registers are restored, a return
code of 04 is set, and return is If,ade.
PACK SUBROUTINE:
If the output-DSCB-full
flag is set, OBTAIN is called to get the
CCHHR for available continuation DSCBS, if
any.
RETAIN is called to write the DACSMCSCB. A CCHHR, if one was saved, is used
as the address of a new output DSCB. Allocated extents are moved to the out~ut DSCB.
If there are more extent slots in the output DSCB, PACK moves its pointer to the
next available slot and exits.
If there
are no extent slots in the output DSCB, the
output-DSCB-full flag is set, and exit is
[f;ade.
UNPACK SUBROUTINE:
If the next extent in
the CSCB is 0, the DSCB is scanned for a
chain address; if there is none, normal
exit is made; if there is one, an error
exit is taken.
If the next DSCB extent is not 0, it is
put in a work area; the count of extents in
the DSCB is incremented by one. The size
of the extent in tracks is computed or set
equal to the cylinder count, depending on
the type of request.
If there is room for
more extents in the DSCB, this process is
repeated. When all the extent fields of
the DSCB are filled, exit is made.
SCRATCH (CZCES)
SCRATCH deletes data set DSCBs on all
volumes of a specified data set and assimilates the external storage back into the
available space (the DADSM) on the volume.
(See Chart BC.)
Entry Point:
CZCES1
Input:
Register 1 contains a pOinter to a
word containing the address of a JFCB.
output:
1 - data set
Registers 0-14 are restored.
Exit to ABEND if a mounted volume cannot be
found. or if an error is encountered by
PUMP.
operation: The first volume field in the
JFCB is examined. If a JFCB chain field or
other than a data set volume is selected,
the next volume field in the JFCB is
selected until a data set volume is found.
If the selected volume is mounted but cannot be found. the next volume field in the
JFCB is selected.
If a mounted data set
volume is found but has already been ~ro
cessed, BUMP is called to mount the next
volume of the data set.
If a mounted
volUll,e is not found, the mounted-volurnefound indicator is set, the relative volume
number of the volume that was found is
saved, and the parameter list for BUMP is
initialized.
None
Assumptions: At least one of the volumes
indicated in the JFCB is mounted upon entry
to SCRATCH.
Modules Called:
BUMP (CZCAB) -- dismount and mount external
volume on same device
OBTAIN/RETAIN (CZCFO)
from/to external volume
read/write DSCBs
MERGESAM (CZCEE) -- merge physical sequential data set extents with DADSM extents
VMA (CZCGA) -- allocate and release virtual
storage
WTO macro (CZABQ) -- write error message to
system operator
SYSER (CEAIS>
minor system Error
ABEND (CZACP)
force abnormal end of task
PAIR (CZACS) -- set and delete ABEND Table
Entry
Exits:
Normal - register 15 contains 0; registers
0-14 are restored.
Error
TDTV8 = 1; TDTV9
not found
- register 15 contains 04, ffieaning
SCRATCH was unsuccessful on one or
more volumes as indicated in JFCB
volume fields, as follows:
TDTV8
0; TD'IV9
o
TDTV8
0; TDTV9
1
to system problems
successful
error due
If the VTOC is locked, time-slice end is
invoked until such time as the VTOC becomes
available. The VTOC lock byte is then set,
and OBTAIN is called to read in the first
data set CSCB (format-l) and the VTOC-DSCB.
GETMAIN is called to get storage for the
extent list, and the list is constructed
from the format-l DSCB.
The DSCB is then
zeroed out, and RETAIN is called to write
it back as a zero record; the VTOC hole
count is incremented by one.
If the data
set CSCB is chained, the continuation DSCBs
(format-3 or -0) are read in by OBTAIN,
zeroed out.• and written back as zero records by RETAIN. The VTOC hole count is
incremented by one for each such DSCB
returned.
MERGESAM is then called to return the
free extents to the available space on the
volume. FREEMAIN then releases the storage
used for the extent list. RETAIN writes
back the updated VTOC-DSCB, and the hole
count in the VTOC and the gross available
space indicator in the SDAT are updated.
The VTOC lock byte is reset and the next
volume field in the JFCB is examined. This
Frocess is repeated for each volume on
which the data set resides.
When all volumes have been processed.
SCRATCH returns with a return code as indicated under Exits.
EXTEND (CZCEX)
EXTEND is the external storage allocation routine that is called when additional
space on a direct access volume is required
for a data set. EXTEND makes the allocation and uFdates the VTOC, JFCB, and SDAT.
Secticn 2:
External storage Allocation
35
2.
This routine is called by SAM EOV when an
end-af-volume condition is encountered and
additional direct access space must be
allocated.
(See Chart BD.)
~nt.!:LPoints
:
CZCEX1. normal entry point.
CZCEX2, used only by SAM EOV when calling
EXTEND after having a new private volume
nounted.
Inpu!::
Register 1 contains a pointer to a
two-word parameter list.
Word 1
Address of JFCB
Word 2
Address of a word in which EXTEND
places output address.
If this
wcrd has a value of 1, FEOV has
been requested on current volume.
oU!:f>ut: The word pointed to by parameter
two contains an address painting to the
first OSCE containing the new extents, followed by a doubleword containing the CCRHR
address of the DSCE.
If extents are contained in a second DSCB, the word following
the doubleword contains the address of the
DSCB followed by its CCHHR.
If no such
OSCB exists, the address is zero.
Restrictions:
Each allocation is made from
one volume only; a maximum of 5 extents are
allocated to a physical sequential data
set.
Modules Called:
OBTAIN/RETAIN (CZCFO) -- read/write DSCBs
SAMSEARCH (CZCFC) -- assign extents to data
set
MTREQ (CZCAA) -- allocate additional private volume
SYSER (CEAIS)
minor system error
ABEND (CZACP)
force abnormal task end
Unable to obtain Format-l DSCB
from data set volume.
Cperation: The internal subroutine GET is
usej to l:.Et_rieve the last mounted volume in
the JFCB.
The TEST subroutine is used to
determine if there is sufficient space on
th-:- volurre.
It cheCKS the SDAT hole count;,
thE- gross space field, and the VTOC lock
cyte.
If the volurre satisfies the request,
TEST OBTAINs the VTOC-DSCB and calls
~A~SEARCH to allocate space for the requ~st.
OBTAIN reads in a data set DSeB
(Forwat-l) and lWRITE enters the newly
allocated extents into it. The 1WRITE
internal subroutine is used to write
extents in a OSCB when space allocation is
from an old volume.
2WRITE is used when
space allocation is from a new volume (see
telow). The VTOC-DSCB, JFCB, and SOAT are
updated, and a successful return is taken.
If thE last volume in the JFCB list does
not contain enough available space, EXTEND
will return to the calling program (SAMEOV)
with a return code of 08. SAM EOV then has
a new volume mounted.
EXTEND is then
entered at its secondary entry point
(CZCEX2); the newly mounted volume is then
the last volume in the JFCB list. The TEST
internal subroutine is used to determine if
the volurre is suitable.
If the volume does
not contain sufficient space, return is
made with a code of 08; if sufficient space
is available, the 2WRITE subroutine sets up
a new Forrrat-l OSCB and writes the extents.
Continuation OSCBs, if needed, are read and
written using OBTAIN and RETAIN respectively. The VTOC-DSCB, JFCB, and SDAT are
updated and return is made with a code of
O.
~~~KS
--
Give Back SAM Storage (CZCEG)
GIVBKS returns unused external storage
from physical sequential data sets to ESA
control and deletes the references tc the
storage from the format-l and -3 data set
DSCBs. GIVBKS is called only by SAM CLOSE.
(See Chart BE.)
PAIR (CZACS) -- ABEND deinterlock routine
CZCEG1
Exits:
Normal - Register 15 contains 00.
Register 15 contains 04 - New
VoluIfle.
Error
- Register 15 contains 08 available.
36
General Register 1 contains a
Fointer to this list:
Word 1
Address of the JFCB
Word 2
Address of extent list
No space
Exit to ABEND if either of these
conditions exists:
1.
!BEE!:
No mounted volumes in JFCB.
The extent list contains a 4-word entry
for each extent being returned; there can
te a maximum of 256 entries. The entry has
this format:
extent
sequence
number
Word 1
X'SO'
byte 1
byte 2
unused
byte 3
byte 4
Word 2
Lower cylinder and track CCHH of
the extent
Word 3
upper cylinder and track CCHH of
the extent
unused
Word 4
byte 1
byte 2
symbolic device
address of the
volume
Notes: The flag in byte 1 of Word 1
denotes the last extent in the list; this
byte contains binary 0, for all other
entries. The symbolic device address of
the volume in bytes 3 and 4 of Word 4 is
only in the first extent of the list.
These bytes are unused in all other
entries, since extents can be returned
only for one volume.
Qutput:
extents field of the format-l OSCE. This
figure must be increased by one if the
first extent is a label track, since that
extent is not included in the count.
A
list of extents is then constructed, the
manner in ~hich this is done depends on the
number of extents being returned.
More Than Three Extents:
If there are more
than three extents described, the space
required for format-3 DSCBs and the
MERGESAM list is computed as follows:
Every record read into the work area is
preceded by a marker doubleword to identify
end-of-record condition during the scan
process. consequently, 148 bytes of
storage are required for every reccrd (144
for the DSCB and four for the marker), containing up to thirteen extents, and eight
tytes are required for every extent to construct the MERGE SAl-' parameter list.
The
space-requirement computation is therefore:
bytes, where N is the
count of extents,
adjusted for label
track if necessary.
None
Restrictions:
Extents can be returned for
one volume only.
Modules Called:
OBTAIN/RETAIN (CZCFO) -- read/write formats
-1, -3, and -4 DSCBs from/to external
volume
MERGESAM (CZCEE) -- merge physical sequential data set extents with OADSM extents
VMA (CZCGA) -- allocate and release virtual
storage
SYSER (CEAIS)
minor system error
ABEND (CZACP)
force abnormal end of task
This space is obtained by use of GETMAIN.
The marker words are moved into the
area.
OBTAIN is called to bring in the
format-] DSCBs; a continuation character
indicates that there are more to be read
in.
The last extent in the last format-3
[SCE is located; then the last extent in
the list is found.
The index is set to the
end cf MERGESAM's list, to enter the DSCB
teing returned.
Three Extents:
If there are
not rrore than three extents, MERGESAM's
list index is set to the end of the PSECT
work area.
The last valid extent in the
tormat-l oseE is found, the number of
extents returned is counted, and an index
is set to the end of the input list. The
last extent in the last format-3 DSCB is
located; then the last extent in the list
is found.
The index is then set to the end
cf MERGES1\M's list to enter the OSCB being
returned.
~Q~Mor~Jh~n
Exits:
Normal - registers 0-14 are restored:
register 15 contains 0, meaning
GIVBKS successful or 04, meaning
GIVBKS successful and t.he entire
prime data set DSCB (format-I) has
been zeroed.
Error
- registers 0-14 are restored, register 15 contains OS, meaning
GIVBKS unsuccessful.
Operation: A JFCB and the symbolic device
address are passed as input; from this,
GIVERS finds the volume on which space is
to be returned. GIVBKS obtains the SDAT
pointer, sets the VTOC lock byte, and calls
OBTAIN to read the VTOC-DSCB and the format
-1 DSCB for the data set. The amount of
space required for reading continuation
DSCBs and constructing the extent list for
MERGESAM is computed from the number-of-
Each extent in the OSCB is zeroed out.
and the count of extents still to be
returned is decremented by one for each
extent.
This process is repeated until the
count of extents to be returned is zero
(i.e., there are no more extents to
return), or until the lower level CCHH of
the extent being returned does not comFare
with that of the extent in the OSCE (meaning that part of the extent was used and
:-;ection 2:
External Storage Allocation
37
the entry in the Dses must be changEd to
this condition). The nlimher of
pxtents in the format-l DseB is adjusted by
the number being returned. How~ver, when
only part of an extent is returned, the
resultant number of extents rr:ilst 1)(': i,lcremented by one.
~eflcct
When a continuation record
Ca format-3
useS) is zeroed out because of returned
extents, REI'AIN is called to write it back
as a zero record, and the hole count in the
v'TOC-DSCB is incremented by aD".
.If all
extents for a data s et on a ~ctrticular
volume are returned, the format-l DSeB is
also zerc~d; RETAIN is again used to write
it back as a format-O DSCB, and the hole
count in the VTOC-DSCB is incremented by
one.
The format-l DSCB is updated, and
RETAIN is called to write it back.
After all the data set DSCBs (frrmats-l
and -3) have been adjusted, MERGESAM is
called to merge the returned extents with
the available space on the volume.
RETAIN
is called to rewrite the VTOC-DSCB.
The
hole count indicator and gross available
space field in the SOAT are adjusted
according to the values in the VTOC-DSCB.
The VTOC lock-byte is reset, and FREEMAIN
is called to release work areas.
Return is
then made to SAM CLOSE.
MERGESAM (CZCEE)
MERGESAM returns extents from physical
sequential data sets passed to it by
SCRATCH or GIVBKS and merges them with the
DAOSM extents on their volume.
(See Chart
BF .)
Entry Point:
CZCEEl
Input:
Register 1 contains a feinter to
the following rarameter list:
Word 1
Address of an SOAT entry
Word 2
Pointer to a list of data set
extents
Word 3
Address of the VTOC DSCB
Word 4
Pointer to HW containing number of
extents
outl2ut:
None
Modules Called:
OBTAIN/RETAIN (CZCFO) -- read/write formatS DADSM-DSCBs from/to external volumes
WTO macro (CZABQ) -- write error messages
to system operator
SYSER (CEAIS) -- minor system error
38
;;r'l. al
- r(>o: c t<"r 15 contains 0;
0-1 1; are restored
5:,[~~.5"at: !~::.r.,:
registers
The list of ext.ents to be
n'Jl",d I;"j ,:h the OADSM extents is first
se': +~"d; ('ontiglJous extents are merged and
cf Extents is adjusted accordingly.
Th" extents are put into DADSM
:orm. OBTAIN reads the DADSM-DSCBs until
the first extent is within the range of the
CPDSM ext~nts in that DADSM-DSCB.
If the
pxtent cannot be merged with a DADSM
extent, it is inserted, and following
Extents are pushed down to make reom.
If
this causes the DADSM extents to overflow
the CADS~-DSCB, OBTAIN rpads an available
D:;CE t.O create a new DADSM-DSCB chained to
the oth~r with the overflow extent
lDserted.
The hole count (available DSCB
records) in the VTOC-DSCB is decremented by
Gnp.
If the list extent can be merged with
cne of the OADSM extents, the DADSM extent
is modified to reflect the list extent
also; no other action is required in this
case.
If, however, the list extent can be
rrerged with two of the DADSM extents, the
three extents are merged into one DADSM
extent and the following extents are
shifted up to fill the hole created.
The
last vacated DADSM extent field is zeroed
cut.
If, in this process a DADSM-DSCB
becomes em~ty, its key and data are zeroed
out (making it a zero DSCB), and RETAIN
writes it back; the hole count in the VTOCoseB is incremented by one. This procedure
is repeated for all extents in the list.
Lhpu~b~~
When the list of extents to be returned
is exhausted, the holes, if any, in the
CADSM-CSCB are filled.
OBTAIN is called
toread in DSCBs and the OADSM extents are
rushed uFo
RETAIN writes out the DSCBs
after the holes have been filled.
This
process continues until either there are no
more holes or until all DADSM-DSCEs have
teen processed.
Should a oseB become vacant as a result
of the push-up process, it is zeroed out,
and written back as a zero DSCB.
When the
extents in all the OADS~-DSCBs have been
processed, successful return is made.
GETAIN/RETAIN (CZCFO)
OETAIN/RETAIN is a reenterable, nonrecurSlve, privileged routine residing in
virtual storage. This routine is used fer
SAM format DSCBs with the exception of the
option for reading or writing volume
labels, which can be used with either VAM
cr SAM.
OETAIN reads the VTOC, obtains virtual
and builds an IORCB.
A channel
stor~ge,
progran: is constructed in the lORCB according to the type of OBTAIN requested. When
the IORCB is completed, an lOCAL is issued
followed by an internal check routine
(AWAIT if I/O is not complete). A posting
routine checks for errors when I/O is completed and links to SYSER if necessary.
If
successful, the data is moved from the
IORCE buffer to the user's input: area.
RETAIN writes one or more DSCBs, volume
labels. or end-of-file markeTS t.o specified
addresses. Virtual storage is assigned and
an lORCB constructed. j, channel program is
then developed and an lOCAL is executed.
When I/O is complete, a posting routine
checks for errors and links to SYSER if
necessary.
(See Chart BG.)
Entry Points:
CZCF01 - OBTAIN
CZCF02 - RETAIN
CZCFR1 - RETAIN
CZCF02.
writing DSCBs. When reading a
label, this field will point to
the CCHH of the track upon which
the label resides.
Note: When writing records,
fields 4 and 5 are repeated as
many times as the count in word
2.
Word 5
~
Word 2
1
2
3
"
5
Same entry point as
or
pointer to a packed word that
is arranged as follows:
A
bits 8-15 - used type of RETAIN
request.
bits 16-31 - count of RETAIN
requests; otherwise binary zeros.
Word 4
A painter to the input area for
the RETAIN request being made.
A pointer to the symbolic device
address entry table (SDAT) for
the volume containing the VTOC
or data set. This field is a
32-bit virtual storage address.
hits 0-7 - Type of OBTAIN request desired. The type is
designated by a binary
number as indicated in
Table 1. The type is designated by a binary number
as indicated in the 'RETAIN
REQUEST' section.
Word 3
bength
140 hytes
101 bytes
244 bytes
5 byt.es
10 bytes
80 bytes
o
Input: General register 1 contains a
pointer to the parameter list:
Word 1
painter to the input area for
the OBTAIN request heing made or
t.he address of the reccrd to be
written.
II
A pointer to a field containing
a data set key or a label key
when requesting a Tyre 1, 2, or
5 OBTAIN. When this field does
not apply to the function
requested, it must be defined
hut can he left blank.
The data
set key is assumed to be q4
bytes in length, and a label key
is assumed to tc 4 bytes in
length.
A pointer to a CCHHR when performing direct reads for formats
3, 5, B, and D DSCBs, 0r when
Length
140 bytes
84 bytes
user specified
~
o
1
2
Note: OBTAIN and RETAIN use identical
parameter lists.
Output:
Register 1 points to the input
paralLeter list.
Restrictions:
1. The writing of DSCBs, labels, and endof-file marks cannot be intermixed.
2.
OBTAIN/RETAIN does not set the interlock byte in the symbolic device allocation table (SDAT). To prevent concurrent references to a particular
VTOC, the user must test and set the
lock byte.
Modules Called:
lOCAL (CEAH16) -- execute request for I/O.
AWAIT (CEAP7) --
wait~
for I/O completion.
VMA (CZCGA) -- GETMAIN for the virtual
storage used to construct the IORCB.
RESET (CEAAH)
re-enable an I/O device.
SYSER (CEAIS)
entered when request type
or parameter is invalid.
ERRORRETRY (CZCRH) -- direct access error
retries.
VMSDR (CZCRY) -recording.
Section 2:
V~
statistical data
External Storage Allocation
39
;:;;xits:
Normal - register 15 contains nu.
Error - register 15 ccntai;;,:; on of the
following codes:
write error CI\ETj\l;'~i
OSCB record not found
(OBTAIN)
08 - hardware error Cl)llf"l i =_ i(l~l
(OBTAIN)
08 - error in input pard[l~ete.t: Ii!:.:.
(RETAIN)
oc - unit exception
;B'IldN)
10 - intervention reqllir('cl (urn'!. .! N
type 5)
04 04 -
For both OBTAIN dr:d Bl:.'lAI N
requests, upon entry a data control tlcck
(DeB), a data extent block (DEB.l, and aD
Ope;-~tion:
event control block (ECB) are constructed
in order to maintain compatible linkage
with rommon system hardware error routines
'.mdLbe t.a sk monitor.
A page of virtual
,;tc£age h; allocatedt.hrough GETf'lAIN. and
~n initialized copy of an input/output reQuest control block (IORCB) is moved into a
re·:e:cved section of the page.
Thi~ co~y of the IORCB is then ufdated
to p2rform the requested read function.
': L'e' loca ticn of the symboli c device address
and th~ location of the VTOC are computed,
fctchei1, and placed in the IORCB.
A channel rrogram is developed within the lCRCB
as rEquired to perfo1.Tn one of the types of
requ2st shown in Figure 4.
r----T-------------T---------··~---------------------------------------------------------,
I Type! F,lliction
I Input ArEa I DescrlptioJ;
I
.----+-------------+----------t---------------------------------------------------------~
! 0
I
I Direct
I Reference
I DSCB
!
I!
I
I
I
I
I
I
1140 bytes IThis re'juest is initiated to read FOrmat 3, ~, 5, B, and I
I
Ie DSCBs where the ]. 0(; ical address of t.he record is known I
I
Ifrom a previous operation such as Type 2 (below).
The
I
I
laddrec;s of the rpad is rrovided to the OBTAIN routine in I
I
I the forUl CCHHR. I, search for an equal ID is performed. I
I
1',4her: the ID is fO:.Jnd, t.he key and data fields are read
I
I
: (140
!
bytes.).
~----+-------------+----------+---------------------------------------------------------~
I 1 jSearch for
I
I DSCE key and
I
I read count
I
I
I!
I
I
I
I
I
I
I
I
1101 bytes IThis request is initlated to read type 1 and A OSCBs.
Ani
I
lin-channel search is performed on a key, which is the
I
I
I dsname of t.he data set whose DSCB is being searched for. I
I
!wtpn an equal k~y is found, the catalog data field (96
I
I
!bytes) is read into the IORCS buffer area. The count
I
I
Ifield (5 bytes) is then read into the buffer area to
I
I
loccupy the tyte of the data field.
The count field is
I
I
i decl. errent e(~ by OJ,f, to ad just it to the correct address of I
l i t h e data fielJ. on files.
I
.----+-------------+----------+---------------------------------------------------------~
ISearch for
1244 bytes !This request i~ the same as type 1 above. except that thel
I 2
I
I
I
I
IDSCB -I Read count
I and Read
IOSCB
I
i
I
I
IVTOC-DSCB is also read and [laced in the area contiguous I
Ito the right-hand byte of the count field starting cn thel
I next fullword l::;cund2,ry.
I
I
I
~----t-------------t----------+---------------------------------------------------------~
I 3
I
I
I
Isearch for
15 bytes
lone available\
I DSCB
I
I
I
jUnassigned DSCEs contain a field of binary zeros.
This
I
I request causes an in-channel search on a field of binary I
Izeros.
The count field is read in the form CCHHR and is I
I placed in the input area.
I
t----t--------------t---------t----------------------------------------------------------~
I 4
I Search for
110 bytes
IThis request perforrrs the same functions as types above
I
I
I
I
I
\two availablel
I
I DSCBs
I
I
I
I
lexcept that i t ,iearches for two available DSCBs.
The
I first address is placed in the first five bytes of the
linput area; the second address is placed in the second
I five bytes.
I
I
I
I
t----+-------------+--------·--+------------------------------------------.---------------~
I 5
IVolume/User
180 bytes
IThis request initiates a track search for a data set or
I
I volume label key.
When an equal is found on the key, the I
Idata field is read.
If an end-of-file is detected on thel
I
I
Iread, a code is placed in register 15 and control is
I
I
I
I
Ireturned to the user.
This request can be used for eith-I
Il ____ I _____________ I __________ ler
VAM or SAM data sets.- - - - - - - ___________________________ JI
_______________________
I
I
I
Ilabel read
I
~
Figure
40
I
I
~
4.
~
Types of OBTAIN Requests
The initial DADSM-DSCB (the DseB used to
define available extents) can be accessed
directly by incrementing the record address
of the VTOC.
After the 10RCB has been bU~llt. the
lOCAL SVC is executed, followed by the
OBTAIN routine and an AWAIT.
When 1/0 is
complete, the task monitor links to OBTAIN
posting, which checks for errors.
If no
errors occurred, posting moves the data
from the IORCB buffer drEd (now located in
the ISA) to the user's inr~t area.
If an
error occurred, postJ.n9 1 inks to common
system error routines.
l':),;t: D']. however.,
selects out end-of-cylinder and end-of-file
for further processing by OBTAIN dnd the
user.
If the IORNP or the IORPG flag in
the IORCP has been set by either the HOLDI
DROP facility, paging error rCC,)Vt'ry Elrocedures, or the Purge I/U facility to indicate that no path is available, OBTAIN posting will post the 1/0 action a~ incomplete
and intercepted. When posting completes,
it returns control to the user with an
indicative code in register 15, or updates
the IORCB for another search if the VTOC
exceeds a cylinder and end-of-cylinder was
detected.
RETAIN REQUEST
Types of RETAIN requests are:
~
o
InFut
Function Area
DescEipti~.!:J
This request is iniWRITE
140
DSCB
bytes tiated to write one or
more DSCBs. Available
location found by type3 OBTAIN
1
WRITE
LABEL
84
To write a user label
bytes or standard label on a
volume -- key must be
included
2
EOF
markers
user
specified
When the initialized IORCB, which contains an appropriate channel program to
write the DSCB or label, is moved into a
reserved section of the page allocated
through GETMAIN, the symbolic device
address is obtained from the symbolic
device address table
minor system error.
ABEND (CZACP)
task.
force acnormal End of
ROUTINES USED wITH VAM FORMAT VOLUMES
FINDEXPG (CZCEL)
Exits:
Normal
Error
register 15 contains 00:
ters 0-14 are restored.
regis-
- register 15 contains 04; RENAME
was unsuccessful on one or more
volumes as indicated by flags:
TDTV8 = 0 and TDTV9
Successful.
=
0 -
TDTV8 = 0 and TDTV9 = 1 - error
due to system problems.
TDTV8 = 1 and TDTV9
not found.
=
FINDEXPG is a reentrant, nonrecursive,
rrivileged routine, which resides in virtual storage. This routine is entered when
rages of external storage are required for
a data set.
(See Chart BI.)
Entry Point:
CZCELl -- Normal entry.
Type I linkage.
1nput: Register 1 contains a pointer to a
rararreter list:
hard 1
JFCB address
Word 2
Address of the receiving area
Word 3
Address of a word containing the
number of pages required (negative
if WRITDSCB is not to be called)
0 - data set
TDTV8 = 1 and TDTV9 = 1 - new data
set name already exists.
Registers 0-14 are restored.
Operation: This routine uses OBTAIN to
search the VTOC to determine if there is
already a DSCB with the new data name and
to retrieve the DSCB with the data set name
to be changed.
If a DSCB with the new data
42
Output:
Each rage aSSigned will be indicated by one word in the receiving area of
parameter two, in the following forrrat.
Bits 0-15 - Relative Volume Nurrber
Bits 16-31 - Relative page Number
Assumptions: The format of the volume list
for private data sets is exactly the same
as the PVT.
Modules Called:
VOLSRCH (CZCEH) -- To find suitable volumes
frow which to allocate space.
RELEXPG (CZCEN) -- To return assigned pages
and adjust user resource count if ~ntire
allocation cannot be wade.
WRITDSCB (CZCEW) -- To update the DSCB
chain.
&,A LOCK (CZCEJ) -- To lock and unlock PAT
pages.
RCR (Macro) -- Used in accounting for user
public resources.
READWRIT (CZCEM) -- To write PAT pages.
Exits!
Normal - Register 15 contains 00.
Error
- Register 15 contains one of the
following codes:
04
Insufficient space.
08
Resource limits exceeded.
The following errors cause an ABEND.
1.
Error writing a PAT page
2.
Illegal device code in the SDAT
Operation: The JFCB address, the address
of a receiving area, and the address of the
number of pages required are presented to
the routine.
If the data set is public.
FINDEXPG passes this inforrration to the
Resource Control Routine which determines
if the request is allowed, or if the user
has already reached his resource limits.
If RCR makes an error return, FINDEXPG
returns to the calling routine with an
indicator (08) in GR 15.
needed, the PAT is scanned for more zero
entries, as above.
When either the allocation is complete, or there are no more
unallocated slots in the PAT, the PAT page
is written out via READWRIT and the lock
released.
In the second case, the appropriate PAM
tit in the SDAT is set. to indicate no
further space.
If there are more PAT pages
for this volume, they are inspected in
turn. When the space request cannot be
satisfied from the current volume, VOLSRCH
is called at the second entry point to find
another volume.
If VOLSRCH is unable to find a suitable
volume, RELEXPG will be called to release
any pages already aSSigned and the callers
receiving area will be zeroed out.
If the
data set is public, RCR will be called to
delete those pages requested but not
assigned, the return code will be set to
(04) and the following message will te sent
to the operator:
ZCEL - NO MORE DATA PAGES AVAILABLE ON
PUBLIC VOLS
The following message will then be written to the user:
ZCEL - INSUFFICIENT SPACE TO BUILD DATA
SET (data set name)
When the request has teen satisfied,
control is returned to the calling routine
with GR15 zeroed, to indicate success.
Just before a successful return. WRITDSCB
.. ill be called to update the DSCB chain,
unless the word containing the number of
required pages is negative.
ACDDSCB (CZCElO
ACDDSCB is a reentrant, nonrecursive,
privileged routine, residing in virtual
rreocory.
ACDDSCB is called by ADDCAT,
WRITDSCB, and DSCBREC to assign space for a
new forwat E or format F DSCB.
(See Chart
EJ. )
otherwise, VOLSRCH is called to locate a
volume from which allocation may be made.
When a suitable volume has teen located,
the PAT is obtained, by using the PVMA in
the SDAT, and locked. The PAT is scanned
for invalid codes.
If one is found, a message is sent either to the operator if the
volume is public or to the user if the
volume is private.
Then VOI,SRCH is called
for a new volume.
The PAT is next
inspected for unallocated pdges.
As one is
iound, the user count is incremented in the
PAT entry for this page and a word entry,
consisting of relative volurr,e number and
relative page number is stored in the
user's receiving area, the address of which
is an input parameter.
If more pages are
Entry Points:
Input:
list:
CZCEKl -- Normal entry.
Register 1 points to a parameter
Word 1
Address of the JFCB associated
with the VAM data set for which
the DSCB assignment is to be made.
Word 2
Address of the volume table associated with this data set.
Word 3
Address of a one-word return area.
Word 4
Address of a control word that has
the following format:
:iection 2:
External Storage Allocation
43
- X'SO' if call i~ for a format E OSCB
X'OO' if call is for a format F OSCE
Bits 8-15 - unused
Bits 16-31 - The RVN of the current DSCE
page if the call is for a
format F OSCB.
Bits
0-7
(Note:
If the call is from
DSCBREC (CZCEF) for a format E
DSCB, word 4 will be set to zero.)
3.
The address of a one-word return area.
In addition, if the call is to request
space for a format F DSCB, it is assumed
that a DseB Fage is being used by the calling routine and that the device containing
this DSCB page is locked.
In this case a
fourth parameter is necessary.
This fourth
Farameter will be the address of a word
containing the RVN of the locked device.
The calling routine will signify a request
for a format E DSCE by making the fourth
j:arameter zero.
Workpage CZCOZ will contain the new DSCB
leage.
To find space for a format F DSCB,
ADDDSCB _ill scan first the OSCB page and
then the volume on which the format E OSCB
resides.
If there are no usable pages on
that vclume, or if the call is for a format
E DSCB, ADDDSCB will obtain a volume to
search by calling VOLSRCH (CZCEH). VOLSRCH
will select a suitable volume, place its
relative volume number in an address supplied by AODDSCB, set a successful return
code, and return to ADDDSCB.
Assumptions:
If the call is for a format F
DSCB, the device indicated by fdrameter
four is assumed locked and will be used,
then left locked upon return. The new
device obtained from VOLSRCH will be locked
and left locked, and the pointer of parameter four will be changed to point to this
new device.
If VOLSRCH returns with an unsuccessful
return code (no suitable volume found),
ADDDSCB will call VOLSRCH again at the initial enTry (CZCEHl) and this time will
attempt to allocate OSCB space frorr. any
continuation slots.
If, in this attempt,
VOLSRCH again returns unsuccessfully,
AODOSC~ will call ABEND with a message to
the user.
output:
A pointer to the newly assigned
OSCE will be placed in the return area
whose address is the third input parameter.
The pointer is in the form:
Bits
0-3 - DSCB slot number
4-15 - Relative Volume Nwrber
16-31 - Page numter
Modules Called:
VOLSRCH (CZCEH) -- To find suitable volumes
from which to allocate space.
ESA LOCK (CZCEJ) -- To unlock or lock PAT
ijag es .
READWRIT (CZCEM) -- To read and write DSCB
pages and to write the PAT.
Exits:
Normal - Register 15 contains 00.
as described.
hrro~
- 1.
2.
3.
Output
No OSCB sface available.
ABEND.
Error reading or writing DSCB
or PAT.
Message to operator.
Illegal device code.
ABEND.
Operation: ADDDSCB requires that, on
entry, general register t contain a pointer
to a parameter list containing:
1.
The address of the JFCB associated
with the VAM data set for which the
OSCB assignment is to be made;
2.
The address of the volume table associated with this data set;
44
Upon a successful return, the PAT page
of the returned volume is checked for invalid codes.
If one is found, a message is
sent to the user if the volume is private
or to the operator if the volume is public.
An attempt is made to get another volume.
If no invalid code is found, VOLSRCH return
indicators are checked for one of two possible cases:
(a) space exists on an
unfilled OSCB page, or (b) all OSCB pages
j:resently assigned are full but unassigned
j:ages exist from which a new OSCB page may
be allocated. These two cases are
described below.
availatle.
If no available slots are found in this DseB page, the
PAT entry is set to '83' to ind"lCdte a completely full page and the search for another page continues.
When an available slot
is found, it is assigned by setting bits
6-7 of DSETYP. The DSCB is checksummed
and, if call is for a format_ E DSCB, wri tten back to external storage via CZCEM.
If
tne FAT page has been changed, it is written back to external storage via CZCEM.
The new DSCB assignment is IBssed back to
the calling module as noted in the previous
paragraph.
If the calling program is
ADDCAT (CZCFA), any devices locked by
AODOSCB will be unlocked before returning.
(Case b) SDAT PST indicates all OSCB
[Jiiges full but unassigIHcd pages exist.
When VOLSRCH returns a volume pointer
and indicates a PAT page from whch a new
DSCB page may be assigned, ADDCSCB searches
that PAT page and, upon finding an unasSigned page, assigns that page as a DSCB
page by setting the PAT entry to 'BO'. The
SLAT PST DAM (DSCE Availability Mask) is
uf!dated to reflect this newly assigned OSCB
page. The new page is read into workpage
CZCOZ.
All DSCB slots on the page are made
available for future assigr~ent by setting
them to zero.
OSCB assignroent then continues as described in CdS~ (a) for a newly
assigned DSCE page.
If no unassigned pages are available for
DSCB assignment, the PST is updated to
reflect the fact that no more space is
available on the volume page described by
the PAT page under examination. AODDSCB
will then examine the next PAT ~age (if
more than one exist) for the volume and
repeat the above process.
If no space can
be found on this volume, VOLSRCH is reentered at its second entry point (CZCEH2),
and a new volume is obtained. The entire
procedure is then repeated.
~OLSRCH
(CZCEH)
VOLSRCH is a privileged, reentrant nonrecursive routine which is called by
ADDDSCE and FINDEXPG t:o determine the most
suitable volume in a given list, pul:;lic or
rrivate. from which to allocate space.
(See Chart EK.)
Entry Points:
CZCEHl
For initial call.
CZCEH2 -- For sul:;sequent calls.
lQBut:
Register 1 contains a pointer to a
rararreter 1 ist:
Word 1
Address of control word.
(Control
word format is as follows:
Byte 0 - X'OO' DAM, PAM search
- X'80' PAM search only
- X'CO' Primary allocation
set by OPENVAM
(CZCOJ\)
Bytes 1-3 - Number of pages
requested by FINf,EXPG
(CZCEL)i Not used when
Byte 0 is X'OO'.)
word 2
JFCB adress.
Word 3
Address of the halfword return
slot for the relative
volume number.
Word 4
Address of the volume list.
gut put :
The relative volume number of the
selected volume will be placed in the halfword which is addressed by word 3 of the
input fararneter list. Register 1 contains
OJ pointer t.O the input parameter list.
Restrictions:
The second entry point
(CZCEH2) may be entered only after the
first (CZCEH1) has been entered.
The task will SYSER and ABEND if the
data set is public and there are no volumes
in the PVT.
Modules Called:
SYSER (CEAIS)
Full VM dump.
ABEND (CZACP)
Terminate task and return
control to the terminal.
Interlock (CZCOH) -- To lock RESTBL.
Release Interlock (CZCOI) -- To unlock
RESTBL.
Exi t.s:
Normal - Register 15 contains 00.
Error
- Register 15 contains one of the
following codes:
:;ect ion 2:
External Storage Allocation
45
04
08
No space on dny volume.
CZCEH2 called out of turn.
Operation: The first input parameter is
the address of a control byte which indicates the type of search required.
If the
control byte contains an '80', VOLSRCH will
examine the PAM bits of each volume to find
one containing available data pages.
If
the control byte is '00', VOLSRCH will test
each volume. examining first the DAM bits
to find one containing an available DSCB
page.
If the DAM bits indica e that no
such page is available, the PAM is then
examined to see if a data page is present
which may be assigned as a DSCB page.
If
one is, the control byte is changed to '80'
to inform the calling routine that such is
the case.
If there are none, the next
volume is then examined.
If the second bit
of the control byte is on, VOLSRCH is being
called for primary allocation and the
RESTBLE will not be searched to determine
on which volumes the data set is currently
located.
Whenever a suitable volume is found, the
relative volume nurrber is placed in the
halfword return slot whose address is the
third input parameter.
If no suitable
volume is found, return will be rr,ade to the
calling routine with general register 15
set to • 04 t •
For a private new data set, the volume
list is examined for the device having the
most available space.
For an existing private data set, the search begins with the
volume containing the format E OSCB, and
cycles from the last in the list to the
first.
For public data sets, the volume entries
in the JFCB will be examined for valid,
Kounted, public volumes.
If any are found,
the search will be restricted to them.
If
none are found in the JFCB, the public
volume table will be searched.
For public data sets, the first volume
of the PVT is reserved for systerr. use and
will be examined last.
For a new public
data set, a search will be made for the
device having the most available space.
For existing public data sets, the search
begins with the volume containing the format E DSCB.
have been inhibited. data sets will not be
allowed to expand to more than one device.
If an old data set is already multivolume,
it will be restricted to those volumes on
which it already exists.
RELEXPG (CZCEN>
RELEXPG is a reentrant, nonrecursive,
privileged routine residing in virtual
storage, which is called by CLOSEVAM.
DELVAM, ~RITDSCB. DSCBREC, and FINDEXPG
when external pages and DSCBs are to be
rrade available.
(See Chart BL.>
Entry Point: CZCEN1 -- Normal entry by
type I linkage.
InEut:
Register 1 points to the following
parameter list:
Word 1
JFCB address
Word 2
Address of the list of entries to
be released.
Word 3
Address of a word containing the
number of entries in the list.
The format of entries in the release
list is:
r-------T-------------------T-------------,
I
I
1External Page 1
Number
I
IField AIRelative Volume No.1
t-------+-------------------+-------------~
10
314
15116
311J
l _______
___________________
_____________
~
~
The release list must be aligned on a
fullword boundary.
Field A contains a DSCB
slot number when a DSCB is being released.
Output:
Relevant PAT entries and DSCB
pages will be changed to reflect the
requested releases.
AssurrEtion: Private data sets will have a
volume list in exactly the same format as
the PVT.
!'odules Called:
CZCOy -- ~orkpage for reading OSCB pages.
RCR -- To credit user with pages being
returned.
When the data set is duplexed, the
volumes containing the duplexed copy are
not examined unless there is no space on
any other public volume, including the system volume.
ESA LOCK (CZCEJ) -- To lock and unlock
devices.
If the calling routine needs more than
one volume, the second entry (CZCEH2)
should be called.
VOLSRCH will then continue the search.
If multivolume data sets
Exits:
Normal - Register 15 contains 00.
46
READWRIT (CZCEM) -- To read and write DSCB
pages and to write PAT pages.
Error
- None.
Operation: The routine L; entered with the
address of the JFCB, the address of the
~ist of entries to be released (these can
be mixed data pages and DSCBs), and the
address of a word containing the number of
entries in the release list.
~hese last
two parameters are set up as indices and a
loop count and t_he first entry in the
release list is obtained.
is set to CO, thus making it an error
entry.
As rages are made available, PVTAVS, the
number of available pages is updated.
The relative volume number is stored in
a comparison field so that the current PAT
page can be used to reledse consecutive
entries for the same relative volume before
being rewritten. The relative VOIUllH'; number is used to index the volume list; the
SOA is extracted and used to calculate the
appropriate SLAT entry.
Processing continues by incrementing
indices and decrementing the count of
Entries in the release list. When more
entries are to be released, the relative
volume number of the next entry is compared
with that of the previous entry.
If these
are equal, the routine will loop to [rocess
this entry. Otherwise, any altered PAT
pages must be rewritten using READWRIT and
this relative volume number saved. The
routine then loops to use the relative
volurre number as an index to the volume
list.
The external page nwnber of the entry in
t.he release list is examined for validity
ty type of device and set to modulo 4096 to
get the relative PAT page and entry within
the page. The device is locked and the
virtual memory address of the PAT obtained
using the PVMA field in the SOAT.
When all entries have been processed,
the altered PAT pages on the current volume
are written using READWRIT. The Resource
Control Routine is called to adjust the
resource limits when any public pages are
returned. RELEXPG then returns to the
calling routine.
The PAT is scanned for invalid codes.
If one is found, a message is sent either
to the user if the volume is private or to
the operator if the volurre is Fublic.
If
the PAT is invalid, it will not be changed
or written.
The PAT entry is examined.
If it is 80,
82, or 83 (a DSCB page) the proper DSCB
fCage, if not already in core, will be read
in. The indicated slot will be released
and the PAT entry changed, if necessary,
according to the number of slots still
assigned.
If no slots are left assigned,
the PAT entry will be set to zero, making
the entire page available, and the appropriate PAM bit set to show at least one
available page entry. Otherwise, the relevant DAM bit will be set to show at least
one DSCB available.
When a data page is being released, the
count of users is decremented.
If the
resulting count is non-zero, the page cannot be released. Other~ise, the PAM bit is
set to show at least one available page
entry in this PAT page.
If the PAT entry of the page to be
released is 'cO', an errcr entry, the relocation field will be searched to find the
relocated page number.
If none is found,
SYSER 002 is called and the program continues with the next entry to be released.
A special feature of RELEXPG allows
external PAT page entries to be rrarked as
When a data page is being
error pages.
released, bit 1 of the release entry is
examined.
If it is en, the PAT page entry
DSCBREC is a reentrant, nonrecursive,
routine residing in virtual
memory.
This routine is used to recover as
far as possicle from a checksum error.
(See Chart BM.)
~rivileged
g~£2ints:
CZCEFl - Normal entry via
type I linkage.
l~ut:
Register 1 contains a pointer to
the follewing rarameter list:
Io :
ESA LOCK (CZCEJ) -- To lock and unlock
devices.
ZCEF - RECOVERY (SOCCESSfUL.XXXX)/
(IMPOSSIBLE. ALL) PAGES LO~;T
~EADWR1~
(CZCE~) -- To read and write CSCB
fages and to write the PAT.
To the user:
Exits:
Normal - Register 15 contains 00.
ZCEF - CHECKSUM ERROR ON SLOT XX, FAGE
XXXX, R.V.N.
XX, V.S.N. XXXXXX
Error
- 1-
ZCEF - RECOVERY (SOCCESSFUL.XXXX)/
(IMPOSSIELE.ALL) PAGES LOST
2.
3.
3.
To the user if recovery was not
successful:
ZCEF - CHECKSUM ERR HAS CAUSED DELETION OF DATA SET (d.s.name)
Error reading DSCB page.
AEEND.
Error writing CSCE page or
PAT.
ABEND.
Unrecoveratle checksulT error.
ABEND.
Inrut parameters for WRITr::SCE
are the address of the RESTBL and the
address of a contrcl byte ~hich is -FF for
a new data set and '00' for an old one.
If
the data set is new, two additional rarameters, the address of the JFCB dnd the DCB
are al~o rEquired.
~terat.ion:
ft
WRITDSCB
(CZCE~)
~RITDSCB is a reentrant, nonrecursive,
privileged routine which resides in virtual
memory. ~RITOSCB is called by OPENVAM,
CLOSEVAM. and FINOEXPG to construct a oseB
chain frow the RESTBL, JFCB, DCB, and PVT.
(See Chart BN.)
Entry Points:
I linkage.
Input:
~ointer
~ord
1
Word 2
CZCE~l
- Nonnal entry.
Type
General Register 1 contains a
to the parameter list:
Address of the RESTBL reader
Address of a control tyte
bits 0-3 -
'F' - new data set
'0' - old data set
bits 4-7 -
'F' - write all rages in
RESTBL
'0' - write only pages in use
Word 3
Address of the JFCB
word 4
Address of the DCB
After initial housekeeping activities.
the rage containing the format E OSCB will
be read in using subroutine 1.
If a checksurr error is encountered and the data set
is not being shared, DSCBREC will be called
to provide a new format E OSCB.
If the
return from DSCBREC indicates an unsuccessful recovery or if the data set is shared.
WRI'ICSCB will and ABEND with appropriate
rr€ssages.
Once a good forrrat E OSCB has been read
in, the rage totals in the OSCE header will
be u[dated frorr the RESTBL header. At this
time also, if the data set is not partitioned the OSCE header will be filled in
from inforrration in the JFCB and DCB.
If the data set resides on private
volurres, the number of volumes in the DSCB
will be checked against the nuwber of private vclurres.
If they are equal or if the
volume count is equal to one, no vclume
updating is required.
If they are not
equal, the DSCB volume count will be
updated froIT t_he numter in the PVT. Volume
Secticn 2:
External Storage Allocation
49
IDs from the PVT will then be rroved into
the format E OSeB.
If more DSCBs are
required, the next DseB in the chain will
be used.
If there is no entry in the chain
field, subroutine 3 will be called to get a
new one.
This will continue until all
volume IDs have been entered.
Following any volume updating, WRITDSCB
will begin updating page entries in the
DSCB f ron t.he RESTBL, oct aining any additionally needed DSCBs as in the volume
updating procedure. Whenever a OSCB has
been filled and its chain field updated,
its checksum will be computed and stored
using sUbroutine 2. When all extents have
been moved into the oseE chain, ilny
unfilled entry space in the last DSCB will
be set to zero and any unused DSCBs will be
released via PELEXPG.
subroutine 1: This subroutine will read
in the page containing the indicated DSCB
and set the base register for that DSCB.
The checksum will then be tested and a
branch will be made accordingly to either
the normal or the error return.
Subroutine 2: This subroutine has two
entrles. When the first entry is used,
OSETYP will be checked to see if this is a
format E DSCB. If it is not, DSETYP will
be set to indicate a format F DSCB. The
checksum value for the DSCE will then be
computed and placed in the checksum field
(OSECKS). When the second entry is used,
only the checksurrming will be done.
Subroutine 3:
This sUbroutine will
search tne currently held DSCE page in
CZCOY for a usable DSCb slot.
If one is
found, it will be assigned and the PAT
entry updated as necessary.
If one is not
found, the PAT entry will be set to indicate a full page and ArDDSCB will be called
to furnish a new OSCB slot. The value
returned from AOODSCB will be rlaced in the
chain field (DSECHN) of the previous DSCB,
that OSCB will be checksummed via Subroutine 2, and the old OSCB page will be written out. The new DSCB page, placed in
CZCOZ by ADODSCB, will be transferred to
CZCOY.
VAMINIT (CZCEQ)
VAMINIT is a privileged, reentrant, nonrecursive routine residing in virtual
meffiory. This routine initializes private
VAM volumes when they are entered into the
system.
(See Chart EO.)
Entry Point:
CZCEQ1 via type I linkage.
InFut:
Register 1 contains the address of
the SOAT entry for the volume to be
initialized.
50
CutFut: The tables associated with the
volune are updated.
Restriction: VA~INIT must not be invoked
for a putlic volume.
~odules Called:
SETXP (CEAH7)
tual storage.
To read the PAT into vir-
GETMAIN (CZCGA2) -- To get the virtual
storage for the PAT.
CBTAIN (CZCF01) -- To read the volume
label.
ABEND (CZACP) -- Returns control to the
terminal.
Exits:
Normal - Register 15 contains 00.
Error
- ABEND
ABEND
Routine was invoked for a
public volume.
Device code other than
2311 or 2314.
0Feration: VAMINIT is entered with Type I
linkage and is passed the following
pararreter:
Address of SDAT entry
After a normal initialization procedure
(storing registers, setting up base registers, etc.), VAMINIT will check SCAT location SCAPP to determine whether this is a
priVate or public volume.
If public,
VAMINIT will invoke the ABEND procedure
with an appropriate error nessage.
If private, VAMINIT will have the volume
label read into virtual memory by invoking
the OBTAIN routine.
From inforrraticn in
the volurre label VAMINIT will then enter
the volume IL and the PAT origin (PTC) in
thE SDAT.
VAMINIT will then invokE the GETMAIN
routine to obtain virtual memory for the
Faye assignment table (PAT).
If the device
is a 2311, PAT will be one page in length;
if 2314, two pages in length. The PAT sumrrary mask (PSM) in the SOAT is set up and
VA~I~IT invokes the SETXP routine to read
in the PAT. After reading in the PAT,
VAMINIT will set the VAM/SAM flag (SDAAM)
to 0 and set up the PAT Virtual Menory
Address (PVMA).
VANINIT will verify that the PAT pages
read in by SETXP are valid.
If they are
not valid, a message will be written to the
system log and to the user, and the invalid
fAT tit will he set in the SDA.
VAMINIT will then return to the routine
which called it via Tyre I return linkage.
rtEADWRIT (CZCEM)
READWRIT is a reentrant, nonrecursive,
routine residing in virtual
storage.
It is used to read DSCB rages
into virtual storage or write DSCE or PAT
pages to external storage.
(See Chart BP.)
~rivileged
Entry Point:
CZCEM1 - Nornal entry via
Type 1 linkage.
Input:
Register 1 contains the address of
the following parameter list:
Word 1
Word 2
If the requested DSCB page is
found to have teen relocated, the new fage
number will be used to update the OSCB
pointer supplied in parameter 3.
~utrut:
Address of the volulfe table or, if
none Exists, of the halfword containing the SDA number.
Address of a one-byte request
flag.
The first half-byte is '0'
to write a DSCB ~age, '4' to read
a DSCB page or '8' to write the
PAT.
The second half-byte is in
the following format:
Assumpt~ons:
It is assumed that the device
to be read from or written to has been
locked, if necessary, prior to the call to
READWRIT.
No deviCE locks will be set or
reset within READWRIT.
However, if the request is to write to a public device, a
check will be made to be sure the device
has been locked by this task.
Modules Called:
SETXP (SVC 244)
PGOUT (SVC 242)
rages.
Exits:
Normal
Error
To read DSCB pages.
To write OSCB and PAT
Register 15 contains 00.
- Register 15 may be set to one of
the following return codes:
bit 1 unused.
04
bit 2
bit 3
bit 4
0,
of
1,
of
pararr>eter 1 has address
PVT.
farameter 1 has address
SDA no.
DB
DC
0, slot no. in parameter 3
used.
1, slot no. ignored.
10
14
0, address of JFCB in parameter 5.
1, parameter') contains
address ot iON or is
ignored.
IS
1e
20
24
28
'",ORO 3
Address of a onE word pointer to
the DSCB or RVN in the following
format:
bits
0-3
OSCE slot nurrber.
bits
4-15
Relative volume
numter.
bits 16-31
Relative fage number.
For a write DSCB request, the slot
number will always be ignored.
For a write PAT request, only the
relative volume field will be
used.
Word 4
Address of a page boundary buffer
into or from which thE DSCB page
will be read or written.
Parameters 4 and 5 arF not required for
a write PAT request.
Word ')
Address of the JFCB or, if there
is none, the address of the fully
qualified data set narre (FQN).
2C
Indicated volume beyond PVT
limi t.
JFCB and RESTBL DSCB pointers
disagree.
Relocation entry cannot be
found.
Pointer indicates a non-OSCB
page.
Checksum error on indicated
OSCE slot.
Data set names disagree.
Unable to write PAT.
Unable to write DSCE page.
Device not locked by this task
for a write operation.
Page number beyond device
limits.
Invalid buffer area address.
f£eration:
If the PVT address is given,
the infut RVN is check~d to see that it is
within PVT limits and the SOA number
obtained frorr the proper PVT entry.
The
::iDA ntlIT,ber is then used to compute the SOA'!'
Entry address.
If the request is to write
the PAT, control passes to the write PAT
subroutine.
Other~ise. the address of the buffer
area (rarameter 4) is checked to be sure it
is non-zero and on a page boundary.
The
[aye nurrter to be read or written is
checked against the limits for that device.
If the JFCB has been supplied (in parameter
5), and if a RESTBL exists for this data
set, the OSCB rointers in the JFCB and
RESTBL are comFared to be sure they agree.
The PAT entry is then checked to see that
it indicates a DSCB page.
If the entry is
'CO', READWRIT scans the PAT relocation
entries to find the correct page.
If the
reqUEst is to write the oseB page, contrel
Secticn 2:
External Storage Allocatien
51
is passed to the write subroutine.
If not,
the OSCB page is read in.
If the slot number has been specified, the checksum is
computed and compared and, if this is a
completed format 'E" OSCB, the data set
name is compared to that in the JFCB or the
F~N supplied in parameter 5.
byte 3 - Lock code.
If this byte
is set to X'SO', the calling task is allowed to
lock more than two PATs.
byte 4 - Reserved
.. ord 2
REAOWRIT then returns control to the
routlne which called it via type I return
linkage.
Address of the SDAT entry .
Cutput:
Lock processing will be perforrr,ed
as requested.
Write DSCE Subroutine:
If the device to
be written to is pUblic, the SCAT entry i::;
checked to see that it has been locked by
~his task.
The page is then written out
Modules Called:
PAIR (CZACS)
To put an entry in the AIR
table.
via l'(;CU'I.
SYSER (CEAIS) --
Write PAT subroutine:
If the device is
public the SLAT entry is checked to be sure
the device was locked by this task.
The
f'AT page number is obtained from the SDAT
and compared with the page limits for this
device.
The PGOUT parameter list is then
filled in from the SDAT and the PAT pages
writtpn.
Exits:
Normal - Return to calling routine with register 15 set to 00.
Any error found results in a diagnostic
mess~ge to the operator and a nonzero
return code U"J the caller.
(See Exits.)
1:.SA LOCK (CZCEJ)
ESA LOCK is a reentrant. nonrecursive,
privileged routine residing in virtual
storage.
It is called to set and clear
virtual memory locks and to record the ta~"k
and module which applied the lock.
CZCEJ
is called for the SDAPLO lock by all routines reading and writing DSCR and PAT
Fages.
(See chart B~.)
Entry Points:
CZCEJl
to set lock.
CZCEJ2
to clear lock.
CZCEJ3
ABEND reset of locks.
Input:
Register 1 points to the following
farameter list:
Word 1
Address of a ~ara~eter word formatted as follows:
byte 1
Type code.
(X'Ol' for
the SDAPLO lock.)
byte 2 - Wait count.
This specifies the numter of
TSEND's to wait for the
lock to be released.
when the lock cannot be
set in the requested
tiwe, control is returned
to the cdller with return
code set to X'OQ'.
52
Error
~inor
system error.
- Return to calling routine with
return code 04; lock could not be
set in lirr.ited attempts requested.
Cperation:
The type code is first edited
to deternine the type of lock to be set.
currently any code but X'Ol' (SDAPLO lock)
~ill cause a SYSER.
PAIR is then called to
~ut the address of the ABEND reset routine
(CZCEJ3) into the AIR table.
Entry is then
rrade to the appropriate lock set or lock
reset routine.
The leek set routine first determines
whether the lock is already set.
If set by
this task it returns control to the calling
routine ~ith return code of 00.
If set by
another task it forces time slice ends
until the lock is cleared or until the
rraxirrurr nunber of TSEND's specified by the
~ait count pararreter is reached.
In the
latter case. it exits to the calling routine with return code 04.
If the lock is clear, the lock set routine determines whether this task is
allowed to lock more than two PATs.
If so.
the lock is set; the task ID and PSECT
address of the routine setting the lock are
recorded in the SOAT and control is
returned to the calling routine with return
code 00.
If the task is not allowed to set
rr,ore than two FATs, the lock set routine
determines whether the task already has the
maximum number of locks allowed (currently
two for SDAPLO).
If so, SYSER is called.
If not, the lock is set; the task 10 and
PSECT address of the routine setting the
lock are recorded in the SDAT and control
is returned to the calling routine with
return code 00.
The lock reset routine first determines
whether the lock was set by this task.
If
not, SYSER is called.
It then checks if it
was set by this roodule.
If not, it returns
centrol to the caller ~ith return code 00,
but does not reset the lock.
If locked by
this module, the lock reset routine clears
the lock task ID and PSECT address and
return~ control to the caller ~ith return
code 00.
The ABEND reset routine is called by
ABEND to clear all locks set by the task if
an abnormal terminate becorres necessary.
SEction 2:
External Storage Allocation
53
SECTION 3:
DEVICE MANAGEMENT
Device rr:anagement allocates, mounts, and
releases private devices used by all tasks
except the BULKIO task.
Devices required
by the BULKIO task are allocated by BULKIO;
MTREQ is called only to update tables in
this case.
At system startup, each device
attached to the time sharing cystem is
designated as either public or private.
Public (system) devices are assurred to be
r:ermanently mounted.
Device management
also restricts tasks to the limits allowed
for private devices, and maintains charges
for their use.
Five routines make up device management
as follows:
MTREQ - allocates devices, restricts tasks
to preestablished resource limits, and
starts charges for private devices.
PAUSE - issues mount requests to the operator and awaits his response and validates
the suitability of the mcunted volume.
RELEAS - releases a device that has been
allocated, services requests for devices
enqueued on the request queue, and updates
and/or stops charges.
BUMP - called to mount subsequent volumes
of a mUlti-volume SAM data set.
MOUNTVOL - initializEs, builds the PVT for,
and calls MTREQ to mount, all volurres of a
VAM private data set.
GENERAL OPERATION
For a conversational task, the DDEF command routine will call MTREQ each tirre a
private device is requested for non-VAM
data sets. If a private device is
requested for a VAM data set, the DDEF command routine will invoke MOUNTVOL to
initialize the PVT. MOUNTVOL will call
L"JTRE(,.l and return control to the DDEF command routine.
If the USER's ration allows
the allocation, MTREQ first checks to see
if a device of the required type is available and whether or not the desired volume
is already mounted.
If the device and
volume are ready, allocation is carried out
at once.
If a device is available but the
required volume is not mounted, MTREQ calls
the PAUSE routine to issue a mount request
to the operator.
Allocation is completed
as soon as the operator indicates that
mounting was done.
Finally, if the USER's
ration allows, and a device of the required
type is not available, MTREQ places an
54
entry in the request queue table. This
table is scanned by the RELEAS routine each
time it releases a device, to see if the
just-released device has been requested.
If requested, it allocates the device and
fasses to MTREQ for table updates.
Note that every task needing a private
device has its own copy of the MTREQ routine.
If that routine finds a requested
private device unavailable, it adds a request to the request queue table, which is
shared by all tasks, and then puts itself
and its task into wait status. When the
RELEAS rcutine operates, it scans the reguest queue and interrupts the first task
awaiting the just-released device according
to a thrEe lEvel priority; SDA requests
first, conversational requests second, and
all ether requests in the third level.
Device managerrent operations for a nonconversational task are similar except that
every private device required by the task
rrust be allocated before the task is
allowed to proceed. To do this, device
rranagerr,ent performs in two phases. In the
first phase, the SECURE command routine
(resfonding to a SECURE command) calls
MTREQ to allocate every ~rivate device
needed by the task. Only when the allocation is complete does the nonconversational
task start executicn; until then, the task
is suspended.
In the second phase, when
the nonconversational task is executing,
the [DEF comrrand routine calls MTREQ or
~OUN~VOL for each priVate device request,
asking that the desired device and volume
be allocated from the set of devices
secured for the task. On each call, MTREQ
makes an allocation from the set of private
devices it has secured for that task. This
continues until the nonconversational task
terminates.
During the second phase MTREQ
will determine if the volume is mounted
elsewhere, and if so, will exchange the
reservation for the device on which the
volurre is rrounted.
MTRtQ handles the mounting of VAM
volurres or the mounting of an initial SAM
volurre, as well as the allocation of unitrecord devices. Mounting of subsequent
volurres of a multi-volume SAM data set is
the function of the BUMP routine.
EUMP
calls PAUSE to ask the operator to dismount
the currently mounted volume and replace it
~ith the next volume.
Only one device is
assigned to a SA~ data set, since only cne
volume is mounted at a time.
The general flow of device management is
illustrated in Figure 5.
Restrictions: This routine can be used
only on PAT formatted private volurres.
MOUNTVOL Routine (CZCAM)
t-:odules Called:
l'ITREQ (CZCAA)
the JFCB.
MOUNTVOL is a reentrant, nonrecursive,
privileged routine which resides in virtual
storage.
This routine will mount and
initialize all volumes of a VAM private
data set and build for it a ~rivate Volume
Table to be in the same format as a Public
Volume Table.
(See Chart CE.)
CZCAMl via type I
VAMINIT (CZCEQ)
To initialize the SDAT
entry of a mounted VAM volume.
LOCATE (CZCFL) -- To retrieve the DSD of a
data set if one was not provided as an
input parameter.
linkage.
~ointer
Input:
Register 1 contains a
the parameter list:
SETXP (SVC 244) -- To prepare to read an
external page into virtual storage.
to
GETMAIN (CZCGA) -- To obtain space for the
PVT and the JFCB volume field extensions.
I-iord 1
Pointer to JFCB
v.ord 2
Pointer to DSD (optional)
Word 3
pointer to a fullword return area
SYSER (SVC 228) -- To provide a full virtual storage dumr.
SECURE -- To allocate the devices needed
for the task, if BULKIO.
output: Register 1 contains a pointer to
the input parameter list. A pointer to the
PVT is placed in the third input parameter
word.
(
To mount all volurres in
READWRIT (CZCEM)
To read DSCB pages and
to write PAT rages.
MTRE0
,-=r_TOS~:
Check to see
if device is
'I
I
Ii
avai labie
I
L_r--i
/-
~
(/
'"
'~
/
I
'~jO'Put
Available
request in
Request Queue
"
/
, , /
r---~=- i
~____ PAU~ ___
I Ask operator to
I
mount de.; ice
'--~=1~=-~
/
I,
"
l
"
-~
,
~Ilt~;o;~~~~)
!
!
.,
MOUNTVOL
I
-
~--------,
(~~t:;p'
For subsequent volumes of a
multivolume SAM dato set
5.
L~=J_ -=----J
PAUSE
I
Ask operoto,
voiu:-ne
-----1---- .
,...'----....
[--l-----l
_J
---""
(RETURN
'---
j
Mount
Volume
to rrount next
_."-
"'HREQ
f----
I --- - - .- ---~-- -----
RetU"')J1/
--- - -
Figure
I
I
I
i
Initialize
and Build
PVT Entry
L______
/
--~..--
•
(---~
L.J Return ')
i",---~--~/
~~
General Diagrarr of Device Manaqement Oreration
Section 3:
Device Management
55
ic_x its :
return is made to the caller with a code of
Norrr~l
- Register 15 contains 00.
• 00 ' •
Error
- Register 15 contains one of the
following return codes:
For an old data set, MOUNTVOL will first
check the ,JFCB to determine whether the
user specified any volumes in his DDEF.
If
he did, the volume IDs are moved into a
save area to be examined later for duplication or addition.
04
08
oc
10
14
Not a VAM data set.
Not a private data set.
DSD not found by LOCATE, or
unmounted volume returned
from MTREQ.
Non-zero return code returned
from MTREQ or LCCATE.
More than three volumes in
JFCB appendage.
Operation: Upon entry the JFCB field,
1DTOSV, is checked for data set organization. If other than VAM organization, a
return to the caller is made with a code of
'04'. MOUNTVOL assumes it will only be
called for private data sets.
If a RESTBL is indicated by the JFCB and
a PVT is indicated by RESTBL field RHDVTA,
the PVT pointer is placed in the return parameter list and a return is made to the
caller with a code of '00'.
The disposition field, TDTDSP, is
examined.
If zero, the data set is 'new';
if non-zero, the data set is 'old'.
In
either case, if the task is BUIKIO, SECURE
is called to allocate the devices needed
for the task.
For new data sets, MTRE~ is called to
rrount all volumes indicated ty the JFCB
volume fields.
If a non-zero return code
is received from MTREQ, a call to RELEAS is
issued if one or more of the volumes in the
J~CB is mounted.
Control is returned to
the calling routine with a return code of
'10'. On a zero return from MTREQ, PVT
size is calculated and GET~~IN is called to
acquire the PVT space. The volume count is
placed in the PVT header. A loop is set up
to initialize each volume entry, build the
PVT entries, and set the flag field if the
PAT table indicates that relocatEd PAT
pages exist. All assigned pages which are
not in use are set to available in the PAT.
VAMINIT is called to initialize each
volume. After the volume is initialized,
the SDAT entry is used to build the PVT
entry (VSN, dev code, and SDA). The ordering of the volume entries in the JFCB is
the ordering of the entries in the PVT.
While scanning the JFCE volume fields if an
unmounted volume or different nuwber of
volumes than the JFCB volume count are
found, a SYSER (minor software) occurs and
a call to RELEAS is issued for all the
mounted volumes followed by a return to L~~
calling routine with a return code of '10'.
After the PVT is built, a pointer t.o it is
placed in the return parameter list and a
56
The parameter list DSD pointer is
examined; if zero, LOCATE is called to
return the DSD of the data set.
If a nonzero return code or other than a DSD is
returned by LOCATE, SYSER (minor software)
is invoked and a return is made to the
caller with a code of 'Oct.
Once the eSD is located, the JFCB volume
count is set initially to one, and the
first JFCB volume field is set up with the
OSO volume 10. Task Common is checked to
see if the BULKIO flag is set; if it is,
~TREQ must be called with an SDA request,
using the SDA which will be in the JFCB, to
mount the first volume of the data set.
If
the BULKIO flag is not set, MTREQ will be
called with the usual JFCB request to mount
that volume.
If a non-zero code is
returned, a call to RELEAS is issued if one
cr more of the volumes in the JFCB is
rrounted. Control is returned to the calling routine with a return code of '10'.
If the volume was already mounted and SDAPVMA has been initialized, the call tc
VAMINIT will be typassed; if not, VAMINIT
is called to initialize the first volume.
A dUll'my ene-entry PVT is built using this
volume and the PVTFLG is set to 'SO' if the
PAT table indicates any relocated pages.
The REACDSCB subroutine is called to read
the 'E' OSCB pointer froIT. the DSD using the
VAM workpage (CZCOY) for the OSCB page.
The volume count in the 'E' OSCB is
examined.
If the count is zero, the data
set resides on only one volume which is
already rrounted.
If no additional volumes
were specified in the JFCB, GETMAIN is
called te get 32 bytes for a one-entry PVT.
The PVT is built from the previously built
dummy PVT, the pointer is placed in the
return parameter list, and a return is made
to the caller ~ith a code of '00'.
If the OSCB volume count is greater than
ene, the DSCB string contains a volume
entry for each volume of the data set including the first volume. The volume
count plus one, times sixteen, is used to
calculate the space required for the PVT.
GETMAIN is called to acguire the PVT space.
The volume entries of the first DSCB are
transferred to the JFCB volume fields.
GETMAIN is called to acquire all the space
needed for the JFCB volume field appendages
(number of volumes divided by 3 and rr.ultiplied by 32). Then, as each 32-byte ap-
pendage is needed, it is taken from this
area.
When all volume ent~ies of the DSCB
are transferred to th., TFeB vc,iUIT,( fields.
MTREQ is called with a ~equest to mount all
volumes just entered,
If a L!~n- Zf"rn return
code is returned by MTl(Z(" a ':all to RELEAS
,is issued if one o~ more ot the volumes in
the JFCB is mounted. Control is returned
to the calling routine ... ith " !",tu~,n corie
of '10'. Ot,herwise ii lOOt' 1:, ';f'~ :Jp teO
call VAMINIT to initicllize each volume,
build the PVT entry trom the ~oxresronding
SDAT entry, and to exan·ine tln- PAT table
for relocated entries, s~tting PVTFLG to
'80' if any are found.
All dssigned pages
which are not in use drp s~t dvailable in
the PAT. A SYSER (minor software) is
invoked if a null field, unmounted volume,
or more than three volume fields are discovered in a JFCB apf-endaqe.
i\ return code
of '10' is issued for the tirsr t.~o condltions and '14' for the third.
FlEADDSCB stores the DseB address for the
READWRIT routine (CZCEM) and then puts the
address cf the page-boundary buffer into
the parameter list for READWRIT.
READDSCB
assumes that the address of the JFCB is
already in the parameter list. READDSCB
then calls READWRIT to read in the DseB
[,age.
After all volumes are ir,iLldllzed, a
check is nade to deterrrine it lh~rE are
data set volumes that have not yet been
mounted.
If umr,ounted volumes remain,
another DSCB must be read to obtain the
next volume fields.
If the "next- DSCE
pointer is zero, a SYSER (minor software)
and an ABEND (comp code 1) dre invoked.
Otherwise the READDSCB subroutine is
entered to read the next OSCB (if necessary). A branch is made to the previously
described code to process the volume
entries in this DSCE.
DSCBs dre read until
all volumes of t_he data set have been precessed and the PVT has been built.
CHECKSUM DID NOT COMPARE UPON REACDSCB.
Once this has been accomplished,
MOUNTVOL will check to see if any volume"
had been specified in the JFCB.
If not,
the PVT pointer is moved to the return parameter list and a return is made to the
caller with a code of '00'.
If there were
volumes specified, the volume: ~;f,rial numbers in the JFCB will be compared to those
from the DSCB(S).
If the serial numbers do
not compare, they will be placed in the
JFCB in the sequence defined by the user,
but immediately following those placed
there from the DSCB(s).
If the volume
serial numbers do compare, they will be
ignored. The new volumes are then mounted,
initialized, and entered into the end of
the PVT via normal processing; return is
made to the caller with a code of '00' and
the PVT pointer in the third input parameter ~ord.
MOUNTVOL also contains t:11e HEADDSCB subroutine that is branched to ~hen a DSCB is
to be read.
The READDSCB subroutine is
entered with register 1 pointing to the
USCB to be read, and a word at location
MNTDSCB that points to an aligned page of
virtual storage (a page-houndary buffer)
into which the DseB page is to be read.
When READWRIT returns to READDSCB, the
return code in register 15 is checked.
If
the return code is zero (good), READCSCB
calculates the address of the forrrat E OSCB
and ~uts it into register 6.
REAODSCE then
branches back to MOUNTVOL with register 6
pointing to the requested oseB.
If. upon
return from READWRIT, READDSCB finds a nonzero return code in register 15, the return
code is saved and then examined to see if
it indicates a DSCB checksum error.
It it
does. REA~LSCB issues the following
rr,essage:
READDSCB then sets a return code to indicate a bad return from READWRIT and checks
to see if the volume has already been
mounted.
If it has, then READDSCB calls
RELEAS (CZCAD) t.o release the volume. Upon
return from RELEAS, READDSCB returns to
~OUNTVOL with the return coce (F'28') indicating a tad return from READWRIT in
register 15.
~TRE~
Routine (CZCAA)
MTREQ is a reenterable, recursive, ~ri
vileged routine residing in virtual
storage, used to allocate unit-record
devices, and devices such as disk or tape
Jrives required for private volumes.
For a
nonconversational task, the routine tries
to allocate ~very device needed for that
task.
For a conversational task, it allocates the reguested device as soon as it
tecomes availatle.
(See Chart CA.)
Entry Points: CZCAA1 - Type I linkage.
Entry is rrade under any of these
conditions:
1.
During conversational task execution.
2.
During nonconversational task
execution.
3.
Prior to nonconversational task execution, that is, entry from the SECURE
cOIT.ITand routine.
!••
When a s~ecific device, rather than a
type of device, is specified.
~)
..
To exchange reservations when BUMP
discovers the volume requested is
presently mounted on another device
(Nonconversational).
Section 3:
Device Management
57
CZCAA3 - Entry at this point is for the
purpose of resetting lock bytes when a task
is abnormally ended or when SYSERR
080502509 occurs.
(CZCGA3) -- To release storage
obtained by GETMAIN.
FREE~~IN
RELEAS (CZCAD1) -- To free any device that
has been reserved but could not be used
because of a non-zero return frOID PAUSE.
Input: On entry register 1 contains a
pointer to one of the following 4-word parameter lists:
Entry Point 1 (private devices)
Word 1
Number of parameters minus one
Word 2
Pointer to a flag word
byte 0
-
-
No msg to user
Mount all volumes
in JFCB
bit 2 - JFCB pointed to by
word 4
bit 3 - Dev Code pointed to by
word 4
bit 4 - SDA pOinted to by
word 4
bit 5 - This is a reserve
request
bit 6 - Scratch volume
bit 7 - CE is caller
bit 0
bit 1
byte 1
-
Tape density code
byte 2
-
not used
byte 3 - bits 0-2 not used
bit 3 - label status
(unlabeled=U
bit 4 - RING flag set
(RECOGNITION=U
bit 5 - tape ring required
(RING=l)
bit 6 - ASCII request
bit 7 - do not verify volume label on call
to PAUSE
Word 3
Pointer to a volume serial field
or the number of device codes for
reserve requests
Word 4
Pointer to a JFCB, to a list of
device codes, or to an SDA
Parameters 3 and 4 may be repeated for
device code or SDA requests.
Modules Called:
MSGWR (CZAAD2)
To issue messages to a
conversational user.
(CZCAD3) -- To update tables and/or
release devices.
ADDEV -- To add symbolic device address to
the Task Device List.
SETAE -- To set asynchronous entry for SAM
modules.
RMDEV -- To remove the symbolic device
address from the Task Device List.
PAIR (CZACS)
To interface with the ABEND
routine for the release of SDAT locks.
PRMPT -- To inform the user that he has
atterrpted to exceed his device ration.
Exits: The routine normally returns to the
caller, via the RETURN macro.
If a minor
system error occurs, the routine exits to
ABEND.
In the event that a major system
error occurs the routine calls SYSER.
MTREQ checks for the following errors,
placing a hexadecimal code in register 15
before returning control to the caller:
Code
00
04
08
OC
10
14
18
1C
20
24
28
2C
30
34
38
3C
40
MTREQ also issues three messages to the
user:
D301
NO PRIVATE DEVICE AVAILABLE FOR
volume AT THIS TIME WILL YOU WAIT?
D302
PRIVATE VOLUME volume IS IN USE WILL YOU WAIT?
PAUSE (CZCAC1) -- To issue volume mounting
messages to the operator.
AWAIT (CEAP7) -- To place the task in wait
status.
GETMAIN (CZCGA2) -- To obtain more virtual
storage.
58
Significance
No error detected
Volume not found
User canceled request
Label error detected
Invalid device code or SDA
Private volume count exceeds limit
No room in request queue
No reservation for this request
Volume requested is public
Volume-Id not found in SDAT
Flag incorrect in SDAT
Volume in use
Error return from MSGWR
seA requested device detached, partitioned or system reserve
CE requested partitioned device
Ration exceeded
Non-zero return code from PAUSE
CZCAA100 devcie NOT AVAILABLE - YOUR
PRIVATE DEVICE RATION IS USEe
UP
OPERATION: For a conversational task,
MTREQ allocates requested devices one at a
time, as each becomes available.
Allocation and volume mounting are done at once.
CZCAB2 - Entry at this point is used to
reset lock bytes when a task is
abnormally ended.
For a nonconversational task, MTREQ
actually operates twice. First it is
called by the SECURE command routine to
reserve, as a set, all devices needed by
the task. A nonconversational task cannot
start until all of its required devices
have been secured. Later it is called as
each DDEF command is executed. MOUNTVOL
calls MTREQ for VAM data 3ets, and it is
also called if BUMP discovers the volume on
another device.
In SECURE processing,
MTREQ reserves only private devices until
the entire set is available; unit-record
devices are reserved aft.er all private
devices have been reserved for the task.
upon entry to this routine, regist.!nput:
er 1 point.s to t.he following parameter
list:
If the caller furnishes a symbolic
device address, and thus requests a specific device, that device will bE allocated
as soon as it becomes available.
When MTREQ allocates a device, it flags
the symbolic device allocation 1~dble (SDAT)
entry for that device as unavailable. Next
it increments the TSI device queue, via
ADDEV. Finally it calls PAUSE to carry out
the volume mounting required.
When a required volume is mounted but
not yet available, or if no device of the
required type is available, or if the specific device requested is currently unavaildble, MTREQ enqueues the request in the request queue (RQUE). A conversational user
will be asked at this roint if he wants to
wait; he can cancel his request and end the
wait at any time simply ty pressing the
ATTENTION key at his terminal. After queuing the request, MTREQ places itself in
wait status which continues until RELEAS
operates, allocates the device, and interrupts MTREQ. RELEAS will supply a pointer
to the SDAT entry of the just-released
device, and MTREQ then ~roceeds with its
customary table and pointer update
functions.
BUMP Routine (CZCAB)
BUMP is a reenterable. non-recursive,
privileged routine, residing in virtual
storage, used to dismount a specified private volume and wount another private
voluroe on the same tape or disk drive.
If
the second volume is already mounted,
device pointers are interchanged.
The routine may be used just to reverify the label
of an already mounted tape volume.
(See
Chart CD.)
.E.ntry Point:
CZCABl - Type I linkage
word 1
Address of first JFCB
Word 2
Address of volume serial field
Word 3
Address of second JFCB
Word
Address of second volume serial
field
4
Modules Called:
Vol Label Processor (CZCWX)
-- To read
tape volume label for reverification.
PAUSE (CZCACl) -- To issue mounting message
to system operator and await operator
response.
PAIR (CZACS) -- To provide for the release
of SDAT locks when a task is abnormally
ended.
RELEAS (CZCADl) -- To release the original
device if an exohange is made for a conversational task.
(CZAD3) -- Release for a nonconversational task.
MTREQ (CZCAA1) -- To reclaim the released
device when an exchange is made for a nonconversational task.
Exits:
BUMP returns control to the calling
frogram, and sets a return code to show the
results of BUMP operation.
If a system
error occurs, the routine is terminated cy
ABENC.
Return Code
(Hexadecimd 1)
00
oc
10
14
18
lC
24
28
Significance
Norrral return. no errcr
detected.
Reverification found incorrect latel.
Old volume not ~ounted.
Device not available, that
is, another task is using
old volume.
Device codes differ but concatenation is not indicated.
Reverification requested for
a non-tape volurre.
Device not tape or direct
access.
New volume has already been
rrounted and is in use.
BUMP will also return any error code
received from the PAUSE routine.
See the
Section 3:
Device Management
59
description of PAUSE for that routine's
return codes.
CZCAD2 - To reset lock bytes when a task is
abnormally ended.
Operation: BUMP begins by checking its
input parameters to see if reverification
is desired. This is indicated if the paran.eters (JFCB Fointer and volume serial
field) for both old and new volumes are the
same.
In this case, only a tape label
check is made. BUMP sets a return code to
show the result of the check before returning control to the calling program.
CZCAD3 - Same as CZCADl with no charges
calculated.
When a dismount/mount oFeration is
requested, BUMP checks that the old volume
is mounted, that the new volume is not
mounted, and that the specified device is
available. A comparison of the device
codes for the two volumes decides the next
action. If the volume is presently on
another device, the pointers are exchanged.
If the device codes are the same (i.e.,
the new volume is to be mounted on the
device used for the old volume), the routine builds a message to the system operator, asking him to mount the aFpropriate
volume.
BUMP then calls the PAUSE routine
to transmit the message and wait for the
operator's reply.
If PAUSE reports a successful mount, BUMP updates the SDAT (symbolic device allocation table) entry for
the device and adjusts the JFCBs to indicate that the old volume has been dismounted and the new volu~e mounted.
If the device codes differ and concatenation is specified, BUMP will try to
mount the next volume in the concatenation
that uses the same type of device.
To do
this, BUMP searches the concatenated JFCBs
to find the next one with the same device
code as the old volume. The JFCB and
volume serial field of this volurr,e are then
accepted as the new volume parameters. The
remainder of BUMP processing is the same as
for volumes with identical device codes.
RELEAS Routine (CZCAD)
RELEAS is a reenterable, non-recursive,
privileged routine residing in virtual
storage, used to decrement the user count
or, if the user count reaches zero, to
release either a single device or all
devices associated with a private data set.
Release means to inform the system that the
device upon which a private volume was
mounted is now free for other use. The
routine also notifies any task(s) awaiting
the freed device(s) that the device(s) is
now available.
(See Chart CC.)
Entry Point:
CZCADl - To update the user count and/or
release devices, and to calculate charges
against a task for device utilization.
60
Input: Register 1 contains a pointer to
the parameter list:
Word 1
Pointer to a flag byte which contains one of the following:
X' 80' JFCB pointer is given
X'OO' SDAT pointer is given
X' 40' SDAT pointer is given and
drive is to be completely
released.
Word 2
Pointer to a JFCB or SDAT entry
Modules Called:
VSEN£ (CEAQ5) -- To send message to task
that was awaiting just-released device.
PAIR (CZACS1) -- To provide for the release
of SDAT locks when a task is abnormally
ended.
SETAE
To set asynChronous entry.
PURGE
To remove a device from a task's
list of available devices.
Exits:
RELEAS always returns control to
the calling program, setting a return code
to show the results of the RELEAS
operation:
Return Code
X'OO'
Significance
No error was detected.
X'04'
Release was for a public
device; request was ignored.
X'OC'
Release was for device not
assigned to this task; request
was ignored.
Operation:
REIEAS first inspects the input
parameter list to see if an SDAT or a JFCB
pointer was supplied.
The parameter list
consists of a pointer to a flag byte and a
pointer to an SDAT entry or a JFCB (which
resides in the task data definition table).
An SLAT pointer is given when just one
device is to be released. A JFCB pointer
is given to release more than one device.
The flag byte equal to 'SO' implies that
the second painter is to a JFCE.
When the pointer is to an SDAT entry,
RELEAS reduces by one the user count in
that entry. When the pointer is to a JFCB,
the routine scans the volume serial numbers
in that JFCB to see if any volumes are
rrounted.
For each volume that is mounted,
RELEAS reduces by one the user count in the
corresponding SDAT entry, resets the
volume-La field in the .JFCB to the volume
serial number, and zeros the volume mounted
Bit 15 unused
Bits 16-23 tape density
Bit 24 tal::€! ring required
Bit 25 RING flag set
Bit 26 remount volume
Bit~ 27 reverify volume
Bits 28-31 unused
flag.
If the user count is now non-zero, no
further action is taken.
If an SLAT request, RELEAS merely returns to the calling
program.
If a JFCB request, the routine
looks for the next mounted volumE.
If the user count is zero, a PURGE is
done to remove the device from the task's
list of available devices. Then, if the
release is being done dUling a nonconversational task. no further action is taken.
Otherwise, the device is now free, and
RELEAS searches the request queUE for a request involving the device type just
released.
Priority is given to requests in
this order:
1.
Request for a specific device, by symbolic device address
2.
Request from a conversational task
3.
Any other kind of request
When a request can te filled, RELEAS
sends a message to interrupt the task that
made the request and sUfplies the appropriate SDAT pointer. Whether or not there is
a request for the just-released device,
RELEAS flags the SOAT entry for that device
to show its availability.
SDAT entry address
!Wodules Called:
lWSGWR (CZAA~-- To issue messages to a
conversational user.
SAM Vol Label Rdr (CZCWX) -- To rewind and
unload a tape volume.
VSENC (CEAQS) -- To send a message to the
operator.
AWAIT (CEAP7) -- To place the task in wait
status.
OBTAIN (CZCFO) -- To read a volume label
and to read the VTOC OSCB or SAM organized
volurres.
PAIR (CZACS) -- To provide for the release
of SDAT locks when a task is abnormally
ended.
ESAM REAr/WRITE (CZCRA) -- To read a tape
header label.
Tape Volume Label Reader (CZCWX) -- To read
tape volume latels.
PAUSE Routine (CZCAC)
PAUSE is a reenterable, non-recursive.
~rivileged routine residing in virtual
storage, used to send mount reguest messages to the system operator, asking him to
mount. vol umes.
It also verif ies the operator's reply and, for tape or direct access,
checks the label of the newly mounted
volume.
(see Chart CB.)
Entry Point:
CZCAC1 - Type I
Code
00-
Significance
Nc error detected.
04
Operator has made a negative reply,
indicating he could not perform
reount request.
08
Attention interrupt or notice of
shutdown received.
OC
Label error or read error detected.
linkage.
CZCAC2 - Entry at this point is used to
reset lock bytes when a task is abnormally
ended.
Input:
Upon entry to PAUSE, register 1
contains a pointer to a parameter list:
Word 1
Exits:
PAUSE always returns control to its
caller, ~lacing a hexadecimal code in
register 15 to show the results of processing.
The codes are as follows:
Flagword address
The flagword is formatted as
follows:
Bi ts 0-7 un u~;ed
Bit 8 volume verification
Bit 9 tape volume
Bit 10 scratch volume
Bit 11 unlabelled volume
Bit 12 no message to user
Bit 13 SAM volume
Bit 14 ASCII
Operation:
For a conversational task the
routine next issues a message (via MSGWR)
to inforrr the user that his task is now
~aiting operator action.
The mount request message, built ty
PAUSE, is sent to the operator via WTOR.
When PAUSE regains control, it checks
first to see if an attention has occurred;
if so it merely returns control to its
caller after setting an appropriate return
code.
The action taken depends on the request.
PAUSE now informs the user (proSection 3:
revice Managerrent
61
'.Ii,jed he is conversational) that his task
i.s no longer wdi t_inq
and re-tu}. ns cant.roJ.
to t.hL' caller.
6
When verification has Leen ~;tipuldted,
proceeds according to the type of
volume involved.
The volume identification
supplied by the caller (or by the operator,
if a scrat.ch volume) i:; compared against
the. actual volwli!:c label.
Fllr a disk, t.he
routine copies the volume latel.
Some of
the information from the volume label is
used to u~date the SCAT entri~s designated
by the caller. On SAM orqanized packs the
volume label contains a pointer to the VTOC
DSCB, which PAUSE cdlls OBTAIN to read.
Some of the device constants Jnd space
information contained in the DSCE are also
used to update the SDAT entry_
f~USE
The density at which a new or existing
td[e is to be processed is always determined at mount time.
'lh(c PAUSE. routine
uses the density specified in a newly
defined field in SDAT (SGADN) for its label
~rocessing.
For labeled tapes, PAUSE attempts to
read the volume label at the density specified in SDADN.
If the label is not readable at the density specified in SCAT or if
the label could not ce read, a check is
made to ~ee if a scratch tape or user tape
was requested.
If a scratch tape was
requested, the operator is instructed to
rr,ount another tape with tile correct density.
If a user tape was requested, PAUSE
returns a -label error" return code (X'OC')
to the callinq routine.
Once the volume
label has been read successfully, an
attempt is made t.o read header label 2, if
any, at the density srecified in SDAON.
If
there are header labels and the density
specified in the header label does not
agree with the density specified in SOAT or
if the label could not be read, the same
proceSSing as for the volume label verification is performed.
If there are no header labels and the volune label is read
correctly, the density in SDAT is considered correct._
The ta[.:€ is always backspaced to its original position following
the volume label, ano E-'rocessi ng continues.
If an unlabeled tape was requested,
attell'pts to read the volumE label at
all densities in order to verity that a
label does not exist.
If a label was found
on a SCRATCH tape that was requested with
no labels, the operator is asked to mount
another tape.
If a lacel was found on a
user tape defined as unlabeled, PAUSE
returns a -label error- return code (X'OC')
to the calling routine.
Note that the system cannot protect against the user specifyiIlq the wrong density for unlabeled.
uncataloged user tape~.
~Qr SCRATCH tapes only, PAUSE checks the
expiration date in the first header label 1
on the tape to determine if the expiration
date has been exceeded.
The current date
is ol~tained by use of the EBCDTIME macro
instruction.
If the header label 1 was
properly read and the expiration date has
been reached, or if the header label 1 did
not exist or could not be read, the tape is
tackspaced to its original position following the volume label, and processing
continues.
If the expiration date was not reached,
a rressage is sent to the operator stating
·F~PIRATION CATE NOT REACHED,
(original
mount rressage inserted here), OR REWRITE
THIS TAPE BY REPLYING R.If the operator
res[cnds to rewrite the tape, a new expiration date is assigned and recorded in header label 1.
When the PAUSE routine requests the
operator to mount a SCRATCH volume (lateled
er unlabeled>, it Expects the operator to
respond with the volume serial nUll'ber of
the vclmre mounted.
If the volume is
labeled and the operator's response does
not natch the volume serial numLer in the
label, the operator is told to mount a new
volurre.
If the operator's response is
correct. the volume serial number is placed
in SCAT.
If the volume is not labeled the
volume serial nmr,ber supplied by the operator is placed in SDAT.
The PAUSE routine issues the following
messages to inform the user of task
processin'.J :
B075
WAITING:
MOUNTED
8076
VOLUME MOUNTED
B077
VOLUME SERIAL NUMBER number HAS BEEN
ASSIGN1,D TC YOU
YOUR VOLUME IS BEING
Fer d scratch volume that is not identified by the operator, the routine sends a
request to the operator to provide the misSing volume identification.
When a volume
cannet be verified, the operator will be
prompted to inform hirr of the error.
The
nurrber of times the o~erator message is
issued depends on the lioit set in system
conmen ~y the installation. The message is:
PAUS~
62
I:NTEH SERIAL NC.
device address).
OF VeL
~--.~--------
th~
Other n,pssagec:. sent t.o thE: ope rater by
PAUSE routine are:
REAr; ERHOR ON (.§ymcolic
CORRECT IF POSSIBLE.
VCL.
addres,_;}
.
-----
-~---
-~-
dEvie~.il2gIes~).
SECTION 4:
• System Packing Parameter: an indication of whether or not private control
sections and private data sets should
be packed.
• Public Segment Indicator:
an indication of whether a ~utlic segment is
being used.
• System Indicator:
an indication of
whether the system has 16 (24-bit
addressing) or 4096 C32-bit addressing)
!;egments.
• Virtual Storage Pointer:
the virtual
storage address at which packing can
begin.
• Variable Length I~dicator:
Indicates
variable or nonvariable allocation for
next segment inforrraticn.
• Next Available Segment Pointer:
the
virtual storage address of the next
full segment available for allocation.
These pararceters, initialized in the
System Table (SYS) or in the Interrurt
Storage Area (ISA) -- page 0, segment
are copied into the PSECT of VMA the first
tirre VMA is entered.
In order to alter th9
basic algorithm to meet the need of a particular allocation, the GETMAIN rracro may
s~ecify farameters which override, for that
allocation. those which Startup presented
to the systerr.
The standard method of
allocation is shown in Figure 6.
°
r-----------------------------------------,
!
TYPE OF SEG~ENT
I
I r--------------T---------T------------, !
I I TYPE OF DATA ! PACKED I NON-PACKED I I
! ~--------------+---------+------------~ I
I I Private
I Packed I Private
I I
I I CSECT
I Private I Segment
I I
I I
I Segment I
I I
I ~--------------+---------t------------~ I
I I Public
I Packed I Shared
I I
I
!
I
I
I
I
I
I
I
I
I
I
I
II
I CSECT
I
I I
I I
~--------------+---------+------------~ I
I PSECTS
I Packed I Packed
I I
I
I Private I Private
I I
I I
I
I Segment I Segment
!
I
t--------------t---------+------------~
i
I I
I I
I I
t--------------t---------+------------~ I
I Public VAJ!J
I ~3ha r:ed I Shared
I I
I Data Set
I Segment I Segment
I I
il ______________
(RESTBL)
I _________ I ____________ JI II
I Private VAM
I Da ta Set
I (RESTBL)
I
I
I
!
IPrivate - Pages Tables are in the task's I
I
XTSI and are available only to I
this task.
I
I
I
Ipublic
I
I
I
I
I
I
- Page Table is in real core and I
is ~ointed to by a segment
I
table entry for all tasks wish-I
ing to reference it.
Packed byl
page boundary.
!
I
- Page Tatle exists in real core I
and is pointed to by a segment I
table entry for all tasks who
I
wish to reference it,
j\lloca- I
tion is on a seqment LUlnc(]ary. I
___ ______ ____ _______ ________ _______ ____________ J
IShared
I
I
I
Il__ _
• Variable Allocation Parameters:
-
Figure
the
I Packed I Private
I Pri va te I Segment
I Segment I
IDefinitions:
IPacked - Allocate on page boundar-yo
" Public Segment Number:
the shared page
table number of the public segment_, if
a public segment exists.
-~--~--,--------
I Public I Segment
I Segment I
~
To provide VMA with this facility, the
following parameters are presented to the
system and are interrogated by VMA in the
course of determining the pages to be
allocated:
the number of pages in a variable
request.
~
Virtual Memory Allocation (VMA) provides
a centralized routine for dynamically servicing all requests for virtual storage
issued by the system or user's programs
during the execution ot a task. VMA determines if a request for virtual storage
should be &acked or placed in a unique segment, starting on a segment boundary.
The
general allocation requirements are for
segmentation ona 32-bit systerr, and for
packing on the 24-bit system.
However,
there is no firm division tetween the two
systems, regarding the method of allocation
used.
Sharatle data sets will always be
located on segment boundaries, and private
PSECTS will always be packed regardless of
system type.
In order that installations
may choose other than the basic rhilosophy,
and may arbitrarily allocate on segment or
page boundaries, VMA is designed to allow
implementation of either form ot allocation
on either system.
VIRTUAL MEMORY' ALLOCATION
6.
Stand~rd
1"PfTory
(Lef~ult}
!111oc.Jt_ion
Virtu21
Entry Points:
CZCGA2 (GETMAIN) -- called via GETMAIN
macro
VMA has two primary functions.
It controls the allocation of virtual storage and
it controls the construction of segment and
~agc tables by issuing the a~pro~riate
SVCs. The various control fields in the
VMA PSEC'T provide a virtual storage picture
of various aspects of the task's segment
and page tables. On examining tne nature
of a request for virtual storage allocation, V~A (either private or shared) will
examine its parameters under various
algorithms, select the proper address for
the allocation, update its parameters, and
issue the appropriate Svc for updating the
segment and ~age tables.
(CZCGA4) EXPANC -- called via CALL MACRO;
Type I linkage
There are six entry points to Virtual
Memory Allocation:
(CZCGAS) DISCONNECT
rracro; Type I linkage
•
GETM~IN
(CZCGA2) - Get virtual storage
(CZCGA3) FREEMAIN -- called via
rracro
FREE~AIN
(CZCGA6) GETSMAIN -- called via CALL macro;
'IYI::e I linkage
CZCGA7 (CONNECT) -- called via CALL macro;
Type I linkage
Input:
CALLED VIA CALL
GETMAIN - register 0 contains:
l:y pages
• FREEMAIN (CZCGA3) - free virtual
~;torage by r:;ages
• EXPAND (CZCGA4)* - Ex~and an existing
block of virtual storage
• Binary count of pages in lower three
bytes
• Protection class (in binary) in tits
4-7 of the high-order byte
• Packing paraffeter (binary) in bits 1-3
•
GE~SMAIN
(CZCGA6)* - Get shared virtual
0torage
• CONNECT (CZCGA7)* - Connect to a shared
page table
• DISCONNECT (CZCGASJ* - Disconnect from
a shared ~age table
Note: Entry points marked * are available
to privileged programs only.
• Variable parameter in bit 0
- binary count of pages in register 0; variable parameter in sign bit of
register 0; virtual storage address in register 1.
FREE~AIN
EXPAND - register 1 contains a pointer to
the following two-word parameter list:
word 1
Input and output parameters are discussed in the descri~tions of the various
sutroutines.
VM~
-- Virtual Memory Allocation (CZCGA)
The Virtual Memory Allocation Routine is
a closed, re-enterable, privileged service
routine located in the task's initial virtual storage. It is called via Type I or
~ype II linkage depending on the privilege
class of the user.
The primary functions
of the module are to control the allocation
of virtual storage, and to control the construction of segment and page tables by
issuing the required SVCs. VMA is used by
system routines that require storage space
for a user's task as well as by user's
prog rarr·s.
Task interrupts (synchronous I/O, asynchronous I/O, external, timer) are inhibited on entry by use of an ITl (inhibit task
interrupt) macro. The mask field is
restored to its original state on return.
(See Charts DA and DB. J
64
r----------------------------------,I
IPointer to a four-word pararreter
larea
I
.----------------------------------~
hord 2 lIlocation
of output parameter list I
_________________________________
~
The four-word pararreter area pointed to by
Word 1 above is as follows:
r----------------------------------,I
Word 1 IVirtual storage address of block
I to be eJ. The VMA is
checked for a doubleword boundary.
If it
is not a doubleword boundary, a code of 08
is returned to the user.
The routine then searches the correct
page header table (privileged or nonprivi-
76
leged) for the page header which has the
sr:;ecified page address (high order 20 bits
of the input address).
This search ends
when the page header controlling the r::age
is located.
If the page header cannot be
found. a code of 04 is returned in Register
15.
Once the correct page header is located,
the r:;rogram checks that the next available
unit address is not less than the maximum
address to be freed. This is an error condition, unless the request was for more
than a page, and results in a return to the
caller with a code of 04 in Register 15.
If the request exceeded one page, then the
fage being freed is checked to insure that
all units were assigned and that no units
were previously freed.
If either of these
conditions is not met. an error is indicated and control is returned to the caller
with a code of 04 in Register 15. If these
conditions are met then the page is removed
from the chain via the DELINK subroutine,
the request is decreased by 4096, the
starting address (address of first unit to
te freed) is increased by 4096, and the
search is re-started for the next page
involved. This ~rocess continues until the
request value is reduced to one page or
less. When the correct page is located
this time, or if the initial request was
for less than a [age, and the next available unit address is not less than the
maximum address to be freed, the program
checks tc insure that all units to te freed
dre now assigned (the unit table contains
O's in each unit position to be freed).
If
all units are not aSSigned (one or more
contains a 1 bit), an error condition
exists and control is returned to the caller with a code of 04 in Register 15.
However, if all units are assigned, the
progra~ frees them by placing 1-bits in
each pOSition to be freed.
The next step is to determine if all
units are no~ free for that page. This is
done by comparing the next available unit
(NAU) address with the numher of freed
units.
If they are equal, the page is
freed via FREEMAIN (pages) before beginning
the normal return sequence. Any pages previously r:;rocessed to be freed are freed via
FREE~AIN (pages), Register 15 is set to 0
(in case of an error reSUlting in a return
code in Register 15, these two operations
are typassed when returning>, program
switches are reset, all other registers are
restcred and control is returned to the
user.
SECTION 6:
A symbolic library is a collection of
separate components called farcels~ each
farcel being a nawed gIOUp of symbolic
statements, which are combined into one
VISAM line data set and indexed so that any
single parcel may be retrieved by specifying its nawe.
The parcels of a syrrbolic
li~rary may be macro definitions for use by
the TSS/360 Assembler, or they may be any
other groups of statements which the user
might wish to store within the system and
retrieve during the execution of his
programs.
Associated with the symbolic component
of each symbolic library is a ser:-arate data
set called the index which contains in
alphabetic order the names of all the parcels in the symbolic component and the line
number of the first syrobolic statement in
each named parcel. Once the symbolic component and the index have been created,
system programs (such as the assewbler) or
user programs may call a system routine to
automatically search the index for a given
parcel name and thus lecate the desired
r:-arcel to be processed.
The symbolic component of a sy[[,bolic
library may be created by the user using
the system DATA command, dnd may be modified using the system MODIFY command.
Alternatively, the user way employ any prograil' that constructs a VISAM line data set.
Once the symbolic component. has been
created, a system routine may te called ty
the user to automatically construct the
index for the entire library.
If the
library is replaced or modified it may be
automatically re-indexEd after each such
modification, by invoking the indexing program via an appropriate RUN cOlw,and.
The following routines are invoked by
the user to index and retrieve symbolic
libraries:
symbolic Library Indexing Routine
(SYSINDEX)
This routine automatically indexes the
symbolic component of a symtolic library to
credte an alphabetical index of all the
parcels. and is invoked when the user
issues the appropriate RUN command or
executes a program calling this routine.
Before execution, DATADEF cowmands must be
issued for both the symbolic component and
indexed data sets. The ddname SOURCE and
dsorg (data set organization) VI must be
specified in the DATADEF for the symbolic
component. The DATADEF for the indexed
SYMBOLIC LIBRARY SERVICE ROUTINES
data set wust specify the ddname INDEX and
dsorg of VE. The individual parcels are
identifi(,d by SYSINDEX either autorr.atically
er by HEans of a user-supplied subprogram.
In the automatic method, parcels are
identified by being immediately preceded by
one or more header lines, which are distinguished ty havinga unique first byte distinct frcm the first byte of any syrrtolic
line.
Each header contains one narre or
alias for the following parcel.
The parcel
name (or alias) begins with the second tyte
cf each header and may have at most the
number of bytes specified by the user in
his LENGTH parame-t.er (see below). Alternati vely, the user rna i' en:rloy any n:ea ns for
identifying parcels and their names. and
may supply a subprogram to examine each
SOURCE line provided by SYSINDEX and pass
the name, aliases and retrieval line number
for each parcel back to SYSINDEX.
The SYSINDEX routine analyzes the usersupplied parameters and calls the actual
index-building routine SYSXBLD. which scans
the entire SOURCE data set, testing each
line for the user-supplied header identifier byte cr allowing the user-supplied subprogram to perform the test and extract
each narrE and alias. SYSXBLD collects a
list of the narre and aliases of each parcel
in the temporary array LIST until the first
non-header line is detected; then the names
in LIST are placed one by one into a temporary index TINDEX along with the retrieval line number of the first non-header line
in the parcel.
The temporary index TINDEX is used in
order to sort the entries into EBCDIC
collating sequence in the final index
CHASLX.
Each TINDEX entry consists of the
fields (name, Ietrieval line number> which
will be entered in the final index, plus a
forward link pointing to the relative location of the TINDEX entry for the next higher name in EBCCIC sequence. As each name
is received for entry into TINDEX it is
compared with all previously entered names,
in ascending sequence, until its proper
location in the ascending chain is deterrrined. Then it is placed at the end of
TINLEX with a link field pointing to the
next higher nawe. and the link field of the
next lower name is adjusted to point to the
new entry.
Once the entire SOURCE data set has been
scanned and the complete TINDEX created,
the last pnase of SYSXBLD extracts all the
entries fro~ TINDEX in ascending name
Section 6:
Syubclic I.ibrary Service Rout ines
77
sequence and places them, without the link
field, into the final index CHASLX.
Symbolic Library Search Routine (SYSEARCH)
This routine may be called by a system
or user program to locate any individual
parcel of a symbolic library, using its
index as created by SYSINDEX. The virtual
address of the index and the name of the
parcel are given to SYSEARCH, and the
retrieval line number of the first line of
the parcel is returned. The calling program should, before calling SYSEARCH using
a given index for the first time, open the
data set containing the index, find the
index member and GET the index in order to
give its address to SYSEARCH.
It is the function of SYSEARCH only to
locate the line number beginning a parcel;
the calling program must then access and
process the parcel as required. Once the
retrieval line number of a particular parcel is obtained and the data set containing
the symbolic component is open, the calling
program may use the SETL macro instruction
to position the symbolic data set to the
beginning of the parcel and then get each
line of the parcel in turn until the end of
the parcel is detected. The assembler, for
example. rray detect the MEND symtolic
statement as the end of the parcel; a user
program might either use a special symbolic
line within the parcel or detect the next
parcel header as the delimiter of this
parcel.
User subroutine for SYSXBLD
The user subroutine for scanning the
symbolic statements, if provided to
SYSINDEX, will be entered by SYSXBLD after
each SOURCE line is obtained, and will be
supplied with the virtual address of the
last source line. the address of the DCB
for the SOURCE data set, and the addresses
where a retrieval line number (in 8-byte
EBCDIC format) and a name or alias may be
returned to SYSXBLD by the user. The user
subroutine may insrect the line and return
one of the following condition codes to
SYSXBLD:
o-
No index entry to be made; proceed to
get next SOURCE line
4 - Enter the returned name and retrieval
line number into TINDEX and return to
user subroutine without getting
another source line
8 - Enter the returned name and retrieval
line number into TINDEX and proceed
to get next SOURCE line
If there are one or more header lines
(not considered rart of the rarcel) con78
taining the name and aliases of the following Farcel, then before returning either
code 4 or 8 the user routine must have
located the proper retrieval line number to
be associated with the following parcel by
repeating the VA~ GET macro instruction
until the first line of the parcel is
obtained; the DCB address supplied to the
user routine must be used in this macro.
During this process, the name and any
aliases must be accumulated internally by
the user routine until the proper retrieval
line number for the following parcel is
available to be passed back to SYSXBLD.
Return code 4 is then used repeatedly to
pass back all but the last alias and return
code 8 is used to passback the last (or
only) name for entry into TINDEX. The user
routine is always entered at the same Foint
and rrust therefore remember when returning
code 4 not to re-process the last line
obtained by SYSXBLD.
When the SOURCE data set is exhausted,
whether it is SYSXBLD or the user routine
issuing the last GET macro, control autorratically Fasses to the last phase of
SYSXELD for constructing the final index.
SYSINDEX -- Symbolic Library Indexing
Routine (CGCKA)
SYSINDEX receives the user's input parameters. promrts the user for missing parameters, and [rocesses the parameters.
After the parameters have been processed,
SYSINDEX calls SYSXBALD, the routine that
actually builds the index (CHASLX).
(See
chart Fl',.)
SYSINDEX
Input:
Parameters are received in one or
more control statements in the forrr:
keyword=parameter.
keyword-parameter
r-------T---------------------------------,
IKeywordl
I
~-------+---------------------------------~
ILENGTH INumber of characters in each narrel
I
Ito be entered in the index
I
~-------+---------------------------------~
IHEADE~
1
I
I
ISingle character that is ccrrraredl
Iwith the tirst byte of each
I
Isource line to determine whether I
Ithat line requires an index entry!
~-------+---------------------------------i
I SCAN
I
IThe symbolic name of a userI
Isurplied routinE to be called fori
I
leach source line to determine if I
l i t h e line is an index entry
I
~-------i---------------------------------i
l~otE:
HEADER or SCAN, but not toth, mustl
Ibe
specified.
L _________________________________________
JI
output:
symbolic library index - a virtual
sequential data set.
The index contains
the names of, and line number rointers to,
the elements contained in the source data
set.
Restrictions:
1.
If the user is operating in nonconversational mode, all infut paraffieters to
SYSINDEX must be correctly spelled in
a single control statement.
2.
Names to be placed in the index must
net be longer than 255 characters.
3.
An input parameter must not be split
between two control sta teIf>ents.
4.
Continuation records are not
perrritted.
Assumptions:
1.
Before SYSINDEX is executed, the user
must have stored the symbolic component as a line data set, organized
sequentially by line number.
2.
The user must have supplied two DDEF
comreands:
one named SOURCE that
defines the data set containing the
source lines to be processed, and one
named INDEX that defines the index to
be created.
~odules
Called:
VAM
G'H-lAR
GATWR
~YSXBLD-CGCKB
- to create the index CHASLX
Exits:
Normal - end of job
Error
- if user is nonconversational, any
parameter errors cause the index
generation ~rocess to be terminated and a return to SYSIN for
the next command
Operation: USing the GTWAR macro instruction, SYSINDEX requests the user to enter
his in~ut rarameters.
Records received
with errors are not processed. The SCAN
routine (described below) scans the record
for a delimiter (equal Sign, comma, or
blank). The first scan obtains a keyword;
the second, a parameter; the third, a keyword; and the fourth, a parameter.
If the length operand is specified as
zero or is not specified, the conversation
a1 user is prompted to sup~]y the length,
I:!xecution is terminated for the nonccnvl'rsational user.
If a valid length is speci
fied, it is converted to bind!'v dnd stor.,',L
SYSINCEX then checks that either the
HEADER or SCAN keyword (but not both) has
teen specified. The header character or
address of the scan routine is stored.
When SYSINDEX determines that either
HEADER or SCAN and a non-zero length have
teen specified, it calls SYSXBLD to generate the index.
Upon return from SYSXBLD,
SYSINDEX ret.urns to the Command Language
Jntprp.reter.
If the user makes an error in entering
his parameters or omits a required parameter, the GATWR macro instruction is used to
write the appropriate error message.
SCAN SUBROUTINE:
SCAN is an internal subroutine used exclusively by SYSINDEX.
It
scans the user's control statement to
extract keyword symbols and parameter
values. The scan detects delimiters, which
may be:
comma, equal siqn, or an EOR rr·arkere
Imbedded blanks, which also halt the
scan, dre discarded.
SYSINDEX and SCAN
allows blanks to surround delimiters, but
not. wi thin a keyword symbol or a parameter
value.
From its normal exit, the SCAN routine provides the character field scanned
(left-adjusted with trailing blanks). the
length of this field, and the delimiter.
Delimiters obtained by SCAN are retained in
a '3tcrage area until replaced by the next
delimiter. When SCAN detects that the
delimiter of the last field scanned was an
end-af-record marker, all informaticn en
the control statement has been processed,
and SCAN makes an end-of-record exit.
SYSXBLD -- Build
(CGCKB)
----
~~mbolic
Library Index
SYSXBLD consist.s of two major components:
LOOP, which scans each line of
the source data set ta locate, extract, and
place entries in a temporary index; and
TERM, which operates on the temporary index
to form a final and complete index.
(See
Chart FE'.)
Fegist_er 1 contains a i._ointer to
this list:
.!npu~:
Word 1
r---------------------------------,I
IPointer to full word containing
! lengt.h of parcel names in index
I
t---------------------------------~
iPointer tc one-byte field ccnItaining hEoder character, if
I specifie(j
t---- - ---- .._- -.. _--.- .--._-..
I
i
I
. .-.-- -·----1
jPointer to variable-lenqth fieJ_cl I
I (with IT.axiwum of ejght t:vtes)
I
I cont i~ in i n0 Ildme () f 11!JC1~'
I rCIlt.i Jl", if '3pt"ci j jyr!
I
I
. ____ J
output: The index CHASLX to be used in the
subsequent retrieval of information from
the symbolic library.
Modules called:
VAM
FINDJFCB
OPEN
FIND
GET
PUT
STOW
CLOSE
User's scan routine (if scan ortion is
specified)
Exits:
Normal - return to calling program
Error
1. If the same name is specified more
than once, SYSXBLD terminates.
2.
If an unreadable record is encountered
in the source member, control is
transferred to the SYNAC exit.
SYSXBLD provdies no SYNAD exit for the
CHASLX DCB; any unrecoverable I/O
error associated with CHASLX invokes
the systere error rrocedure.
Operation: FINDJFCB is used to determine
the nature of the symbolic comronent; it is
assumed that this data set has been
described by a DEFINE DATA command with the
ddnarre SOURCE. The data set is opened and
a FIND is issued for the member. GETMAIN
obtains a page of virtual storage for the
terrpcrary index. The VISAM GET rr,acro
instruction (locate mode) is used to obtain
d
line from the symbolic component. If an
unreadable record is encountered, control
is transferred to the I/O error routine
(IOERR) by means of the SYNAD exit in the
DCB; GATWR is used to write an error message, and exit is made.
Upon normal exit
from GET, the input parameters are checked
to determine the option selected - scan or
header.
If scan was supplied, a CALL is made to
the named routine.
If the user's scan routine determines that no entry is to be
rlaced in thE index for a given line, it
returns with a code of O.
If a narre and
line number are to be placed in the index,
the AETI (add entry to index> subroutine is
aIled to supply the appropriate entry to
TINDEX. A return code of entries 4 or 8 is
returned.
If the return code is 4, SYSXBLD returns
to the user's scan routine to obtain a
synonym for the entry. This process is
repeated as long as the user's scan routine
returns a code of 4.
(Note that it is the
user's responsibility to avoid an infinite
loop here.) The user must also make cer80
tain that the correct retrieval liDe nu~ter
fainter is returned in the pararreter list.
This retrieval line number must be that of
the first symbolic statement to be input
following a CALL to SYSEARCH for a given
name. Consequently, it is the first symcolic line of a parcel following the line
containing the parcel name; the user's scan
routine must get the former line to obtain
the appropriate line numcer. For this
reason, and so that the user can obtain
synonyms already in the symbolic component,
the DCB location is given in the CALL to
the user's scan routine.
If thE user's scan routine returns a
code cf 8, SYSXBID makes the approrriate
entry in TINDEX, gets the next source line,
and then calls the user's scan routine as
described in the previous paragraph.
If the user supplied a header character
in the CALL to SYSXBLD, the character is
corrpared with the first byte of the symbolic line. When an equal comparison is made,
the narre is placed in LIST; this name
begins in the second byte of the syrrbolic
line. The length of this name is given in
the CALL to SYSXBLD. Note that the names
are not placed in the index at this time,
since this header rray be irr@ediately followed by other headers carrying synonymous
nanes.
Entering of names in the index is postponed until a non-header is encountered, so
that the correct retrieval line number may
be obtained. When a non-header line is
encountered, the list of names is dequeued.
and AfTI places the names in the index.
GET then ottains the next source line.
This process is repeated until there are
no more symbolic lines to process; the
EODAD exit in the DCB associated with the
SOURCE data set is then taken.
The SOURCE
DCB is closed, dnd the DCB associated with
the index is opened. FINDJFCB is used to
determine the nature of the index.
Me~bers
of partitioned data sets are located by the
FIND macro instruction, which also indicates if the merrber is new or a replacement; this influences the type of STOW
rracrc instruction to be used later. For
replacement rrembers, a SETL macro instruction is iSSUEd to position to the beginning
of the index.
PUT (locate mode) is then
used to obtain the address of this index.
The length of the entry is extracted
from th~ o~erdnd field of the CALL macro
instruction.
LINK, a link pointer to the
next-higher entry in the index, is estatlished. The entries are placed in the
index until LINK attains a value of zero,
indicating that the highest value name has
teen reached. Processinq is then ccrr~lete.
AE~I
SUBROUTINE: The add entry to index
routine (AETI) is an internal sutroutine
used exclusively by LOOP. AETI shares the
PSECT used by SYSXBLD.
It expects a parameter list containing the location of the
name to be an index and the location of the
associated retrieval line number.
Entries are made in a temporary index
(TINDEXJ, not in the final index.
Entries
in TINDEX are ordered rhysically in the
order of submittal, but are linked together
by ascending EBCDIC collating sequence.
TINDEX entries contain:
1.
A left-adjusted p~rcel name (NAME),
the length of which was specified in
the CALL to SYSXBLD.
2.
The retrieval lin. number (RLN) contained in dn 8-byte EBCDIC field.
3.
A link pointer (LiNK) to the highest
name in ascending EBCDIC collating
sequence contained in a 4-byte field.
The highest value name has d zero link.
AETI Ilaintains NEX'l', a [ointer to the
first unused byte in TINDEX. Since the size
of TINLEX is not predictable, the GETMAIN
macro instruction is used. as needed. to
acquire udditional working :;torage.
The SYSEARCH routine is used to locate
1niormation ~tor~d in d symbolic library.
(See Chart Fe.)
Entry Point:
1
Word 2
Word 3
Exi!:
Ncrrr,al - return to calling routine
Operation: SYSEARCH executes a conventional binary search using the starting point
(SLXSSP) established by SYSINDEX or
SYSXEL:C.
DELTA, the increment value used in the
tinary search, is initially set to a value
cf SLXSSP-4tSLXNLN. SLXNLN is the length
of a line in the index.
The input name is
COil Fared with the name retrieved from the
index.
If an equal comparison is aade, the
line nunter is returned to the calling program. SYSEARCH exits with a return code of
o.
If an unequal comparison is made, DELTA
is divid€d by 2 (by a shift-register
instruction) and added to, or subtracted
from, the current [osition Fainter (register 15), deFending on whether the routine
rrust Ir.uve forward or backward in the index
to find the desired name. The current
ro~iticn fOinter is initialized to the
Linary search starting point.
SYSEARCH
Input:
Register 1 cuntdins the add res!; uf
this list.
~ord
output:
If the index entry is found.
SYSEARCH places the retrieval line number
at the location specified by word 3 of the
inFut raraffieter list and returns with a
code of O.
If the name does not exist in
the index, return is made with a code of 4.
r---------------------------------,
IAddress of the index corr~onent ofl
Ithe library to l~ searched.
I
~---------------------------------~
IAddress of first byte of name to I
tbe located.
This ndm€ ~ust ~e ofl
Ithe length ~~ecified to SYSINDEX I
lor SYSXLLD dnd must te leftI
I justified with truiling blanks.
I
t---------------------------------~
ILocation at which SYS~RCH is to I
lstore the retrieval line number
I
lit
utt.:..ins.
l _________________________________
JI
The inFut name is compared to the index
name indicated by register 15.
If the
input name is greater, SYSEARCH moves forward in the index; if the input name is
less, SYSEARCH moves backward.
Register 15
is adjusted and the compdrison refeated.
On an equal ccrr'Farison, SYSEARCH rlaces
the retrieval line number associated with
the inrut ndffe at the location indicated by
word 3 of the infut parameter list, sets
the return code to 0, and exits.
If DELTA
reaches a value of SLXNLNf8, the infut name
does net exist in the index. SYSEARCH
exits ~ith a return code of 4.
Section 6:
SYlI'vclic Library Service RontinE::s
81
SECTION 7:
CONTROL SECTION STORE ROUTINE
The Control Section Store routine processes user requests made through the
CSTORE macro instruction. During program
execution, any set of contiguous virtual
storage bytes may be transformed into an
object module consisting of a single control section. The module is sto~ed in the
current JOBLIB. It can then be loaded by
the program that created it, or by a subsequent program. When the module is loaded,
no relocation takes place; therefore, it
may contain no relocatable items.
The resulting module will consist of an
unnamed control section which contains a
copy of the hexadecimal text beginning at
the page boundary preceding the address
specified as the starting address parameter, and terminating at the page boundary
following the address computed froffi the
fourth parameter. Thus the resulting control section will always be an integral
number of pages in length.
When the module is loaded by the user,
the module name, as well as the entry point
name, will point to the address computed by
adding to the address of the new module the
page offset (if any) implied cy the starting address. For example, assume that the
user requests that a control section of
4048 bytes be created from the bytes beginning at virtual storage address 50050.
Also assume that the new module is later
loaded at 70000. The loaded module and
control section will occupy the full two
pages beginning at 70000. The second page
is required so that the new control section
will include the last two bytes requested
by the user. The module and entry point
names will both point to 70050.
Maximum control section size is one
segment.
r-------T---------------------------------,
'Word
Icontents
I
.-------t---------------------------------~
11 and 21Module Name
,
~-------+---------------------------------~
13 and 41Entry Point Name
,
.-------t---------------------------------~
I 5
IVirtual storage address of first I
I
,
I byte of text
.-------t---------------------------------i
,6 ILength of text, in bytes
I
.-------t---------------------------------~
7
Icontrol section attribute code.
I
I
I as follows:
I
I
I
I
I
iBit 24 on - System
I
IBit 25 en - Privileged
I
I
I
iBit 26 on - Common
I
I
IBit 27 on - Prototype (PSECT)
I
IBit 28 on - Public
I
I
I
(Bit 29 on - Read-only
I
I
IBit 30 on - Variable length
I
30 off - Fixed-length
lI _______ i IBit
_________________________________
JI
I
Restrictions: The module name and entry
~oint na~e must ce unique in the job
library. The control section to be created
rrust not ce more than a segment in length.
Modules Called:
CZCLJI (OPEN)
CZCLB (CLOSE)
CZCOJ (F IND)
CZCOK (STOW)
CZCOS (PUT)
To detect duplication and
to place the created
~odule in the litrary
Exit: Return, with register 14 containing
the exit address, and register 15 containing one of the following return codes:
00
normal return
04
rr,odule name or CSECT name already in
use.
CFeration:
CONTROL SECTION STORE (CZCKZ)
The Control Section Store routine is a
privileged. reenterable, public system routine which permits the user to create a
control section during program execution.
(See Chart GA.)
Entry Point:
CZCKZ, type I or II linkage
Input: General register 1 contains a
pOinter to the following parameter list:
82
This routine receives input
passed to it ty the CSTORE macro
instruction. After opening the DCB for the
current job licrary, it checks for potential duplication of the module and entry
point names by issuing a FIND.
If duplication exists, the DCB is closed, the return
code in register 15 is set for duplication
(X '04'), and the routine exits.
~ararneters
The PMD is no~ constructed in this routine's PSECT work area. The def for the
CSECT is given a name of eight hexadecimal
zeros, and V- and R- value displacerr,ents of
zero.
The offset between the address given as
the third parameter and the preceding page
boundary is installed as the V- and Rvalue displacements in the def for the
ent.ry point name. The ref for the module
name (standard entry point) is set to name
this def.
The new PMD and the s~ecifi€d text are
flaced in the current JOELIB with successive calls to move mode PUT.
The STOW routine is then called to enter
the specified module name in the POD as the
n,ember narre. and the sr.;€cified entry point.
name as an alias.
The DeB is closed. the register 15
return code set to zero. and the routine
exits.
section 7:
Control Section Store Routine
8~
SECTION 8:
SERVICEABILITY AIDS
The serviceability aids corlsist of routines recording error information, routines
retrieving error information, and a time
conversion routine, SYSTIME, which converts
time from machine format to EBCDIC time and
date.
flows or in the case of a solid outboard
error. VMER is also called by SAM posting,
TAM posting, MSA~ posting, and RTAM reporting interface routines in the event of a
solid inboard error.
ERROR INFORMATION RECORDING ANC RETRIEVAL
ERROR INFORMATION RETRIEVAL
During the course of TSS/360 operations,
a history is maintained of the environment
of the system at the occurrence of any
hardware failures or major software errors.
The pertinent information for each error -error indications, machine status information, instruction retry data -- is
collected by various TSS/360 programs and
recorded on the paging drum for later
retrieval and analysis by the Customer
Engineer.
The paging drum is formatted so that
following every page of 4096 bytes there is
an unused record of 246 bytes into which
error statistics may be ~laced. The error
environment information is recorded on the
even numbered records cn each track. The
first of these records (track 0, record 2)
contains a pointer to the end of the error
information on the drum, as well as some
summary information. Ap~roximately 192,000
bytes, capable of storing information about
500 error incidents, are available per paging drum.
If additional incidents occur
after the recording area is full, further
recording will be bypassed until a retrieval program is run, freeing the recording
area.
ERROR INFORMATION RECORDING
Machine checks resulting from central
processor and storage unit hardware
detected errors, system errors, and solid
outboard errors on direct access devices
are accumulated and recorded on the paging
drum by the system error recording and
retry (SERR) frogram.
The virtual memory statistical data
recording (VMSDR) and virtual rr.emory error
recording (VMER) programs are called when a
task I/O retry operation for a sequential
device either ends successfully (intermittent error) or with error af~er a prescribed number of retries (solid error).
VMSDR accumulates intermittent error information on the statistical data table (SOT),
and calls VMER to record error information
on the paging drum when a SDT field over84
Two programs have been developed for
retrieving the information from the drum.
organizing the data into a usefUl format,
and sending it to an output device. The
first of these, virtual memory envircnrr.ent
recording edit and print (VMEREP), runs as
a virtual storage program under the Tirr,e
Sharing System. The second program,
environment recording edit and print -~odel 67 (EREP67), is a stand-alone program
operating in real core. These retrieval
~rograms are reserved for the use of the
customer engineer.
VIRTUAL STORAGE I/O OPERATION AIDS
Two 1/0 operation aids are fundarrental
to virtual storage error recording and
retrieval: the I/O request control block
(IORCB) and the I/O statistical data table
(SDT) •
1/0 Request Control Block (IORCB)
The IORCB is the basic 1/0 communication
link between virtual storage and the resident supervisor. A virtual storage program
requests the execution of an I/O operation
ty issuing the LOCAL supervisor call. Following the LOCAL is a variable length pararreter list termed the IORCB.
The IORCB is variable in size, but the
first 80 bytes are considered to be a fixed
length sub-area whose internal fields are
all in fixed and known locations relative
to the teginning of the IORCB. There are
three variable sub-areas:
• Cata buffer
• Page list
• CCW list
The page list has a maximum size of
eight doublewords. The maximum collective
size of the three sub-areas is 1840 bytes.
I/O Statistical Data Table (SD'r>
The I/O statistical data table (SDT)
accumulates statistical data on outtoard
failures of task I/O devices.
The SDT contains one statistical data record (SDR)
entry for each task I/O device on the system.
Each of these SDk entries consists of
statistical data on outboard failures of
the associated task symbolic I/O device.
Fields in the SDT are:
SDTLSD - Length of an SOR entry (72 tytes)
SDTLBA - Address of byte following last
byte of SLT
Entry Point:
CALL macro.
CZCRYY, type-l linkage, via
Input:
Register 0 contains the following
Ecrror codes:
1 - intermittent outboard error.
2 - solid outboard error.
Register 1 contains a full word rointer
to the failing ccw address in the IORCB.
Modules Called:
CZCRXI - Virtual memory error recording
(VMER) - generates I/O error records to be output on drum via drum
access module (DRAM), and informs
or-erator of the failing task I/O
comr-onent if the immediate rerort
flag is on for the device.
SOTSDA - Symbvlic device address
CZAB(..l -
SDTFB -
Flag bytes (Example:
operator flag)
write-to-
SDTLP -
Last path used (actual 1/0
address)
SOTEIC - Total error incident count
SDTRE.T - Total retry count
SDTRTH - Retry threshholds (specific error
condition for device)
SDTTSl - Time stamp at error n-·2
SDTTS2-
Time stamp at error n-l
SDTTS3-
Time stamp at error n
SDTSDB - SDR save area (64 half-bytes)- a
4-bit frequency counter for each
bit of sense data
If an SOT field (bucket) overflow
occurs, the SDR entry of a symbolic I/O
device is written on the drum for preservation recording.
Virtual Memory Statistical Data Recording
(CZCRY)
The purpose of the virtual memory statistical data recording (VMSOR) subroutine
is to accumulate error statistics on task
I/O devices in the statistical data table
(SOT). VMSDR is a privileged, reenterable
subroutine operating in virtual storage,
and is called by SAM posting, TAM posting,
MSAM posting, and RTAM reporting interface
routines when a task I/O retry 0feration
either ends successfully (intermittant outboard failure) or is comfleted with error
after a prescribed number of retries (solid
outboard failure).
(See Chart HA.)
Write to cperator (WTO> - transmits a rressage to the main or-erator control program (MOCP) which
will r-rint the message on the
or-erator's terminal.
fxits:
Normal - when recording is comr-leted. control is returned to the caller via
a RETURN.
Error
- if the statistical data reccrd
(SDR) entry for the failing device
cannot be found in the SOT, a
SYSERR of the minor software error
type is invoked, followed ty an
ABEND rracro.
Operation: VMSDR is called by the fosting
routines to record hardware outboard errors
on I/O devices. The posting routines distinguish between two types of errors; solid
and intermittent. VMSDR recognizes four
types cf errors; solid, immediate report,
critical interrrittent. and statistical data
recording.
A solid error (call type 2B) is any
error which was not recovered from after a
specified number of retries by the access
method.
Intermittent errors are those
which have been recovered from
sUCCEssfully.
If the irrmediate report flag is on in
the SDT entry all intermittent errors for
that device will be recorded as irrmediate
report errors (call type 26l).
If the
irrrrediate re~ort flag is not set, a test is
rrade to determine if the error is anyone
cf five critical errors on direct access.
Critical direct access errors are recorded
as intermittent errors (call ty~e 2F).
If the error is neither a solid nor
critical error and the immediate report
flag is off, the statistical data tatle
Section 8:
serviceability Aids
85
entry for the device will te updated and
tested for bucket overflow.
Updating the SDT tatle consists of recording the current system time if this is
the first error incident (indicated hy a
zero error incident count) and incrementing
the error incident count ty one. The 64
sense bits are checked individually and the
corresponding SDT bucket is incremented by
one if the bit is on. There are 64 buckets
of a half tyte each.
An overflow indicator
is set whenever a bucket valul. reached 15.
In the event of bucket overflo~ an SDR
error (call type 2A) will he recorded.
CZCRX4 - Entry from Main Operator Housekeeping Routine (MOHR) to initialize the
drum index if it is invalid.
Input:
Upon entry at CZCRX1, register 1
to a parameter list which contains
the fOllowing:
~oints
Word 1 - SeT entry address of failing
component.
Word 2 - Failing CCW address (zero if
unpredictable) •
word 3 - Sense bytes 0-3.
If there is no overflow VMSDR sets the
retry count in the SDT entry to zero thus
completing the update of the statistical
data table. VMSDR then returns control to
the posting mcdule.
If the error was solid, immediate
report, or intermittent, or if there is a
bucket overflow condition, the retry count
remains in the SDT and the last path is
moved from the IORCB into the SOT. The parameter list is completed and a call is
made to VMER to record the error on the
drum. On return from VMER a test is made
for error type.
If the error was either an
immediate report or SDT type, the SDT buckets and error incident count are reset.
The retry count is then reset and a return
is made to the posting routine.
Virtual Memory Error Recording (CZCRX)
Virtual memory error recording (VMER) is
a privileged, reenteratle, subroutine,
operating in virtual storage, which informs
the operator of the failing task I/O component and generates I/O error records that
are to be output for preservation recording
on drum via the drum access module (DRAM).
VMER is called by VMSCR in the event of a
solid outboard failure or an SDR hucket
overflow, and by SAM posting, TAM posting,
MSAM posting, and RTAM reporting interface
routines on a solid inboard failure of a
task I/O operation.
(see Chart HB.)
Entry Points: CZCRXI - Entry from virtual
memory statistical data recording (VMSDR)
to form the I/O outboard error record
(CHADER) and reset to zero the SDR buckets
in the SOT entry.
Type-I linkage, via CALL
rr.acro.
CZCRX2 - Entry from SAM rosting and TAM
error posting routines to form an I/O
inboard error record. Type-I linkage, via
CALL macro.
CZCRX3 - Entry from task monitor to call
DRAM for recording I/O error records on
drum.
This is a queued linkage entry.
86
word 4 - Sense bytes 4-7.
word 5 - One of the following
X'OO' - call type 2B
X'OB' - call type 26
rer;ort error
X'IO' - call type 2F
error
X'l8' - call type 2A
error codes:
solid error
immediate
intermittent
SDA error
word 6 - Address of SDAT entry for failing
comr;onent.
Upon entry at CZCRX2, register I r;oints
to a parameter list that contains the
following:
Word I
-
Address of failing CCW (Zero if
unpredictable).
word 2 - Pointer to failing symbolic
address.
Upon entry at CZCRX3, register 0 contains 22 minus the buffer number tc be recorded. Register 1 contains the address of
the page containing the buffer.
Cutput:
If VMER is entered from VMSDR, and
if the immediate report flag is on, the
following message is printed on the operator's terminal for all solid outboard
errcrs:
I/O OUTBOARD ERROR ON SDA XXXX,SOLID
For all other outboard errors the message
is:
I/O OUTBOARD ERROR ON SDA XXXX,I.R.
The variable is the symbolic device
address field taken from the SDT entry for
the device in error.
If VMER is entered from a posting routine, and if the irrmediate report flag is
cn, the following message is printed on the
operator's terminal:
I/O INBOARD ERROR ON LP XXXX
The variable is the last path used taken
from the SOT entry for the device error.
~odules Called:
CZASY - Drum access module (DRAM) - outputs
I/O error records on the dummy spaces on
t.he paging drum.
CZABQl - Write to operator (WTO) - transmits a message to the main operator control
program (MOCP) which will print the message
on the operator's terminal.
CZGG2 - GETMAIN routine used to allocate
space for buffering data which is to be
recorded.
CZGG3 - FREEMAIN routine used to release
buffer space when no lcnger required.
CZCJTQ - Queue linkage entry routine used
to set up later entry at CZCRX] by task
monitor.
Exits:
Normal -
(After entry at CZCRXl or CZCRX2)
When Queued Linkage entry has been
set up, VMER returns to caller via
RETURN.
(After entry of CZCRX]) After I/O
error records havE been recorded
on drum, VMER returns to caller
vja RETURN.
Error
- It an I/O error occurred while
outputting the I/O error records
on drum, the following message is
printed:
I/O DRUM FAILURE ON SOA XXXX
If no available drum path can be
located, the following message is
printed on the operator's
terminal:
NO DRUM PATH AVAILABLE
If the drum used for recording is full, the
fcllowing message will be issued:
DRUM OVERFLOW ON SOA XXXX
operation: When VMER is called by VMSDR to
format and record task outboard errors, the
code in word five of the parameter list is
used to set the proper error type in the
outboard error record.
Error information
is moved from the SDT entry for the failing
task I/O device and from the IORCB in the
interrupt storage area and the ISA to the
outboard error record. An in-line routine
is then entered to determine the proper CCW
list, failing CCW, number of CCWs, and OER
record length all of which are then stored
in the outboard error record.
If the failing CCW is unpredictable all of the CCWs
(up to a maximum of 10) are saved in the
error record. If the failing CCW is known
and its relative number is 10 or less, all
the CCWs (up to a Iraximum of 10) are saved
along with a pointer to the failing CCW.
If the failing CCW is known, but its relative nUIf\ber is greater than 10. the number
of CCWs and relative number of the failing
ecw are both set to 10 and the failing CCW
and the nine CCWs preceding it are saved in
the outboard error record.
If the failing device is tape or disk.
the volume 10 and th(~ current system time
are put in the outboard error record.
Current systew time reflects the time of the
last error for an SDR record or the time of
€:rrer for the other types of task outboard
errors.
Wben VMER is called by posting routines
to record task I/O inboard errors (call
type 2C) the tiwe of error is put in the
inboard error record and an immediate
report message is set up for the operator.
The CSW, Channel log, user 10, last fath,
last seek address, and SDA are stored in
the inboard error record.
If the failing
ecw is known the CCws are moved to the
inboard error record.
The remaining procedure is the sane fer
toth types of entry (CZCRX1 and CZCRX2).
If the iwmediate report flag is on, the WTO
nacre is invoked to transmit the message to
the main operator control prograw which
prints the message out on the operator's
terminal.
If there is no tuffer space available,
the GET~AIN routine is called to allocate a
page for use as buffers. The I/O error
information to be recorded is moved into an
availatle buffer space and a queued linkage
entry is set up to provide a letter entry
ty task rronitor at CZCRX3. The parameters
required to locate the buffer are also provided.
VMER then returns to caller via
RETURN.
Task monitor then calls VMER at CZCRX3
and passes the parameters used to locate
the cuffer containing the I/O error inforrraticn tc be recorded.
A CCW list is constructed for a channel
frograffi to locate and read in the environITIent recording (ER) index record.
The CCW
list is descrited in the drum access module
(DRA~) description.
The drum access module
(DRA~) subroutine is then called to execute
the channel program.
Upon return from DRAM. the return code
is checked to determine if the file protect
tit is on (set to one), indicating that the
task-supervisor interlock is locked or the
task-task interlock is locked for another
Section 8:
Serviceability Aids
87
r---------T----------------------T------------------------------------------------------,
IConditionl
I code
I
Error
I
I
Recovery Procedure
I
I
t---------t----------------------t------------------------------------------------------~
I
1
ISIO instruction r€jectlGenerate message to cperator informing him of drum 1/01
I
I failure.
I
1
t---------t----------------------~
I
2
10peration complete
,with error
I
IIssue RDI and return to caller.
I
1
I
I
t---------t----------------------t------------------------------------------------------~
I
2
I Drum Path unavailable I Get new drurr. SDA frOlf first half word of parameter
I
I '
Ilist and repeat recording sequence.
If new SDA is
I
I
I
Izero, issue RDI and inform operator that no drum path I
I
:
is available.
L ________
i - _____________________ LI ______________________________________________________
JI
Figure
8.
DRAM Condition Code Recovery Procedures
task.
If the file protect bit is on, the
sequence of operations beginning with the
construction of a CCW list is repeated.
If
net, the condition code is checked to
determine if the I/O operations have successfully completed.
If successful, a
check is made to see if the time stamp
exists.
If there is nc time stamp, the
current system time is obtained via the
REDTIME macro and stored in the index time
stamp.
If the index record is invalid, it
is initialized and the current system time
is stored in the error index time stamp.
released cy calling the FREEMAIN routine.
VMER then returns to the caller via RETURN.
When VMER is called by the ~ain Operator
Housekeeping Routine (MOHR) during the
startu~ ~rocessf entry point CZCRX4 is
used. A flag is set to indicate entry from
~OHR, and a branch is made to the routine
normally entered at CZCRX3. The drUIf index
is read, and the current system tirre is
stored in the index record. The updated
index record is written on the drurr, the
drum index interlock is reset. and control
is returned to ~OHR.
DRAM is then called to read the first
available 246 byte dumrry record from the
drum. The error record is moved from the
error buffer to the dummy record.
[rum Access Module (CZASY)
If the entire record did not fit in the
dummy record, DRAM is called to write the
dummy record onto the drum and the record
number portion of the index is updated.
The remainder of the error record is then
moved to the drum buffer and DRAM is called
again to write the next durrmy record on the
drum.
The drurr access module (DRAM) is a special purpose, ~rivileged, closed, reenterable, virtual storage subroutine provided
for the use of those virtual storage programs, such as VMER and VMEREP. which Uoust
access the error records stored on the
dummy spaces of the paging drum. This special access method is needed primarily to
prevent interfering with the drum paging
operations.
(See Chart HC.)
If the entire record fits in the dummy
record which was read, DRAM is only called
once to write the dummy record on the drum
and the record number is left unchanged.
The byte count portion of the index
record is updated and DRAM is called to
write the index back onto the drum.
If the condition code indicates that I/O
operations have not been successfully completed, one of the following recovery procedures is taken, depending upon the condition code returned by DRAM. See Figure 8.
When the I/O error record has been recorded on the drum, VMER resets the task
interlock by issuing the extended instruction RESET DRUM INTERLOCK (RDI).
If the
buffer which was recorded was the first
buffer in the buffer page, the page is
88
Entry Point:
CALL macro
CZASYl - Type-l linkage, via
Input: Register 1 contains a pointer to a
location containing a pointer to a parameter list which contains the following:
byte
r-----------------------------------,
1
2
3
I
10
t--------------r----------T---------~
Word 1 Il Device
Addressl
Flags. i ICCW
Count JI
_____________
- i __________
_________
*cit 2 of the Flag Byte contains the
-ignore sick unit" indication.
The rerraining input parameter list is in
the form of a CCW list:
r----------------------------------,
Word 2 I
First CCW
I
t----------------------------------~
I
I
I
I
t----------------------------------~
Word n IL __________________________________
nth CCW
JI
If a new device address was posted, the
new one is placed in the first two bytes of
the r:ararreter list; otherwise, these bytes
renain unchanged. The appropriate flags
and CCw count are inserted, paraweters
replaced. and the registers are restored.
DRAM then RETURNs to the calling program.
CCW n must be a NOP VCCW.
Virtual ~emory Environment Recording Edit
and Print (CZASE)
output: Register 1 is returned to the
calling program unchanged; the parameter
list is unchanged, except for the following
changes in Word 1:
Flag Byte:
I!i t(s)
o
1*
6,7
Meaning
File protect was on.
Device address has been changed.
Condition Code after S10:
-00-01-10-11-*
*
Operation complete
Error after SIO
Complete with error
Drum unavailable
In the event that condition code 3 has
been received, a new device address is
returned in bytes 0 and 1 of Word 1.
Virt.ual memory environment recording
edit and print (VMEREP) retrieves, forrrats,
and Frints the environment recording infornation stored on the paging drum.
VMEREP
is a non-reenterable, privileged, virtual
storage service routine reserved fer the
custcmer engineer. The routine receives
job requests from the C.E.
or a user with
a privilege class of A or E, and communicates with him via the GATE subroutine
(CZAAB).
(See Chart HD.)
Entry Point: CZASEl - Type-I linkage, via
VMEREP conrr,and.
Input:
Error history reports located on
the dummy spaces on the paging drun.
Modules Called:
lOCAL (SVC) - called to
initiate the I/O operation.
Output:
Formatted reports are sent to
[rinter or SYSOUT.
Exits:
Normal - when I/O operations are complete,
DRAM RETURNs to caller.
Modules Called:
CDEF (CZ~EA) - Obtains use of printer for
output.
Error
CPEN (CZCEA) - Opens output data set.
.- when I/O operations are either
complete with error or incomplete,
DRAM RETURNs to caller with condition code indications.
operation: The calling routine provides
DRAM with a CCW list, which is used to
build an I/O request control block (IORCB).
A page list for the IORCB is constructed by
inserting the high-order 20 bits of each
CCW address into the list. The origin of
the CCW list is calculated, and each output
CCW is created relative to the page table.
The length of the IORCB is then calculated
in 64-byte blocks, and, when creation of
the IORCB is complete, the I/O operation is
initiated by executing an lOCAL SVC.
A special DRAM flag bit (IORAMM) is set
in the IORCB to notify the page drum queue
processor and other programs concerned that
the call is from DRAM.
When th€~ I/O operation completes, the DRAM posting routine
(CZASX) is given control. When posting is
completed, control is returned to DRAM,
which determines if a new device address
was posted, as indicated in the condition
code bits of the flag byte.
CRAM (CZASY) - Accesses error records on
raging drum.
CLOSE (CZCLB) - Closes output data set.
RELEASE (CZAFJ) - Releases DDEF for
printer.
GTWSR (CZATC> - COIr.municat.es with C. E.
user.
or
Exits:
Normal - Exit is made when user
enters job request END.
Operation: After identifying himself as a
C.E. or user with proper rrivilege class,
the C.E./user enters the command verb
VMEREP which is interpreted by CLI. VMEREP
is then trought intc the system and given
control. The C.E.
then enters the following information via the console typewriter:
• Symbolic Device Address of the paging
drum.
• ,Job Request.
Sec~ion
8:
Serviceability Aids
89
If the desired output device is a printer, the VMEREP routine calls DDEF (CZAEA)
to obtain a printer.
The job request specifies the type of
information to be retrieved, and the
options applicable.
The following job
requests and options are valid:
LIST FAILURES - Lists all errors recorded
on the drum by record-id and error type.
PRINT INDEX - Print contents of the index
record (track O. record 2).
PRINT ALL - Print contents of the index
record and all error information on the
drum.
PRINT ID HHRRNN - This job request is given
when information about a particular error
is desired. HH, RR, and NN are the hexadecimal values of the track number, head
number, and byte number respectively.
SEARCH CSEE - This request is used when a
particular class of errors is to be retrieved and processed.
C is the CPU number (1-8) to which failure was atributed.
S is the storage element identification
(A-H) to which failure was attributed.
SET INDEX TO HHRRNN - The pointer in the
index record is changed to HHRRNN. Any new
records written on the drum will be recorded just after the byte located at track
HH, record RR. byte number NN.
SET IR •••• (SDA in four hexadecimal digits)
- This job request sets the immediate
report to operator flag in the SDT which
causes each error for the particular device
to be recorded.
RESET IR •• *.(SD~ in four hexadecimal
digits) - This request causes the immediate
report flag to be set off.
END - This job request is used when no
further requests are to follow, and indicates that data sets should be closed,
devices relinquished. etc.
The following options are available to
the user:
PRINT ZEROES - This option forces the
printing of the complete CPU log, zeroes as
well as non-zeroes.
Note: This option is applicable only to
error types 01 and 09 and must be entered
in one of these three ways:
SEARCH CSOl PRINT ZEROES
SEARCH CS09 PRINT ZEROES
PRINT ALL PRINT ZEROES
EE is error type, as follows:
01
09
26
27
28
29
2A
2B
2C
2D
2E
-
-
2F 41 -
Internal machine check.
Multiple internal machine checks.
Iffimediate reFort.
paging I/O statistical data record.
Solid Faging I/O outboard error.
External machine check.
Task I/O statistical data record.
Solid task I/O outboard error.
Task channel failure.
Paging channel failure.
Intermittent paging I/O outboard
error.
Intermittent task I/O outboard
error.
System error.
Any parameter not used should be replaced
with an X.
Example: SEARCH XX29 means print all records whose error type is 29.
RESTART - This request causes VMEREP to
return to its initial routines.
RESET INDEX - This request should only be
used whenever all the data on the drum has
been retrievEd, so that programs which
record information on the drum can start at
the first record (track 0, record 4).
90
SYSOUT - This option causes the output of
this jcr request to be sent to SYSOUT
instead of the printer.
After the user enters his job request,
VMEREP retrieves the desired inforrration
via the drum access module (D~M), formats
the data, and prints it on the specified
cutput device.
If VMER or SERR stored
additional information on the drum while
the serVicing of the jor request was in
progress, and is applicable to the type of
information requested, this new information
is fcrrratted and printed.
When the job requested has been completed. VMEREP asks the user for his next
job request. When no more error data is to
be retrieved. the user normally issues a
RESET INDEX job request followed by an END
request. VMEREP terminates via norreal progran: end.
Environment Recording Edit and Print, Model
67 (CMASN)
The environment recording edit and print
program for Model 67 (EREP67) is an offline, self-loading, and self-controlled
prograrr used by the customer engineer to
edit and print the information recorded on
the paging drum by error recording programs
(SERR and VMER). This program does not run
the TSS monitor. It loads itself into
storage and operates under its o~n control.
(See Chart HE.)
E is the error type as follows:
~ith
Entry Point: The deck provided is selfloading. The program is assumed to be the
sole user of the system at execution time.
Input: Error information stored on the
dummy spaces on the paging drum.
Formatted reports are sent to the output
device (usually a high-speed printer.
Assumptions:
• The ~SS monitor ~ill have to be stopped
before this program can be used.
• The EREP67 program ~ill have access to
paging drum and a print device.
• EREP67 does not save or restore any
environment.
Exits: Ncrmal - exit is made
enters job request END.-
~hen
C.E.
Operation: EREP67 cannot ce run concurrently ~ith the TSS/360 monitor, since
access to the paging device is required.
After loading the program, the operator
enters the following information via the
console type~riter.
01
09
26
27
28
29
2A
2B
2C
2L
2E
-
Internal machine check.
Multiple internal machine checks.
Immediate report.
Paging 1/0 statistical data record.
Solid paging I/O outboard error.
External machine check.
Task I/O statistical data record.
Solid task I/O outboard error.
Task channel failure.
Paging channel failure.
Intermittent paging 1/0 outboard
error.
2F - Intermittent task 1/0 outboard
error.
41 - System error.
Any parameter not used should be
replaced with an X.
ExamEle: SEARCH 3XOl means print all type01 records pertaining to CPU 3.
PRINT ZEROES - This option is used in connection ~ith the PRINT ALL, PRINT ID, and
SEARCH job requests, to force the printing
of the complete CPU log, zeroes as well as
non-zeroes.
RESET INLEX - This request should 2nly be
used ~henever all the data on the drum has
been retrieved, so that programs ~hich
record information on the drum can start at
the first record (track O. record 4).
SET INDEX TO HHRRNN .. The pointer in the
index record is to be changed to HHRRNN.
Any ne~ records ~ritten on the drmn ~ill be
recorded just after the byte located at
track HH, record RR, byte number NN.
• Address of the paging drum.
• Address of the output device.
• Job request.
The following job requests, which specify
the type of information to be retrieved and
the options available, are valid:
END - This job request indicates that no
rrore job requests follo~, and that the program is to be terminated.
PRINT IN[;EX - Print contents of the index
record (track 0, record 2).
After the C.E. enters his job reguest,
EREP67 rEtriEves the desirEd information
from the paging drum, formats the data, and
frints it on the specified output device.
when no more jobs are requested, the C.E.
normally issues the RESET INDEX job request
follo~ed by an END request.
PRINT ALL - Print contents of the index
record and all error information on the
drum.
PRINT ID HHRRNN - This job request is given
when information about a particular error
is desired.
HH, RR. and NN are the hexadecimal values of the track number, head
number, and byte number respectively.
SEARCH CSEE - This request is used ~hen a
particular class of errors is to be retrieved and processed.
C is the CPU number (1-B) to
ure was attributed.
~hich
fail-
S is the Storage Element identification
(A-H) to ~hich failure is attributed.
RTAM Error Recording Interface Module
(CZCTR)
The RTAM error recording interface
module (RERIM) is a privileged, reenterable, subroutine residing in virtual memory
which acts as the central point for Fassing
error information between the RTAM subsysterr and the TSS subroutines VMSDR and VMER.
The purpose of this interface routine is to
allow terminal error recording information
to be stored in virtual ~emory and net tie
up real core space unnecessarily. RERIM is
passed error information in the MCB wessaSection 8:
Serviceability Aids
91
gearea frmf! the real core RTAM error routine CEATCS. RERIM then analyzes the
information and passes it on to either
VMSDR or VMER for recording.
(See Chart
HG. )
Entry Points: CZCTR1 - Entry from LOGON of
Main Operator, and SHUTDOWN. When entered
from LOGON this entry ~oint is used to
establish CZCTR2 as the entry point for
processing external interrupts with code
value 255. When entered from SHUTDOWN,
this entry point is used to delete CZCTR2.
This is a Type-I linkage entry point,
entered via the CALL macro.
block in the message area defined with the
SEEC macro issued by CZCTR1.
If the error is an intermittent or solid
cutboard error, VMSDR is called to record
the error information. If it is a solid
inboard error, VMER is called to record it.
If the error is none of these, SYSER is
called to indicate a system error. After
recording the error information, CZCTR2
restores ISA fields so they contain the
sarre information they had when CZCTR2 first
received control. CZCTR2 then issues a PTI
to permit interrupts and returns control to
the task monitor.
CZCTR2 - Entry from the task monitor for
recording external interrupt 255 (X'FF').
This is a queued linkage entry.
TIME CONVERSION
Input:
Upon entry at CZCTR1, register 1
contains a value of X'04' if called by
SHUTDOWN.
The SYSTIME routine is a closed, reenterable, nonrecursive, virtual storage
routine. It is used by the EBCOTIME macro
to convert time from the format in which it
is maintained by the system (that is,
double precision fixed point binary number
of micro seconds that have elapsed since
3/1/1900) into various EBCDIC forms of time
and/or date. The privilege is the same as
that of the calling routine, implying that
SYSTIME is a fence straddler.
(See Chart
HF. )
Modules Called: CZCRYY - Virtual memory
statistical data recording (VMSDR) - to
accumulate error statistics on task. I/O
devices in the statistical data table (SDT)
and to inform the operator of the device
failure if the system is in the immediate
report mode.
CZCRX2 - Virtual memory error recording
(VMER) - to inform the operator of a solid
inboard failure of a task I/O operation and
record error records on drum.
Exits:
Normal - control is returned to the calling
routine via a RETURN macro.
Error
- if CZCTR2 receives control for an
error other than a solid outboard,
solid inboard, or intermittent
error, a SYSER is issued and control is returned to the caller via
a RETURN macro.
- if the SDA of the terminal is not
found in CHBSOT a SYSER is issued
and control is returned to the
caller via a RETURN macro.
SYSTIME ROUTINE (CZCTA)
Entry Point:
Input: General register 1 contains a
pointer to the following parameter list:
Word 1
Address of a halfword containing
the length in bytes of the text
field. Maximum allowable length is
50 bytes.
Word 2
Address of the text field in which
the output of SYSTIME is to be
placed.
On input, the text field contains
special character groups which
specify to SYSTIME the form that
its output should have. The special character groups are as
follows:
Operation: When CZCTR is entered at
CZCTR1, register 1 is checked to see if the
routine was called by LOGOFF. If it was,
CZCTR1 issues a OIR macro to end CZCTR2
external interrupt processing and then
returns to LOGOFF. Otherwise, CZCTR1
issues a SEEC to create an ICB and a message area for external interrupts. CZCTR1
then issues a SIR designating CZCTR2 as the
external interrupt 255 handling rO
._B},~l
1
8
'--_ _ _....J
---c:~~
Section 9:
Flowcharts
259
APPENDIX A:
OATA SET CONTROL BLOCK (OSCB) FOIUlAT
Each SAM direct access volume has a
volume table of contents (VTOC) that
describes its contents; the VTOC contains
all the data set control blocks (OSCBs) for
the data sets contained on that volume.
Each"VAM volume has a PAT table describing whether a page is used for OSCB or
Data.
The VAM DSCBs are of E and F
formats.
For SAM formatted volumes, the TSS/360
OSCB formats are:
Format-O - an unused OSCB; contains binary
zeros.
sequential data sets.
Figure 12.)
(See
Format-A - the data set label for dire~t
access volumes containing virtual storage data sets.
(See
Figure 13.)
Format-B - used to describe additional
extents of a virtual storage
data set if there are more than
can be described in a format-A
DSCB.
(See Figure 14.)
Format-1 - the data set label for direct
access volumes containing physical sequential data sets.
(See
Figure 9.>
Format-c - describes available extents on a
volume containing virtual
storage data sets.
(See Figure
15. >
Format-3 - used to describe additional
extents of a physical sequential
data set if there are more than
can be described in a format-1
OSCB.
(See Figure 10.)
For VAM formatted volumes, the TSS/360
OSCB formats are:
Format-4 - the first OStB in the VTOC.
(See Figure 11.)
Format-5 - describes available extents on a
volume containing physical
260
Format-E - This OSCB is used for single or
mUlti-volume VAM public or private data sets.
(See Figure
16. )
Format-F - This OSCB is used as an extension of the format E OSCB.
(See
Figure 17.>
r------~---------~-------------~-------~--------------T-------------------------------------------,
I Field I
I
I
I
I
I
INumberlField Name IIdentificationlLength 1Representation I Usage
I
~------t-----------t--------------t--------t--------------t-------------------------------------------~
11
IData set
IDSCNME
144 byteslalphameric
IMay have one of two forms:
I
I
I Name
I
I
I (EBCDIC)
I
I
I
I
I
I
I
I 1. User !D.User Name
I
I
I
I
I
I
! 2. User ID.User Name.Generation
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
i
I
I
I
I
1
1
I
I
1
1
I
1
I
I
I
I
j
f
I
I
I
I
I
I !
I
IThe user ID is eight bytes in length.
I
1
I
1
I
1
1
1
1
1
I
I
I
!
The!
luser name is a maximum of 35 bytes in form I
!1. and 26 bytes in form 2. The generator 1
lis of the form GNNNNVNN (eight characters) I
Iwhere N is a decimal number.
I
I
1
I Note:.
If a user declares himself an OS/3601
luser, the User ID is not concatenated and I
Ihe is allowed a 44-character name in form 1\
I and 35 charact.?rs in form 2 I
t------t-----------t--------------t--------t--------------t-------------------------------------------~
12
I
I Format
I DSCFID
I Identifier I
I hexadecimal
!Contains X'Fl'
I
1
I
I
~----+-----------t--------------t--------t--------------+-------------------------------------------1
13
!Data Set
I DSCVSR
16 bytes lalphameric
!Used for data/volume relationship_ This
I
ISerial
I
1
1 (EBCDIC)
!field contains the volume serial number of I
I
I
I
I
Ithe first (or only> volume which contains I
I
I Number
I
I
I
1
I
! the da ta set.
I
~------+-----------+--------------+--------+--------------+-------------------------------------------1
14
I Volume
I DSCVSQ
12 bytes Ibinary
I Used to indicate the order of the present I
I
I
I
Ivolume relative to the first volume,
I
I
I Sequence
I
I Number
I
1
I
!containing the data set. Range is from
I
I
I
I
I
1
10001 to 9999.
I
11 byte
I
~------+---------__+--------------t--------t--------------t-------------------------------------------1
15
I
I Creation
IDate
I
13 bytes Idiscontinuous lyeD where Y=year (0-99) and DD=day (1-366) I
1
1binary
I
I
16
I
I
IDate
1
I
1binary
I
I
1
I
IDSCCRD
r------t-----------t--------------t--------t--------------+---------------------------------------------1
IExpiration IDSCEXP
13 bytes Idiscontinuous iIndicates the year and day the data set may!
Ibe purged.
I Date.
I
I
Has same form as the Creation
~------+-----------t--------------t-------t--------------t------------------------"------------------~
17a
I
I
!
INumber of
IDCBNEX
I Extents on I
IVolume
I
i
I
11 byte
(binary
I
I
I
1
1
I
I
I
IThe number of total separate extents in
I which the data set resides on this volume;
Icount does not include extent describing a
I user's label track.
1
I
t------t-----------t--------------t--------t--------------+-------------------------------------------~
17b
I
I
I
I
1
INumber of
IBytes Used
I in Last
(Directory
IBlock
I
1DCBFL1
I
1
11 byte
1
1binary
I
I
1
1
I
I I !
I
1
I
I
IUsed only for an 05/360 partitioned data
I
Iset. It contains a binary number indicating I
I the tota 1 number of bytes being used in the I
!last available directory block. Value of 1
I zero indicates that the last available
!
! block is not being used.
1
t------t-----------t-~------------t--------t--------------+-------------------------------------------1
17c
ISpare
I DCBSP1
I
11 t:yte
I
I
t------t-----------t--------------+--------t--------------t-------------------------------------------~
18
I system
IOCBSCD
113 byteslalphameric
1'10 identify the programming system.
Only !
I
(Code
I
I (EBCDIC)
1
I
Icharacters A-Z, 0-9, and blanks are used.
t------+-----------t---------------+--------t--------------+-------------------------------------------~
19
I
I
I Reserved
1
(For Future I
IUse
1
17 bytes I
I
1
I
I
i
I !
I !
I
r------+-----------t--------------+--------+--------------+--------------------------------------------i
110
IFile Type ICCBFTY
12 bytes Ihexadecimal
IHex Cod~ Description
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I 4000
Sequential organi zation
I
I
1
I
I 2000
I:irect Organization
I
I
I
I
I 0200
Partitioned Organization
I
I
1
I
I 0000
Organizat_ion not defined
I
I
I
1
I 8000
Index Sequential Organization
I
I
I
I
I
I
1
1
INote: .If bit 7 of byte zero is en, t h e . I
I
I
I
1
I
I data set descr ibed by this DSCE must rema1n I
I
I
1
I
lin the same absolute location of the directl
I
!___________ I ______________ I ________ I ______________ I access
device.
I
L ______
__________________________________________
~
Figure 9.
~
~
~
~
~
Format-l DSCB (Part 1 of 4)
Appendix A:
Data Set: Control Block (OSCB) Format
261
r------y---------T--------'------,--------,--------------,-----------------------------------------,
I Field I
I
I
I
I
I
INumberlField Name IIdentificationlLength I Representation I Usage
I
~------t-----------t--------------t--------t--------------t---------------------------------------~
111
I Record
I DSCRFM
11 byte I binary
I Bi t Binary Code
I
I
1Format
I
I
I
10,1 10 - fixed-length record (F)
I
I
I
I
I
I
I
01
variable-length record (V)
I
I
I
I
I
I
I
11
undefined-format record (U)
I
I
I
I
I
I!
I
I
I
I
I
I
I
I
I
I
I
1
I
I
I
I
I
1
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
1
I
1
1
1
1
I
1
I
I
I
I
I
I
I
I
I
I
I
I
2
track overflow feature must be
used
3
blocked (B)
I
I
I 4
I
15,6 10
I
01
I
00
control character ASA code (A)
control character machine code
control character stated
I
1
I
I
Not used
I
I
I
I
7
I
I
I
I
1
truncated records in data set (T)
I
I
I
I
(M)I
I
I
1
t------t-----------t--------------t--------t--------------t-------------------------------------------~
112
IOption
I DSCOPT
1 byte I binary
IThe 8 bits of this field are used to
I
I
1Codes
1
I
I
I
I
I
I !
I
I
I
I
I
I
!
I
I
1
1
I
I
1
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
various options used in building
Ithe data set. The bit configuration of
Ithis field is exactly the same as that
Idescribed for the OPTCD field in the DCB.
I Bit 0 of this field is common across the
Ivarious data set organizations, as follows:
I
I
I
I
I indicate
1
I Bit Description
10
If on, indicates data set was created
1
using Write Validity Check
I
11-7 reserved
I
1
I
I
I
I
1
I
I
1
I
I
I
~------+-----------t--------------t--------t--------------+-------------------------------------------~
113
IBlock
IDSCBKS
12
I
I Length
I
1
1
I
bytes Ibinary
1
I
I
I
IBlock length for fixed-length records or
lmaximum block size for variable-length
I records (1-32,767 bytes).
I
1
I
~------t-----------t--------------t--------t--------------t------------------------------------------~
114
I
I
I Record
I Length
I DSCLRC
I
I
I
12 bytes Ibinary
I
I
I
1
IRecord length for fixed-length records or I
Ithe maximum record length for
I
lvariable-Iength records.
(1-32,767 bytes) I
t------f-----------t--------------t--------t--------------t-------------------------------------------~
115
I
1
IKey Length IDSCKLN
I
I
I
I
11
byte
1
I
(binary
1
I
ILength (1-255 bytes) of the key of the datal
Irecord in the data set. A value of zero
I
Imeans no key exists.
I
r------t-----------t--------------t--------t--------------t------------------------------------------~
116
I
I
IKey
iLocation
I
I
I
I
I
I
I!
I
I DSCRKP
12 tytes Ibinary
I
I
I
I
I
I
I
1
tHigh order position (byte 1 through byte
I
132,767) of the key in the data record. A I
Ivalue of zero indicates that the key is notl
lin the data portion but corresponds to the I
(physical key on the direct access volume.
I
~------t-----------t--------------+--------+--------------+-------------------------------------------~
1Data Set
I DSCDSI
11 byte I binary
I Eit Description
I
! 17
I
1
I
I
I
I
IIndicators I
I
I
I
I
I
I
I
I
I
1
I
I
1
I
I
I
11
I
I
I
I
I
I
I
I
I
12
I
I
1
I
I
I
I
I
I
1
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
!
I
I
I
I
I
I
I
I
I
I
1
IL ______ I
__________
Figure
9.
~
262
I
I
I
I
I
I
(
I
I
1
I
~
10
I
_____________ L ________
Format-l
Sr: are
1
I
I
If on, indicates that the block lengthl
must always be a multiple of eight
I
byt es .
I
1
13
I
If on, indicates that this data set isl
security protected and a password mustl
be Frovided in order to access it.
I
14
(Data Set Abnormal Close) i f on,
I
indicates that this data set may be
I
invalid due to abnormal termination ofl
a task which was writing or updating I
the data set.
1
I
I
1
I
I
I
I
~
If on, indicates that this is the lastl
volume which normally contains this
I
data set.
I
I 5- 7
I
Spare
I
I
______________ i __________________________________________ -J
DseE (Part 2 of 4)
r------T-----------T--------------,.-------T--------------T----------------------------------------------,
I Field I
I
' I
I
INumberlField Name lIdentificationlLength IRepresentationlUsage
I
,
..
~·------+-----------+--------------i---------+---------------+----- -------------------------------------~
IOriginal
I
IRequest E'orl
I
I
I
I Space
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
!!
I
I
I
I
I
i
I
!
I
,
I
I
I
I
I
I
I
I
I
I
{
I
I
I
I
I
I
I
I
I
I
!
I
I
' I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
lISa
,binary
IThis field indicates the type of request
I
I
I
I that was issued for the initial allocation: I
I
I
I
I
I
I
I
I
I '
I Bit lLescription
I
I
I
10,1 00 indicates original request was in
I
I
I
I
absolute tracks; no secondary
I
allocation is made.
,
I
I
I
I
I
I
I
I
I
I
01 indicates request is in number of
I
I
I
I
records.
I
I
I
I
I
' I
I
10 indicates request is in number of I
I
I
I
tracks.
I
I
I
I
I
I
I
I
11 indicates request is in number of
I
I
I
'cylinders.
I
I '
I
I
"
I 2
If on, indicates original request was I
I
I
!
for an indexed sequential data set
I
I
I
I
wi th embedded index.
I
' I
I
I
I
I
I 3
Spare
I
I
I
I
i
I
I
I 4
I f on, indicates that the original
I
I
I
I · r equest was for the maximum contiguous I
i
I
I
quantity on the volume.
I
I
I
I
I
I f on, indicates that the original
I
I
I
I 5
I
I
I
request was for the maximum contiguous I
I
I
I
quantity on the volume.
I
I
I
I
I
I
I
I 6
I f on, indicates that the original
I
I
I
I
request was for the five or fewer
I
I
I
I
extents that were larger than or equall
' I
I
to a specified minimum.
I
I
I
I
I
I
I
I 7
If on, indicates that the original
I
I
I
I
request was a record request and was
I
I
I
I
too be rounded upward to a cylinder
I
I
I
I
boundary.
I
11 byte
t------~-----------t-------------_+--------+--------------+----------------.---------------------------~
,lab
I secondary
I
IAllocation
I '
I
I
I
I
I DSCSAL
I
I
13 bytes Ibinary
I
I
I
I
I
I '
I
I
I
IThe three bytes of this field are a
I
I binary number indicating how many blocks, I
I t.racks, or cyl inders are to be requested at I
Ithe end of the initial extent when
I
I processing a sequential data set.
I
t------+-----------+--------------+--------+--·------------+------.-----------------------------------i
119
ILast RecordlDSCLRD
I
I
I
I
I Pointer
I
I
I
I
I
,
I
I
I
I
I
I
I
,
I
I
I
I
I
!
I
I
I
I
I
15 bytes !binary
!
I
I
I
I
I
I
I
I
I
,(Direct Access Address) -- identifies the I
Ilast record.
It is in the format TTRLL
I
t (where TT is the x'elati ve address of the
I
I track containing the last record, R is the I
110 on that track, and LL is the number of
I
Ibytes remaining on that track following thel
Irecord).
If all five bytes equal binary
I
Izeros, the last record pointer does not
I
laHlyI
~------+-----------+--------------+--------+--------------t-
.------------------------------------------i
120
ISpare
12 _______
bytes iI ____________ __ iI ___________________________________________ JI
l ______ L__________ iI DSCSP2
_____________ -L_.
Figure
9.
Format-l DSCB (Part 3 of 4)
Appendix A:
Data Set Control Block (DSCB) Format
263
r------T-----------T--------------r--------T--------------T-------------------------------------------,
I
I
I
I Field I
I
I
I Number I Field Name IIdentificationlLength
I
(Representation I Usage
~------+-----------+--------------t--------t--------------+-------------------------------------------~
121
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
IExtent TypelDSCxTS
I Indicator
I
IHex
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
j
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
11 byte Ihexadecimal
I
I
I
I
I!
!
I
I
I
I
I
t
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
(
I
I
I
I
I
I
I
I
I
I
I
I
I
(Bex Code
I 00
I
01
02
I
I
I
04
I
I
I
40
I
I
!
I
I
(81
I
I
I
I
Prime Areas (Index Sequential)
I
I
or consecutive area, that is, the!
I
extent containing the data rec- I
l o r d s (user's).
I
I
I
I
I
I
I
Meaning
I
Next three fields do not indicatel
any extent.
I
I
80
I
I
I
I
I
Overflow area of an indexed
sequential data set.
t
t
I
I
INDEX area of an Index Sequentiall
data set.
I
Next three fields indicate one
track is used to contain user's
data set labels.
The extent described is sharing
one or more cylinders with one
or more data sets.
The extent described begins and
ends on cylinder boundaries,
i.e., the extent is composed of
one or more cylinders.
I
I
I
I
I
I
I
I
I
I
I
I
I
~------+-----------t--------------t--------t--------------t-------------------------------------------~
122
I
I
I
I
I
I
I
I
I
I
I
I
I Extent
ISequence
I Number
I
I
I
I
I DSCMVL
I
I
I
I
I
I
I
I
1
I
I
I
I
I
I
I
I
I
11 byte Ibinary
IThis field uniquely identifies each
I
I
I
Iseparate extent on a given volume for a
I
I
I
Idata set. For all organizations but
I
I
I
lindexed sequential the first extent of the I
I
(
(data set on each volume is identified with I
I l i a zero in this field. The first extent on I
I
I
leach volume of an indexed sequential data
I
I
I
Iset is identified with a value of one in
I
I
I
Ithis field. Additional extents on the
I
I
I
I volume are identified with sequentially
I
I
I
lincreasing binary values. This field is
I
I
I
lalways zero for an extent field pointing tal
I
I
la user label track.
I
~------~-----------+_-------------t--------t--------------t-------------------------------------------i
123
I
I
ILower LimitlDSCLCH
I
I
I
I
14 bytes I
I
I
I
I
I (Direct Access Address) - the cylinder and I
Itrack address (CCHB) specifying the
I
Istarting point of this extent component.
I
r------t-----------t--------------t--------t--------------t-------------------------------------------~
124
IUpper LimitlDSCLCH
I!
I
I
I
I
14 bytes I
I
I
I
I
I (Direct Access Address) - the cylinder and I
Itrack address (CCBB) specifying the ending I
IFoint of this extent component.
I
125-28 IAdditional I DSCEX2
I
I Extents
I
I
I
129-32 IAdditional IDSCEX3
I
I Extents
I
110 bytes I
I
I
t------t-----------t--------------t--------t--------------t-------------------------------------------i
110 bytesl
1Same as fields 21-24.
I
I
I
~------+-----------+--------------t--------t--------------t-------------------------------------------i
ISame as fields 21-24.
I
t
I
~------t-----------t--------------+--------+__------------+-------------------------------------------i
IThis field contains the CCHBR of a
I
Icontinuation DSCB, if needed, to further
I
Idescribe the data set. The next DSCB will I
I
I
I
Ibe of the format-3 type. All zeros signify I
I
I
I
I
Ithat this is the last DseB.
I
I
I
I
I
I
1
I
I
I
I
I
I
I (If field 10 indicates Index Sequential
I
I
I
I
I
I Organization, this field will point to a
I
I
1______ I ___________ I ______________ I ________ I ______________ I format-2
DSeB.)
___________________________________________
JI
133
I
I
I
~
Figure
264
IPointer to
INext OSCB
1Record
I
I
~
IDSCCN3
I
I
~
9.
15 bytes I
I
I
I
I
~
~
Format-l DSCB (Part 4 of 4)
~
f-----,-----------.,---------------T--------T------------T---------------------------------------·--,
I Field I
I
I
I
I
I
iNumberiField Name IIdentificationlLength I Representation I Usage
I
.------t-----------+--------------t--------t--------------t-------------------------------------------~
11
!Key Identi-IDSVNME
14 bytes Ihexadecimal
1'03030303'
I
i
lfication
I
I
I
I
I
I
lCin key)
I
I
I
I
i
t------t-----------t--------------t--------t--------------+------------------------------------------~
12-17 I Extents
IOSCEX4
140 bytesl
Isame as fields 21-24 of format-1 DSCB.
I
I
I
I
IFour extents.
I
I
I (in key)
r-----+---------+--------------+--------+-------------+---------------..----------------------.----.;
11 byte I hexadecimal
I 'F3'
I
I
I
I
I
t-----t-----------+--------------+--------+--------------+------------------------------------------~
119-Sq iAdditional IDSCEX9
190 bytes I
ISame as fields 21-24 of Iormat-1 DSCB.
I
I
I
I
I Nine extents.
. I
I
I Extents
118
I
I Format
IOSCFID
I Identifier I
t-------t----------+--------------t--------+--------------+-----------------------------------------1
{Pointer to IDSCCHN
15 bytes I
ICCHHR for next format-3 DSCB.
I
155
I
!Next DSCB I
I
I
IZero in field signifies this is the last
I
Il ______ I ___________ I _____________ I ________ I ___________ ___ kI __________________________________________
Dsce.
I
~
Figure 10.
~
~
~
~
Format-3 DSCB
,..------T-----------T--------------T--------T--------------T----------------------------------------------,
I
I
IIdentificationlLength
IField IField
!Number!Name
I
I
IRepresentationlUsage
I
I
t----+-----------+--------------t--------+--------------+--------------------------------------------1
\1
IKey Field IVTC Key
Iqq byteslhexadeciroal
,"04's·
I
t------f-----------t--------------f--------t--------------+-------------------------------------------~
12
i Format ID ! VTCFID
11 byte I hexadecimal
I • F4'
I
~------+-----------t--------------+--------t--------------+------------------------------------------~
I
I prime
IHighest
IVTCHPC
I
15 tytes I
I
I
I
ICCHHR
1
I
I
13
IThis field contains the address of the lastl
lactive format-lor -A OSCB. It is used to i
Istop a search for a data set name.
I
r------f-----------+--------------t--------t--------------f-------------------------------------------~
I
I Available
I DSCB
! Records
I
I
I
I
i of the Next I
IAvailable I
I Alternate I
i Track
I
16
INumber of
I Alternate
! Tracks
14
I
IVTCHCT
I
1
12 bytes Ibinary
I
I
1
1
I
I
I
I
ICount of number of unused records in VTOC. I
I
I
I
I
I
I
I
I
I
I
I
I
t------+----------+--------------+--------+--------------+------------------------------------------.;
15
iThe CCHH
IVTCHCA
1q tytes I
I (See Note 1 in field 7.)
I
I
I
I
I
1-------+-----------+--------------+--------+--------------+--------------------------------------------~
I
I
i
I
I
I
IVTCNAT
1
I
I
I
12 bytes Ibinary
I
I
I
1
1
I
1
I
IThis fiE!ld contains the number of alternate I
itracks available. For the 2321 the
I
I assigned alternate area will be the last
I
I four strips in each cell. (See Note 1 in I
Ifield7.)
I
t------+-----------+--------------+--------t--------------+------------------------------------------~
IVTOC
IVTCFLl
11 byte 1
IBit 0 - If on, means that either no
I
17
!
I
I
I
I
I
I
I
I
I
!Indicators I
I
I
1
I
I
I
I
I
I
I
I
I
I
I
I
I
t
I
I
I
I
I
I
!!
I
i l l
I
I
I
I
I
I
i
I
I
I
I
I
I
i
I
i
I
I
I
I
I
1
1
I
I
I
I
I
I
I
Iformat-5 or -C DSCBs exist or that they do I
Inot reflect the true status of the volume. I
I
I Bi t 1 -
I
I f on, means that the format-C DSCBI
lis being used for storage management.
I volWIle is formatted for
I
The I
I
I
VAl'!.
IBit 2 - If on, indicates that the volume isl
ja system (putlicl volume, and should have I
I space allocated (by TSS/360) accordingly. I
I
I
IBits 3-7 - Spare.
I
I I !
I
!Note 1: Alternate tracks will be assigned I
I
I
I
I
lin ascending sequences. Thus, field 5 willi
I
I
!be incremented and field 6 decremented by I
I
I
I
I
I
lone when an alternate track is used.
1
t------+-----------+-------------+--------+---------------+------------------------------------------~
18a
INumber of IVTCNEX
11 byte Ihexadecirr,al
I This field contains the hexadecimal
I
i
I Extents
I
1
1
I constant • 01' to indicate one extent in the I
!I. _____ ..lI ___________ I ______________..l1________ I ______________ I VTOC
.
_________________________________________
JI
~
Figure 11.
~
~
Format-4 DSCB (Part 1 of 3)
Appendix A:
Data Set Control Block (DSCB) Format
265
r------T-----------T--------------T--------T-------------~-------------------------------------------,
IField IField
I
I!
I
I
IIdentificationlLength I RepresentationlUsage
I
I Number I Name
~------t-----------t--------------+--------+--------------+-------------------------------------------~
ISb
I Reserved
I VTC$02
12 bytes I
I
I
I
Ifor Future I
!
I
I
I
IUse
I
I
I
I
I
I
r------t-----------t--------------t--------t--------------t-------------------------------------------;
IDevice
IVTCDVC
114 byteslbinary
IThis field contains physical constants
I
19
I
I
1
I
r
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I Constants
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
' I
I
I
I
I
I
I
I
I
I
I
I '
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
' I
I '
I
I
' I
I
I
,
I
I
I
I
1
I
I
I
I
I
I
,
I
I
I
I
I
1
I
I
I
I
Il ______ I
~
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
Idescribing the device on which this volume
!was mounted ~hen the VTOC was created.
IThis field contains the follo~ing
I informa tioD:
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
i
I
I
II Overhead required for a keyed record
I other than the last record on the track.
I This is the first byte.
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
IK Overhead bytes to be subtracted from the I
I I and L tytes if the record does not have,
I a key field.
This is the third byte.
I
IFlag (1 byte) - Further defines unique
Icharacteristics of the device.
I
I Bit Descrif!-ion
10-4 Reserved for future use.
I
15
I
' I
I
I
I
I
I
I
I
I
16
CCHH of an absolute address (CCHS) is
used as four separate one-byte binary
values as in the case of the 2321.
A tolerance factor must be aFplied to
all tut the last record on the track.
I
I
I
17
I
I
I
I
I
I
I
I
~
DseB (Part 2 of 3)
CCHH of an absolute address (CCHH)
is used as a continuous binary value
as in the case of the 2301.
I
I
Format-4
I
I
I
IL Overhead required for a keyed record thatl
I is the last record on the track. This isl
I the second byte.
I
I
I
~
I
I
I
I
I
~
I
I
I
I
I
I
I
I
I
I
I
I
,
I
,
I
I
I
I
I
I
I
I
1
I
I
I
I
I
I
I
I
I
I
I
ITrack Length (2 bytes) - The number of
I
lavailable bytes on a track exclusive of
I
I hOIT,e address and record zero (record zero I
lis assumed to be a non-keyed record with ani
I eight byte data field).
I
I
I
IRecord Overhead (3 bytes) - The number of
I
Ibytes required for gaps, check bits, and
I
Icount field for each record. This value
I
Ivaries according to the record
I
{characteristics and thus is broken down
I
I into three subfields:
I
I
I
I
I
I
Logical Cylinder Size (2 bytes) - The
number of tracks in a logical cylinder
on this device.
I
I
I
I
I
,
I
I
Device si ze (2 bytes) - 'I'he number of
logical cylinders in a volume on this
device.
(A logical cylinder is the
smallest collection of t~o or more
tracks that can be protected by a Set
File Mask CCW.)
I
I
I
I
I
! !
I
I
I
I
I
I
I
I
I
I
I
I
I
,
I
I
__________ ______________ ________ ____________
Figure 11.
266
I
I
I
I
I
1
I
I
I
I
I
I
I
I
I
INote that if bits 5 and 6 are off, the cc I
land the HH of an absolute address (CCHHR)
I
tare used as half-word binary values as in
I
I the case of the 2311. ______________________ JI
--~---------------------
r------T-'----------T--------------,.--------T--------------T----------.
.·-------..-·-----·-------·--------,I
!Field 'field
I
I
I
t
I Number I Name
I Identification I Length
I Representation I Usage
f
I
I
i
I
I
!
I
i
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
!
I
I
I
I
I
I
I
I
I
I
110A
i Spare
IS-byte key and 256-hyte data lengtb that
lean be contained on one track of this
I device.
-------+--------+--------------t-----------·---------------------------·-----~
! VTC$04
119 bytes j
I
I
!
I
I
I
I
I
I
I
IAvailable
ISpace
I
I
t------+-----------+--------------t--------t--------------+-------------------------------------------1
!
I
I
I
I
ITo1erance (2 bytes) - A value that when
I
1
I
I
I
j
t-·...---·--t---·-·-------t------· .
I
I
I
I
I
I
I
I
I
i
I
I
I
I
1
I
I
I
Idivided by 512 is used to determine the
I effective length of the record on the
Itrack.
I
IDSCBS per track (1 byte) - Contains the
of full records of 44-byte key and
196-byte data length that can be contained
i on one track of this device.
! numbel:
I
I Directory blocks per track (1 byte) I Contains the number of full records of
I
I
I
t----·--f-----------+--------------t--------+--------------+-------------------------------------------1
110B
IGross
I
15 bytes Ihexadecimal
IRight-most four bytes indicate number of
I
I
I
I
I
I
1
1
I
I
I I !
I
I
!
I
I
I
I
I
I
I
I
I
I
I
I
!~ages available if it is a VA~ volume
I
I (field 1, bit 1 on); otherwise the first
I
I two bytes indicate the number of cylinders I
IloIhich are entirely free and the next two
I
Ibytes indicate the tracks not on the
I
lcyclinder which are free.
Left-most byte
I
I (X' FF') indicates space allocation by
I
ITSS/360 only.
I
I
~------f-----------t--------------+--------+--------------t-------------------------------------------i
!lOC
lPointer to IVTCPTR
15 bytes Ibinary
!This field contains the CCBBR of the first I
I
I Format-6
I
I
I
Iforrnat-6 DseB if i t exists.
Otherwise it
I
I
I DSCB
I
I
1
I conta i TIS binary zeros.
I
t-------+-----------f--------------+---·-----f---------_.----+-----------------------.------------------1
111-14 IVTOC
I
110 bytes!
IThese fields describe the extent of the
I
I
I
1 Extent
I
I
I
I
I
I
I
IVTOC, and are identical in format to fieldsl
J 21-24 of the fm:mat-l DSCB.
I
.------+-----------+--------------+--------+--------------+-------------------------------------------~
115
Spare
I ______________
VTC$05
125
bytes I
! ___________________________________________ JI
L ______ I ___________
________
__________
~
~
~
~
Figure 11.
----~
Format-4 DSeB (Part 3 of 3)
r------T-----------T--------------T--------T--------------T-------------------------------------------l
1
I
1
I
I
IField IField
!NumberlName
I Identificationl Length
I
IRepresentationlUsage
t------t-----------t--------------+--------f--------------+-------------------------------------------1
11
I Key Identi-I DASKEY
III bytes I hexadecimal
1•
I
05050~,05'
Ification
I
I
I
I
I
!
I lin Key}
I
I
j
I
I
~------+-----------+--------------+--------+---------.-----+-------------------------------------------~
12
IAvailable
IDASE1
15 bytes I
jExtent of space available for allocation tol
I
I Extent
I
I l i a dat.a set. First two bytes ~ relat.ive
I
! (in key)
I
I
I
I t rack address. Next. two bytes = number of I
I
I
I
I
1
I
If ull cylinders included in extent. The
I
I!
I
I
1
Ilast byte = number of tracKS in addition tol
I
I
I
1
I
I cylinders in the extent.
I
~------t-----------t--------------+--------+--------------+-------------------------------------------1
13-9
jAvailable
IDASE2
135 bytesl
ISall,e as field 2; they are in relative trackl
!
I Extents
I
I
I
I address sequence.
I
!
I (in Key)
I
1
1
I
I
~------+-----------+--------------f--------f--------------+-------------------------------------------1
110
Il"ormat
IDASFID
11 byte I hexadecimal
I'FS'
i
i
i Identifier 1
I
I
I
I
1
j-------+-----------+--------------+-----.-.
. -+--------------+------.--------..
-.... ------.--------------------1
IAvailable
ICASE9
190 bytesl
ISame as field 2.
There are 26 available
I
111-28
I Extents
I
I
I
I extent fields in this OSCB (.key and data). I
t------+-----------+--------------+--------f--------------+-------------------------------------------~
!29
IPointer to IDASCHA
15 tytes Ibinary
IThis field contains t.he CCHHR address of
I
I
I Next
I
1
I
I the next format- 5 OSCB if i t exists. It
I
!
IFormat 5
I
I
I
Icontdins
binary zeros otherwise.
I
l ______ ..L_.__________ _______ •• ______ ..L _________ _________ ... ____
•. _________ ... __ .... __________ ." __________________.1
i
~
Figure 12.
~
~_
Format-5 DSeE
Appendix A:
Data Set control Block (DSeB) Format
267
r------T-----------T--------------r--------T--------------T-------------------------------------------l
I
I
I
I
I
I Field I Field
I Number I Name
IIdentificationlLength IRepresentationlUsage
I
~------+-----------+-------------_+--------+--------------+-------------------------------------------1
11
IData Set
IDSVNME
144 byteslalphameric
ISame as format-I, field 1.
I
I Name
I
I
I (EBCDIC)
I
I
I
r------+-----------+--------------t--------+--------------+-------------------------------------------1
I Format
I DSVFID
11 byte
Ihexadecimal
I'FA'
I
12
I
I Identifier I
I
I
I
I
I
lUsed
I
I
1
1(1-366).
I
I
I Usage
I
I
I
I
1
I
I
I Number
I
I
l
I
r------+-----------+--------------t--------+--------------+-------------------------------------------1
13a
IDate Last
I DSVDLU
13 bytes!
IYDD, where Y=year (0-99) and DD=day
I
t------t-----------+--------------+--------+--------------+-------------------------------------------1
I 3b
I Rate of
I DSVROU
13 bytes I
I
I
r------+-----------+--------------+--------+--------------+-------------------------------------------1
14
I Volume
I DSVVSQ
12 bytes I binary
I SalT,e as format-1, field 4.
I
ISequence
I
I
I
1
1
I
t------+-----------t--------------+--------+--------------+-------------------------------------------1
15
Icreation
I DSVCRD
13 rytes Idiscontinuous ISame as format-1, field 5.
I
I
IDate
l
I
Ibinary
l
I
~------+-----------+--------------+--------+--------------+-------------------------------------------1
16
IExpiration IDSVEXD
13 rytes ldiscontinuous ISame as format-1, field 5.
I
I
I Date
I
I
I binary
I
I
t------+-----------+--------------+--------+---------------+-------------------------------------------1
I Number of I DSVNEX
11 l::yte
I
I
I
17a
I
I
I Extents of I
IVolume
I
I
I
I
IBytes Used I
l in Last
I
I Data Page
I
I
I
I
I
1
I
1
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
1 (EBCDIC)
1
I
I
I
lindex
I
I sequential I
I data set
I
I
I
I
I
I
I
I
I
I
I
I
I
IType
I
I
t------+-----------+--------------+--------+--------------+-------------------------------------------1
pb
INumber of
I DSVLPB
12 bytes Ibinary
ISane as format-1, field 7b.
I
I
r------+-----------+--------------+--------+--------------+-------------------------------------------1
18
ISystem codelDSVSCD
113 byteslalphameric
ISane as format-I, field 8.
I
r------+-----------+--------------+--------+--------------+-------------------------------------------1
18a
I PAD for
I DSVXPD
11 byte
I
I
I
I
1
r------t-----------+--------------+--------+--------------+-------------------------------------------1
I 9
I Spare
I DSV 01
16 bytes 1
I
I
t------+-----------+--------------+--------+--------------+-------------------------------------------1
I 10
I Jo'ile
I DSVFTP
12 l::ytes I
!X'7100' VAM Index Sequential
I
I
I
IX'7200' VAl'Sequential
I
I
IX'7300' VAM Partitioned Index Sequential
I
I
I
I
I
I
IX'7400' VA~ Partitioned Sequential
I
I
I
I
I
I
IX'7500' VAM Partitioned
I
~------+-----------t--------------+--------+--------------+-------------------------------------------1
I 11
I Record
I DSVRFM
11 byte
lbinary
ISane as format-I, field 11.
,
I
I Format,
I
I
I
I
~------+-----------+--------------+--------+--------------+-------------------------------------------1
I 12
IOption
I DSVOPC
11 byte
Ibinary
iSan,e as format-I, field 12.
I
I
I Codes
I
I
I
I
!
~------t-----------t--------------+--------+--------------+-------------------------------------------1
I 13
'Record
I DSVRCL
14 bytes Ibinary
ISa~e as fermat-l, field lQ.
1
I
ILength!
I
I
I
I
I
I
r------+-----------t--------------+--------+--------------+-------------------------------------------1
I 14
IKey Length IDSVKYL
11 byte
Ibinary
IsalI.e as format-I, field 15.
1
r------+-----------+--------------+--------+--------------+-------------------------------------------1
I 15
,Key
1 DSVKLC
12 bytes I binary
I SaIl1e as format-l, field 16.
I
I
iLocation
I
I
I
1
I
~------+-----------+--------------t--------+--------------+-------------------------------------------1
I 16
IData Set
I DSVDSI
11 byte
I binary
(Same as format-l, field 17.
I
I
I Indicators I
I
I
I
I
r------+-----------+--------------t--------+--------------+-------------------------------------------1
(Original
I
!1 l:yte I hexadecimal
IX'OO' No secondary allocation.
I
I 17a
(
(Request fori
I
I
I
I
ISpace
I
I
I
(
I
I Indicators (
I
I
I
I
I
~------+-----------+--------------+--------+--------------+-------------------------------------------1
117b I Secondary
I DSVSAL
13 l::ytes Ibinary
ISane as format-1, field 18.
I
Il ______ IAllocation
I ___________________________________________ JI
___________ I ______________ 1________ I __________
I
~
Figure 13.
268
~
~
~
Format-A DSCB (Part 1 of 2)
----~
r------T-----------T-------------,.--------T--------------T--'--------------------------------------,
jF'ield lField
I
I
I
. I
\
I Number I Name
I Identification \ Length IRepresentat~onlusage
I
t------+-----------+--------------t--------+--------------+------------------------------------------~
! 18
I Number of ! DSVNDP
I 2 bytes I
I
!
I
I
I
I
I
I Data Pages !
1-------+--,--------+--------------+--------+--------------+---------------.--------------------------~
! 19
INumber of I DSVDOP
12 bytes I
INumber of page in POD or index directory.
I
I
!Directory I
I
I '
I
i
I Pages
I
I
I
I
I
~---_i 19a 'Number of I DSVNOP
11 byte I
I
I
i
I Overflow
I
I
I
i
I
I
I pages
I
I
I
I
.
I
~-_----+-----------+--------------+--------+------_-------+-------------------------------------------1
I 20
ITotal
I DSVTNP
I 2 bytes I
I
I
I
I Number of I
I
I
I
I
I
I Pages Thus I
I
i
I
I
iFar!
I
I
I
i
I
I
IAssigned
I
I
I
I
I
~-_-----+-----------+--------------+--------t-----'---------+-------,------------------------------------~
! 21
I Extent
I
16 bytes I
I
I
~------+---------+-------------t--------t--------------+--------------------------------------------1
I 21a I
I DSVXTS
I
I
I Bits Description
I
I
I
I
I
I
I2
00 - pages are in use
I
!
I
I
I
I
I
01 = pages are not in use
I
! 21b I
I
I
I
I lit
number of continuous external pages I
I
I
I
116
first external page number
I
I 2Ie I
I 2ld I
I
I
I
116
first virtual page number
I
t------t-----------+--------------t-------+--------------+-------------------------------------------~
__+-----------+--------------+--.------+--------------t-------------------------------------------i
I 22- 25 IExtents
I
121t bytes I
I Four more extents.
I
r------+-----------+--------------t--------+--------------+-------------------------------------------1
I 26
INext OSCB IDSVWXT
15 cytes Ibinary
ICCHHR of a continuation DSCB (format-B).
I
I
I
I
I
I
I If there a.re no format-B DSCSs for the data I
!
I
I
I
1
Iset, then this field contains binary zeros·1
l ______ ~ __________ ~ ______________ ~ __ ,______ ~ __________ ----~------------------------------------------~
Fi.gure 13.
Format-A DSCB (Part 2 of 2)
r------,.-----------T--------------,.---------,.--------------T-----------------------------------------l
I Field I Field
jNumberlName
IIdentificationlLength
I
1
I
I
I Representation I Usage
I
I
I
I
I (in key)
I
I
I
I
I
I
I (in key)
I
I
I
I field 21.
I
I Identifier I
I
I
I
I
!
I
I
I
121.
I
t------+-----------+--------------+--------+--------------+-------.----------------------------------1
1
IKey Field I DSV1KY
12 bytes Ihexadecimal
,'OBOB'
I
!--------+-----------+--------------+--------+--------------+-------.------------------------------------1
I 2
I Extent
!DSV1Xl
Iq2 bytes I
(Seven extents as described in format-A
I
•
I
t------+-----------+--------------t--------+--------------+-------------------------------------------1
I 9
[Format
I DSV1ID
11 byte I hexadecimal
I'FS'
I
r------+-----------+--------------+--------+--------------+-------------------------------------------1
I lO-2 Q IExtents
I DSV1XZ
190 bytes I
115 extents as described in format-A, field I
I
.
~------+-----------+--------------+--------+--------------+-------------------------------------------1
I 25
IPointer to IDSV1NX
15 I:ytes Ibinary
ICCIlHR format. Binqry zero if there are no I
I
I Next for- I
I
I
I chained format-B DSCBs.
I
DseB J.I _____________ -J.I ___. _____ I ______________ I _______ .____________________________________JI
Il ______ J.Imat-B
___________
~
Figure 14.
~
Format-B DSCB
Appendix A:
Data Set Control Block (DSCB) Format
269
r------T-----------T-------------~--------T--------------T-------------------------------------------,
I
IField IField
I Number I Name
I
I Identificationl Length
I
I
j Representation I Usage
I
I
~------+-----------t--------------t--------t--------------t------------------------------------------~
I
I
1
1
I
2
I
1
2a
IKey Field
I (in key)
I
IDAVKEY
14 bytes Ihexadecimal
!
I
I'OCOCOCOC'
I
IDAVEl
1
14 bytes I
I
1
I
I
I DAVEll
I
I
I
I Bi ts
116
j
I
t------t-----------t--------------t--------t--------------t------------------------------------------~
I Extents
I (in key)
I
I
r------t-----------t--------------t--------t--------------t------------------------------------------~
1
I
I
I
I
Description
nUDlber of continuous external pages
1
~----+_----------+--------------t--------t-----------·---t-------------------------------------------~
I
2b
I
IDAVE12
I
j
116
I
first external page number
~------t-----------t--------------t--------t--------------+-------------------------------------------~
I
I
3-111 Extents
I(in key)
I DAVE 2
136 bytes I
Isame as field 2 above.
I
I
I
I
I
I
11 byte
I
Ihexadecimal
I
I'FC'
I
I
I
r------t-----------t--------------t--------t--------------t-------------------------------------------~
I 12
I
lFormat
IDAVFID
I Identifier I
t------t-----------t--------------t--------t--------------t-------------------------------------------~
I 13
I Spare
IDAVSl
13 bytes 1
I
I
r------t-----------t--------------t--------t--------------t------------~-----------------------------~
I 14-34lExtents
IDAVEB
184 bytes I
ISaDle as field 2 above.
I
I
I
IDAVEIF (last I
I
I
I
I
I
I ext ent )
I
I
I
I
r------t-----------t--------------t-------- t --------------+-------------------------------------------~
1 3~
I Spare
IDAVS2
13 bytes I
I
I
r------t-----------t--------------t--------t--------------t-------------------------------------------~
I 36
IPointer to IDAVCHA
15 bytes Ibinary
ICCHHR format. Binary zero if there are no I
I
jNext
I
I
I
Ichained format-C DSCBs.
I
I Format-C
I
I
I
I
IL______ I ___________
(DSCB)
I _____________ _ Ii _ _ _ _ _ _ _ _ i I _____________ _ iI ___________________________________________ ,I
~
Figure 15.
~
Format-C DSCB
r----T------T------------------------T-------T------------------------------------------,
(Bytel
ID I
Full Name
ILength I
Representation
,
I No. I
I
I (bytes) I
,
t----t------t------------------------t-------t------------------------------------------~
I OOIDSENME!Data Set Name
I 44
,
I
I
I
!
I
I
I
I
I
I
1
I
I
I
I
I
I
I
I
I
I
I
441DSESCDISystem Code
511DSEXPDIPad for Indexed
I
I Sequential
58IDSELPBINO. of Bytes in Last
I
IData Page
I
,
601 DSERFM I Record Forma t i
I
I
,
I
'I
1
,
I '
I
2
I
I
I
I
I
l
,
I
I
1
1
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I Indicator
I
I
2
I
I
1
'Spare
I
I
I
3
,
I
I
I
1
I
I '
I
1
I
I
I
I
2
I
I
I
I
1
I
I
I
I
I
I
621DSEFTPIFile Type
651DSERCLIRecord Length
681 DSEDSI 1Data Set Indica tors
691DSEKYLIKey Length
10 I DSEKLC I Key Location
721 DSESAI I Secondary Allocation
I
IL- ___
131DSESALISecondary
Allocation
I
i ______ i ________________________
~
Figure 16.
270
13
I
611DSEOPCIOption Codes
,641
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
Format-E DSCB (Part 1 of 2)
1
3
I
I
I
I
I
I
I
I
I
I
I
I
I
I
,
I
1
I
I
I
I
I
I
,
I
I
I
I
I
I
I
I
I
1
I
______ i _______________- - - - - - - - - - - - - - - - -_________ -J
r----T------T------------------------T-------y------------------------------------------,
ID
I
Full Name
I Length I
Representation
I
I Bytel
I No. I
I
I (bytes) I
I
r----+------+------------------------+-------+------------------------------------------~
I 76IDSENDPINo. of Data pages
I
2
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
!
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
78IDSEDOPINo. of Directory Pages
80 1DSENOP I No. of Overf low Pages
811 DSENVLI No. of Private Volumes
821DSETNPIData Set size at Close
I
I
I
851 DSECRD I Reference Date
I
I
881 DSEEXD I Change Date
I
I
911
I
I
I
961
I
!
I
I
I
I
I
i DSEENT I Page Entries (1
I
I
I!
II
841
I
I
I
I
I
I
2
1
1
2
I
I
I
I
I
I
I
I
I
I
I
I
I
I
!
I
!
I
I
I
I
I
I
1
3
3
I Spare
I
I
I
I
I
I Spare
I
I
I
I
i
I
I
I
I
I
I
I
5
I
I
IList of Vol.
IDs for volumes of a private I
I
I data set in 6-byte entries. Length is
I
Idependent on the value of DSENVL
I
I
I
I
I
word)
I
I Format:
I
I
I r-----T---y--------------T--------------, I
II
IIAP(2)
(2) IRel Vol No(2) I Ext Pg. No(16) I I
I l _____ J.I ___
J. _____________ ..l ______________ J I
2481DSECHNIPointer to Next DSCB
I
4
I
I
I
I
I
I
I
2521 DSETYP I DSCB Type
I
1
I
I
I
I
I
I
I
2531
I
I
1
1Spare
I
I
I
I
I
I
Il ____
2541DSECKSIchecksum
I ______
2 1J. __________________________________________ JI
..l ______ ..l ________________________ ..l
Figure 16.
Format-E DSCB (Part 2 of 2)
r----y-----y------------------------T-------y------------------------------------------,
IBytel
I
ILength I
I
I No. I
ID I
Field Name
I (bytes) I
Representation
I
t----+------+------------------------+-------+------------------------------------------~
!
0I
I
I
I List of volume IDs for volumes of a pri- I
i
I
I
I
I vate data set in 6-byte entries. variablel
!
I
I
I
Ilength field depending on value of DSENVL I
i
I
I
I
Ifrom the format-E DSCB.
I
I
I
I
I
I
I
I
I DSFENTI Page Entries
I
I Format:
I
I
I
I
I
I r-----T---y"--------------T--------------, I
I
lIAP(2) I
IRel Vol No(2) I Ext Pg. No(6) I I
I!
II
II
I
Il-----J.---J.----__________ ..l ______________ J I
I
I
I
I
I
I
I 2481
I Pointer to next DSCB
I
4
I Format:
I
I
I
I
I
I r-----T---y--------------y--------------, I
I
I
I
I
I I DSCE I
1
I
I I
I
I
I
I
IISlot I
I
I
I I
II
1
(4) J.I ___ ..lIRelVoINo(12)\ExtPg.
No(16) I II
I
II
II
IIIl _____
______________ ..l ______________ J
I 2521DSFTYPIDSCB Type
I
1
I
I
I
I
I
I
I
I
I 2531
I
I
1
(Spare
I
I
I
I
I
I
I
254 J.I ______
DSFCKS ..lI Checksum
2
I _________________________________________ -JI
lI ____
________________________ J.I ________
~
Figure 17.
Format-F DSCB
Appendix A:
Data set Control Block CDSCB) Format
271
APPENDIX B:
CATALOG SBLOCK FORMAT
Each member in the catalog data set is
comprised of an integral number of pages.
Each page is divided into 64-byte blocks,
called SBLOCKs, which serve as the basic
unit of storage within the catalog.
Each logical entity within the catalog
is comprised of a chain of one or more
SBLOCKs. These logical entities are:
• Indexes
• Generation Indexes
• Data Set Descriptors
• Sharing Descriptors
• Sharer Lists
Catalog service routines receive data in
varied parameter lists and pack it into
available SBLOCKs. Data is retrieved from
the catalog, via the LOCATE routine, in the
SBLOCK form. Various command language
service routines retrieve data in this
form.
SBLOCK Format
The first eight bytes of an SBLOCK
always have the same format. The last 56
bytes of an SBLOCK vary in format depending
on the logical entity which the SBLOCK is
part of.
Figure 18 shows the format of a generalized SBLOCK; Figures 19 through 25 illustrate specific SBLOCK formats.
r-------T-----T-------T--------------------------------------------------------T--------,
I Symbolic I
1
I
ILength I
IField #IBytesl m the
I format -1 and -] data set DSCBs. It is called
lonly by SAM CLOSE.
I BE
!
I
I
I
I
I
I
I
I
~--------------------t------t-------------------t-----------------------------------------------t-----1
1INDEX
ICZCFI Icatalog Services
I
1
1
I
1
I
1LOCATE
lCZCFL Icatalog Services
I
I
IConstructs chained index levels in the catalog. I AI
land creates new members within the catalog datal
I set.
I
I
I
ILocates and returns SB10CKs from the catalog.
leither by name or relative address.
I
I
~--------------------t------t-------------------t-----------------------------------------------t-----~
I
I AH
I
I
~--------------------t------t-------------------t-----------------------------------------------+-----~
IMERGE SAM
I
I
I
ICZCEE IESA
1
I
I
I
I
1
IReturns extents from physical sequential data
Isets passed to it by scratch or GIVBKSAM. and
Imerges them with the DADSM extents on their
1volume.
I BF
I
I
1Mounts , initializes, and builds PVT for all
lvolumes of a VAM private data set.
I CE
I
I
I
I
I
~--------------------+_-----t------------------_t-----------------------------------------------t-----~
IMOUNTVOL
I
ICZCAM IDevice Management
I
I
I
I
I
~-----------------~--t------t-------------------t-----------------------------------------------+-----~
IMTREQ
ICZCAA IDevice
I
I Management
I
I
I
I
I
I
IAlloc~es and mounts unit record devices, such
las disk or tape drives. used for private
Ivoluues. This routine can also be called by
Iprivileged system programs to obtain the
Isymbolic device address of a public volume.
1
I
I
I
I
lin designated virtual storage locations.
I Writes DSCBs, user labels. and end-of-file
Imarkers to sFecified addresses.
I
I
I
I
I CA
I
I
1
I
I
I
I
I
I
r--------------------t------t-------------------t-----------------------------------------------t-----i
ICZCFO IESA
IReads VTOC and places DSCBs and volume labels I BG I
I OBTAIN/RETAIN
1
I
I
I
I
I
I
I
I
I
r-------------------_t------t-------------------+-----------------------------------------------+-----~
ISends mount request messages to the system
I CB I
I operator. asking him to mount volumes or to
I
I
I
Iready unit-record devices. It also verifies
I
I
I
I
1
Ithe operator's reply and. for tape or direct
I
I
I
I
I
I access, checks the label of the newly-mounted I
I
I ____________________ L1______ LI ___________________ LIvoluRe.
L
______ _________________________________________ LI _____ JI
I PAUSE
I
Figure 26.
280
ICZCAC IDevice
I Management
1
I
I
Module Directory, Indexed Alphabetically by Module Title (Part 2 of
ij)
r------ -- -, -,------.-- --T------T-------'------- -----T------ ----,-,---- ,-----.. ---- -_._-----.------.------._-----·------T-----1
I
I Module I Type of
!Name
IService Routine
ITitle
I
lehart!
lID
i
iSynop;i<]
1-------------------+------+-------------------+-----'-.--------------'----.-------------------------+-----~
!READWRIT
ICZCEM
!
I
I ESA
j
IReads DSeE pages into virtcual storage and
Iwrite'~ DSCE or- PAT pages t.o external storage.
I BP
I
I
I
.------ -------------,--+----- -+--------------------+--------_._- ---------- ,._,-----,---. --...._--,---,- ,-_. --.------.--+-----~
I
I
I
I
I
I
I!
!
~---- ----------------+------, +----------- --------.-+ ---- "-, -.. ----- -- -,----,----'-------.. _.-, ---'-' ----------------+ --- --1
i RELEXPG
I CZCEN ! ESA
I Makes ext.<, rnal and DSCJ:l [Ja<]cs available to the I BL I
!system.
I
I
I
I
I
IRELEAS
ICZCAD IDevice
I
I Management
I
IInforms the system that the device upon
I CC
a rr ivate volume was mounted is no ... free I
Ifor other use. and notifies any task awaiting
I
!the freed device that it iei now available.
I
! which
~--------------------t------+-------------------t-----------------------------------------------+-----i
I RENAME
lCZCFZ ICatalog Services
I
I
I
t i l
~------------------
jRERIM
I
IChanges the name in the key field of a format
I-lor -A DSCE to the name specified for all
I volumes by the calling program.
!
I
I
BH
I
I
I
-t------t-------------------+ ----.---.-------------- -_.. --- ----- -- --------.------- -----,+ -----1
ICZCTR IServiceability Aids I Passe,; erIcr infcrmat~on between the RTAM
I
I
I subsyst,e![ and the subroutilJes VMER and VMSDR.
i HG
I
I
I
~--------------------t------t-------------------+-----------------------------------------------t-----i
ISAM SEARCH
ICZCEC
!
!
1
I
I
I
IESA
I
I
I
ICalled by either ALLOCATE or EXTEND to search
I the DADSM-DSCBs for available space to fill a
I request. The DAl)SM DSCBs are then updated to
I reflect the allocation.
I
I
I
I
EE
I
I
I
I
I---------------------+------t-------------------+-----------'------'----------·--------------------t-----~
!CZCES IESA
IDeletes datea set DSCBS on all volumes of a
I BC I
I
I!
Ispecified data set_ and assimilates the externall
I
I
I
I
Istorage tack into the available space
3
TDTSPO, primary allocation field of
JFCB 32
30
84
TDTSP2, secondary allocation field of
JFCB 32
temporary index (TINDEX) 77
TEST subroutine 36
time conversion 92
TINDEX (t:emporary index)
77
t.ype parameter
OBTAIN 38
RET.AIN 38
unlink trom shared page table 72
(see also DISCONNECT)
unit table 74
universal shareability 15
UNPACK subroutine 34
USERCAT SCAN routine (CZUFY)
24
flowchart 126
UNSHARE routine (CZCFV) 12
collective removal 14
flowchart 106
restrictions 13
selective removal 14
update mode 12
updating
DADSM-DSCBs 34
the POD 3
the SDT 86
UPDATE subroutine 34
user subroutine for SYSXBLD 78
utility programs 30
VAM buffer sizing 23
VAM data sets
adding to catalog 8
option codes 6
50
VAMINIT routine (CZCEQ)
flowchart 188
restriction 49
VAM volume
initializing, private 49
processing 31
routines 43
variahle allocation parameters 63
variable length indicator 63
Virtual Memory Allocation (VMA)
63
virtual memory allocation routine
(CZCGA)
64.221
CONNECT (CZCGA7)
70
DISCONNECT (CZCGA8)
71
EXPAND (CZCGA4)
68
FREEMAIN (CZCGA3)
67
GETMAIN (CZCGA2)
66
GETSMAIN (CZCGA6)
69
Virtual Memory Allocation, Small routine
(CZCHA)
74
flowchart 234
restrictions 75
Virtual Memory Environment Recording Edit
and Print (see VMEREP)
Virtual Meulory Error Recording (see VMER)
Virtual Memory Statistical Data Recording
(see VMSDR)
Virtual Memory Task Initialization
(see VMTI)
virtual fartitioned access method 3
virtual storage
allocation 67
1/0 operation aids
84
pOinter 63
release 67
VMl\ (Virtual Memory Allocation)
63
VMA (virtual memory allocation) routine
(CZCGA)
64
flowchart
221
VMAINIT 222
VMER routine (CZCRX) 86
flowchart 245
VMEREP routine (CZASE)
89
flowchart 253
VMSDR routine (CZCRY)
85
flowchart 244
restrict. ion 85
VMTI routine 3
volume label 30
volumes
containing physical sequential data
sets 30
containing virtual storage data sets 30
direct access 30
external 30
mounting 57
private 30
public 30
Voluree Table of Contents (VTOC)
30
VOLSRCH routine (CZCEH)
45
flowchart 163
restrictions 45
VPAM 3
VTOC, standard location of 30
VTOC, hole count 38
WRITDSCB routine (CZCEW)
flowchart 181
lWRITE subroutine
2WRITE subroutine
49
36
36
Index
289
GY28-2018-3
co
S;
U'l
-<
'".-+
U'l
:::r
Q)
-.
:::l
<0
U'l
-<
en
.-+
'"
"'"
Z
~
U'l
w
en
0
W
"
:::!,
:::l
.-+
'"C.
:::l
C
U'l
~
Gl
-<
r--)
co
~
0
.....
co
W
-
------ - - - --- - - ---
-- --
-~-,
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.4 Linearized : No XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37 Producer : Adobe Acrobat 9.13 Paper Capture Plug-in Modify Date : 2009:09:08 17:20:31-07:00 Create Date : 2004:03:10 14:20:48-06:00 Metadata Date : 2009:09:08 17:20:31-07:00 Creator Tool : HardCopy Format : application/pdf Title : Scanned Document Document ID : uuid:8c4006b2-38bf-4ec5-ac22-c68bde7a022a Instance ID : uuid:35a07987-98ab-46d1-937a-e782a0ea306f Page Count : 133 Creator : HardCopyEXIF Metadata provided by EXIF.tools