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