CDF Note No. 156 YBOS PROGRAMMERS REFERENCE MANUAL Version 4.00 18 May 1995 David Quarrie Brian Troemel CDF Computing Group Fermilab MS318 Batavia IL 60510 Tel: (312) 840-3975 DECnet Address: B0HOST::QUARRIE B0HOST::TROEMEL BITNET Address: "QUARRIE@FNALB0" "TROEMEL@FNALB0" _______ 1 PREFACE YBOS is based on two previous memory management systems, BOS and ZBOOK, developed at DESY and CERN, respectively. Version 1.00 was designed and implemented by:- V. Blobel II. Institute fuer Experimentalphysik University of Hamburg Notkestrasse 85 2000 HAMBURG 52 WEST GERMANY This Reference Manual describes the CDF implementation of YBOS which has been modified to run on a VAX or IBM and has several extensions added. CDF-156 YBOS (V4.00) Page 2 PREFACE TABLE OF CONTENTS 1 PREFACE . . . . . . . . . . . . . . . . . . . . . . 1 2 REVISION HISTORY . . . . . . . . . . . . . . . . . . 3 2.1 Differences between Version 4.00 and 3.00 . . . . 3 2.2 Differences between Version 3.00 and 2.00 . . . . 4 2.3 Differences between Version 2.00 and 1.00 . . . . 6 3 INTRODUCTION . . . . . . . . . . . . . . . . . . . . 7 3.1 Named Banks . . . . . . . . . . . . . . . . . . . 7 3.2 Work Banks . . . . . . . . . . . . . . . . . . . . 9 3.3 Comparison of Named Banks and Work Banks . . . . 10 3.4 Bank Storage . . . . . . . . . . . . . . . . . . 11 3.5 Protected Named Banks . . . . . . . . . . . . . 11 4 BANK TYPES . . . . . . . . . . . . . . . . . . . . 12 4.1 Access to Data within Bank . . . . . . . . . . . 12 4.2 Bank Types Parameter Definition File . . . . . . 12 5 ALIAS BANK NAMES . . . . . . . . . . . . . . . . . 13 6 SETS OF BANKS . . . . . . . . . . . . . . . . . . 13 7 SUBSETS OF BANKS . . . . . . . . . . . . . . . . . 13 8 USER ACCESSIBLE YBOS LOCATIONS . . . . . . . . . . 14 9 YBOS OPERATING MODES . . . . . . . . . . . . . . . 15 10 SUBPROGRAMS, FUNCTION VALUES AND ERROR CODES . . . 15 11 SHAREABLE IMAGES . . . . . . . . . . . . . . . . . 18 12 INITIALISATION SUBPROGRAMS . . . . . . . . . . . . 19 12.1 BOS77 - Initialise Basic YBOS Array . . . . . . 20 12.2 BOSAR - Initialise Secondary YBOS Array . . . . 21 13 SUBPROGRAMS FOR SINGLE NAMED BANKS . . . . . . . . 22 13.1 BCOPY - Copy a Named Bank to another Bank . . . 23 13.2 BCOPYG - Copy a Named Bank to another Bank and Garbage Collect . . . . . . . . . . . . . . . . 25 13.3 BGARB - Named Bank Garbage Collection . . . . . 27 13.4 BIGEST - Returns Largest Bank Number for Given Name . . . . . . . . . . . . . . . . . . . . . . 29 13.5 BLAST - Locate Last Bank In Current Chain . . . 30 13.6 BLINK - Create Index Work Bank For Named Banks . 31 13.7 BLOCAT - Locate a Named Bank with Bank Type . . 33 13.8 BMAKE - Create a Named Bank with Bank Type . . . 35 13.9 BMAKEN - Create a Named Bank with Bank Type if the Bank doesn't exist . . . . . . . . . . . . . 37 13.10 BMAKEG - Create a Named Bank and Garbage Collect 39 13.11 BTYMAK - Create a Named Bank with Bank Type Using String Descriptor . . . . . . . . . . . . . . . 42 CDF-156 YBOS (V4.00) Page 3 PREFACE 13.12 BTYMKG - Create a Named Bank - String Descriptor with Garbage Collection . . . . . . . . . . . . 45 13.13 BMOVE - Copy a Named Bank to another YBOS Array 49 13.14 BSMOVE - Copy a List of Banks to another YBOS Array . . . . . . . . . . . . . . . . . . . . . 51 13.15 BMOVEG - Copy a Named Bank to another YBOS Array and Garbage Collect . . . . . . . . . . . . . . 53 13.16 BRENAM - Rename Selected Named Banks . . . . . . 55 13.17 BRNALL - Rename all Specified Named Banks . . . 56 13.18 NBANK and MBANK - Create a Named Bank . . . . . 57 13.19 NLINK and MLINK - Locate a Named Bank . . . . . 59 13.20 NDROP and MDROP - Delete a Named Bank . . . . . 61 13.21 NPRNT and MPRNT - Print a Named Bank . . . . . . 62 14 SUBPROGRAMS FOR NAMED BANK INTERNALS . . . . . . . 64 14.1 BDATA - Return Data Index from Bank Index . . . 65 14.2 BDLEN - Return Length of Data . . . . . . . . . 66 14.3 BLENG - Return Length of Bank . . . . . . . . . 67 14.4 BNAME - Return Bank Name . . . . . . . . . . . . 68 14.5 BNEXT - Return Index of next Bank . . . . . . . 69 14.6 BNUMB - Return Bank Number . . . . . . . . . . . 70 14.7 BTYPE - Return Bank Type Word(s) etc. . . . . . 71 14.8 BTPACK - Pack Bank Type or Group Type Words . . 72 14.9 BTUNPK - Unpack Bank Type or Group Type Words . 74 14.10 BTYBLD - Build A Bank Type Header . . . . . . . 76 15 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS . . . . . 78 15.1 BDECAL - Declare Alias Name for Bank . . . . . . 79 15.2 BALIAS - Get Alias Name from Basic Bank Name . . 81 15.3 BBASIC - Get Basic Bank Name from Alias Name . . 83 15.4 BCANAL - Drop The Specified Alias Name . . . . . 85 15.5 BLOCAL - Locate a Named Bank using Alias Name . 86 15.6 BMAKAL - Create a Bank using Alias Name . . . . 87 16 SUBPROGRAMS FOR WORK BANKS . . . . . . . . . . . . 89 16.1 WBANK - Create a Work Bank . . . . . . . . . . . 90 16.2 WDATA - Return Data Index from Bank Index . . . 92 16.3 WDLEN - Return Length of Data . . . . . . . . . 93 16.4 WDROP - Delete a Work Bank . . . . . . . . . . . 94 16.5 WGARB - Work Bank Garbage Collection . . . . . . 96 16.6 WLENG - Return Length of Bank . . . . . . . . . 97 16.7 WLOCK - Lock Work Banks . . . . . . . . . . . . 98 16.8 WPRNT - Print a Work Bank . . . . . . . . . . . 99 16.9 WSETD - Set new Data Length of Work Bank . . . . 101 16.10 WUNLK - Unlock Work Banks . . . . . . . . . . . 102 17 SUBPROGRAMS FOR SETS OF BANKS . . . . . . . . . . 103 17.1 BLIST - Manipulate Bank Sets . . . . . . . . . . 104 17.2 BDROP - Drop Set of Banks . . . . . . . . . . . 106 17.3 BKEEP - Drop all except a Set of Banks . . . . . 107 17.4 BPHEAD - Print Headers of a Set of Banks . . . . 108 17.5 BPRNT - Print Set of Banks . . . . . . . . . . . 109 17.6 BSINDX - Return Index of lowest Bank given Set and Member Number . . . . . . . . . . . . . . . 111 CDF-156 YBOS (V4.00) Page 4 PREFACE 17.7 BSINQU - Inquire whether Bank belongs to Set . . 112 17.8 BSMEMB - Return Members of Bank Set . . . . . . 113 17.9 BSMNUM - Return Member Number of Bank in Set . . 115 17.10 BSNUMB - Return Number of Members in Bank Set . 116 17.11 BSINTR - Form a Bank Set Intersection . . . . . 117 18 SUBPROGRAMS FOR SUBSETS OF BANKS . . . . . . . . . 118 18.1 BSBADD - Add a List of Banks to a Subset . . . . 119 18.2 BSBALD - Add All Current and Future Banks to a Subset . . . . . . . . . . . . . . . . . . . . . 120 18.3 BSBALS - Add All Current Banks to a Subset . . . 121 18.4 BSBDRP - Drop a List of Banks from a Subset . . 122 18.5 BSBPRG - Drop All Banks from a Subset . . . . . 124 18.6 BSWRIT/BFSWRT - Write Logical Record, Subsets only . . . . . . . . . . . . . . . . . . . . . . 125 18.7 BSREAD/BFSRED - Read Logical Record and form Subsets . . . . . . . . . . . . . . . . . . . . 127 19 SUBPROGRAMS FOR ACCESS TO USER LOCATIONS . . . . . 129 19.1 BRESUS - Reserve User Location . . . . . . . . . 130 19.2 BRELUS - Release User Location . . . . . . . . . 131 19.3 BGETUS - Get Index to User Location . . . . . . 132 20 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT . . . . . 133 20.1 BAAPND - Append List of Banks to an Array . . . 135 20.2 BAREAD - Read Logical Record from Array . . . . 137 20.3 BAWRIT - Write Logical Record to Array . . . . . 139 20.4 BNREAD - Read Set Of Banks from Array . . . . . 140 20.5 BNWRIT - Write Set Of Banks to Array . . . . . . 142 20.6 BEREAD/BZREAD - Read Logical Record into Array . 143 20.7 BEWRIT/BZWRIT - Write Logical Record from Array 145 20.8 BLOPEN/BFOPEN - Open Logical Unit . . . . . . . 146 20.9 BLPYMT - Mount A Volume On A Tape Device . . . . 149 20.10 BLPYDM - Dismount A Volume From A Tape Device . 150 20.11 BLPYOP - Open A File On A Volume . . . . . . . . 151 20.12 BLPYCL - Close A File On A Volume . . . . . . . 152 20.13 BLCLOS/BFCLOS - Close Logical Unit . . . . . . . 153 20.14 BLREAD/BFREAD - Read Logical Record . . . . . . 154 20.15 BLPICK/BFPICK - Position Logical Record . . . . 156 20.16 BBPICK/BZPICK - Pick One Bank from Logical Record . . . . . . . . . . . . . . . . . . . . . 158 20.17 BLVERM - Specify a Logical Record Verify Mode . 159 20.18 BLWRIT/BFWRIT - Write Logical Record . . . . . . 160 20.19 BBPUSH - Write one Bank to Logical Record ** . . 161 20.20 BLPUSH - Push Logical Record ** . . . . . . . . 162 21 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT . . . . . 163 21.1 BDSAVE - Save YBOS Array Named Bank Region on Discfile . . . . . . . . . . . . . . . . . . . . 164 21.2 BDREST - Restore YBOS Array Named Bank Region from Discfile . . . . . . . . . . . . . . . . . 165 21.3 BDOPEN - Open Discfile for YBOS I/O . . . . . . 167 21.4 BDCLOS - Close Discfile . . . . . . . . . . . . 169 21.5 BDRBNK - Read a Single YBOS Bank from Discfile . 170 CDF-156 YBOS (V4.00) Page 5 PREFACE 21.6 BDRLST - Read Banks or List of Banks from Disc . 172 21.7 BDRNUM - Read Banks from Disc . . . . . . . . . 173 21.8 BDWBNK - Write a single YBOS Bank to Discfile . 174 21.9 BDWLST - Write Banks or List of Banks to Disc . 175 21.10 BDWNUM - Write Banks to Disc . . . . . . . . . . 176 21.11 BDUNIT - Specify new Logical Unit for Disc I/O . 177 21.12 BDRECL - Specify new Record Length for Disc I/O 178 21.13 BDLIST - Modify A Bank Set With All Banks On Disk . . . . . . . . . . . . . . . . . . . . . . 179 21.14 BDNEAR - Find The First Bank Number On Disk That Exceeds A Threshold . . . . . . . . . . . . . . 180 21.15 BDNLST - Return A List Of All Banks On Disk With A Given Name . . . . . . . . . . . . . . . . . . 181 21.16 BDBGST - Find Largest Bank Number On Disk For A Given Name . . . . . . . . . . . . . . . . . . 182 21.17 BDSMLL - Find Smallest Bank Number On Disk For A Given Name . . . . . . . . . . . . . . . . . . 183 21.18 BDJRNL - Turn On/off File Journaling . . . . . . 184 21.19 BDSEAR - Search A Disk File For A Target Bank . 186 22 SUBPROGRAMS FOR NAMED BANK VALIDATION . . . . . . 188 22.1 BVALID - Validate YBOS Array Named Bank Region . 189 22.2 BVALON - Turn On Bank Validation Mode . . . . . 190 22.3 BVALOF - Turn Off Bank Validation Mode . . . . . 191 22.4 BVALST - Select an Alternate Bank Validation Mode . . . . . . . . . . . . . . . . . . . . . . 192 22.5 BVALEX - Examine Named Bank Validation Flag . . 193 22.6 BCHECK - Check Extended Bank Header for Consistency . . . . . . . . . . . . . . . . . . 194 23 SUBPROGRAMS FOR YBOS ARRAY FREE SPACE MONITORING . 195 23.1 BMNSPR - Report Lowest Free Space Value. . . . . 196 23.2 BMNSPI - Initialize Lowest Free Space YBOS Header Word. . . . . . . . . . . . . . . . . . . 197 23.3 BFRSPC - Report Current Free Space Value. . . . 198 23.4 BSPACR - Report Length Of YBOS Array. . . . . . 199 24 UTILITY SUBPROGRAMS . . . . . . . . . . . . . . . 200 24.1 BAHEAD - Print all Bank Headers . . . . . . . . 201 24.2 BCONV - Convert YBOS Banks to and from VAX Representation . . . . . . . . . . . . . . . . . 202 24.3 BDUMP - Dumps YBOS Bank According to the Extended Bank Header . . . . . . . . . . . . . . 204 24.4 BERROR - Return Error Code for last YBOS Call . 206 24.5 BERLEV - Specify new YBOS Error Level . . . . . 207 24.6 BERMES - Print A Warning Message . . . . . . . 209 24.7 BGRBEX - Examine Named Bank Garbage Collection Flag . . . . . . . . . . . . . . . . . . . . . . 210 24.8 BIOERR - Return I/O Error Code . . . . . . . . 211 24.9 BOPTN - Specify Special Option . . . . . . . . . 212 24.10 BOSDP - Print YBOS Array . . . . . . . . . . . . 213 24.11 BOSTA - Print YBOS Status . . . . . . . . . . . 215 24.12 BPUNIT - Specify Print Unit . . . . . . . . . . 216 24.13 BPLIMT - Specify Print Limit . . . . . . . . . . 217 24.14 BPREST - Reset Bank Print Count . . . . . . . . 218 24.15 BVERSN - Check YBOS Version Number . . . . . . . 219 CDF-156 YBOS (V4.00) Page 6 PREFACE 24.16 BWLIMT - Specify Warning Message Limit . . . . . 220 24.17 NAMIND - Get Name-index for Bank . . . . . . . . 221 24.18 YBERMS - Print A Warning Message . . . . . . . 222 24.19 BWRTOF - Place YBOS Array in Readonly Mode . . . 223 24.20 BWRTON - Take YBOS Array out of Readonly Mode . 224 24.21 BCHINT - Convert Character*4 Variable To Integer*4 . . . . . . . . . . . . . . . . . . . 225 24.22 BINTCH - Convert Integer*4 Variable To Character*4 . . . . . . . . . . . . . . . . . . 226 APPENDIX A FORMAT OF NAMED BANKS APPENDIX B FORMAT OF WORK BANKS APPENDIX C BANK STORAGE APPENDIX D BANK TYPES D.1 EXTENDED BANK HEADER FOR BANK TYPE DESCRIPTION . . D-1 D.2 FORMAT OF THE BANK TYPE AND GROUP TYPE WORDS . . . D-2 D.2.1 Mono-Type Bank Example . . . . . . . . . . . . . D-3 D.2.2 Simple Mixed-Type Bank Example . . . . . . . . . D-4 D.2.3 More Complex Mixed-Type Bank Example . . . . . . D-5 D.3 BANK TYPE PARAMETER DEFINITION FILE . . . . . . . D-6 APPENDIX E LOGICAL AND PHYSICAL RECORD FORMATS E.1 PHYSICAL RECORD STRUCTURE . . . . . . . . . . . . E-1 E.2 LOGICAL RECORD STRUCTURE . . . . . . . . . . . . . E-3 APPENDIX F EXAMPLES F.1 MAIN PROGRAM IN STANDARD EVENT PROCESSING . . . . F-1 F.2 SIMPLE HISTOGRAM PACKAGE . . . . . . . . . . . . . F-3 CDF-156 YBOS (V4.00) Page 7 REVISION HISTORY ________ _______ 2 REVISION HISTORY 2.1 Differences between Version 4.00 and 3.00 (a) A Bank Subset functionality has been added. Subsets of banks are defined by lists of bank numbers which are associated with a single bank name. One Bank Subset is allowed per bank name. The members of a subset for a particular name are stored in a work bank maintained internally by YBOS. Bank subsets are used in conjunction with BSWRIT and BSREAD. BSWRIT acts just like BLWRIT except that only banks which are subset members for the current name are written to the logical record. BSREAD acts just like BLREAD except that read banks are placed in the appropriate bank subsets. The following subprograms (described latter in this document) have been added: BSBADD-add list, BSBALD-add dynamic all, BSBALS-add static all, BSBDRP-drop list, BSBPRG-drop all, BSWRIT-write logical record,BSREAD- read a logical record. (b) The internals of YBOS have been extensively reworked to improve performance. Thus most YBOS operations (such as BLOCAT or BMAKE) are 50-100% faster, whilst some others (such as sequences of BMAKE and BLOCAT with many banks of the same name) are significantly faster (up to 1000%). (c) The documentation has been updated to include all user-accessible YBOS Subprograms. CDF-156 YBOS (V4.00) Page 8 REVISION HISTORY 2.2 Differences between Version 3.00 and 2.00 (a) This document has been renamed to be a Programmers Reference Manual to better reflect its scope and intended audience. It has undergone a major revision, reflecting a change in philosophy whereby the details of the YBOS Bank formats (both for named and work banks) are better hidden from the casual user. Additional subprograms have been incorporated so that the user data within a bank, or components of the bank header may be accessed in a transparent fashion. (b) A Bank Type has been made an integral part of a YBOS Bank. This describes the internal format of the Bank, whether it contains Integer or Real*4 datawords etc., or a mixture of datatypes. It's purpose is to allow the automatic conversion of datatypes on machines of different architecture and internal representation of datatypes. The implementation is backwards compatible in that the basic Bank Structure is unchanged and all subprograms from previous Versions are unchanged. (c) Extra subprograms have been added to YBOS to deal with the Bank Type and to aid access to the data within a Bank or components of the Bank Header (Bank Name etc.). (d) Some User-accessible locations have been allocated within YBOS. These locations may, for example, be used to save work bank indices and to allow different modules within a program to access the same work banks. (e) Long Alias Names may be declared for Named Banks. A Bank having both an Alias Name and a Basic Name may be located by either. (f) Various Modes of Operation for YBOS may be specified. These Modes allow, for example, for Work Banks to be locked in place temporarily, or for the automatic reporting of error messages to be disabled. (g) All YBOS subprograms may be accessed as Subroutines or Integer Functions, where the function value is either a Success/Error Flag or a Bank Index. In both cases the Success/Error Flag is also located in the 2nd element of the appropriate YBOS array, and is therefore backwards compatible with previous Versions of YBOS. Subprogram BERROR has been added to allow the Success/Error Flag for the last YBOS call to be examined as an alternative either of the above. CDF-156 YBOS (V4.00) Page 9 REVISION HISTORY (h) Error Codes and Function Values are specified as Integer Parameters rather than numbers. These Parameters are defined in a Section of this Manual and an "Include" File for insertion into each program module accessing YBOS. (i) In an attempt to rationalise names, the convention has been made that YBOS subprogram names will commence with the letter B unless they refer to work banks, in which case they commence with W. Exceptions to this are NBANK, MBANK etc., which are retained for backwards compatibility. However the Disc-based routines have been renamed to commence with a B rather than a Y. (j) MLINK and NLINK have been modified such that they return the Index to the lowest numbered bank of the specified name if presented with a negative bank number. (k) BCOPY and BRENAM have been added. BCOPY copies the contents of a named bank to another bank, and BRENAM renames a named bank. (l) BKEEP has been added to enable all banks to be ______ dropped except for specified banks. (m) BAREAD and BAWRIT perform similar functions to BLREAD and BLWRIT except that the destination (or source) for the logical record is an array rather than being an I/O channel. (n) BEREAD and BEWRIT perform similar functions to BLREAD and BLWRIT except that the Logical Record is read into (or written from) an Array rather than a YBOS array. (o) YBERMS and BWARN have been added to enable error messages to be reported. (p) Several new subprograms for Bank Printing have been added (BAHEAD, BPHEAD). (q) For clarity, the previously named "Call Parameters" and "Return Parameters" have been renamed "Input Parameters" and "Output Parameters" respectively. CDF-156 YBOS (V4.00) Page 10 REVISION HISTORY 2.3 Differences between Version 2.00 and 1.00 (a) Bank Set Names may now be any Uppercase Alphabetic Character (A-Z) rather than just C,E,R,S and T (Version 2.00). (b) Secondary YBOS Arrays (JW) are now totally independent of the Primary YBOS Array (COMMON/BCS/IW). Previously the Bank Name Table and Hash Algorithm Table for all Arrays was held in IW. There is only one exception to this; That is for the YBOS Input/Output Subroutines. The Physical Record Banks are always kept in /BCS/IW independent of the array within which the Logical Record Banks appear (Version 2.00) (c) YBOS Arrays may be dumped to a Discfile and later restored from the file. This is intended to allow YBOS oriented histograms to be accessed by programs other than the originating one. In addition, individual Banks may be read from such Discfiles. Refer to the section on Disc Based YBOS for details (Version 2.00) (d) Several Checkwords have been included in the YBOS Header. These can be verified and hence provide some measure of protection against corruption (Version 2.00). (e) Several additional Subroutines are provided. These mainly are involved in the Discfile accesses mentioned previously and also in providing extra printout and debugging facilities (Version 2.00). CDF-156 YBOS (V4.00) Page 11 INTRODUCTION ____________ 3 INTRODUCTION YBOS is a memory management system and data structure that serves two main purposes:- (a) It enables a hierarchical event structure to be set up that allows rapid access to major subsections of an event. This data structure is simple and compact, introducing a minimal overhead in terms of space and time. Subsections (called banks) may be manipulated in the course of event processing, being extended, deleted or created so as to allow a flexible transition between the raw data and fully processed events. (b) It allows for modular programming while avoiding the explosion in work space that sometimes results. Portions of analysis programs may be written independently while sharing a global work area. As modules require work space they request it, releasing it before passing on to further processing modules. Basic data elements in the YBOS system are banks which may be either named banks or work banks. Banks consist of a header that identifies them and describes their size, and a data area that contains the user's data. Banks are always an integral number of Integer words long, although this does not imply any restriction in the format of the user's data. All indices to banks are Integer relative in the FORTRAN sense (i.e. relative to 1). In order to run YBOS, a computer must have an architecture where an INTEGER has at least 32 bits of storage and can contain at least 4 characters. 3.1 Named Banks Named Banks are identified by a 4 character bank name and a bank number. The bank name may be any 4 characters, there being no formal restriction to alphanumeric names, but it is highly recommended that names be declared such that they are printable. The bank number must be a positive integer. A named bank consists of two sections, a bank header and a data area. The bank header is managed by YBOS and, except in rare circumstances, should not be modified by the Application Program, while the data area may be used to store the particular data array desired by the application. Banks can be of variable length, having, if so desired, no data area. Once a bank has been created, the contents and length of the data area may be modified by the application program. CDF-156 YBOS (V4.00) Page 12 INTRODUCTION A bank is located by its index within an array (the particular array being defined by the user), and has both a primary bank index that points to the bank header and a data index that points to the start of the data area of the bank. This data index will only be setup if the bank is created with an extended bank header describing the internal format of the data area of the bank. This description may be used to perform automatic reformatting of banks when passing data between computers with different machine architectures and data representations. Lists or sets of banks can be set up that may be manipulated as a single entity. Thus the banks associated with one bank set name may be added to or deleted from those associated with another bank set name etc. Named banks may be created, located, deleted, associated with a set of banks, disassociated with a set of banks, and both read from and written to permanent storage in a form consistent with the logical and physical record structures described in Appendix E. Banks with the same name but different numbers are chained together by pointers contained within the bank header allowing rapid movement down such chains. Optionally a work bank (see next section) may be created containing the indices for all banks of a particular name allowing the bank indices to be determined by direct table lookup. When a named bank is deleted no automatic garbage collection is performed, but subprograms exist to do this explicitly. Garbage collection entails detecting any holes resulting from deleted banks and shuffling existing banks around to merge any non-contiguous holes together so as to maximise the available free space. Note however, that performing a named bank garbage collection may move some of the remaining banks such that their indices change. It is the application programs responsibility to relocate (determine the new indices of) the remaining banks (unless a table lookup work bank has been setup in which case this will be performed automatically). The detailed structure of a named bank is described in Appendix A. An Application Programmer can choose to ignore the detailed structure of the bank header, using subprogram calls to locate elements of interest to him, or may directly access the individual elements. The former approach is highly recommended since it will cause the program to remain compatible with any future versions of YBOS that might alter the format of the bank header. For the remainder of this document the bank name is referred to as NAME, being either a Character*4 variable or 4 character long quoted text string (e.g. 'FRED'). The bank CDF-156 YBOS (V4.00) Page 13 INTRODUCTION number is denoted by NR, being a positive integer. The bank index is denoted by IND and the data index is denoted by DATIND. 3.2 Work Banks Work banks are identified by an index only rather than by name. They consist of a work bank header and user data area. As in the case of named banks, the user data area can be of variable length and may be modified after creation of the work bank. A name may be associated with a work bank but its only function is as a debugging aid in reading dumps, etc. Work banks may only be created, deleted or modified. None of the other functions (association with a set of banks, Input/Output etc.) allowed for named banks are supported for work banks. In particular, no detailed description of the internal data structure of a work bank is supported. In contrast to the case of named banks, an automatic garbage collection will be performed automatically if necessary, ______ unless YBOS is explicitly set into a mode where any movement of work banks is inhibited. Thus work banks may be relocated transparently without the Application Program being informed (except as noted above). The contents of the variable containing the index of the bank will automatically be modified if the work bank is moved through garbage collection ____ operations. Note however, that only the contents of this single variable will be modified, not any other variables that, through the use of assignment statements, might have contents depending on this variable. YBOS provides the facility for a work bank to be setup to contain the indices to all the named banks having a particular name. This allows the use of this direct table lookup in locating thes banks. Such a work bank will be automatically updated by YBOS if new named banks (with that name) are created or if the banks are moved through explicit garbage collection operations on the named bank storage area. Also in contrast to named banks, a work bank can keep track independently of the both total length and the data area length of the bank. This allows the possibility of modifying the length of the data area (within the limits determined by the total length) without moving the work bank or creating gaps that might get removed through garbage collection operations. Thus a guaranteed data area maximum length may be setup. The detailed structure of a work bank is described in Appendix B. CDF-156 YBOS (V4.00) Page 14 INTRODUCTION 3.3 Comparison of Named Banks and Work Banks In typical applications named banks will be used for all long-living data (input, output, communication between program modules) while work banks will be used for short-lived data (intermediate results and communications inside a module). CDF-156 YBOS (V4.00) Page 15 INTRODUCTION Comparison of Named Banks and Work Banks +----------------------------------------------------------+ | | | | Named Banks | Work Banks | | | | +----------------------------------------------------------+ | | | | Stored from the low index | Stored from the high index | | part of each array | part of each array | | | | | No automatic garbage | Automatic garbage | | collection | collection | | | | | No automatic update | Automatic update of | | of pointer to Bank | pointer to Bank | | | | | Input/Output | No Input/Output | | | | | Extended Bank Header | Short Bank Header | | with Bank Type allowing | No Machine Independence | | Machine Independence | | | | | +----------------------------------------------------------+ 3.4 Bank Storage Both named and work banks may be stored in one of several arrays, usually (but not necessarily) Common Blocks. There is one basic array IW in Common Block /BCS/, and additional arrays KW may be used if desired. Such arrays are totally independent and self-contained. There are no ______ cross-connections between them except in one case. That is for Sequential Input/Output where the primary YBOS array in Common /BCS/ must always have been initialised irregardless of which array the data to be read to or written from. The detailed layout of a YBOS array is described in detail in Appendix C. 3.5 Protected Named Banks In order to allow some banks to be protected from being dropped during normal cleanup operations, named banks whose names begin with either a "+" character or "$" character (e.g. '+DSK' or '$SAV') can only be dropped individually, not in conjunction with a list of banks. CDF-156 YBOS (V4.00) Page 16 BANK TYPES ____ _____ 4 BANK TYPES Version 3.00 of YBOS allows the Bank Header to be extended to include the concept of a Bank Type. This describes the internal data format of the Bank; whether the data is Integer, Real*4 etc. or a mixture of datatypes. The intention is to allow for the automatic conversion of datawords for machines with different architectures and data representations. The implementation of the extended Bank Header to include the Bank Type descriptors is backwards compatible such that all existing YBOS routines and subroutines are unchanged. Extra subprograms have been added to provide access to the various sections of the Bank Header and to the data within a Bank. The detailed format of the extended bank header is given in Appendix B. 4.1 Access to Data within Bank Since the length of the extended Bank Header (including Bank Type and Group Type words) can vary depending on whether the Bank is Mono-Type or Mixed-Type, additional subprograms have been added to YBOS to allow components of the Header to be accessed, as well as the base Index of the Data. For the remainder of this document, the Base Index of the Data is given the name INDDAT, and is defined such that JW(INDDAT) contains the first dataword in the Bank. An example of how to access data within a Bank is given in an Example in Appendix F. It is strongly recommended that an Application Program follow this example. 4.2 Bank Types Parameter Definition File An Include File defining the standard bank data types has been setup. This is described in detail in Appendix B. CDF-156 YBOS (V4.00) Page 17 ALIAS BANK NAMES _____ ____ _____ 5 ALIAS BANK NAMES A problem with YBOS (Versions 1.00 and 2.00) is that Bank Names are limited to 4 alphanumeric characters. This is a severe handicap in assigning a name having nmemonic value to a YBOS Bank. In an attempt to overcome this problem, Version 3.00 allows an Alias Name to be defined for each Bank Name. Internally YBOS uses just the 4 character basic Bank Name, but the Application Programmer may declare an Alias Name of up to 32 alphanumeric characters in length. Subprograms have been added that enable this declaration, and return the basic Bank Name given the Alias Name. In addition, an extra routine has been added to locate a Bank via its Alias Name. This just combines the functions of the Name translation routine and the normal Bank location routine and therefore has some extra overhead involved. All other Named Bank access subprograms described in the following sections utilise the basic 4 character Bank Name. ____ __ _____ 6 SETS OF BANKS Sets of banks are defined by lists of bank names which are associated with a single character. This set may be handled as a single entity, being read from permanent storage, expanded or reduced in scope, copied or appended to other sets or dropped by single subprogram calls. Subprograms exist for simple bank set manipulations and inquiries, as well as for more complex input/ouput operations with bank sets. The typical environment for the use of such sets is one where an event record is read, analyzed in such a way as to add extra information (in the form of banks) to the event (or perhaps delete redundant banks), and is then written to further permanent storage. 26 different sets may be defined, each being specified by a single uppercase letter (A-Z). The "*" is used to indicate all bank names. _______ __ _____ 7 SUBSETS OF BANKS Subsets of banks are defined by lists of bank numbers which are associated with a single bank name. One Bank Subset is allowed per bank name. The members of a subset for a particular name are stored in a work bank maintained internally by YBOS. Bank subsets are used in conjunction with sequential input/output routines in which only banks that are subset members for the specified names are read/written. Subprograms (described latter in this document) have been added for simple bank subset manipulations, such as add and deleteing banks from subsets, as well as for more complicated CDF-156 YBOS (V4.00) Page 18 SUBSETS OF BANKS input/output. ____ __________ ____ _________ 8 USER ACCESSIBLE YBOS LOCATIONS A common situation is that one module in a program creates a work bank (e.g. containing the indices of a set of named banks). YBOS only keeps track of the location containing the index to the work bank, updating its contents if the work bank is moved due to a garbage collection etc. Consider the following code fragment:- STATUS = BLINK(JW,NAME,NRMAX,IND) JND = IND STATUS = WGARB IND contains the Index to the created Work Bank, and the contents of IND will be modified by YBOS if the call to WGARB moves the work bank. However, JND will only contain the old index to the work bank and its contents will not be automatically updated if the work bank has moved through the call to WGARB. Attempting to access the work bank via JND is therefore unreliable and dangerous. Version 3.00 of YBOS allows work banks to be explicitly locked such that they cannot be moved by garbage collections. In order for several subroutines to access the same work bank, the pointer to the work bank (IND in the above example) must either be transferred as a parameter of each subroutine call, or a Common Block setup, within which IND resides. While the former technique (parameter to subroutine call) is preferred, there are situations where it is inappropriate. Version 3.00 allows cooperating modules to utilise locations within YBOS itself for performing the transfer of these pointers between themselves. The mechanism is for a reservation to be attempted of a User accessible location. If this reservation is successful, then the location may be used; if unsuccessful, then another location should be tried. Other subroutines can access, but should not modify, the reserved locations. Note, however, that there is no formal protection to prevent illegal access to reserved locations. The use of the User accessible Locations is not limited only to the above function, but can be for more general communications between program modules. 32 such User accessible Locations are defined within YBOS. CDF-156 YBOS (V4.00) Page 19 YBOS OPERATING MODES ____ _________ _____ 9 YBOS OPERATING MODES Version 3.00 introduces the concept of YBOS operating modes. Various modes of operation for YBOS may be setup on request through the use of subprogram calls. The following modes may be affected:- (a) Work Bank Locking. Normally YBOS has the freedom to move Work Banks so as to optimise the available space. This movement takes place transparently to the Application Program and can give rise to problems in certain instances. To prevent this, the Application Program may "Lock" all Work Banks for the duration of a critical piece of code, and then later Unlock them. Note that the default is for work banks to be unlocked. (b) Error Message Reporting. The YBOS error level may be specified so as to control the printing of error messages. The error level may take on the following values:- Level 0 Disable all automatic error message reporting Level 1 Print error message Level 2 Print short error message and dump YBOS array (omitting the contents of banks). Level 3 Print error message and perform full dump of YBOS array, including bank contents. The default is Level 1. ____________ ________ ______ ___ _____ _____ 10 SUBPROGRAMS, FUNCTION VALUES AND ERROR CODES The following sections describe in detail the Programmer's Interface to the YBOS Package. All subprograms may be accessed as Integer Functions where the Function Value is either:- (a) An Error Code as described below. (b) A Bank Index. In both cases the Error Code is made accessible to the caller in the 2nd element of the appropriate YBOS array, and in addition, subprogram BERROR may be used to return the Error Code from the previous YBOS call. CDF-156 YBOS (V4.00) Page 20 SUBPROGRAMS, FUNCTION VALUES AND ERROR CODES The caller should refer to the Error Code by name rather than number, these names being defined in an "Include" file to be inserted in the header section of each program module (subroutine or function) that accesses YBOS subprograms. For VAX installations these Error Code Parameter Definitions reside in file:- YBOS$Library:ErrCod.Inc For non-VAX installations consult your local YBOS expert. The following Error Codes are defined:- YESUCC Successful Completion YECORR YBOS array header corrupted YEILUN Illegal Logical Unit No. YEIOUS Using Input/Ouput for Output/Input YEEOF End-of-File Detected on Input YELROF Logical Record too big for Space YELRLN Logical Record Length Error YEPRBD Bad Physical Record YEBKOS Bank out of Sequence on Input YEBKXD Bank Length exceeds Data on Input YEBKNG Negative Bank Length YEBKTS Bank Length too small YEBSIL Illegal Bank Set Name YELRZL Attempting to write zero length record YEILOP Illegal Operand YEOVRF Insufficient Space (Overflow) YEBKSP Insufficient Space to extend Bank YENOBK Non-existent Bank Name YENONR Non-existent Bank Number YEMANY Too many Bank Names YEUSAR Using Basic Array with BOSAR CDF-156 YBOS (V4.00) Page 21 SUBPROGRAMS, FUNCTION VALUES AND ERROR CODES YEILUS Illegal User Location No. YERSUS User Location No. already reserved YENRUS User Location No. not reserved YEDUPB Attempt to create Duplicate Bank YEWLOK Work Banks Locked YEILLA Illegal Alias Name YEDUPA Duplicate Alias Name YEBKOV Insufficient space to create bank YEBTIL Unrecognized bank Id YEGRIL Unrecognized group Id YECHKF Internal consistancy check failed YESTOF Stack limit exceeded YENOTA Data not alligned YEBNKP Bank padded with extra words YEINDX Corrupted bank index warning...BVALID YEBDCH Corrupted bank chain...BVALID YEBDBK Corrupted bank header word...BVALID YEBDLU Corrupted Blink lookup work bank...BVALID YEBDBS Corrupted binnary search bank...BVALID YEDKOP Unable to open diskfile YEDKWT Unable to write to diskfile YEDKRD Unable to read diskfile YERSTF Diskfile dictionary restore failed, rebuild to follow The relationship between these Error Codes as Parameters and the actual Integer Numbers represented by them may be installation dependent and, in particular, may not be ________ backwards compatible. Application Programmers are strongly recommended to use the Parameters rather than Numbers when testing Error Codes. CDF-156 YBOS (V4.00) Page 22 SHAREABLE IMAGES _________ ______ 11 SHAREABLE IMAGES The YBOS object library exist in the form of a shareable. This shareable image is linked with a finit number of Common YBOS array (BCS) shareable images. The application selects a BCS array size when the YBOS logicals are SETUP. The allowed BCS sizes are 16K, 32K, 64K, 128K, 256K, 512K, 1024K. The advantage of linking against the YBOS shareable image is that link time is reduced and applications need not be relinked to get the latest bug fixes. To link against the shareable image do the following: $SETUP/SIZE="one of the allowed sizes...eg 16K" YBOS $LINK "Your application", YBOS$LIBRARY:YBOSOPT/OPT CDF-156 YBOS (V4.00) Page 23 INITIALISATION SUBPROGRAMS ______________ ___________ 12 INITIALISATION SUBPROGRAMS Each array to be used by YBOS has first to be initialised by a call to the appropriate initialisation subprogram detailed below. Note that for YBOS Version 2.00 onwards, it is no longer necessary that BOS77 be called, even if only a secondary YBOS Array is in use. The following descriptions assume the following array definitions:- COMMON/ BCS /IW(ndim) INTEGER IW DIMENSION KW(jdim) INTEGER KW The generic array JW is used to refer to either the basic YBOS array IW or to a secondary array KW. Note that some of the subprograms described in the next sections may have special options or may produce an error code. Special options may be selected by calling the option setting subprogram BOPTN immediately before calling the required subprogram. Such special options are always reset to the defaults on return from each subprogram. Any error code produced by a subprogram may be found after return in the second element JW(2) of the appropriate YBOS array (as an alternative to the Function Value). It may either be accessed directly, or by accessing subprogram BERROR, which returns the error code of the previous YBOS call. The following initialisation subprograms are available:- BOS77 Initialise basic array in COMMON/BCS/ BOSAR Initialise user specified secondary array. CDF-156 YBOS (V4.00) Page 24 INITIALISATION SUBPROGRAMS 12.1 BOS77 - Initialise Basic YBOS Array This subprogram is used to initialise the basic YBOS array in COMMON/BCS/. _______ ________ Calling Sequence STATUS = BOS77(NDIM,NAMX) _____ __________ Input Parameters NDIM (Integer) The size of the basic YBOS array (in Integer words). NAMX (Integer) The maximum number of different names of banks. The default is 128, being specified by NAMX being set to zero. ______ __________ Output Parameters None ________ _____ Function Value BOS77 (Integer) YESUCC Success YEOVRF Insufficient Space N.B. 1. It is the programmers responsibility to correctly dimension the array in COMMON/BCS/. ______ 2. This subprogram should always be called before any other YBOS subprograms involving the basic YBOS array in COMMON/BCS/. 3. In the event of an error (insufficient space) then a warning message will be printed. In this case, the Application Program should terminate cleanly since the integrity of the YBOS array following this error is suspect. CDF-156 YBOS (V4.00) Page 25 INITIALISATION SUBPROGRAMS 12.2 BOSAR - Initialise Secondary YBOS Array This subprogram is used to initialise a secondary YBOS array. _______ ________ Calling Sequence STATUS = BOSAR(KW,NDIM,ARNAME,MAXNAM) _____ __________ Input Parameters KW Secondary array name. NDIM (Integer) The size of the array (in Integer words). ARNAME (Character) The array name (max 8 characters). MAXNAM (Integer) Max Number of bank names (Optional on VAX or IBM) ______ __________ Output Parameters None ________ _____ Function Value BOSAR (Integer) YESUCC Success YEOVRF Insufficient Space YEUSAR Using Basic Array N.B. 1. It is the programmer's responsibility to correctly dimension the array KW. 2. The array name ARNAME is used purely for debug printouts, etc. 3. In the event of an error (insufficient space) then a warning message will be printed. 4. If the user attempts to initialise the basic YBOS array IW in COMMON/BCS/ using BOSAR then he will receive an error message and no further action will be taken. 5. In the case where an error return occurs, the Application Program should terminate cleanly since the integrity of the YBOS array following these errors is suspect. 6. The MAXNAM argument is optional in VAX or IBM environments. If it is not specified, a default value of 128 is used. CDF-156 YBOS (V4.00) Page 26 SUBPROGRAMS FOR SINGLE NAMED BANKS ___________ ___ ______ _____ _____ 13 SUBPROGRAMS FOR SINGLE NAMED BANKS Some of the following subprograms have two versions, one applicable to manipulations on banks in the basic YBOS array in COMMON/BCS/, the second applicable to bank manipulations within secondary arrays. The following subprograms are available:- BCOPY Copy contents of a named bank to another BCOPYG Copy a named bank to another & garbage collect BGARB Perform garbage collection for named banks. BIGEST Returns largest existing bank number for the given name. BLAST Locat last bank in current chain. BLINK Create work bank containing indices of named banks. BLOCAT Locate a named bank with bank type BMAKE Create or extend named bank with bank type BMAKEN Create named bank with bank type BMAKEG Create named bank & garbage collect BTYMAK Create named bank with bank type using string descriptor BTYMKG Create named bank using string descritor & garbage collect BMOVE Move a named bank to another YBOS array BSMOVE Move a bank set to another YBOS array BMOVEG Move a named bank & garbage collect BRENAM Rename Bank NBANK ) Create named bank or change length of MBANK ) existing bank. NLINK ) MLINK ) Get index of named bank. NDROP ) MDROP ) Drop (delete) named bank. NPRNT ) MPRNT ) Print named bank. CDF-156 YBOS (V4.00) Page 27 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.1 BCOPY - Copy a Named Bank to another Bank This subprogram may be used to copy the contents of an existing named bank to another bank. _______ ________ Calling Sequence STATUS = BCOPY(JW,NAMSRC,NRSRC,NAMDST,NRDST,IND,INDDAT) _____ __________ Input Parameters JW Secondary array name NAMSRC (Character*4) Source Bank Name NRSRC (Integer) Source Bank Number NAMDST (Character*4) Destination Bank Name NRDST (Integer) Destination Bank Number ______ __________ Output Parameters IND (Integer) Index to the Destination Bank INDDAT (Integer) Index to data of Destination Bank ________ _____ Function Value BCOPY (Integer) YESUCC Success YENOBK Non-existent Bank YEOVRF Insufficient Space to create Bank YEBKSP Insufficient Space to extend Bank N.B. 1. INDDAT is defined such that JW(INDDAT) contains the first dataword following the Bank Header of the destination bank. 2. This Subprogram will perform a Work Bank Garbage collection if insufficient space is available. The Application Program may prevent this via a prior call to WLOCK. 3. If insufficient space remains following any Work Bank Garbage collection, in addition to returning an error code, the IND and INDDAT parameters will be set to zero. The Application Program may try again after performing a named bank garbage collection (BGARB). 4. No action will be performed if the destination bank is identical to the source bank (i.e. NAMSRC and NAMDST are identical, and NRSRC and NRDST are identical). However, IND and INDDAT are correctly returned in this situation. CDF-156 YBOS (V4.00) Page 28 SUBPROGRAMS FOR SINGLE NAMED BANKS 5. The destination bank will be created with the length required to accommodate the source bank. If the destination bank already exists, all information within the bank will be overwritten by the contents of the source bank. 6. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 29 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.2 BCOPYG - Copy a Named Bank to another Bank and Garbage Collect This subprogram operates identically to the BCOPY Subprogram except in the instance where there is insufficient room to create the specified bank. Whereas BCOPY will immediately signal an error, BCOPYG will perform an implicit Garbage Collection of the Named Bank region (BGARB) and try again, only signalling an error if it fails on the second attempt. _______ ________ Calling Sequence STATUS = BCOPYG(JW,NAMSRC,NRSRC,NAMDST,NRDST,IND,INDDAT) _____ __________ Input Parameters JW Secondary array name NAMSRC (Character*4) Source Bank Name NRSRC (Integer) Source Bank Number NAMDST (Character*4) Destination Bank Name NRDST (Integer) Destination Bank Number ______ __________ Output Parameters IND (Integer) Index to the Destination Bank INDDAT (Integer) Index to data of Destination Bank ________ _____ Function Value BCOPYG (Integer) YESUCC Success YENOBK Non-existent Bank YEOVRF Insufficient Space to create Bank YEBKSP Insufficient Space to extend Bank N.B. 1. INDDAT is defined such that JW(INDDAT) contains the first dataword following the Bank Header of the destination bank. 2. This Subprogram will perform a Work Bank Garbage collection if insufficient space is available. The Application Program may prevent this via a prior call to WLOCK. If Insufficient space exists after work bank garbage collection, named bank garbage collection will occur. In this case, named banks must be relocated. CDF-156 YBOS (V4.00) Page 30 SUBPROGRAMS FOR SINGLE NAMED BANKS 3. To examine whether implicit named bank garbage collection has occured, call BGRBEX. For example, STATUS = BGRBEX(JW,FLAG) (Reset the garbage collection flag) STATUS = BCOPYG(JW...) STATUS = BGRBEX(JW,FLAG) where flag is an integer with the following meaning:- FLAG = 0 named bank garbage collection has not occured. FLAG = 1 named bank garbage collection has occured. 4. If insufficient space remains following any Garbage collection (Work or Named bank), in addition to returning an error code, the IND and INDDAT parameters will be set to zero. 5. No action will be performed if the destination bank is identical to the source bank (i.e. NAMSRC and NAMDST are identical, and NRSRC and NRDST are identical). However, IND and INDDAT are correctly returned in this situation. 6. The destination bank will be created with the length required to accommodate the source bank. If the destination bank already exists, all information within the bank will be overwritten by the contents of the source bank. 7. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 31 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.3 BGARB - Named Bank Garbage Collection This subprogram performs an explicit garbage collection on just the named bank area of the specified YBOS array. Any dropped named banks are identified and remaining banks are shuffled towards decreasing indices so as to remove holes. _______ ________ Calling Sequence STATUS = BGARB(JW) _____ __________ Input Parameters JW YBOS array name ______ __________ Output Parameters None ________ _____ Function Value BGARB (Integer) YESUCC Success YENOBK Non-existent Bank Name YENONR Non-existent Bank Number N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. It is the programmers responsibility to call BLOCAT, NLINK or MLINK again following a call to BGARB in order to correctly locate any moved named banks. Note that the NAMIND function to determine the name-index of a bank may be used to avoid having to call BLOCAT, NLINK or MLINK. 3. As BGARB is moving over holes, it checks whether an area is a hole or not. If it isn't a hole, then BGARB checks whether the name and no. correspond to a bank that it knows about. If this check fails, then the errors YENOBK or YENONR will be produced. In this case, the Application Program should terminate cleanly since the integrity of the YBOS array following these errors is suspect. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) CDF-156 YBOS (V4.00) Page 32 SUBPROGRAMS FOR SINGLE NAMED BANKS STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 33 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.4 BIGEST - Returns Largest Bank Number for Given Name This subprogram returns the largest existing bank number for banks with the specified (input) name. _______ ________ Calling Sequence STATUS = BIGEST(JW,BNKNAM,BIGNUM) _____ __________ Input Parameters JW YBOS array name BNKNAM Bank name ______ __________ Output Parameters BIGNUM Largest existing bank number ________ _____ Function Value BIGEST (Integer) YESUCC Success N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. If there are no banks of name BNKNAM, BIGNUM will be set to 0. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 34 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.5 BLAST - Locate Last Bank In Current Chain This routine locates the last bank in the current chain. The current chain is specified by passing a named bank index. _______ ________ Calling Sequence STATUS = BLAST(JW,IND,INDLST) _____ __________ Input Parameters JW YBOS array name IND Bank index (chain specifier) ______ __________ Output Parameters INDLST Index to last bank in specified chain ________ _____ Function Value BLAST (Integer) YESUCC Success N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. The IND parameter can be the index to any bank in the chain of interest. It is the responsibility of the programmer to assure that IND is a proper name bank index. CDF-156 YBOS (V4.00) Page 35 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.6 BLINK - Create Index Work Bank For Named Banks This subprogram creates a work bank containing the indices of all named banks with the specified name (with differing numbers). _______ ________ Calling Sequence STATUS = BLINK(JW,NAME,NRMAX,IND) _____ __________ Input Parameters JW Array name. NAME (Character*4) Bank Name. NRMAX (Integer) Dummy Argument ______ __________ Output Parameters IND (Integer) Index of created work bank....STATIC variable ________ _____ Function Value BLINK (Integer) YESUCC Success YEOVRF Insufficient Space N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. A work bank will be created with sufficient datawords where each element will contain the index to the corresponding named bank. Thus, the index for bank name NAME and number NR is contained in JW(IND+NR). In this case, NR must be greater than zero. Note that JW(IND) is equal to the maximum bank number for banks with name NAME. 3. This subprogram may be called either prior to or after creation of the named banks to be indexed. If JW(IND+NR) is zero, the bank with the bank number NR does not exist. 4. Any movement of named banks through garbage collection operations is tracked by the corresponding indices in this work bank. 5. The work bank index (IND) must not have been used as the index to any other work bank prior to the call to BLINK. Multiple calls to BLINK for the same bank name are not necessary. If multiple calls do occur, the same work bank index variable should be used. If multiple calls with different index variables do CDF-156 YBOS (V4.00) Page 36 SUBPROGRAMS FOR SINGLE NAMED BANKS occur, only the index provided in the first call will be updated upon work bank garbage collection. Since work bank garbage collection often occurs without user knowledge, it is suggested that work bank locking be used if multiple BLINK indices are used. 6. In the case of insufficient space, IND will be set to zero and an error function value returned. The Application Program may attempt a garbage collection of the named banks (remembering to relocate them afterwards) and retry. If this still fails, the Program should terminate cleanly. 7. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 37 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.7 BLOCAT - Locate a Named Bank with Bank Type This subprogram combines the functions of MLINK and BDATA for banks conforming to the Bank Type specifications. _______ ________ Calling Sequence STATUS = BLOCAT(JW,NAME,NR,IND,INDDAT) _____ __________ Input Parameters JW Secondary YBOS array name. NAME (Character*4) Bank Name. NR (Integer) Bank Number. ______ __________ Output Parameters IND (Integer) Index to the Bank INDDAT (Integer) Index to the Data within Bank ________ _____ Function Value BLOCAT (Integer) YESUCC Success YENOBK Nonexistent Bank N.B. 1. BLOCAT may be used either with the basic YBOS array IW in COMMON/BCS/ or with a secondary array. 2. If the specified Bank is non-existent, both IND and INDDAT will be set to zero. 3. If NR is negative, then BLOCAT will return the Index of the lowest numbered Bank with the specified Bank Name. The actual number of this bank may be determined using the BNUMB routine described elsewhere. 4. Banks with the same name are chained together via pointers in the Bank Header. These chains may be rapidly accessed by locating the first bank using BLOCAT and then calling BNEXT to access subsequent members in the chain. 5. The value of the Parameter INDDAT will be undefined if the specified bank does not conform to the Bank Type specifications. 6. INDDAT is defined such that JW(INDDAT) contains the first dataword following the Bank Header. CDF-156 YBOS (V4.00) Page 38 SUBPROGRAMS FOR SINGLE NAMED BANKS 7. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 39 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.8 BMAKE - Create a Named Bank with Bank Type This subprogram may be used to create a named bank or to change the length or bank type of an already existing named bank. The extended Bank Header including the bank type information will be setup using the specified parameters. _______ ________ Calling Sequence STATUS = BMAKE(JW,NAME,NR,ND,TYPE,IND,INDDAT) _____ __________ Input Parameters JW Secondary YBOS array name. NAME (Character*4) Bank Name. NR (Integer) Bank Number. ND (Integer) No. of datawords. TYPE (Integer Array) Bank Type specifiers ______ __________ Output Parameters IND (Integer) Index to the Bank INDDAT (Integer) Index to the Data within Bank ________ _____ Function Value BMAKE (Integer) YESUCC Success YEBKNG Negative Bank Length YEOVRF Insufficient Space for new Bank YEBKSP Insufficient Space to extend Bank N.B. 1. The argument ND refers to the number of datawords desired rather than to the actual bank length. The bank length will be calculated on the basis of this number and the Bank Type specifier. 2. The Bank Type specifier is an Integer array containing the Bank Type word and Group Type words as defined previously. For a Mono-Type Bank (containing datawords of a single data type), this array can be replaced by a single Integer conforming to the necessary Bank Type specification (or a Bank Type Parameter from the Bank Type Include File described in Appendix D). For a Mixed-Type Bank (containing mixed data types), the Bank Type specifier array will be used to calculate the extended bank header necessary. CDF-156 YBOS (V4.00) Page 40 SUBPROGRAMS FOR SINGLE NAMED BANKS 3. If the specified Bank already exists, BMAKE can be used to specify a new data length for the bank (by specifying ND as the required length and setting TYPE to zero), or a new bank type (by specifying a new TYPE array and setting the data length equal to that in the original creation of the bank) or both. Note that either of these may cause the indices to the bank and the first dataword to change. 4. INDDAT is defined such that JW(INDDAT) contains the first dataword following the Bank Header. Data can be stored in words JW(INDDAT) to JW(INDDAT+ND-1). 5. The YBOS option subprogram BOPTN may be used to specify special options. This subprogram should be called immediately prior to accessing BMAKE, thus:- STATUS = BOPTN(JW,OPTION) STATUS = BMAKE(JW,...) where OPTION is an Integer having the following meanings:- OPTION = 0 Datawords preset to zero OPTION >< 0 Datawords not preset In the case where an already existing bank is being extended then only the data words in the new region will be preset to zero if appropriate. 6. This Subprogram will perform a Work Bank Garbage collection if insufficient space is available. The Application Program may prevent this via a prior call to WLOCK. 7. If insufficient space remains following any Garbage collection, in addition to returning an error code function value, both IND and INDDAT will be set to zero. The Application Program may try again after performing a named bank garbage collection via BGARB. If this retry fails, the YBOS array is full and the Program should either delete some other banks or terminate cleanly. 8. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 41 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.9 BMAKEN - Create a Named Bank with Bank Type if the Bank doesn't exist This subprogram may be used to create a named bank if and only if the bank does not already exist. No bank length extension or extended bank type header change will be done. During creation, the extended Bank Header including the bank type information will be setup using the specified parameters. _______ ________ Calling Sequence STATUS = BMAKEN(JW,NAME,NR,ND,TYPE,IND,INDDAT) _____ __________ Input Parameters JW Secondary YBOS array name. NAME (Character*4) Bank Name. NR (Integer) Bank Number. ND (Integer) No. of datawords. TYPE (Integer Array) Bank Type specifiers ______ __________ Output Parameters IND (Integer) Index to the Bank INDDAT (Integer) Index to the Data within Bank ________ _____ Function Value BMAKEN (Integer) YESUCC Success YEBKNG Negative Bank Length YEOVRF Insufficient Space for new Bank YEBKSP Insufficient Space to extend Bank YEDUPB Duplicate bank N.B. 1. The argument ND refers to the number of datawords desired rather than to the actual bank length. The bank length will be calculated on the basis of this number and the Bank Type specifier. 2. The Bank Type specifier is an Integer array containing the Bank Type word and Group Type words as defined previously. For a Mono-Type Bank (containing datawords of a single data type), this array can be replaced by a single Integer conforming to the necessary Bank Type specification (or a Bank Type Parameter from the Bank Type Include File described in Appendix D). For a Mixed-Type Bank (containing mixed data types), the Bank Type specifier array will be used to calculate the extended bank header CDF-156 YBOS (V4.00) Page 42 SUBPROGRAMS FOR SINGLE NAMED BANKS necessary. 3. If the specified Bank already exists, BMAKEN will return YEDUPB. 4. INDDAT is defined such that JW(INDDAT) contains the first dataword following the Bank Header. Data can be stored in words JW(INDDAT) to JW(INDDAT+ND-1). 5. The YBOS option subprogram BOPTN may be used to specify special options. This subprogram should be called immediately prior to accessing BMAKEN, thus:- STATUS = BOPTN(JW,OPTION) STATUS = BMAKEN(JW,...) where OPTION is an Integer having the following meanings:- OPTION = 0 Datawords preset to zero OPTION >< 0 Datawords not preset 6. This Subprogram will perform a Work Bank Garbage collection if insufficient space is available. The Application Program may prevent this via a prior call to WLOCK. 7. If insufficient space remains following any Garbage collection, in addition to returning an error code function value, both IND and INDDAT will be set to zero. The Application Program may try again after performing a named bank garbage collection via BGARB. If this retry fails, the YBOS array is full and the Program should either delete some other banks or terminate cleanly. 8. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 43 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.10 BMAKEG - Create a Named Bank and Garbage Collect This subprogram operates identically to the BMAKE Subprogram except in the instance where there is insufficient room to create (or extend) the specified bank. Whereas BMAKE will immediately signal an error, BMAKEG will perform an implicit Garbage Collection of the Named Bank region (BGARB) and try again, only signalling an error if it fails on the second attempt. _______ ________ Calling Sequence STATUS = BMAKEG(JW,NAME,NR,ND,TYPE,IND,INDDAT) _____ __________ Input Parameters JW Secondary YBOS array name. NAME (Character*4) Bank Name. NR (Integer) Bank Number. ND (Integer) No. of datawords. TYPE (Integer Array) Bank Type specifiers ______ __________ Output Parameters IND (Integer) Index to the Bank INDDAT (Integer) Index to the Data within Bank ________ _____ Function Value BMAKEG (Integer) YESUCC Success YEBKNG Negative Bank Length YEOVRF Insufficient Space for new Bank YEBKSP Insufficient Space to extend Bank N.B. 1. Since BMAKEG, unlike BMAKE, may cause some of the named banks to move if an implicit BGARB was necessary in order to allocate enough space, the User should be careful to relocate (via BLOCAT) any already located named banks. 2. To examine whether implicit named bank garbage collection has occured, call BGRBEX. For example, STATUS = BGRBEX(JW,FLAG) (Reset the garbage collection flag) STATUS = BMAKEG(JW...) STATUS = BGRBEX(JW,FLAG) where flag is an integer with the following meaning:- CDF-156 YBOS (V4.00) Page 44 SUBPROGRAMS FOR SINGLE NAMED BANKS FLAG = 0 named bank garbage collection has not occured. FLAG = 1 named bank garbage collection has occured. 3. The argument ND refers to the number of datawords desired rather than to the actual bank length. The bank length will be calculated on the basis of this number and the Bank Type specifier. 4. The Bank Type specifier is an Integer array containing the Bank Type word and Group Type words as defined previously. For a Mono-Type Bank (containing datawords of a single data type), this array can be replaced by a single Integer conforming to the necessary Bank Type specification (or a Bank Type Parameter from the Bank Type Include File described in Appendix D). For a Mixed-Type Bank (containing mixed data types), the Bank Type specifier array will be used to calculate the extended bank header necessary. 5. If the specified Bank already exists, BMAKEG can be used to specify a new data length for the bank (by specifying ND as the required length and setting TYPE to zero), or a new bank type (by specifying a new TYPE array and setting the data length equal to that in the original creation of the bank) or both. Note that either of these may cause the indices to the bank and the first dataword to change. 6. INDDAT is defined such that JW(INDDAT) contains the first dataword following the Bank Header. 7. The YBOS option subprogram BOPTN may be used to specify special options. This subprogram should be called immediately prior to accessing BMAKEG, thus:- STATUS = BOPTN (JW,OPTION) STATUS = BMAKEG(JW,...) where OPTION is an Integer having the following meanings:- OPTION = 0 Datawords preset to zero OPTION >< 0 Datawords not preset In the case where an already existing bank is being extended then only the data words in the new region will be preset to zero if appropriate. CDF-156 YBOS (V4.00) Page 45 SUBPROGRAMS FOR SINGLE NAMED BANKS 8. This Subprogram will perform a Work Bank Garbage collection if insufficient space is available. The Application Program may prevent this via a prior call to WLOCK. 9. If insufficient space remains following any Garbage collection, in addition to returning an error code function value, both IND and INDDAT will be set to zero. In this case the YBOS array is full and the Program should either delete some other banks or terminate cleanly. 10. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 46 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.11 BTYMAK - Create a Named Bank with Bank Type Using String Descriptor This subprogram may be used to create a named bank or to change the bank type of an already existing named bank. The extended Bank Header including the bank type information will be setup using the specified input descriptor string. _______ ________ Calling Sequence STATUS = BTYMAK(JW,NAME,NR,STRING,ND,IND,INDDAT) _____ __________ Input Parameters JW Secondary YBOS array name. NAME (Character*4) Bank Name. NR (Integer) Bank Number. STRING (Character*(*)) Bank Type specifiers ______ __________ Output Parameters IND (Integer) Index to the Bank INDDAT (Integer) Index to the Data within Bank ND (Integer) No. of datawords. ________ _____ Function Value BTYMAK (Integer) Status flag N.B. 1. The argument ND refers to the number of datawords rather than to the actual bank length. ND will be calculated using the Bank Type specifier. The actual bank lenght will then be determined using ND and the Bank Type specifier. 2. The header descriptor, STRING, is much like a fortran format statement. It consists of a combination of data type descriptors, commas, numbers, and parenthesis. The parenthesis are used to indicate entry loops, the commas seperate descriptor elements. Numeric characters are used to indicate the number of words of the specified data type; for example, 8I2 means 8 integer*2 words. BTYMAK will determine the number of 32 bit words required . 3. A STRING filled with one or more blanks and nothing else will result in the Bank Type header word being set to zero. In this case, an existing bank will be unchanged. CDF-156 YBOS (V4.00) Page 47 SUBPROGRAMS FOR SINGLE NAMED BANKS 4. The following is a list of allowable data tye descriptors and a sample call to BTYMAK along with its results. Data Type Data Type Descriptor INTEGER*2 I2 ASCII CHARACTER AS INTEGER*4 I4 REAL*4 R4 VAX D REAL*8 VD VAX G REAL*8 VG VAX H REAL*16 VH BYTE BY Sample: STATUS = BTYMAK(JW,NAME,NR, '26I2,5(R4,2I2),34I4',ND,IND,INDDAT) Results: BITS WORD 16-31 8-15 0-7 Description JW(IND) 63 Data words JW(IND+1) 5 0 0 Bank type mixed JW(IND+2) 13 0 1 Group type I2 JW(IND+3) 5 2 64 Entry loop JW(IND+4) 1 0 4 Group type R4 JW(IND+5) 1 0 1 Group type I2 (End loop) JW(IND+6) 34 0 3 Group type I4 JW(INDDAT) INDDAT = IND+7 . . . JW(INDDAT+56) ND = 57 5. See Appendix D for several more examples. 6. If the specified Bank already exists, BTYMAK can be used to specify a new bank type (by specifying a new STRING data type descriptor, the data length will automatically be modified to be consistent with the new descriptor). Note that this may cause the indices to the bank and the first dataword to change. 7. INDDAT is defined such that JW(INDDAT) contains the first dataword following the Bank Header. 8. The YBOS option subprogram BOPTN may be used to specify special options. This subprogram should be called immediately prior to accessing BTYMAK, thus:- STATUS = BOPTN(JW,OPTION) STATUS = BTYMAK(JW,...) where OPTION is an Integer having the following CDF-156 YBOS (V4.00) Page 48 SUBPROGRAMS FOR SINGLE NAMED BANKS meanings:- OPTION = 0 Datawords preset to zero OPTION >< 0 Datawords not preset In the case where an already existing bank is being extended then only the data words in the new region will be preset to zero if appropriate. 9. This Subprogram will perform a Work Bank Garbage collection if insufficient space is available. The Application Program may prevent this via a prior call to WLOCK. 10. If insufficient space remains following any Garbage collection, in addition to returning an error code function value, both IND and INDDAT will be set to zero. The Application Program may try again after performing a named bank garbage collection via BGARB. If this retry fails, the YBOS array is full and the Program should either delete some other banks or terminate cleanly. 11. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 49 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.12 BTYMKG - Create a Named Bank - String Descriptor with Garbage Collection This subprogram operates identically to the BTYMAK Subprogram except in the instance where there is insufficient room to create (or extend) the specified bank. Whereas BYTMAK will immediately signal an error, BTYMKG will perform an implicit Garbage Collection of the Named Bank region (BGARB) and try again, only signalling an error if it fails on the second attempt. _______ ________ Calling Sequence STATUS = BTYMKG(JW,NAME,NR,STRING,ND,IND,INDDAT) _____ __________ Input Parameters JW Secondary YBOS array name. NAME (Character*4) Bank Name. NR (Integer) Bank Number. STRING (Character*(*)) Bank Type specifiers ______ __________ Output Parameters IND (Integer) Index to the Bank INDDAT (Integer) Index to the Data within Bank ND (Integer) No. of datawords. ________ _____ Function Value BTYMKG (Integer) Status flag N.B. 1. Since BTYMKG, unlike BTYMAK, may cause some of the named banks to move if an implicit BGARB was necessary in order to allocate enough space, the User should be careful to relocate (via BLOCAT) any already located named banks. 2. To examine whether implicit named bank garbage collection has occured, call BGRBEX. For example, STATUS = BGRBEX(JW,FLAG) (Reset the garbage collection flag) STATUS = BTYMKG(JW...) STATUS = BGRBEX(JW,FLAG) where flag is an integer with the following meaning:- FLAG = 0 named bank garbage collection has not CDF-156 YBOS (V4.00) Page 50 SUBPROGRAMS FOR SINGLE NAMED BANKS occured. FLAG = 1 named bank garbage collection has occured. 3. The argument ND refers to the number of datawords rather than to the actual bank length. ND will be calculated using the Bank Type specifier. The actual bank lenght will then be determined using ND and the Bank Type specifier. 4. The header descriptor, STRING, is much like a fortran format statement. It consists of a combination of data type descriptors, commas, numbers, and parenthesis. The parenthesis are used to indicate entry loops, the commas seperate descriptor elements. Numeric characters are used to indicate the number of words of the specified data type; for example, 8I2 means 8 integer*2 words. BTYMKG will determine the number of 32 bit words required . 5. A STRING filled with one or more blanks and nothing else will result in the Bank Type header word being set to zero. In this case, an existing bank will be unchanged. 6. The following is a list of allowable data tye descriptors and a sample call to BTYMKG along with its results. Data Type Data Type Descriptor INTEGER*2 I2 ASCII CHARACTER AS INTEGER*4 I4 REAL*4 R4 VAX D REAL*8 VD VAX G REAL*8 VG VAX H REAL*16 VH BYTE BY Sample: STATUS = BTYMKG(JW,NAME,NR, '26I2,5(R4,2I2),34I4',ND,IND,INDDAT) Results: BITS WORD 16-31 8-15 0-7 Description JW(IND) 63 Data words JW(IND+1) 5 0 0 Bank type mixed JW(IND+2) 13 0 1 Group type I2 JW(IND+3) 5 2 64 Entry loop JW(IND+4) 1 0 4 Group type R4 JW(IND+5) 1 0 1 Group type I2 (End loop) JW(IND+6) 34 0 3 Group type I4 CDF-156 YBOS (V4.00) Page 51 SUBPROGRAMS FOR SINGLE NAMED BANKS JW(INDDAT) INDDAT = IND+7 . . . JW(INDDAT+56) ND = 57 7. See Appendix D for several more examples. 8. If the specified Bank already exists, BTYMKG can be used to specify a new bank type (by specifying a new STRING data type descriptor, the data length will automatically be modified to be consistent with the new descriptor). Note that this may cause the indices to the bank and the first dataword to change. 9. INDDAT is defined such that JW(INDDAT) contains the first dataword following the Bank Header. 10. The YBOS option subprogram BOPTN may be used to specify special options. This subprogram should be called immediately prior to accessing BTYMKG, thus:- STATUS = BOPTN(JW,OPTION) STATUS = BTYMKG(JW,...) where OPTION is an Integer having the following meanings:- OPTION = 0 Datawords preset to zero OPTION >< 0 Datawords not preset In the case where an already existing bank is being extended then only the data words in the new region will be preset to zero if appropriate. 11. This Subprogram will perform a Work Bank Garbage collection if insufficient space is available. The Application Program may prevent this via a prior call to WLOCK. 12. If insufficient space remains following any Garbage collection, in addition to returning an error code function value, both IND and INDDAT will be set to zero. If work banks are locked, the program should delete some work banks (if possible) and try again. If work banks are not locked, the program should exit cleanly. 13. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, CDF-156 YBOS (V4.00) Page 52 SUBPROGRAMS FOR SINGLE NAMED BANKS STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 53 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.13 BMOVE - Copy a Named Bank to another YBOS Array This subprogram may be used to copy the contents of an existing named bank to another YBOS array. _______ ________ Calling Sequence STATUS = BMOVE(JWSRC,NAMSRC,NRSRC, & JWDST,NAMDST,NRDST,IND,INDDAT) _____ __________ Input Parameters JWSRC Source array name NAMSRC (Character*4) Source Bank Name NRSRC (Integer) Source Bank Number JWDST Destination array name NAMDST (Character*4) Destination Bank Name NRDST (Integer) Destination Bank Number ______ __________ Output Parameters IND (Integer) Index to the Destination Bank INDDAT (Integer) Index to data of Destination Bank ________ _____ Function Value BMOVE(Integer) YESUCC Success YENOBK Non-existent Bank YEOVRF Insufficient Space to create Bank YEBKSP Insufficient Space to extend Bank N.B. 1. INDDAT is defined such that JWDST(INDDAT) contains the first dataword following the Bank Header of the destination bank. 2. This Subprogram will perform a Work Bank Garbage collection if insufficient space is available. The Application Program may prevent this via a prior call to WLOCK. 3. If insufficient space remains following any Work Bank Garbage collection, in addition to returning an error code, the IND and INDDAT parameters will be set to zero. The Application Program may try again after performing a named bank garbage collection (BGARB). 4. This Subprogram does not check for the destination bank being identical to the source bank (i.e. same bank names and numbers and same YBOS arrays). CDF-156 YBOS (V4.00) Page 54 SUBPROGRAMS FOR SINGLE NAMED BANKS 5. The destination bank will be created with the length required to accommodate the source bank. If the destination bank already exists, all information within the bank will be overwritten by the contents of the source bank. 6. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 55 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.14 BSMOVE - Copy a List of Banks to another YBOS Array This subprogram BMOVEs all banks in the source list from the source array to a destination list in the destination array. _______ ________ Calling Sequence STATUS = BSMOVE(JWSRC,SRCLST,JWDST,DSTLST) _____ __________ Input Parameters JWSRC Source array name SRCLST (Character*4) Source Bank list or Set Name DSTLST (Character*4) Destination Bank Set Name plus optional operator. ______ __________ Output Parameters JWDST Destination array name ________ _____ Function Value BSMOVE(Integer) YESUCC Success YENOBK Non-existent Bank YEOVRF Insufficient Space to create Bank YEBKSP Insufficient Space to extend Bank YEBSIL Illegal Bank Set Name YEILOP Illegal Operand N.B. 1. The SRCLST parameter may be either a single letter bank set name, "*" for all bank names, or a list of 4 character bank names. If a list of 4 character bank names is passed, the "*" character can be used as a wildcard. For examle, SRCLST='BI****RD' implies all existing bank names that start with 'BI' (BI**), and all bank names that end with 'RD' (**RD). 2. The DSTLST specifier is a string of one or two characters of the form 'L=', 'L+' or 'L-' where L is one of the allowed bank set names (A-Z) and '=' means copy, '+' means add . The '=',and '+', operators are optional. If no operator is supplied, '=' is assumed. 3. The destination banks will be created with the length required to accommodate the source banks. If a destination bank already exists, all information within the bank will be overwritten by the contents CDF-156 YBOS (V4.00) Page 56 SUBPROGRAMS FOR SINGLE NAMED BANKS of the source bank. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 57 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.15 BMOVEG - Copy a Named Bank to another YBOS Array and Garbage Collect This subprogram operates identically to the BMOVE Subprogram except in the instance where there is insufficient room to create the specified bank. Whereas BMOVE will immediately signal an error, BMOVEG will perform an implicit Garbage Collection of the Named Bank region (BGARB) and try again, only signalling an error if it fails on the second attempt. _______ ________ Calling Sequence STATUS = BMOVEG(JWSRC,NAMSRC,NRSRC, & JWDST,NAMDST,NRDST,IND,INDDAT) _____ __________ Input Parameters JWSRC Source array name NAMSRC (Character*4) Source Bank Name NRSRC (Integer) Source Bank Number JWDST Destination array name NAMDST (Character*4) Destination Bank Name NRDST (Integer) Destination Bank Number ______ __________ Output Parameters IND (Integer) Index to the Destination Bank INDDAT (Integer) Index to data of Destination Bank ________ _____ Function Value BMOVEG(Integer) YESUCC Success YENOBK Non-existent Bank YEOVRF Insufficient Space to create Bank YEBKSP Insufficient Space to extend Bank N.B. 1. INDDAT is defined such that JWDST(INDDAT) contains the first dataword following the Bank Header of the destination bank. 2. This Subprogram will perform a Work Bank Garbage collection if insufficient space is available. The Application Program may prevent this via a prior call to WLOCK. If insufficient space is available after work bank garbage collection, named bank garbage collection will occur. In this case, named banks must be relocated. CDF-156 YBOS (V4.00) Page 58 SUBPROGRAMS FOR SINGLE NAMED BANKS 3. To examine whether implicit named bank garbage collection has occured, call BGRBEX. For example, STATUS = BGRBEX(JW,FLAG) (Reset the garbage collection flag) STATUS = BMOVEG(JW...) STATUS = BGRBEX(JW,FLAG) where flag is an integer with the following meaning:- FLAG = 0 named bank garbage collection has not occured. FLAG = 1 named bank garbage collection has occured. 4. If insufficient space remains following any Garbage collection (work or named bank), in addition to returning an error code, the IND and INDDAT parameters will be set to zero. 5. This Subprogram does not check for the destination bank being identical to the source bank (i.e. same bank names and numbers and same YBOS arrays). 6. The destination bank will be created with the length required to accommodate the source bank. If the destination bank already exists, all information within the bank will be overwritten by the contents of the source bank. 7. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 59 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.16 BRENAM - Rename Selected Named Banks This subprogram may be used to change the name or number of all selected banks . _______ ________ Calling Sequence STATUS = BRENAM(JW,NAMOLD,NROLD,NAMNEW,NRNEW) _____ __________ Input Parameters JW Secondary array name NAMOLD (Character*4) Old Bank Name NROLD (Integer) Old Bank Number NAMNEW (Character*4) New Bank Name NRNEW (Integer) New Bank Number ______ __________ Output Parameters None ________ _____ Function Value BRENAM (Integer) YESUCC Success YENOBK Non-existent Bank YEDUPB Attempt to create Duplicate Bank N.B. 1. If the new Bank already exists, then no renaming will occur and only the Error function will be returned to the caller. 2. No movement of banks occurs during this operation and the bank index is unchanged. 3. NAMOLD and NAMNEW are a four character bank names. The "*" character can be used as a wildcard. For example, NAMOLD = '$**F' and NAMNEW ='+***' will rename selected banks of the form '$**F' to '+**F' banks. 4. Only banks that match NAMOLD and NROLD are renamed. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 60 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.17 BRNALL - Rename all Specified Named Banks This subprogram may be used to change the names of all existing banks with the specified name(s). _______ ________ Calling Sequence STATUS = BRENAM(JW,NAMOLD,NAMNEW) _____ __________ Input Parameters JW Secondary array name NAMOLD (Character*4) Old Bank Name NAMNEW (Character*4) New Bank Name ______ __________ Output Parameters None ________ _____ Function Value BRNALL (Integer) YESUCC Success YENOBK Non-existent Bank YEDUPB Attempt to create Duplicate Bank N.B. 1. If any new Bank already exists, then no renaming will occur and only the Error function will be returned to the caller. 2. No movement of banks occurs during this operation and the bank index is unchanged. 3. NAMOLD and NAMNEW are a four character bank names. The "*" character can be used as a wildcard. For example, NAMOLD = '$**F' and NAMNEW ='+***' will rename all existing banks of the form '$**F' to '+**F' banks. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 61 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.18 NBANK and MBANK - Create a Named Bank These two subprograms may be used to create a named bank either in the basic YBOS array in COMMON/BCS/ (NBANK) or in a secondary array (MBANK). If they are called with an already existing bank name then they alter the bank length to that specified in the call. ************************************************ * * * BMAKE is the preferred method of * * creating or extending a named bank * * * ************************************************ _______ ________ Calling Sequence IND = NBANK (NAME,NR,ND) IND = MBANK(JW,NAME,NR,ND) _____ __________ Input Parameters JW Secondary YBOS array name. NAME (Character*4) Bank Name. NR (Integer) Bank Number. ND (Integer) Bank Length. ______ __________ Output Parameters None ________ _____ Function Value NBANK (Integer) or Index to the bank. MBANK (Integer) IW(2) (Integer) or YESUCC Success JW(2) (Integer) YEBKNG Negative Bank Length YEOVRF Insufficient Space (as appropriate for new Bank to NBANK or MBANK) YEBKSP Insufficient Space to extend Bank N.B. 1. MBANK may be used either with the basic YBOS array IW in COMMON/BCS/ or with a secondary array. 2. The YBOS option subprogram BOPTN may be used to specify special options. This subprogram should be called immediately prior to accessing NBANK or MBANK, thus:- CDF-156 YBOS (V4.00) Page 62 SUBPROGRAMS FOR SINGLE NAMED BANKS STATUS = BOPTN(IW,OPTION) IND = NBANK(...) where OPTION is an Integer having the following meanings:- OPTION = 0 Datawords preset to zero OPTION >< 0 Datawords not preset In the case where an already existing bank is being extended then only the data words in the new region will be preset to zero if appropriate. 3. If insufficient space remains, an addition to returning an error code accessible via BERROR, IND will be set to zero. The Application Program may try again after performing a named bank garbage collection via BGARB. If this retry fails, the YBOS array is full and the Program should either delete some other banks or terminate cleanly. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 63 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.19 NLINK and MLINK - Locate a Named Bank These subprogram may be used to locate previously created banks. ************************************************ * * * BLOCAT is the preferred method * * of locating a named bank * * * ************************************************ _______ ________ Calling Sequence IND = NLINK (NAME,NR) IND = MLINK(JW,NAME,NR) _____ __________ Input Parameters JW Secondary array name. NAME (Character*4) Bank Name. NR (Integer) Bank Number. ______ __________ Output Parameters None ________ _____ Function Value NLINK (Integer) or Index to the bank. MLINK (Integer) IW(2) (Integer) or YESUCC Success JW(2) (Integer) YENOBK Non-existent Bank N.B. 1. MLINK may be used either with the basic YBOS array IW in COMMON/BCS/ or with a secondary array. 2. The function value returned will be set to zero if a non-existent bank has been specified. 3. If NR is negative, then NLINK and MLINK will return the Index of the lowest numbered Bank with the specified Bank Name. The actual number of this bank may be determined using the BNUMB routine described elsewhere. 4. Banks with the same name are chained together via pointers in the Bank Header. These chains may be rapidly accessed by locating the first bank using CDF-156 YBOS (V4.00) Page 64 SUBPROGRAMS FOR SINGLE NAMED BANKS NLINK, MLINK or NAMIND and then calling BNEXT to access subsequent members in the chain. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 65 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.20 NDROP and MDROP - Delete a Named Bank These subprograms may be used to drop (delete) a previously existing bank. _______ ________ Calling Sequence IND = NDROP (NAME,NR) IND = MDROP(JW,NAME,NR) _____ __________ Input Parameters JW Secondary array name. NAME (Character*4) Bank Name. NR (Integer) Bank Number. ______ __________ Output Parameters None ________ _____ Function Value NDROP (Integer) or Index to the bank. MDROP (Integer) IW(2) (Integer) or YESUCC Success JW(2) (Integer) YENOBK Non-existent Bank N.B. 1. MDROP may be used either with the basic YBOS array IW in COMMON/BCS/ or with a secondary array. 2. These functions always return a function value of zero, corresponding to the Index to the now non-existent bank. 3. No automatic garbage collection is performed after a call to NDROP or MDROP. If this is desired then it must be performed explicitly by a call to BGARB. In this case it is the Programmer's responsibility to relocate the remaining named banks via calls to BLOCAT, NLINK or MLINK. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 66 SUBPROGRAMS FOR SINGLE NAMED BANKS 13.21 NPRNT and MPRNT - Print a Named Bank These subprograms print the contents of the specified bank on the currently specified YBOS Print Unit (default 6). The datawords are printed as Integer quantities. _______ ________ Calling Sequence IND = NPRNT (NAME,NR) IND = MPRNT(JW,NAME,NR) _____ __________ Input Parameters JW Secondary array name. NAME (Character*4) Bank Name. NR (Integer) Bank Number. ______ __________ Output Parameters None ________ _____ Function Value NPRNT (Integer) or Index to the bank. MPRNT (Integer) IW(2) (Integer) or YESUCC Success JW(2) (Integer) YENOBK Non-existent Bank N.B. 1. MPRNT may be used either with the basic YBOS array IW in COMMON/BCS/ or with a secondary array. 2. The YBOS option subprogram BOPTN may be used to specify special options. This subprogram should be called immediately prior to accessing NPRNT or MPRNT, thus:- STATUS = BOPTN(JW,OPTION) STATUS = MPRNT(JW,...) where OPTION is an Integer having the following meanings:- OPTION = 0 Print Bank Contents (Default) OPTION >< 0 Print only Bank Header 3. YBOS maintains a count of the number of banks that have been printed. When this count reaches a preset limit (default 100) then no further banks will be printed. This limit may be modified from its default CDF-156 YBOS (V4.00) Page 67 SUBPROGRAMS FOR SINGLE NAMED BANKS setting of 100 by a call to subprogram BPLIMT. 4. The currently specified YBOS Print UNIT (default 6) may be modified by a call to subprogram BPUNIT. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 68 SUBPROGRAMS FOR NAMED BANK INTERNALS ___________ ___ _____ ____ _________ 14 SUBPROGRAMS FOR NAMED BANK INTERNALS These subprograms (added in Version 3.00) allow the Application Programmer to access quantities within a YBOS Header without knowing the details of the format of the Header. In particular, they allow the Index to the Data for a Named Bank conforming to the Bank Type specifications to be determined. The following subprograms are available:- BDATA Return Data Index from Bank Index BDLEN Return Length of Data BLENG Return Length of Bank BNAME Return Bank Name BNEXT Return Index of Next Bank BNUMB Return Number of Bank BTYPE Return Bank Type Word etc. BTPACK Pack Bank/Group Type Word BTUNPK Unpack Bank/Group Type Word BTYBLD Build a Bank Type Header Note that these subprograms only return the Error Code as the function value. They do not set the 2nd element of the appropriate YBOS array, neither do they allow BERROR to be used to determine the Error Code. This is to allow their use in the situation where a YBOS bank is passed to a subprogram as an array. Within the subprogram the bank should be treated just like any normal array and the subprogram has no knowledge that the array in in fact a portion of a larger YBOS array. CDF-156 YBOS (V4.00) Page 69 SUBPROGRAMS FOR NAMED BANK INTERNALS 14.1 BDATA - Return Data Index from Bank Index This subprogram returns the Data Index for the Bank having the specified Bank Index. It only operates correctly for Named Banks conforming to the Bank Type format described earlier. _______ ________ Calling Sequence STATUS = BDATA(JW,IND,INDDAT) _____ __________ Input Parameters JW Secondary YBOS array name. IND (Integer) Index to the bank (Bank Index). ______ __________ Output Parameters INDDAT (Integer) Index to the data (Data Index). ________ _____ Function Value BDATA (Integer) YESUCC Success N.B. 1. BDATA performs no checks to determine whether IND corresponds to a valid Bank. The results will be undefined if IND does not correspond to a Bank or corresponds to a Bank not conforming to the Bank Type specifications. 2. INDDAT is defined such that JW(INDDAT) contains the first dataword following the Bank Header. 3. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of the appropriate YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 70 SUBPROGRAMS FOR NAMED BANK INTERNALS 14.2 BDLEN - Return Length of Data This subprogram returns the Length of the Data for the named Bank with the specified Bank Index. It only operates correctly for Banks conforming to Bank Type format described earlier. _______ ________ Calling Sequence STATUS = BDLEN(JW,IND,LENDAT) _____ __________ Input Parameters JW Secondary YBOS array name. IND (Integer) Index to the bank (Bank Index). ______ __________ Output Parameters LENDAT (Integer) Length of the Data ________ _____ Function Value BDLEN (Integer) YESUCC Success N.B. 1. BDLEN performs no checks to determine whether IND corresponds to a valid Bank. The results will be undefined if IND does not correspond to a Bank or corresponds to a Bank not conforming to the Bank Type specifications. 2. LENDAT is the Length of the data in Integer words _________ (excluding the Bank Header words). 3. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of the appropriate YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 71 SUBPROGRAMS FOR NAMED BANK INTERNALS 14.3 BLENG - Return Length of Bank This subprogram returns the Length of the Bank (including extended Bank Header words) for the named Bank with the specified Bank Index. It operates correctly for all Banks. _______ ________ Calling Sequence STATUS = BLENG(JW,IND,LENBNK) _____ __________ Input Parameters JW Secondary YBOS array name. IND (Integer) Index to the bank (Bank Index). ______ __________ Output Parameters LENBNK (Integer) Length of the Bank ________ _____ Function Value BLENG (Integer) YESUCC Success N.B. 1. BLENG performs no checks to determine whether IND corresponds to a valid Bank. The results will be undefined if IND does not correspond to a Bank. 2. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of the appropriate YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 72 SUBPROGRAMS FOR NAMED BANK INTERNALS 14.4 BNAME - Return Bank Name This subprogram returns the Bank Name having the specified Bank Index. It operates correctly for all Named Banks. _______ ________ Calling Sequence STATUS = BNAME(JW,IND,NAME) _____ __________ Input Parameters JW Secondary YBOS array name. IND (Integer) Index to the bank (Bank Index). ______ __________ Output Parameters NAME (Character*4) Bank Name ________ _____ Function Value BNAME (Integer) YESUCC Success N.B. 1. BNAME performs no checks to determine whether IND corresponds to a valid Bank. The results will be undefined if IND does not correspond to a Bank. 2. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of the appropriate YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 73 SUBPROGRAMS FOR NAMED BANK INTERNALS 14.5 BNEXT - Return Index of next Bank This subprogram returns the Bank Index for the next Bank of the same Name as the Bank having the specified Bank Index. It operates correctly for all Named Banks. _______ ________ Calling Sequence STATUS = BNEXT(JW,IND,INDNXT) _____ __________ Input Parameters JW Secondary YBOS array name. IND (Integer) Index to the bank (Bank Index). ______ __________ Output Parameters INDNXT (Integer) Index to the next Bank ________ _____ Function Value BNEXT (Integer) YESUCC Success N.B. 1. BNEXT performs no checks to determine whether IND corresponds to a valid Bank. The results will be undefined if IND does not correspond to a Bank. 2. INDNXT will be set to the Index of the next Bank in the Bank Chain for the current Bank Name. Thus its Bank Number will be greater than the current Bank's. 3. INDNXT will be set to zero if there is no "next" Bank (i.e. the Bank with Index IND is the bank with the highest Bank Number of the current Bank Name). 4. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of the appropriate YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 74 SUBPROGRAMS FOR NAMED BANK INTERNALS 14.6 BNUMB - Return Bank Number This subprogram returns the Number for the Bank having the specified Bank Index. It operates correctly for all Named Banks. _______ ________ Calling Sequence STATUS = BNUMB(JW,IND,BNKNUM) _____ __________ Input Parameters JW Secondary YBOS array name. IND (Integer) Index to the bank (Bank Index). ______ __________ Output Parameters BNKNUM (Integer) Bank Number ________ _____ Function Value BNUMB (Integer) YESUCC Success N.B. 1. BNUMB performs no checks to determine whether IND corresponds to a valid Bank. The results will be undefined if IND does not correspond to a Bank. 2. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of the appropriate YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 75 SUBPROGRAMS FOR NAMED BANK INTERNALS 14.7 BTYPE - Return Bank Type Word(s) etc. This subprogram returns the unpacked Bank Type (i.e. separated into the components of Bank Type ID and No. of Group words), together with returning the Index to the First Group Type Word (if present) for the Bank having the specified Bank Index. It only operates correctly for Named Banks conforming to the Bank Type format described earlier. _______ ________ Calling Sequence STATUS = BTYPE(JW,IND,BNKTYP,NGROUP,INDGRP) _____ __________ Input Parameters JW Secondary YBOS array name. IND (Integer) Index to the bank (Bank Index). ______ __________ Output Parameters BNKTYP (Integer) Bank Type ID NGROUP (Integer) No. of Group Words INDGRP (Integer) Index to 1st Group Word ________ _____ Function Value BTYPE (Integer) YESUCC Success N.B. 1. BTYPE performs no checks to determine whether IND corresponds to a valid Bank. The results will be undefined if IND does not correspond to a Bank or corresponds to a Bank not conforming to the Bank Type specifications. 2. INDGRP is defined such that JW(INDGRP) contains the first Group Type Word. This word (and the subsequent ones if necessary) may be unpacked into their components via BTUNPK. 3. INDGRP will be set to zero if there are no Group Type Words (NGROUP zero). 4. The Bank Type ID is defined in Appendix D. An Include File giving Parameter Declarations for the various Bank Types is also available (see Appendix D). 5. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of the appropriate YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 76 SUBPROGRAMS FOR NAMED BANK INTERNALS 14.8 BTPACK - Pack Bank Type or Group Type Words This subprogram returns the Bank Type or Group Type word given the individual components. _______ ________ Calling Sequence STATUS = BTPACK(BNKTYP,NGROUP,NWORDS,BGWORD) _____ __________ Input Parameters BNKTYP (Integer) Bank/Group Type ID NGROUP (Integer) No. of Groups per Entry NWORDS (Integer) No. of Datawords or Entries ______ __________ Output Parameters BGWORD (Integer) Bank/Group Type Word ________ _____ Function Value BTPACK (Integer) YESUCC Success N.B. 1. The Bank Type ID is defined in Appendix D. An Include File giving Parameter Declarations for the various Bank Types is also available (see Appendix D). 2. The value of the NGROUP Parameter depends on the details of the Bank/Group Type Word BGWORD being constructed:- (a) NGROUP should be zero for a Bank Type Word. (b) NGROUP should be zero for a normal Group Type Word (i.e. for a non-Entry Count Type). (c) NGROUP should be the No. of Groups within each Entry for an Entry Count Group Type Word. 3. The value of the NWORDS Parameter depends on the details of the Bank/Group Type Word BGWORD being constructed:- (a) NWORDS should be set to the No. of Groups if BGWORD represents a Bank Type Word. (b) NWORDS should be set to the No. of Datawords for the current Group if BGWORD represents a normal Group Type Word (i.e. for a non-Entry Count CDF-156 YBOS (V4.00) Page 77 SUBPROGRAMS FOR NAMED BANK INTERNALS Type). (c) NWORDS should be set to the No. of Entries if BGWORD represents an Entry Count Group Type Word. 4. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of any YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 78 SUBPROGRAMS FOR NAMED BANK INTERNALS 14.9 BTUNPK - Unpack Bank Type or Group Type Words This subprogram returns the unpacked Bank Type or Group Type words (i.e. separated into their components) for the specified Word. _______ ________ Calling Sequence STATUS = BTUNPK(BGWORD,BNKTYP,NGROUP,NWORDS) _____ __________ Input Parameters BGWORD (Integer) Bank/Group Type Word ______ __________ Output Parameters BNKTYP (Integer) Bank/Group Type ID NGROUP (Integer) No. of Groups per Entry NWORDS (Integer) No. of Datawords or Entries ________ _____ Function Value BTUNPK (Integer) YESUCC Success N.B. 1. The Bank Type ID is defined in Appendix D. An Include File giving Parameter Declarations for the various Bank Types is also available (see Appendix D). 2. The returned value of the NGROUP Parameter depends on the details of the Bank/Group Type Word BGWORD:- (a) NGROUP will always be zero for a Bank Type Word. (b) NGROUP will always be zero for a normal Group Type Word (i.e. for a non-Entry Count Type). (c) NGROUP is the No. of Groups within each Entry for an Entry Count Group Type Word. 3. The returned value of the NWORDS Parameter depends on the details of the Bank/Group Type Word BGWORD:- (a) NWORDS will be set to the No. of Groups if BGWORD represents a Bank Type Word. (b) NWORDS will be set to the No. of Datawords for the current Group if BGWORD represents a normal Group Type Word (i.e. for a non-Entry Count Type). CDF-156 YBOS (V4.00) Page 79 SUBPROGRAMS FOR NAMED BANK INTERNALS (c) NWORDS will be set to the No. of Entries if BGWORD represents an Entry Count Group Type Word. 4. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of any YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 80 SUBPROGRAMS FOR NAMED BANK INTERNALS 14.10 BTYBLD - Build A Bank Type Header This subprogram returns the index to the first data word of a work bank that holds the desired bank type header. _______ ________ Calling Sequence STATUS = BTYBLD(JW,STRING,INDX,INDD,NDAT) _____ __________ Input Parameters JW (Array) Ybos Array name STRING (Character) Header descriptor string ______ __________ Output Parameters INDX (Integer) The index to the work bank INDD (Integer) The index to the first header word NDAT (Integer) The number of data words in the named bank ________ _____ Function Value BTYBLD (Integer) Status flag N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The header descriptor, STRING, is much like a fortran format statement. It consists of a combination of data type descriptors, commas, numbers, and parenthesis. The parenthesis are used to indicate entry loops, the commas seperate descriptor elements. Numeric characters are used to indicate the number of words of the specified data type; for example, 8I2 means 8 integer*2 words. BTYBLD will determine the number of 32 bit words required . 3. A STRING filled with one or more blanks and nothing else will result in JW(INDD) being set to zero. 4. The following is a list of allowable data tye descriptors and a sample call to BTYBLD along with its results. Data Type Data Type Descriptor INTEGER*2 I2 ASCII CHARACTER AS INTEGER*4 I4 REAL*4 R4 VAX D REAL*8 VD VAX G REAL*8 VG VAX H REAL*16 VH CDF-156 YBOS (V4.00) Page 81 SUBPROGRAMS FOR NAMED BANK INTERNALS BYTE BY Sample: STATUS = BTYBLD(JW,'26I2,5(R4,2I2),34I4',INDX,INDD,NDAT) Results: BITS WORD 16-31 8-15 0-7 Description JW(INDD) 5 0 0 Bank type mixed JW(INDD+1) 13 0 1 Group type I2 JW(INDD+2) 5 2 64 Entry loop JW(INDD+3) 1 0 4 Group type R4 JW(INDD+4) 1 0 1 Group type I2 (End loop) JW(INDD+5) 34 0 3 Group type I4 NDAT = 57 5. See Appendix D for several more examples. 6. The INDD and NDAT arguments are designed to be used in a call to BMAKE as follows (see section 12.7 for a description of BMAKE): STATUS = BMAKE(JW,NAME,NR,NDAT,JW(INDD),IND,INDDAT). 7. It is the user's responsibility to drop the work bank holding the type header. Drop the work bank with WDROP as follows: STATUS = WDROP(JW,INDX,1) 8. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 82 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS ___________ ___ _____ ____ _____________ 15 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS These subprograms (added in Version 3.00) allow the Application Programmer to declare, and later reference, long Alias Names for Banks. The following subprograms are available:- BDECAL Declare Alias Name for Bank BALIAS Get Alias Name from Basic Name BBASIC Get Basic Name from Alias Name BCANAL Drop the specified Alias Name BLOCAL Locate Bank using Alias Name BMAKAL Create a Bank using Alias Name CDF-156 YBOS (V4.00) Page 83 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS 15.1 BDECAL - Declare Alias Name for Bank This subprogram declares a long Alias Name for the specified basic Bank Name. Only one such Alias may be thus defined. _______ ________ Calling Sequence STATUS = BDECAL(JW,BASIC,ALIAS) _____ __________ Input Parameters JW Secondary YBOS array name. BASIC (Character*4) Basic Bank Name ALIAS (Character) Alias Bank Name ______ __________ Output Parameters None ________ _____ Function Value BDECAL (Integer) YESUCC Success YEDUPA Duplicate Alias Name N.B. ____ 1. The basic name BASIC must be a 4 character name. 2. The Alias Name ALIAS will be truncated to a maximum of 32 characters. 3. The Alias translation is only setup for the specified JW Array. If this translation is desired for more than one array, BDECAL should be called for each array. 4. The translation is only valid for the duration of one program. These translation tables are not written out as part of the logical record structure following the Bank Header. Programs wanting to use Alias Names should always define them themselves, rather than assume that they are part of the input data stream. 5. Only one Alias Name may be defined for each Basic Bank Name. If more than one declaration is made for the same Bank Name, them only the last one is effective. 6. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) CDF-156 YBOS (V4.00) Page 84 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 85 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS 15.2 BALIAS - Get Alias Name from Basic Bank Name This subprogram returns the Alias Name for the specified Basic Bank Name. _______ ________ Calling Sequence STATUS = BALIAS(JW,BASIC,ALIAS) _____ __________ Input Parameters JW Secondary YBOS array name. BASIC (Character*4) Basic Bank Name ______ __________ Output Parameters ALIAS (Character) Alias Bank Name ________ _____ Function Value BALIAS (Integer) YESUCC Success YENOBK Illegal Bank Name YEILLA No Alias exists N.B. ____ 1. The basic name BASIC must be a 4 character name. 2. If no Bank with the specified name exists, ALIAS will be set to ASCII spaces and the error function value will be returned. 3. If no Alias Name has been declared, then ALIAS will be set equal to BASIC, padded out with trailing spaces if necessary, and an error function value will be returned. 4. The actual Alias Name will be padded out with trailing spaces if ALIAS is longer than the actual name. 5. The Alias translation is only setup for the specified JW Array. If this translation is desired for more than one array, BALIAS should be called for each array. 6. The translation is only valid for the duration of one program; thus these translation tables are not written out as part of the logical record structure following the Bank Header. Programs wanting to use Alias Names should always define them themselves, rather than assume that they are part of the input data stream. CDF-156 YBOS (V4.00) Page 86 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS 7. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 87 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS 15.3 BBASIC - Get Basic Bank Name from Alias Name This subprogram returns the basic bank name from the specified Alias Name. _______ ________ Calling Sequence STATUS = BBASIC(JW,ALIAS,BASIC) _____ __________ Input Parameters JW Secondary YBOS array name. ALIAS (Character) Alias Bank Name ______ __________ Output Parameters BASIC (Character*4) Basic Bank Name ________ _____ Function Value BBASIC (Integer) YESUCC Success YEILLA Illegal Alias Name N.B. ____ 1. The basic name BASIC must be a 4 character name. 2. The Alias Name ALIAS will be truncated, or padded out, to a maximum of 32 characters for the purposes of making a name match. 3. If the specified Alias Name ALIAS does not exist, then BASIC will be set to ASCII spaces, and an error function value will be returned. 4. If ALIAS is 4 characters long, then BASIC will be set equal to ALIAS. 5. The Alias translation is only setup for the specified JW Array. If this translation is desired for more than one array, BBASIC should be called for each array. 6. The translation is only valid for the duration of one program; thus these translation tables are not written out as part of the logical record structure following the Bank Header. Programs wanting to use Alias Names should always define them themselves, rather than assume that they are part of the input data stream. CDF-156 YBOS (V4.00) Page 88 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS 7. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 89 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS 15.4 BCANAL - Drop The Specified Alias Name This subprogram drops the specified Alias Name. _______ ________ Calling Sequence STATUS = BCANAL(JW,ALIAS) _____ __________ Input Parameters JW Secondary YBOS array name. ALIAS (Character) Alias Bank Name ______ __________ Output Parameters None ________ _____ Function Value BCANAL (Integer) YESUCC Success YEILLA Illegal Alias Name N.B. 1. The Alias Name ALIAS will be truncated, or padded out, to a maximum of 32 characters the purposes of making a name match. 2. Alias names are only valid for the duration of one program; thus these translation tables are not written out as part of the logical record structure following the Bank Header. Programs wanting to use Alias Names should always define them themselves, rather than assume that they are part of the input data stream. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 90 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS 15.5 BLOCAL - Locate a Named Bank using Alias Name This subprogram may be used to locate previously created banks using the Alias Name previously defined by a call to BDECAL. _______ ________ Calling Sequence STATUS = BLOCAL(JW,NAME,NR,IND,INDDAT) _____ __________ Input Parameters JW Secondary array name. NAME (Character) Bank Alias or Basic Name. NR (Integer) Bank Number. ______ __________ Output Parameters IND (Integer) Index to the bank (or zero if non-existent). INDDAT (Integer) Index to the Data within Bank ________ _____ Function Value BLOCAL (Integer) YESUCC Success YENOBK Non-existent Bank YEILLA Illegal Alias Name N.B. 1. If the Argument NAME consists of a 4 character name, then no Alias Name translation occurs and BLOCAL is identical in function to BLOCAT. Note that in this case BLOCAT is the preferred method since this has less overhead. 2. The argument NAME will be truncated or padded out with trailing spaces before performing the Alias translation (unless it is 4 characters long). An exact match must be made with an already existing Alias Name or a non-existent bank return will be made. 3. Other notes are as for BLOCAT. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 91 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS 15.6 BMAKAL - Create a Bank using Alias Name This subprogram is similar to BMAKE except that the ALias Name may be used to create (or modify) the bank. The Bank thus defined will be created with an extended Bank Header conforming to the Bank Type specifications described in an earlier Section. _______ ________ Calling Sequence STATUS = BMAKAL(JW,NAME,NR,ND,TYPE,IND,INDDAT) _____ __________ Input Parameters JW Secondary YBOS array name. NAME (Character) Alias Name or Bank Name. NR (Integer) Bank Number. ND (Integer) No. of datawords. TYPE (Integer Array) Bank Type specifiers ______ __________ Output Parameters IND (Integer) Index to the Bank INDDAT (Integer) Index to the Data within Bank ________ _____ Function Value BMAKAL (Integer) YESUCC Success YEILLA Illegal Alias Name YEBKNG Negative Bank Length YEOVRF Insufficient Space for new Bank YEBKSP Insufficient Space to extend Bank N.B. 1. If the Argument NAME consists of a 4 character name, then no Alias Name translation occurs and BMAKAL is identical in function to BMAKE. Note that in this case BMAKE is the preferred method since this has slightly less overhead. 2. The argument NAME will be truncated or padded out with trailing spaces before performing the Alias translation (unless it is 4 characters long). An exact match must be made with an already existing Alias Name or a non-existent bank return will be made. 3. Other notes are as for BMAKE. CDF-156 YBOS (V4.00) Page 92 SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 93 SUBPROGRAMS FOR WORK BANKS ___________ ___ ____ _____ 16 SUBPROGRAMS FOR WORK BANKS Work banks are created at the high index part of the array and are identified by an index IND (being a local variable). Access to the data contained within a work bank should always be done directly with the index IND. Garbage collection is done automatically, if necessary, with update of all indices. The following subprograms are available:- WBANK Create work bank or change length. WDATA Return index to data of work bank WDLEN Return data length of work bank. WDROP Drop work bank(s). WGARB Perform garbage collection for work banks. WLENG Return total length of work bank. WLOCK Lock work banks. WPRNT Print work bank(s). WSETD Set new data length of work bank. WUNLK Unlock work banks. CDF-156 YBOS (V4.00) Page 94 SUBPROGRAMS FOR WORK BANKS 16.1 WBANK - Create a Work Bank This subprogram is used to create a work bank of the specified length or to change the length of an already existing work bank. _______ ________ Calling Sequence STATUS = WBANK(JW,IND,ND) _____ __________ Input Parameters JW YBOS Array name. IND (Integer) The index of a previously existing work bank length. Must be STATIC!! ND (Integer) The work bank length. ______ __________ Output Parameters IND (Integer) The index to the work bank. ________ _____ Function Value WBANK (Integer) YESUCC Success YEOVRF Insufficient Space YERSUS Negative Bank Length N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. The variable IND should be preset to zero before attempting to create a new work bank. If IND is non-zero and does not point to an already existing work bank it is considered to be zero. If, however IND points to an already existing work bank then the length of that work bank will be altered. 3. An attempt to extend a work bank while the work banks are locked (via a call to WLOCK) may fail because YBOS is unable to move work banks in this mode of operation. 4. The Bank length ND should specify the length in Integer words. 5. The YBOS option subprogram BOPTN may be used to specify special options. This subprogram should be called immediately prior to accessing WBANK, thus:- STATUS = BOPTN(JW,OPTION) STATUS = WBANK(JW,...) CDF-156 YBOS (V4.00) Page 95 SUBPROGRAMS FOR WORK BANKS where OPTION is an Integer having the following meanings:- OPTION = 0 Datawords preset to zero OPTION >< 0 Datawords not preset In the case where an already existing bank is being extended then only the data words in the new region will be preset to zero if appropriate. 6. If there is insufficient space, IND will be set to zero and an error function value will be returned. In this case the Application Program should attempt a named bank garbage collection (remembering to relocate all named banks afterwards) and retry. If this fails, the Program should terminate cleanly. 7. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 96 SUBPROGRAMS FOR WORK BANKS 16.2 WDATA - Return Data Index from Bank Index This subprogram returns the Data Index for the Work Bank having the specified Bank Index. _______ ________ Calling Sequence STATUS = WDATA(JW,IND,INDDAT) _____ __________ Input Parameters JW Secondary YBOS array name. IND (Integer) Index to the bank (Bank Index). ______ __________ Output Parameters INDDAT (Integer) Index to the data (Data Index). ________ _____ Function Value WDATA (Integer) YESUCC Success N.B. 1. WDATA performs no checks to determine whether IND corresponds to a valid Bank. The results will be undefined if IND does not correspond to a Bank or corresponds to a Bank not conforming to the Bank Type specifications. 2. INDDAT is defined such that JW(INDDAT) contains the first dataword following the Bank Header. 3. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of the appropriate YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 97 SUBPROGRAMS FOR WORK BANKS 16.3 WDLEN - Return Length of Data This subprogram returns the Length of the Data for the Work Bank with the specified Bank Index. _______ ________ Calling Sequence STATUS = WDLEN(JW,IND,LENDAT) _____ __________ Input Parameters JW Secondary YBOS array name. IND (Integer) Index to the bank (Bank Index). ______ __________ Output Parameters LENDAT (Integer) Length of the Data ________ _____ Function Value WDLEN (Integer) YESUCC Success N.B. 1. WDLEN performs no checks to determine whether IND corresponds to a valid Bank. The results will be undefined if IND does not correspond to a Work Bank. 2. LENDAT is the Length of the data in Integer words. It excludes the Bank Header words and any extent remaining in the work bank data area. 3. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of the appropriate YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 98 SUBPROGRAMS FOR WORK BANKS 16.4 WDROP - Delete a Work Bank This subprogram is used to drop (delete) an already existing work bank. _______ ________ Calling Sequence STATUS = WDROP(JW,IND,NDIM) _____ __________ Input Parameters JW Array name. IND (Integer) Index (or index array of work bank(s). NDIM (Integer) The size of the index array (in Integer words). ______ __________ Output Parameters IND (Integer) Index (or index array) set to zero. ________ _____ Function Value WDROP (Integer) YESUCC Success N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. This subprogram may be used to delete multiple work banks by specifying the index as an array IND(NDIM), where each array element is an index to an existing work bank. For deletion of a single work bank then IND need not be dimensioned but NDIM should be set to 1. 3. On return the index IND (or all elements in an index array IND(NDIM)) will be set to zero. 4. A garbage collection is not performed immediately after dropping work banks, but by other YBOS subprograms if their space requirements cannot be met. The user may perform an explicit garbage collection by a call to WGARB. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) CDF-156 YBOS (V4.00) Page 99 SUBPROGRAMS FOR WORK BANKS STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 100 SUBPROGRAMS FOR WORK BANKS 16.5 WGARB - Work Bank Garbage Collection This subprogram performs an explicit garbage collection on just the work bank area of the specified YBOS array. Any dropped work banks are identified and work banks are shuffled towards increasing indices so as to remove holes. The indices for any shuffled work banks are updated. _______ ________ Calling Sequence STATUS = WGARB(JW) _____ __________ Input Parameters JW YBOS array name ______ __________ Output Parameters None ________ _____ Function Value WGARB (Integer) YESUCC Success N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. The action of WGARB is not affected by whether the work banks are locked or not (via WLOCK etc.). Thus WGARB may cause movement of work banks if there are previously dropped work banks to be discarded. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 101 SUBPROGRAMS FOR WORK BANKS 16.6 WLENG - Return Length of Bank This subprogram returns the Length of the Bank (including extended Bank Header words) Data for the Work Bank with the specified Bank Index. _______ ________ Calling Sequence STATUS = WLENG(JW,IND,LENBNK) _____ __________ Input Parameters JW Secondary YBOS array name. IND (Integer) Index to the bank (Bank Index). ______ __________ Output Parameters LENBNK (Integer) Length of the Bank ________ _____ Function Value WLENG (Integer) YESUCC Success N.B. 1. WLENG performs no checks to determine whether IND corresponds to a valid Work Bank. The results will be undefined if IND does not correspond to a Bank. 2. LENBNK is the Length of the data area in Integer _________ words (excluding the Bank Header words). It includes both the occupied data area and any unoccupied extent. 3. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of the appropriate YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 102 SUBPROGRAMS FOR WORK BANKS 16.7 WLOCK - Lock Work Banks This subprogram will cause the work banks to be locked such that YBOS will not attempt to move them so as to gain extra work space. While in this locked mode of operation work banks may only be moved by an explicit WGARB. _______ ________ Calling Sequence STATUS = WLOCK(JW) _____ __________ Input Parameters JW Array name. ______ __________ Output Parameters None ________ _____ Function Value WLOCK (Integer) YESUCC Success N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 103 SUBPROGRAMS FOR WORK BANKS 16.8 WPRNT - Print a Work Bank This subprogram is used to print the specified work bank or banks on the currently specified YBOS Print Unit. The datawords are printed as Integer quantities. _______ ________ Calling Sequence STATUS = WPRNT(JW,IND,NDIM) _____ __________ Input Parameters JW Array name. IND (Integer) Index (or index array of work bank(s). NDIM (Integer) The size of the index array (in Integer words). ______ __________ Output Parameters None ________ _____ Function Value WPRNT (Integer) YESUCC Success N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. This subprogram may be used to print multiple work banks by specifying the index as an array IND(NDIM), where each array element is an index to an existing work bank. For printing of a single work bank then IND need not be dimensioned but NDIM should be set to 1. 3. The YBOS option subprogram BOPTN may be used to specify special options. This subprogram should be called immediately prior to accessing WPRNT, thus:- STATUS = BOPTN(JW,OPTION) STATUS = WPRNT(JW,...) where OPTION is an Integer having the following meanings:- OPTION = 0 Print header and contents (default). OPTION >< 0 Print header only CDF-156 YBOS (V4.00) Page 104 SUBPROGRAMS FOR WORK BANKS 4. YBOS maintains a count of the number of banks that have been printed. When this count reaches a preset limit (default 100) then no further banks will be printed. This limit may be modified from its default setting of 100 by a call to subprogram BPLIMT. 5. The currently specified YBOS Print Unit (default 6) may be modified by a call to subprogram BPUNIT. 6. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 105 SUBPROGRAMS FOR WORK BANKS 16.9 WSETD - Set new Data Length of Work Bank This subprogram allows the Length of the Data Area of the specified Work Bank to be modified. _______ ________ Calling Sequence STATUS = WSETD(JW,IND,LENDAT) _____ __________ Input Parameters JW Secondary YBOS array name. IND (Integer) Index to the bank (Bank Index). LENDAT (Integer) Length of the Bank ______ __________ Output Parameters None ________ _____ Function Value WSETD (Integer) YESUCC Success YEOVRF Insufficient Space YEBKNG Negative Bank Length N.B. 1. If the new data length exceeds the maximum length of the work bank (as returned by a call to WDLEN) error YEOVRF will be reported and no modification of the bank will be performed. WBANK should be called in order to extend the work bank if so desired. 2. If a negative data length is specified error YEBKNG will be reported and no modification of the bank will be performed. 3. This subprogram only returns the Error Code as the function value. It does not set the 2nd element of the appropriate YBOS array, neither does it allow BERROR to be used to determine the Error Code. CDF-156 YBOS (V4.00) Page 106 SUBPROGRAMS FOR WORK BANKS 16.10 WUNLK - Unlock Work Banks This subprogram may be used to cancel the work bank locking caused by a call to WLOCK. After a call to WUNLK, YBOS is free to move work banks when necessary in an attempt to gain enough work space. _______ ________ Calling Sequence STATUS = WUNLK(JW) _____ __________ Input Parameters JW Array name. ______ __________ Output Parameters None ________ _____ Function Value WUNLK (Integer) YESUCC Success N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. By default, work banks are unlocked. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 107 SUBPROGRAMS FOR SETS OF BANKS ___________ ___ ____ __ _____ 17 SUBPROGRAMS FOR SETS OF BANKS Sets of banks are defined by lists of bank names which are associated with a single character. This set may be handled as a single entity, being read from permanent storage, expanded or reduced in scope, copied or appended to other sets or dropped by single subprogram calls. The typical environment for the use of such sets is one where an event record is read, analyzed in such a way as to add extra information (in the form of banks) to the event (or perhaps delete redundant banks), and is then written to further permanent storage. 26 different sets may be defined, each being specified by a single uppercase letter (A-Z). The following subprograms are available:- BLIST Manipulate bank sets BDROP Drop set of banks BKEEP Drop all except a set of banks BPHEAD Print Headers of set of Banks BPRNT Print set of banks BSINDX Returns lowest bank given set and member number BSINQU Inquire whether bank belongs to set of banks BSMEMB Return all members of set of banks BSMNUM Return member number of bank in set BSNUMB Return number of members in bank set BSINTR Intersect two bank sets CDF-156 YBOS (V4.00) Page 108 SUBPROGRAMS FOR SETS OF BANKS 17.1 BLIST - Manipulate Bank Sets This subprogram is used to manipulate sets of banks. Several actions are possible including adding new members to a set, copying one set to another set and deleting members from a set. _______ ________ Calling Sequence STATUS = BLIST(JW,OPT,LIST) _____ __________ Input Parameters JW YBOS array name. OPT (Character*2) Option specifier LIST (Character) Set name or bank list ______ __________ Output Parameters None ________ _____ Function Value BLIST (Integer) YESUCC Success YEOVRF Insufficient Space YEBSIL Illegal Bank Set Name YEILOP Illegal Operand N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. The option specifier is a string of two characters of the form 'L=', 'L+' or 'L-' where L is one of the allowed bank set names (A-Z) and '=' means copy, '+' means add and '-' means delete. 3. The LIST parameter may be either a single letter bank set name, "*" for all bank names, or a list of 4 character bank names. If a list of 4 character bank names is passed, the "*" character can be used as a wildcard. For examle, LIST='BI****RD' implies all existing bank names that start with 'BI' (BI**), and all bank names that end with 'RD' (**RD). 1. STATUS = BLIST(JW,'E=','ANDYB*RTCARL') Sets the E list to contain banks 'ANDY', 'CARL', and any existing bank names of the form 'B*RT'. CDF-156 YBOS (V4.00) Page 109 SUBPROGRAMS FOR SETS OF BANKS 2. STATUS = BLIST(JW,'E+','C') Adds all banks contained in the C set to the E set. 3. STATUS = BLIST(JW,'E-','DAVEFRED') Removes banks 'DAVE' and 'FRED' from the E set (but does not delete them). 4. In the case of insufficient space, the set manipulation will not be performed. The Application Program should perform a a named bank garbage collection or drop some banks before retrying. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 110 SUBPROGRAMS FOR SETS OF BANKS 17.2 BDROP - Drop Set of Banks This subprogram is used to drop all the banks in the specified list. _______ ________ Calling Sequence STATUS = BDROP(JW,LIST) _____ __________ Input Parameters JW YBOS array name. LIST (Character) Set name or bank list ______ __________ Output Parameters None ________ _____ Function Value BDROP (Integer) YESUCC Success N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. The LIST parameter may be either a single letter bank set name, "*" for all bank names, or a list of 4 character bank names. If a list of 4 character bank names is passed, the "*" character can be used as a wildcard. For examle, LIST='BI****RD' implies all existing bank names that start with 'BI' (BI**), and all bank names that end with 'RD' (**RD). 3. Banks whose names begin with either a "+" character or "$" character (e.g. '+DSK' or '$SAV') are protected against being dropped via a call to BDROP or BKEEP. They may only be dropped via calls to MDROP or NDROP. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 111 SUBPROGRAMS FOR SETS OF BANKS 17.3 BKEEP - Drop all except a Set of Banks This subprogram is used to drop all the banks in the ______ specified YBOS array except those contained in the specified list. _______ ________ Calling Sequence STATUS = BKEEP(JW,LIST) _____ __________ Input Parameters JW YBOS array name. LIST (Character) Set name or bank list ______ __________ Output Parameters None ________ _____ Function Value BKEEP (Integer) YESUCC Success N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. The LIST parameter may be either a single letter bank set name, "*" for all bank names, or a list of 4 character bank names. If a list of 4 character bank names is passed, the "*" character can be used as a wildcard. For examle, LIST='BI****RD' implies all existing bank names that start with 'BI' (BI**), and all bank names that end with 'RD' (**RD). All banks may be dropped by specifying a null bank set name (e.g. ' '). 3. Banks whose names begin with either a "+" character or "$" character (e.g. '+DSK' or '$SAV') are protected against being dropped via a call to BDROP or BKEEP. They may only be dropped via calls to MDROP or NDROP. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 112 SUBPROGRAMS FOR SETS OF BANKS 17.4 BPHEAD - Print Headers of a Set of Banks This subprogram is used to print the bank headers only of the banks in the specified set or list of banks on the currently specified YBOS Print Unit. _______ ________ Calling Sequence STATUS = BPHEAD(JW,LIST) _____ __________ Input Parameters JW YBOS array name. LIST (Character) Set name or bank list ______ __________ Output Parameters None ________ _____ Function Value BPHEAD (Integer) YESUCC Success N.B. 1. The array name JW may be either the basic YBOS array or a secondry YBOS array. 2. The LIST parameter may be either a single letter bank set name or a list of 4 character bank names. 3. BPHEAD is identical in action to BPRNT called in conjunction with the BOPTN option setting subprogram in order to turn off printing of the bank contents. 4. YBOS maintains a count of the number of banks that have been printed. When this count reaches a preset limit (default 100) then no further banks will be printed. This limit may be modified from its default setting of 100 by a call to subprogram BPLIMT. 5. The currently specified YBOS Print Unit (default 6) may be modified by a call to subprogram BPUNIT. 6. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 113 SUBPROGRAMS FOR SETS OF BANKS 17.5 BPRNT - Print Set of Banks This subprogram is used to print the banks in the specified set or list of banks on the currently specified YBOS Print Unit. All datawords will be printed as Integer quantities. _______ ________ Calling Sequence STATUS = BPRNT(JW,LIST) _____ __________ Input Parameters JW YBOS array name. LIST (Character) Set name or bank list ______ __________ Output Parameters None ________ _____ Function Value BPRNT (Integer) YESUCC Success N.B. 1. The array name JW may be either the basic YBOS array or a secondry YBOS array. 2. The LIST parameter may be either a single letter bank set name or a list of 4 character bank names. 3. The YBOS option subprogram BOPTN may be used to specify special options. This subprogram should be called immediately prior to accessing BPRNT, thus:- STATUS = BOPTN(JW,OPTION) STATUS = BPRNT(...) where OPTION is an Integer having the following meanings:- OPTION = 0 Print header and contents (default) OPTION >< 0 Print header only 4. YBOS maintains a count of the number of banks that have been printed. When this count reaches a preset limit (default 100) then no further banks will be printed. This limit may be modified from its default setting of 100 by a call to subprogram BPLIMT. CDF-156 YBOS (V4.00) Page 114 SUBPROGRAMS FOR SETS OF BANKS 5. The currently specified YBOS Print Unit (default 6) may be modified by a call to subprogram BPUNIT. 6. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 115 SUBPROGRAMS FOR SETS OF BANKS 17.6 BSINDX - Return Index of lowest Bank given Set and Member Number This subprogram may be used to determine the index of the lowest numbered bank of a particular name for a given set. The name is given by way of its member number in the set. _______ ________ Calling Sequence STATUS = BSINDX(JW,LIST,MEMBER,BNKIND) _____ __________ Input Parameters JW YBOS array name. LIST (Character) Set name or bank list MEMBER (Character*4) Bank Name Member number ______ __________ Output Parameters BNKIND (Integer*4) Base Bank Index ________ _____ Function Value BINDX (Integer) YESUCC Success YENONR Illegal Bank Member YEBSIL Illegal Bank Set Name N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. The LIST parameter may be either a single letter bank set name or a list of 4 character bank names. 3. The MEMBER parameter corresponds to the desired name's location in the bank set. This number can be determined by a call to BSMNUM. 4. The BNKIND parameter is the base bank index for the name of interest. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 116 SUBPROGRAMS FOR SETS OF BANKS 17.7 BSINQU - Inquire whether Bank belongs to Set This subprogram may be used to determine whether the specified bank name belongs to the specified bank set. _______ ________ Calling Sequence STATUS = BSINQU(JW,NAME,LIST) _____ __________ Input Parameters JW YBOS array name. NAME (Character*4) Bank Name LIST (Character) Set name or bank list ______ __________ Output Parameters None ________ _____ Function Value BSINQU (Integer) YESUCC Success YENOBK Non-existent Bank YEBSIL Illegal Bank Set Name N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. The LIST parameter may be either a single letter bank set name or a list of 4 character bank names. 3. If the specified bank name belongs to the specified bank set or list of names, then function value YESUCC will be returned. This does not necessarily imply that any banks with that name exist. This should be verified by using BLOCAT to locate the first bank with that name. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 117 SUBPROGRAMS FOR SETS OF BANKS 17.8 BSMEMB - Return Members of Bank Set This subprogram may be used to return as a concatenated character string the names of all banks within the specified set or list of bank names. _______ ________ Calling Sequence STATUS = BSMEMB(JW,SET,STRING,NMEMBR) _____ __________ Input Parameters JW YBOS array name. SET (Character) Set name or bank list ______ __________ Output Parameters STRING (Character) Membership of Set NMEMBR (Integer) No. of Members ________ _____ Function Value BSMEMB (Integer) YESUCC Success YEBSIL Illegal Bank Set Name YEOVRF String too short for names N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. The LIST parameter may be either a single letter bank set name or a list of 4 character bank names. In the latter case then STRING will be set equal to SET, padded out with trailing spaces if necessary. 3. NMEMBR will give the number of members of the specified bank set, or will be set to zero if the set is empty or illegal. 4. STRING should be declared as CHARACTER*NUMNAM where NUMNAM is four times the maximum no. of bank names as specified in the call to BOS77. If this is not adhered to, truncation may result and error YEOVRF will be reported. 5. STRING will be padded out with trailing spaces if necessary. 6. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, CDF-156 YBOS (V4.00) Page 118 SUBPROGRAMS FOR SETS OF BANKS STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 119 SUBPROGRAMS FOR SETS OF BANKS 17.9 BSMNUM - Return Member Number of Bank in Set This subprogram may be used to determine the member number of a bank within a particular bank set or list of banks. _______ ________ Calling Sequence STATUS = BSMNUM(JW,LIST,MEMNUM,NAME) _____ __________ Input Parameters JW YBOS array name. LIST (Character) Set name or bank list NAME (Character*4) Bank Name ______ __________ Output Parameters MEMNUM (Integer*4) Bank Name Member Number ________ _____ Function Value BSMNUM (Integer) YESUCC Success YENOBK Bank not a Set Member YEBSIL Illegal Bank Set Name N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. The LIST parameter may be either a single letter bank set name or a list of 4 character bank names. 3. The MEMNUM parameter corresponds to the desired name's location in the bank set. 4. The NAME parameter is the bank name of interest. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 120 SUBPROGRAMS FOR SETS OF BANKS 17.10 BSNUMB - Return Number of Members in Bank Set This subprogram may be used to return the number of members in the specified bank set. _______ ________ Calling Sequence STATUS = BSNUMB(JW,LIST,NMEMBR) _____ __________ Input Parameters JW YBOS array name. LIST (Character) Set name or bank list ______ __________ Output Parameters NMEMBR (Integer) No. of Members ________ _____ Function Value BSNUMB (Integer) YESUCC Success YEBSIL Illegal Bank Set Name N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. The LIST parameter may be either a single letter bank set name or a list of 4 character bank names. 3. NMEMBR will give the number of members of the specified bank set, or will be set to zero if the set is empty or illegal. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 121 SUBPROGRAMS FOR SETS OF BANKS 17.11 BSINTR - Form a Bank Set Intersection This subprogram is used to form the intersection of two Bank Sets. _______ ________ Calling Sequence STATUS = BSINTR(JW,LISTA,LISTB,INTER) _____ __________ Input Parameters JW YBOS array name. LISTA (Character) Input Set name A LISTB (Character) Input Set name B INTER (Character) Intersection (output) Set name ______ __________ Output Parameters NONE ________ _____ Function Value BSINTR (Integer) YESUCC Success YEBSIL Illegal bank set name N.B. 1. The array name JW may be either the basic YBOS array or a secondary YBOS array. 2. The LISTA, and LISTB parameters are the names of the bank sets to intersect. 3. The INTER parameter is the name of the bank set that holds the intersection of LISTA and LISTB. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 122 SUBPROGRAMS FOR SUBSETS OF BANKS ___________ ___ _______ __ _____ 18 SUBPROGRAMS FOR SUBSETS OF BANKS Subsets of banks are defined by lists of bank numbers which are associated with a single bank name. One Bank Subset is allowed per bank name. The members of a subset for a particular name are stored in a work bank maintained internally by YBOS. Bank subsets are used in conjunction with BSWRIT. BSWRIT acts exactly like BLWRIT except that only banks which are subset members for the current name are written to the logical record. The following subprograms are available:- BSBADD Add a list of banks to a subset BSBALD Add all current and future banks to a subset BSBALS Add all current banks to a subset BSBDRP Drop a list of banks from a subset BSBPRG Drop all banks from a subset BSWRIT Write one logical record to the specified BFSWRT logical unit ... Bank Subset members only. BSREAD Read one logical record from the specified BFSRED logical unit forming the specified bank list and subsets. CDF-156 YBOS (V4.00) Page 123 SUBPROGRAMS FOR SUBSETS OF BANKS 18.1 BSBADD - Add a List of Banks to a Subset This subprogram adds the specified list of bank numbers to the Bank Subset for the specified name. _______ ________ Calling Sequence STATUS = BSBADD(JW,NAME,NRLST,DIM) _____ __________ Input Parameters JW Secondary YBOS array name. NAME (Character) Input bank name. NRLST (Array-integer) List of bank numbers to add DIM (Integer) The dimension of NRLST ______ __________ Output Parameters None ________ _____ Function Value BSBADD (Integer) YESUCC Success YECORR Ybos array corrupted N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The NAME parameter must be a valid bank name, although no banks of this name need exist. 3. Entries in the NRLST(DIM) array must be greater than or equal to zero. Numbers less than zero are ignored. Again, the actual banks specified need not exist. 4. Calls to BSWRIT, where NAME is part of the output list, will write only those banks in the subset that actually exist. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 124 SUBPROGRAMS FOR SUBSETS OF BANKS 18.2 BSBALD - Add All Current and Future Banks to a Subset This subprogram adds all currently existing and future banks to the Bank Subset for the specified name. _______ ________ Calling Sequence STATUS = BSBALD(JW,LIST) _____ __________ Input Parameters JW Secondary YBOS array name. LIST (Character) Set name or bank list ______ __________ Output Parameters None ________ _____ Function Value BSBALD (Integer) YESUCC Success YECORR Ybos array corrupted N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The LIST parameter may be either a single letter bank set name, "*" for all bank names, or a list of 4 character bank names. 3. Calls to BSWRIT will write all banks with names common to the BSBALD and BSWRIT input lists. 4. Calls to BSBADD or BSBALS will superceed previous calls to BSBALD. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 125 SUBPROGRAMS FOR SUBSETS OF BANKS 18.3 BSBALS - Add All Current Banks to a Subset This subprogram adds all currently existing banks to the Bank Subset for the specified name. _______ ________ Calling Sequence STATUS = BSBALS(JW,LIST) _____ __________ Input Parameters JW Secondary YBOS array name. LIST (Character) Set name or bank list ______ __________ Output Parameters None ________ _____ Function Value BSBALS (Integer) YESUCC Success YECORR Ybos array corrupted N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The LIST parameter may be either a single letter bank set name, "*" for all bank names, or a list of 4 character bank names. 3. Only those banks of name NAME that exist at the time of the call to BSBALS will be added to the subset. 4. Calls to BSWRIT will write all banks with names common to the BSBALS and BSWRIT input lists. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 126 SUBPROGRAMS FOR SUBSETS OF BANKS 18.4 BSBDRP - Drop a List of Banks from a Subset This subprogram drops the specified list of bank numbers from the Bank Subset for the specified name. _______ ________ Calling Sequence STATUS = BSBDRP(JW,NAME,NRLST,DIM) _____ __________ Input Parameters JW Secondary YBOS array name. NAME (Character) Input bank name. NRLST (Array-integer) List of bank numbers to drop DIM (Integer) The dimension of NRLST ______ __________ Output Parameters None ________ _____ Function Value BSBDRP (Integer) YESUCC Success YECORR Ybos array corrupted N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The NAME parameter must be a valid bank name, although no banks of this name need exist. 3. Entries in the NRLST(DIM) array must be greater than or equal to zero. Numbers less than zero are ignored. Again, the actual banks specified need not exist. Banks specified in NRLST that are not part of the subset for NAME are simply ignored. 4. A BSBDRP call after a call to BSBALD freezes the subset such that its' contents are all current banks minus those specified in NRLST. 5. Note: No banks are droped by this routine. 6. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) CDF-156 YBOS (V4.00) Page 127 SUBPROGRAMS FOR SUBSETS OF BANKS STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 128 SUBPROGRAMS FOR SUBSETS OF BANKS 18.5 BSBPRG - Drop All Banks from a Subset This subprogram drops all bank numbers from the Bank Subset for the specified name. _______ ________ Calling Sequence STATUS = BSBPRG(JW,LIST) _____ __________ Input Parameters JW Secondary YBOS array name. LIST (Character) Set name or bank list ______ __________ Output Parameters None ________ _____ Function Value BSBPRG (Integer) YESUCC Success YECORR Ybos array corrupted N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The LIST parameter may be either a single letter bank set name, "*" for all bank names, or a list of 4 character bank names. 3. This routine cancels previous all calls to BSBADD, BSBALD, and BSBALS for the specified name. 4. Note: No banks are droped by this routine. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 129 SUBPROGRAMS FOR SUBSETS OF BANKS 18.6 BSWRIT/BFSWRT - Write Logical Record, Subsets only This subprogram writes the specified bank set or list of banks to the specified logical unit in the form of a logical record. Only banks that are members of the corresponding Bank Subsets will actually be written. BFSWRT uses optimized I/O while BSWRIT uses standard FORTRAN I/O . _______ ________ Calling Sequence STATUS = BSWRIT(LUNIT,JW,LIST) STATUS = BFSWRT(LUNIT,JW,LIST) _____ __________ Input Parameters LUNIT (Integer) Logical Unit Number...opened by BLOPEN JW YBOS array name LIST (Character) Bank set name or Bank List ______ __________ Output Parameters None ________ _____ Function Value BSWRIT (Integer) YESUCC Success BFSWRT YEILUN Illegal Unit Number YEIOUS Attempting to use input unit for output YELRZL Zero Length Record N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The LIST parameter may be etiher a single letter bank set name or a list of 4 character bank names. 3. The Physical and Logical Record formats are described in detail in Appendix E. 4. If no subset exists for some bank name in LIST or the subset for this name is empty, no banks of this name will be written. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) CDF-156 YBOS (V4.00) Page 130 SUBPROGRAMS FOR SUBSETS OF BANKS STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 131 SUBPROGRAMS FOR SUBSETS OF BANKS 18.7 BSREAD/BFSRED - Read Logical Record and form Subsets This subprogram reads the next logical record from the specified logical unit number and creates the relevant banks and bank set. It then modifies the correponding Bank Subsets According to the MODE input. BFSRED uses optimized I/O while BSREAD uses standard FORTRAN I/O . _______ ________ Calling Sequence STATUS = BSREAD(LUNIT,JW,LIST,NWORDS,MODE) STATUS = BFSRED(LUNIT,JW,LIST,NWORDS,MODE) _____ __________ Input Parameters LUNIT (Integer) Logical Unit Number...opened by BLOPEN JW YBOS array name LIST (Character*1) Bank set name MODE (Character*1) Mode equal "+" --> add to current subset Mode equal "=" --> replace cuurent subset ______ __________ Output Parameters NWORDS (Integer) Logical record length ________ _____ Function Value BSREAD (Integer) YESUCC Success BFSRED YEILUN Illegal Unit Number YEIOUS Attempting to use output unit for input YEEOF End of File detected YELROF Logical Record too big for free space YELRLN Logical Record length inconsistency YEPRBD Too many bad physical records YEBKOS Bank out of sequence YEBKXD Bank length exceeds data YEBKNG Negative bank length YEBKTS Bank length too small YEBSIL Illegal bank set name N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The LIST parameter must give one of the valid bank set names. CDF-156 YBOS (V4.00) Page 132 SUBPROGRAMS FOR SUBSETS OF BANKS 3. If MODE is equal to "+" then existing subsets for the specified names will be modified to include the read banks. If it is equal to "=" existing subsets for the specified names will be purged (BSBPRG) and filled with only the read banks. 4. If MODE is not equal to "+" or "=" then "=" is assumed. 5. NWORDS will return the length of the logical record in Integer units. 6. A count is kept of the number of read errors occurring. If this count exceeds 100 (since opening the unit) then error code YEPRBD is returned. 7. If a bank is found to already exist then the previous incarnation will be deleted and replaced by the version read from the logical record. 8. The Physical and Logical Record formats are described in detail in Appendix E. 9. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 133 SUBPROGRAMS FOR ACCESS TO USER LOCATIONS ___________ ___ ______ __ ____ _________ 19 SUBPROGRAMS FOR ACCESS TO USER LOCATIONS The following subprograms are available:- BRESUS Reserve User Location BRELUS Release User Location BGETUS Get User Location Index CDF-156 YBOS (V4.00) Page 134 SUBPROGRAMS FOR ACCESS TO USER LOCATIONS 19.1 BRESUS - Reserve User Location This subprogram attempts to reserve the specified User Location, and returns the Index to it. _______ ________ Calling Sequence STATUS = BRESUS(JW,USERNO,INDEX) _____ __________ Input Parameters JW Secondary YBOS array name. USERNO (Integer) User Location No. ______ __________ Output Parameters INDEX (Integer) Index to User Location ________ _____ Function Value BRESUS (Integer) YESUCC Success YEILUS Illegal User Location No. YERSUS User Location No. already reserved N.B. 1. The User Location No. USERNO must be in the range 1-32. 2. The User Location may be accessed by reading and writing to JW(INDEX). 3. If the specified User Location is already reserved, INDEX will be set to zero, and an error function value will be returned. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 135 SUBPROGRAMS FOR ACCESS TO USER LOCATIONS 19.2 BRELUS - Release User Location This subprogram releases the previously reserved User Location. _______ ________ Calling Sequence STATUS = BRELUS(JW,USERNO) _____ __________ Input Parameters JW Secondary YBOS array name. USERNO (Integer) User Location No. ______ __________ Output Parameters None ________ _____ Function Value BRELUS (Integer) YESUCC Success YEILUS Illegal User Location No. YENRUS User Location No. not already reserved N.B. 1. The User Location No. USERNO must be in the range 1-32. 2. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 136 SUBPROGRAMS FOR ACCESS TO USER LOCATIONS 19.3 BGETUS - Get Index to User Location This subprogram returns the Index of the specified User Location such that it may be read from and written to. _______ ________ Calling Sequence STATUS = BGETUS(JW,USERNO,INDEX) _____ __________ Input Parameters JW Secondary YBOS array name. USERNO (Integer) User Location No. ______ __________ Output Parameters INDEX (Integer) Index to User Location ________ _____ Function Value BGETUS (Integer) YESUCC Success YEILUS Illegal User Location No. YENRUS User Location No. not already reserved N.B. 1. The User Location No. USERNO must be in the range 1-32. 2. The User Location may be accessed by reading and writing to JW(INDEX). 3. If the specified User Location is not already reserved, INDEX will be set to zero, and an error function value will be returned. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 137 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT ___________ ___ __________ ____________ 20 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT The basic requirement for input and output is that individual banks, lists of banks or bank sets be sequentially accessible from permanent storage in the form of logical records. Since data is stored in the form of physical records then the I/O routines should handle any unpacking necessary. Records that are written should conform to the YBOS defined formats (defined in Appendix E) while records that are read should themselves identify changes to the format that might occur during the course of the experiment. The Input and Output Routines described below allow multiple I/O streams to be open simultaneously, such that, for example, logical records from two input streams may be merged to one output stream. For most routines, both optimized and a standard versions exist. The optimized version will typically result in a 30% reduction in processing time. The optimized routines are not supported for network file access. While this user is allowed to issue MOUNT and OPEN commands in the VAX/VMS environment, routines have been provided to perform these operations in VMS and UNIX environments. The use of these MOUNT/DISMOUNT and OPEN/CLOSE routines is required in the UNIX env. The following routines are available:- BAAPND Append list of banks to an Array BAREAD Read Logical Record from Array BAWRIT Write Logical Record to Array BNREAD Read set of banks from Array BNWRIT Write set of banks to Array BEREAD Read Logical Record into Array BZREAD BEWRIT Write Logical Record from Array BZWRIT BLOPEN Open the specified logical unit for reading BFOPEN or writing BLCLOS Close the specified logical unit. BFCLOS BLREAD Read one logical record from specified BFREAD logical unit. CDF-156 YBOS (V4.00) Page 138 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT BLPICK Open next logical record on specified BFPICK logical unit. BBPICK Read next bank from currently opened BZPICK logical record on specified logical unit. BLVERM The routine specifies a logical record verify mode for the given ybos array. BLWRIT Write one logical record on specified BFWRIT logical unit. BBPUSH Write specified bank to currently opened logical record on specified logical unit. BLPUSH Write currently opened logical record to specified logical unit. CDF-156 YBOS (V4.00) Page 139 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.1 BAAPND - Append List of Banks to an Array This subprogram appends a list of banks to the specified array as if it were a logical record (i.e. the first word of _________ the array contains an exclusive wordcount of the length, followed by YBOS banks.) _______ ________ Calling Sequence STATUS = BAAPND(JW,LIST,ARRAY,ARRLEN,NWORDS) _____ __________ Input Parameters JW YBOS array name holding input data LIST (Character*1) Bank set name or list of banks ARRLEN (Integer*4) Maximum length of output array ______ __________ Output Parameters ARRAY Array that data is appended to NWORDS (Integer*4) Actual number of words written to array ________ _____ Function Value BAAPND (Integer) YESUCC Success YELRZL Attempting to write zero length record YEAROF Array overflow (ACP_NODE) YEBKNG Negative bank length YEBKOV Insufficient space to create bank YERSUS User location already reserved YEBTIL Unrecognized bank Id YEGRIL Unrecognized group Id YECHKF Internal consistancy check failed YESTOF Stack limit exceeded YENOTA Data not alligned YEBNKP Bank padded with extra words N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The LIST parameter must give one of the valid bank set names or a list of bank names. 3. The ARRLEN parameter is the maximum length of the output array. 4. The ARRAY parameter is the array to which banks are appended. It is assumed that the array holds a logical record. CDF-156 YBOS (V4.00) Page 140 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 5. NWORDS will return the length of the data record appended to the array in Integer units. 6. The Logical Record format is described in detail in Appendix E. 7. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 141 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.2 BAREAD - Read Logical Record from Array This subprogram reads the the contents of the specified array as if it were a logical record (i.e. the first word of _________ the array contains an exclusive wordcount of the length, followed by YBOS banks. _______ ________ Calling Sequence STATUS = BAREAD(IARR,JW,LIST,NWORDS) _____ __________ Input Parameters IARR (Integer Array) Input Array JW YBOS array name LIST (Character*1) Bank set name ______ __________ Output Parameters NWORDS (Integer) Logical record length ________ _____ Function Value BAREAD (Integer) YESUCC Success YELROF Logical Record too big for free space YELRLN Logical Record length inconsistency YEBKOS Bank out of sequence YEBKXD Bank length exceeds data YEBKNG Negative bank length YEBKTS Bank length too small YEBSIL Illegal bank set name N.B. 1. The Input Array IARR should be setup such that the _________ first element contains an exclusive wordcount (in Integer words) of the data following. This data should be in the form of sequential YBOS banks. 2. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 3. The LIST parameter must give one of the valid bank set names. 4. NWORDS will return the length of the logical record in Integer units. CDF-156 YBOS (V4.00) Page 142 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 5. If a bank is found to already exist then the previous incarnation will be deleted and replaced by the version read from the logical record. 6. The Logical Record format is described in detail in Appendix E. 7. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 143 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.3 BAWRIT - Write Logical Record to Array This subprogram writes the specified bank set or list of banks to the specified array in the form of a Logical Record. _______ ________ Calling Sequence STATUS = BAWRIT(JW,LIST,IARR,ARRLEN,NWORDS) _____ __________ Input Parameters JW YBOS array name LIST (Character) Bank set name or Bank List IARR (Integer Array) Array to receive Data ARRLEN (Integer) Length of the Array ______ __________ Output Parameters IARR (Integer Array) Array to receive Data NWORDS (Integer) Length of data record written to array ________ _____ Function Value BAWRIT (Integer) YESUCC Success YELRZL Zero Length Record YEOVRF Record overflows Array N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The LIST parameter may be etiher a single letter bank set name or a list of 4 character bank names. 3. The Array to receive the data will be setup such that _________ the first word contains an exclusive count of the no. of words (in Integer) following in the logical record. 4. The Logical Record format is described in detail in Appendix E. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 144 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.4 BNREAD - Read Set Of Banks from Array This subprogram reads the contents of the specified array _________ as if it were a set of contiguous YBOS banks with an exclusive wordcount of the length supplied as an argument in the call to BNREAD. _______ ________ Calling Sequence STATUS = BNREAD(IARR,JW,LIST,NWORDS) _____ __________ Input Parameters IARR (Integer Array) Input Array JW YBOS array name LIST (Character*1) Bank set name NWORDS (Integer) Total length of YBOS banks ______ __________ Output Parameters None ________ _____ Function Value BNREAD (Integer) YESUCC Success YELROF Logical Record too big for free space YELRLN Logical Record length inconsistency YEBKOS Bank out of sequence YEBKXD Bank length exceeds data YEBKNG Negative bank length YEBKTS Bank length too small YEBSIL Illegal bank set name N.B. 1. The Input Array IARR should be sequential YBOS banks. The first element in IARR is the first word (bank name) of a YBOS bank. 2. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 3. The LIST parameter must give one of the valid bank set names. 4. NWORDS is the total length of the set of sequential YBOS banks in Integer units. CDF-156 YBOS (V4.00) Page 145 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 5. If a bank is found to already exist, then the previous incarnation will be deleted and replaced by the version read from the logical record. 6. This read array operation is identical to BAREAD with the length of the YBOS banks provided as an input parameter rather than the first word in IARR. BNREAD returns the same function values as BAREAD. 7. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 146 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.5 BNWRIT - Write Set Of Banks to Array This subprogram writes the specified bank set or list of banks to the specified array. _______ ________ Calling Sequence STATUS = BNWRIT(JW,LIST,IARR,ARRLEN,NWORDS) _____ __________ Input Parameters JW YBOS array name LIST (Character) Bank set name or Bank List IARR (Integer Array) Array to receive Data ARRLEN (Integer) Length of the Array ______ __________ Output Parameters IARR (Integer Array) Array to receive Data NWORDS (Integer) Length of YBOS banks written to array ________ _____ Function Value BNWRIT (Integer) YESUCC Success YELRZL Zero Length Record YEOVRF Record overflows Array N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The LIST parameter may be either a single letter bank set name or a list of 4 character bank names. 3. Array IARR receives the specified bank LIST as a sequential set of banks. The first element in IARR is the first word (bank name) of the first bank. 4. This write array operation is identical to BAWRIT _________ with the exlcusive wordcount (no. of 32-bit words) for the write to IARR returned as NWORDS. Array IARR does not receive the wordcount. BNWRIT returns the same function values as BAWRIT. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 147 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.6 BEREAD/BZREAD - Read Logical Record into Array This subprogram reads the next logical record from the specified logical unit number into the specified Array. It does not perform any YBOS manipulations. BZREAD uses optimized I/O while BEREAD uses standard FORTRAN I/O . _______ ________ Calling Sequence STATUS = BEREAD(LUNIT,IARR,NWMAX,NWORDS) STATUS = BZREAD(LUNIT,IARR,NWMAX,NWORDS) _____ __________ Input Parameters LUNIT (Integer) Logical Unit Number IARR (Integer Array) Array to receive data NXMAX (Integer) Length of the Array ______ __________ Output Parameters NWORDS (Integer) Logical record length ________ _____ Function Value BEREAD (Integer) YESUCC Success BZREAD YEILUN Illegal Unit Number YEIOUS Attempting to use output unit for input YEEOF End of File detected YELROF Logical Record too big for free space YELRLN Logical Record length inconsistency YEPRBD Too many bad physical records YEBKOS Bank out of sequence YEBKXD Bank length exceeds data YEBKNG Negative bank length YEBKTS Bank length too small N.B. 1. The specified Logical Unit LUNIT must previously have been opened via calls to BOS77 (to initialise the primary YBOS array) and BLOPEN/BFOPEN (to create the physical record banks) before calling this subprogram. 2. The Logical Record will be read into the array IARR _________ such that the first word contains an exclusive count of the no. of words in the record, thus being identical to the NWORDS Parameter. CDF-156 YBOS (V4.00) Page 148 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 3. NWORDS will return the length of the logical record in Integer units. 4. A count is kept of the number of read errors occurring. If this count exceeds 100 (since opening the unit) then error code YEPRBD is returned. 5. The Physical and Logical Record formats are described in detail in Appendix E. CDF-156 YBOS (V4.00) Page 149 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.7 BEWRIT/BZWRIT - Write Logical Record from Array This subprogram writes the contents of the specified Array to the specified logical unit in the form of a logical record. BZWRIT uses optimized I/O while BEWRIT uses standard FORTRAN I/O . _______ ________ Calling Sequence STATUS = BEWRIT(LUNIT,IARR) STATUS = BZWRIT(LUNIT,IARR) _____ __________ Input Parameters LUNIT (Integer) Logical Unit Number IARR (Integer Array) Array containing Data ______ __________ Output Parameters None ________ _____ Function Value BEWRIT (Integer) YESUCC Success BZWRIT YEILUN Illegal Unit Number YEIOUS Attempting to use input unit for output YELRZL Zero Length Record N.B. 1. The Array must be setup such that the first word _________ contains an exclusive count (in Integer words) of the no. of words following. 2. The specified Logical Unit LUNIT must previously have been opened via calls to BOS77 (to initialise the primary YBOS array) and BLOPEN/BFOPEN (to create the physical record banks) before calling this subprogram. 3. The Physical and Logical Record formats are described in detail in Appendix E. CDF-156 YBOS (V4.00) Page 150 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.8 BLOPEN/BFOPEN - Open Logical Unit This subprogram opens the specified logical unit number. _______ ________ Calling Sequence STATUS = BFOPEN(LUNIT,LRMAX,NBUF) STATUS = BLOPEN(LUNIT,LRMAX) _____ __________ Input Parameters LUNIT (Integer) Logical Unit Number LRMAX (Integer) Physical Record size in Integer units for writing, or maximum physical record size for reading. For BFOPEN only: NBUF (Integer) <<>> Number of I/O buffers ______ __________ Output Parameters None ________ _____ Function Value BLOPEN (Integer) YESUCC Success BFOPEN YEOVRF Insufficient Space N.B. 1. A named bank '+BUF' is created in the COMMON/BCS/ YBOS array with LRMAX data words. This bank is used to organize the physical records for subsequent I/O ____ operations. This implies that BOS77 must be called before attempting any I/O operations, even if the data to to transferred is purely resident in secondary YBOS arrays. 2. The NBUF parameter is an optional argument for BFOPEN that determines the number of I/O buffers; the default is two. The NBUF argument is used in the VAX environment only. In the VAX environment, NBUF replaces the RMS buffer count. For BLOPEN, the default number of I/O buffers is one. CDF-156 YBOS (V4.00) Page 151 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 3. In the case of TAPE devices, the volume must be mounted via the MOUNT utility for VMS, or the BLPYMT routine for UNIX or VMS. See BLPYMT and BLPYDM documentation. 4. In the current version the logical unit number must still be opened via an ASSIGN or OPEN. The following is an open example: For BLOPEN or BFOPEN, use: Open(unit=lunit,file='file.dat',status='new', - form='unformatted',recl=lrmax,recordtype='fixed') Optionally, for BFOPEN, use: For existing files, Open(unit=lunit,file='file.dat',status='new', - form='unformatted',recl=lrmax,recordtype='fixed', - useropen=ybosio_bioopn) To create files, Open(unit=lunit,file='file.dat',status='new', - form='unformatted',recl=lrmax,recordtype='fixed', - useropen=ybosio_biocrt) Failure to use the "Useropen" will result in poor performance. 5. The user should use the BLPYOP routine to open files in the UNIX environment. BLPYOP can also be used in the VMS environment. See BLPYOP and BLPYCL documentation. 6. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) 7. In the BFOPEN context, NBUF determines the number of I/O buffers. I/O buffers determine the unit of physical I/O. The size of each I/O buffer must be such that NUMSEG*4*LPRMAX = n*512 where NUMSEG=8, and n=1,2,3...This is required so that physical I/O will be alligned on disk blocks. Note: NUMSEG is the CDF-156 YBOS (V4.00) Page 152 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT number of physical records per I/O buffer. 8. Because YBOSIO has been ported to multiple computing environments, two routines have been provided to perform MOUNT and OPEN functions, BLPYMT and BLPYOP. The VAX open specifications above are still valid, but it is recomended that these routines be used for newly developed code. CDF-156 YBOS (V4.00) Page 153 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.9 BLPYMT - Mount A Volume On A Tape Device This routine mounts the specified volume on the specified tape device. This routine is intended for UNIX and VMS usage. _______ ________ Calling Sequence STATUS = BLPYMT(DEV,UNIT,VOLID,BLKSZ,MODE) _____ __________ Input Parameters DEV (Character) Tape device name in native format. VMS: mua0 UNIX: /xxx/yyy/tps# UNIT (Integer) Logical Unit Number VMS context. JFN number UNIX context. VOLID (Character) Volume label...max six characters. BLKSZ (Integer) Block size: Max for VMS and defined I/O size for UNIX. MODE (Character*4) Read or Write mode...UNIX context only. Supply as a dummy in the VMS context. ______ __________ Output Parameters None ________ _____ Function Value BLPYMT (Integer) YESUCC Success VMS/RMS error or UNIX/RBIO error N.B. 1. It is essential to note that the UNIX tape device file name is tps ( is an integer). No other name format will work. 2. It is essential to note that the UNIX JFN has an allowed range of 00-99. CDF-156 YBOS (V4.00) Page 154 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.10 BLPYDM - Dismount A Volume From A Tape Device This routine dismounts the specified volume from the specified tape device. This routine is intended for UNIX and VMS usage. _______ ________ Calling Sequence STATUS = BLPYDM(DEV,UNIT) _____ __________ Input Parameters DEV (Character) Tape device...VMS context only. VMS: mua0 UNIT (Integer) JFN Unit Number...UNIX context only. ______ __________ Output Parameters None ________ _____ Function Value BLPYDM (Integer) YESUCC Success VMS/RMS error or UNIX/RBIO error N.B. 1. It is essential to note that the UNIX JFN has an allowed range of 00-99. CDF-156 YBOS (V4.00) Page 155 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.11 BLPYOP - Open A File On A Volume This routine opens the specified file from the specified volume. This routine is intended for UNIX and VMS usage. _______ ________ Calling Sequence STATUS = BLPYOP(LUNIT,FILEN,STAT,RECLN,SEQ,BLKSZ,FAST) _____ __________ Input Parameters LUNIT (Integer) Logical Unit Number.. JFN Unit number...UNIX tape context FILEN (char) File name...includes device name for tapes VAX : MUA0:XXX.YYY MIPS : /dev/vtp/tps1:D=XXX.YYY or /dev/vtp/tps1 where sequence # is used STAT (Char) "old" or "new" file...VMS context. RECLN (Integer) Record length in longwords SEQ (Integer) File sequence number...UNIX tape context. Used if no file name present in FILEN. BLKSZ (Integer) block size ....UNIX tape context FAST (Logical) Fast mode flag for VMS context. ______ __________ Output Parameters FILEN (char>=17) Returned if SEQ # used in UNIX tape context. ________ _____ Function Value BLPYOP (Integer) YESUCC Success VMS/RMS error or UNIX/RBIO error N.B. 1. It is essential to note that the UNIX JFN has an allowed range of 00-99. 2. The RECLN and BLKSZ must be consistent with that actually used on tapes opened for read. In the UNIX context, one can determine these values via RBIO routine calls...RBRECLEN, RBLKLEN.... 3. Out of context calling arguments are ignored, but must be passed. CDF-156 YBOS (V4.00) Page 156 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.12 BLPYCL - Close A File On A Volume This routine closes the specified file on the specified volume. This routine is intended for UNIX and VMS usage. _______ ________ Calling Sequence STATUS = BLPYCL(LUNIT) _____ __________ Input Parameters LUNIT (Integer) Logical Unit Number. JFN Unit number...UNIX tape context ______ __________ Output Parameters NONE ________ _____ Function Value BLPYCL (Integer) YESUCC Success VMS/RMS error or UNIX/RBIO error N.B. 1. It is essential to note that the UNIX JFN has an allowed range of 00-99. CDF-156 YBOS (V4.00) Page 157 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.13 BLCLOS/BFCLOS - Close Logical Unit This subprogram closes the specified logical unit number. Use BFCLOS if the logical unit was opened with BFOPEN and BLCLOS if the unit was opened with BLOPEN. Any incompletely filled physical records are written to the unit if this unit was opened for writing. _______ ________ Calling Sequence STATUS = BLCLOS(LUNIT) STATUS = BFCLOS(LUNIT) _____ __________ Input Parameters LUNIT (Integer) Logical Unit Number ______ __________ Output Parameters None ________ _____ Function Value BLCLOS (Integer) YESUCC Success BFCLOS YEILUN Illegal Unit N.B. 1. The named bank '+BUF' is deleted from the COMMON/BCS/ YBOS array. 2. In the current version the logical unit number must still be closed via CLOSE. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) 4. Because YBOSIO has been ported to multiple computing environments, two routines have been provided to perform DISMOUNT and CLOSE functions, BLPYDM and BLPYCL. 1. CDF-156 YBOS (V4.00) Page 158 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.14 BLREAD/BFREAD - Read Logical Record This subprogram reads the next logical record from the specified logical unit number and creates the relevant banks and bank set. BFREAD uses optimized I/O and requires the use of BFOPEN and BFCLOS. BLREAD uses standard FORTRAN I/O and requires the use of BLOPEN and BLCLOS. _______ ________ Calling Sequence STATUS = BLREAD(LUNIT,JW,LIST,NWORDS) STATUS = BFREAD(LUNIT,JW,LIST,NWORDS) _____ __________ Input Parameters LUNIT (Integer) Logical Unit Number JW YBOS array name LIST (Character*1) Bank set name ______ __________ Output Parameters NWORDS (Integer) Logical record length ________ _____ Function Value BLREAD (Integer) YESUCC Success BFREAD YEILUN Illegal Unit Number YEIOUS Attempting to use output unit for input YEEOF End of File detected YELROF Logical Record too big for free space YELRLN Logical Record length inconsistency YEPRBD Too many bad physical records YEBKOS Bank out of sequence YEBKXD Bank length exceeds data YEBKNG Negative bank length YEBKTS Bank length too small YEBSIL Illegal bank set name N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The LIST parameter must give one of the valid bank set names. CDF-156 YBOS (V4.00) Page 159 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 3. NWORDS will return the length of the logical record in Integer units. 4. A count is kept of the number of read errors occurring. If this count exceeds 100 (since opening the unit) then error code YEPRBD is returned. 5. If a bank is found to already exist then the previous incarnation will be deleted and replaced by the version read from the logical record. 6. The Physical and Logical Record formats are described in detail in Appendix E. 7. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) 8. $BANK handling is controlled by a call to BOPTN just before the BLREAD /BFREAD call. STATUS = BOPTN(JW,OPTION) STATUS = BLREAD(...) or BFREAD where OPTION is an Integer having the following meanings:- OPTION = 0 $Banks on tape overwrite $Banks of the same name and number in the YBOS array. OPTION = 1 $Banks on tape do not overwrite $Banks of the same name and number in the YBOS array. CDF-156 YBOS (V4.00) Page 160 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.15 BLPICK/BFPICK - Position Logical Record This subprogram positions the logical unit at the start of the next logical record (skipping over any incompletely read logical record) such that subsequent calls to BBPICK/BZPICK will pick single banks from the record. BFPICK uses optimized I/O and requires the use of BFOPEN and BFCLOS. BLPICK uses standard FORTRAN I/O and requires the use of BLOPEN and BLCLOS. _______ ________ Calling Sequence STATUS = BLPICK(LUNIT,JW,NWORDS) STATUS = BFPICK(LUNIT,JW,NWORDS) _____ __________ Input Parameters LUNIT (Integer) Length of logical record (or zero if the length was not known at creation time). JW YBOS array name ______ __________ Output Parameters NWORDS (Integer) Length of logical record (or zero if length was not known at creation time). ________ _____ Function Value BLPICK (Integer) YESUCC Success BFPICK YEILUN Illegal Unit Number YEIOUS Attempting to use output unit for input YEEOF End of File detected YEPRBD Too many bad physical records N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. NWORDS provids the length of the logical record in Integer units. It will be set to zero if the length of the logical record was not known at the time the record was created . 3. A count is kept of the number of read errors occurring. If this count exceeds 100 (since opening the unit) then error code YEPRBD is returned. CDF-156 YBOS (V4.00) Page 161 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 4. The Physical and Logical Record formats are described in detail in Appendix E. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 162 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.16 BBPICK/BZPICK - Pick One Bank from Logical Record This subprogram will read one bank from the currently opened logical record. BZPICK uses optimized I/O and requires the use of BFOPEN and BFCLOS. BBPICK uses standard FORTRAN I/O and requires the use of BLOPEN and BLCLOS. _______ ________ Calling Sequence STATUS = BBPICK(LUNIT,JW,IND) STATUS = BZPICK(LUNIT,JW,IND) _____ __________ Input Parameters LUNIT (Integer) Logical Unit Number JW YBOS array name ______ __________ Output Parameters IND (Integer) Index to bank (or zero if logical record exhausted) ________ _____ Function Value BBPICK (Integer) YESUCC Success BZPICK YEILUN Illegal Unit Number YEIOUS Attempting to use output unit for input YEEOF End of File detected YELROF Bank to large for free space YEPRXL Too many bad physical record N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. If a bank is found to already exist then the previous incarnation will be deleted and replaced by the version read from the logical record. 3. The Physical and Logical Record formats are described in detail in Appendix E. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 163 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.17 BLVERM - Specify a Logical Record Verify Mode This subprogram will specify that bank header words be verified prior to writting a logical record to a physical record. _______ ________ Calling Sequence STATUS = BLVERM(JW,MODE) _____ __________ Input Parameters JW YBOS array name ______ __________ Output Parameters MODE (Integer) New verify mode 0 No verification 1 banks verified on output ________ _____ Function Value BLVERM (Integer) YESUCC Success N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. If mode is 1, BVERIF will be called to verify bank headers prior to output of a logical record to a physical record. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 164 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.18 BLWRIT/BFWRIT - Write Logical Record This subprogram writes the specified bank set or list of banks to the specified logical unit in the form of a logical record. BFWRIT uses optimized I/O and requires the use of BFOPEN and BFCLOS. BLWRIT uses standard FORTRAN I/O and requires the use of BLOPEN and BLCLOS. _______ ________ Calling Sequence STATUS = BLWRIT(LUNIT,JW,LIST) STATUS = BFWRIT(LUNIT,JW,LIST) _____ __________ Input Parameters LUNIT (Integer) Logical Unit Number JW YBOS array name LIST (Character) Bank set name or Bank List ______ __________ Output Parameters None ________ _____ Function Value BLWRIT (Integer) YESUCC Success BFWRIT YEILUN Illegal Unit Number YEIOUS Attempting to use input unit for output YELRZL Zero Length Record N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The LIST parameter may be etiher a single letter bank set name or a list of 4 character bank names. 3. The Physical and Logical Record formats are described in detail in Appendix E. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 165 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.19 BBPUSH - Write one Bank to Logical Record ** This subprogram writes the specified bank, bank set or list of banks to the currently opened logical record on the specified logical unit. It may be called several times in order to all extra banks to the logical record. _______ ________ Calling Sequence STATUS = BBPUSH(LUNIT,JW,LIST) _____ __________ Input Parameters LUNIT (Integer) Logical Unit JW YBOS array LIST (Character) Bank set name or bank list ______ __________ Output Parameters None ________ _____ Function Value BBPUSH (Integer) YESUCC Success YEILUN Illegal Unit Number YEIOUS Attempting to use input unit for output N.B. 1. The array name JW may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The LIST parameter may be either a single letter bank set name or a list of 4 character bank names. 3. The Physical and Logical Record formats are described in detail in Appendix E. ** This subprogram is not yet implemented. CDF-156 YBOS (V4.00) Page 166 SUBPROGRAMS FOR SEQUENTIAL INPUT/OUTPUT 20.20 BLPUSH - Push Logical Record ** This subprogram closes the currently opened logical record for writing (via BBPUSH) on the specified logical unit. _______ ________ Calling Sequence STATUS = BLPUSH(LUNIT,JW) _____ __________ Input Parameters LUNIT (Integer) Logical Unit Number JW YBOS array ______ __________ Output Parameters None ________ _____ Function Value BLPUSH (Integer) YESUCC Success YEILUN Illegal Unit Number YEIOUS Attempting to use input unit for output N.B. 1. The Physical and Logical Record formats are described in detail in Appendix E. ** This subprogram is not yet implemented. CDF-156 YBOS (V4.00) Page 167 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT ___________ ___ ____ _____ ____________ 21 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT The following subprograms are available for saving YBOS arrays on disc, restoring them from disc and for accessing individual banks or lists of banks from disc. Note that these subprograms allow multiple files to be open simultaneously. BDSAVE Dump YBOS Array to Discfile BDREST Restore YBOS array from Discfile BDOPEN Open Discfile for reading BDCLOS Close previously opened Discfile BDRBNK Read Single Bank from discfile BDRLST Read Banks or List of banks from discfile BDRNUM Read Specified Banks from discfile BDWBNK Write Single Bank to discfile BDWLST Write Banks or List of banks to discfile BDWNUM Write Specified Banks to discfile BDUNIT Specify new Logical Unit No. for Disc BDRECL Specify new Record Length for Disc I/O BDLIST Modify bank set with all names on disk BDNLST Return a list of all banks of a given name on disk BDNEAR Find first bank of given name with number greater that some threshold. BDBGST Find the largest bank number for a given name on disk. BDSMLL Find the smallest bank number for a given name on disk. BDJRNL Enable/disable file journaling. BDSEAR Search A disk file for a target bank. CDF-156 YBOS (V4.00) Page 168 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.1 BDSAVE - Save YBOS Array Named Bank Region on Discfile This subprogram writes the specified YBOS array named bank region to the specified Discfile. _______ ________ Calling Sequence STATUS = BDSAVE(JW,FILNAM) _____ __________ Input Parameters JW YBOS array FILNAM (Character) Discfile Name ______ __________ Output Parameters None ________ _____ Function Value BDSAVE (Integer) YESUCC Success YEILUN Illegal Unit Number > 0 Standard VAX/VMS Error Code N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The standard Logical Unit Number with which the data is written is 30. This may be changed via a call to BDUNIT. 3. The standard record length can be changed via a call to BDRECL. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 169 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.2 BDREST - Restore YBOS Array Named Bank Region from Discfile This subprogram restores the specified YBOS array named bank region from the specified Discfile. _______ ________ Calling Sequence STATUS = BDREST(JW,NDIM,FILNAM) _____ __________ Input Parameters JW YBOS array NDIM (Integer) The Size of the Array (In Integer words) FILNAM (Character) The Discfile Name ______ __________ Output Parameters None ________ _____ Function Value BDREST (Integer) YESUCC Success YEILUN Illegal Unit Number YEOVRF Insufficient Space > 17 Standard VAX/VMS Error Code N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. Any previous information in this array will be lost. 2. It is not necessary that the size of the array JW (given by NDIM) be identical to that of the original array from which the discfile was created. However, an error return will be taken if the specified array is too small. In this case the user should not assume that the array is correctly setup. 3. On completion of this call the status of the named banks in JW is essentially identical to that of the original array at the time it was written to disc via BDSAVE (except for any length differences). The user may manipulate banks as normal. 4. The standard Logical Unit Number with which the data is read is 30. This may be changed via a call to BDUNIT. CDF-156 YBOS (V4.00) Page 170 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 5. The Illegal Logical Unit Error indicates that a discfile is already opened (via BDOPEN) on the currently setup YBOS disc logical unit number. The user should correct the fault by using BDUNIT. 6. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 171 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.3 BDOPEN - Open Discfile for YBOS I/O This subprogram opens the specified discfile such that individual banks, or lists of banks may be read from it or written to it. _______ ________ Calling Sequence STATUS = BDOPEN(JW,LUNIT,FILNAM,CREATE,RCLEN) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical Unit No. FILNAM (Character) Discfile Name CREATE (Integer) Create file RCLEN (Integer) File record length ______ __________ Output Parameters None ________ _____ Function Value BDOPEN (Integer) YESUCC Success YEILUN Illegal Unit Number YEOVRF Insufficient Space > 0 Standard VAX/VMS Error Code N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. This call creates bank (name)"+DSK" (number)"LUNIT" containing pointers to binary search work banks used to locate named banks on the diskfile. This Data structure is refered to as the diskfile dictionary. 3. If the specified Logical Unit already has an opened file (via BDOPEN), then it will be closed. 4. If the diskfile dictionary from a previous BDOPEN has been saved on disk by BDCLOS, BDOPEN will, by default, read it from disk rather than build it from scratch. 5. If CREATE equals 1, the a new file is created if no file exists. CDF-156 YBOS (V4.00) Page 172 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 6. RCLEN is the file record length in longwords. 7. The following BOPTN options are available: BOPTN(JW,OPTION) OPTION = 1 --> Open file readonly OPTION = 2 --> Build disk dictionary, rather than read it from disk OPTION = 3 --> Readonly and Build 8. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 173 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.4 BDCLOS - Close Discfile This subprogram closes the currently opened Discfile. _______ ________ Calling Sequence STATUS = BDCLOS(JW,LUNIT) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical Unit No. ______ __________ Output Parameters None ________ _____ Function Value BDCLOS (Integer) YESUCC Success YEILUN Illegal Unit Number N.B. 1. The JW array should correspond to that used in the previous call to BDOPEN. 2. To save the diskfile dictionary (see BDOPEN) call BOPTN with option equal 1 just before the BDCLOS call. 3. Once the diskfile dictionary has been saved by BDCLOS, all subsequent BDCLOS calls for that file will automatically save the dictionary. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 174 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.5 BDRBNK - Read a Single YBOS Bank from Discfile This subprogram reads the specified YBOS bank from the currently opened (via BDOPEN) discfile into the specified YBOS array. _______ ________ Calling Sequence STATUS = BDRBNK(JW,LUNIT,NAME,NR,IND) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical Unit No. NAME (Character) Bank Name NR (Integer) Bank Number ______ __________ Output Parameters IND (Integer) Index to the Bank (or zero if non-existent) ________ _____ Function Value BBRBNK (Integer) YESUCC Success YEILUN Illegal Unit Number YENOBK Non-existent Bank YEOVRF Insufficient Space N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The JW array should correspond to that used in the previous call to BDOPEN with this Logical Unit No. 3. If the specified Bank already exists then it will be deleted before performing the read from disc. 4. If NR is negative, then BDRBNK will read the lowest numbered Bank with the specified Bank Name from the discfile. The actual number of this Bank may be determined using the BNUMB routine described elsewhere. 5. The YENOBK Return is informational only, no Error Message being reported. 6. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, CDF-156 YBOS (V4.00) Page 175 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 176 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.6 BDRLST - Read Banks or List of Banks from Disc This subprogram reads all the banks with the specified Bank Name, or all Banks in the specified List of names, from the Discfile. _______ ________ Calling Sequence STATUS = BDRLST(JW,LUNIT,LIST) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical Unit No. LIST (Character) Set name or bank list ______ __________ Output Parameters None ________ _____ Function Value BDRBNK (Integer) YESUCC Success YEILUN Illegal Unit Number YEOVRF Insufficient Space N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The JW array should correspond to that used in the previous call to BDOPEN with the specified Logical Unit No. 3. If any of the specified banks already exist they will be deleted before performing the read from disc. 4. The LIST parameter may be either a single letter bank set name, "*" for all bank names, or a list of 4-character bank names (e.g. ANDYBERTCARLDAVE). In any case, all banks with the specified name or names (but differing bank numbers) will be read. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 177 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.7 BDRNUM - Read Banks from Disc This subprogram reads all the specified banks (having the specified Bank Name and Numbers as given in the array) from the Discfile. _______ ________ Calling Sequence STATUS = BDRNUM(JW,LUNIT,NAME,LIST,NUMB) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical Unit No. NAME (Character*4) Bank Name LIST (Integer Array) Array of Bank numbers NUMB (Integer) Length of LIST Array ______ __________ Output Parameters None ________ _____ Function Value BDRNUM (Integer) YESUCC Success YEILUN Illegal Unit Number YEOVRF Insufficient Space N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The JW array should correspond to that used in the previous call to BDOPEN with the specified Logical Unit No. 3. If any of the specified banks already exist they will be deleted before performing the read from disc. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 178 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.8 BDWBNK - Write a single YBOS Bank to Discfile This subprogram writes the specified YBOS bank from the specified YBOS array to the currently opened (via BDOPEN) discfile. _______ ________ Calling Sequence STATUS = BDWBNK(JW,LUNIT,NAME,NR,IND) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical Unit No. NAME (Character) Bank Name NR (Integer) Bank Number ______ __________ Output Parameters IND (Integer) Index to the Bank (or zero if non-existent) ________ _____ Function Value BDWBNK (Integer) YESUCC Success YEILUN Illegal Unit Number YEOVRF Insufficient Space N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The JW array should correspond to that used in the previous call to BDOPEN with the specified Logical Unit No. 3. The specified Bank should have the same characteristics as the bank already residing on disc. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 179 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.9 BDWLST - Write Banks or List of Banks to Disc This subprogram writes all the banks with the specified Bank Name, or all Banks in the specified List of names, to the Discfile. _______ ________ Calling Sequence STATUS = BDWLST(JW,LUNIT,LIST) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical Unit No. LIST (Character) Set name or bank list ______ __________ Output Parameters None ________ _____ Function Value BDWLST (Integer) YESUCC Success YEILUN Illegal Unit Number YEOVRF Insufficient Space N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The JW array should correspond to that used in the previous call to BDOPEN with the specified Logical Unit No. 3. The LIST parameter may be either a single letter bank set name, "*" for all bank names, or a list of 4-character bank names (e.g. ANDYBERTCARLDAVE). In any case, all banks with the specified name or names (but differing bank numbers) will be written. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 180 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.10 BDWNUM - Write Banks to Disc This subprogram writes all the specified banks to the Discfile. _______ ________ Calling Sequence STATUS = BDWNUM(JW,LUNIT,NAME,LIST,NUMB) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical Unit No. NAME (Character*4) Bank Name LIST (Integer Array) Array of bank numbers NUMB (Integer) Length of LIST Array ______ __________ Output Parameters None ________ _____ Function Value BDWNUM (Integer) YESUCC Success YEILUN Illegal Unit Number YEOVRF Insufficient Space N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The JW array should correspond to that used in the previous call to BDOPEN with the specified Logical Unit No. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 181 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.11 BDUNIT - Specify new Logical Unit for Disc I/O This subprogram specifies a new Logical Unit Number for all subsequent BDSAVE or BDREST operations. _______ ________ Calling Sequence STATUS = BDUNIT(JW,LUNIT) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical Unit Number ______ __________ Output Parameters None ________ _____ Function Value BDUNIT (Integer) YESUCC Success YEILUN Illegal Unit Number N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. A Logical Unit of 0 will cause the default (30) to be setup. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 182 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.12 BDRECL - Specify new Record Length for Disc I/O This subprogram specifies a new record length for all subsequent BDSAVE operations. _______ ________ Calling Sequence STATUS = BDRECL(JW,RECLEN) _____ __________ Input Parameters JW YBOS array RECLEN (Integer) RECORD length...longwords ______ __________ Output Parameters None ________ _____ Function Value BDRECL (Integer) YESUCC Success N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. A RECLEN of -1 will cause the default (128 longwords) to be setup. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 183 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.13 BDLIST - Modify A Bank Set With All Banks On Disk This subprogram modifies the input bank set by adding all bank names on disk to it, dropping all bank names on disk from it, or defining it as all bank names on disk. _______ ________ Calling Sequence STATUS = BDLIST(JW,LUNIT,OPT) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) The logical unit of the opened file OPT (Character*2) Option specifier ______ __________ Output Parameters None ________ _____ Function Value BDLIST (Integer) Status Flag N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The logical unit, LUNIT, must have been opened by a previous BDOPEN call. 3. The option specifier is a string of two characters of the form 'L=', 'L+' or 'L-' where L is one of the allowed bank set names (A-Z) and '=' means copy, '+' means add and '-' means delete. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 184 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.14 BDNEAR - Find The First Bank Number On Disk That Exceeds A Threshold This subprogram finds the first bank of a given name whose number exceeds some input threshold number. _______ ________ Calling Sequence STATUS = BDNEAR(JW,LUNIT,NAME,NR,NRNXT) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical unit of open file NAME (Character*4) Bank Name NR (Integer) Threshold bank number ______ __________ Output Parameters NRNXT (Integer) Number of first existing bank with name NAME such that NRNXT>NR ________ _____ Function Value BDNEAR (Integer) Status Flag N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The logical unit, LUNIT, must have been opened by a previous BDOPEN call. 3. The bank with name NAME and number NR need not exist on disk. 4. This search operation requires no disk I/O. 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 185 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.15 BDNLST - Return A List Of All Banks On Disk With A Given Name This subprogram returns the index of a work bank that holds a list of all banks on disk with the input name. _______ ________ Calling Sequence STATUS = BDNLST(JW,LUNIT,NAME,INDX) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical unit of open file NAME (Character*4) Bank Name ______ __________ Output Parameters INDX (Integer) Index to the list work bank ________ _____ Function Value BDNLST (Integer) Status Flag N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The logical unit, LUNIT, must have been opened by a previous BDOPEN call. 3. This search operation requires no disk I/O. 4. The numbers of all banks on disk of name NAME are sequentially stored in JW(INDX+1) to JW(INDX+JW(INDX)). 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 186 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.16 BDBGST - Find Largest Bank Number On Disk For A Given Name This subprogram returns the largest bank number on disk for the input name. _______ ________ Calling Sequence STATUS = BDBGST(JW,LUNIT,NAME,NR) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical unit of opened file NAME (Character*4) Bank Name ______ __________ Output Parameters NR (Integer) Largest bank number on disk for name NAME ________ _____ Function Value BDBGST (Integer) Status Flag N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The logical unit, LUNIT, must have been opened by a previous BDOPEN call. 3. This search operation requires no disk I/O. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 187 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.17 BDSMLL - Find Smallest Bank Number On Disk For A Given Name This subprogram returns the smallest bank number on disk for the input name. _______ ________ Calling Sequence STATUS = BDSMLL(JW,LUNIT,NAME,NR) _____ __________ Input Parameters JW YBOS array LUNIT (Integer) Logical unit of opened file NAME (Character*4) Bank Name ______ __________ Output Parameters NR (Integer) Smallest bank number on disk for name NAME ________ _____ Function Value BDSMLL (Integer) Status Flag N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The logical unit, LUNIT, must have been opened by a previous BDOPEN call. 3. This search operation requires no disk I/O. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 188 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.18 BDJRNL - Turn On/off File Journaling This subprogram enables/disables file journaling for the files opened by BDOPEN calls that follow. File journaling is relevant only for files opened for write access. _______ ________ Calling Sequence STATUS = BDJRNL(JW,MODE) _____ __________ Input Parameters JW YBOS array MODE (Integer) Journal Mode: MODE = 1 Journaling enabled MODE = 0 Journaling disabled ______ __________ Output Parameters NONE ________ _____ Function Value BDJRNL (Integer) Status Flag N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. YBOS file Journaling protects against corruption of files due to improper program termination. 3. File journaling means that BDOPEN will create a copy of the file ,FILNAM, and open the copy for YBOS disk I/O. BDCLOS will rename the copy (the journal file) to FILNAM only after all I/O is complete. It is important that BDCLOS be called to complete the I/O session. Failure to call BDCLOS will result in the journal file not being renamed, and important file header data being lost. Thus, if BDCLOS is not called, all I/O will be lost and file FILNAM will remain as it was prior to the BDOPEN. 4. File journaling is, by default, enabled for files opened for write access. 5. Since journaling involves additional overhead, YBOS I/O performance is hindered. Thus, it is suggested that journaling be disabled for less important files. For example: CDF-156 YBOS (V4.00) Page 189 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT STATUS = BDJRNL(JW,0) (disable journaling) STATUS = BDOPEN(JW,LUNIT,'DUMMY.DAT') . . STATUS = BDJRNL(JW,1) (Enable journaling) STATUS = BDOPEN(JW,LUNIT,'FILE1.DAT') STATUS = BDOPEN(JW,LUNIT,'FILE2.DAT') STATUS = BDOPEN(JW,LUNIT,'FILE3.DAT').... 6. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 190 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT 21.19 BDSEAR - Search A Disk File For A Target Bank This Subroutine is used to locate a bank (NAME, STRNUM) in a binary search work bank (disk file dictionary), then read, from disk, a bank of the same name that is OFFSET banks from STRNUM. _______ ________ Calling Sequence STATUS = BDSEAR(JW,LUNIT,NAME,STRNUM,STROFF,OFFSET,INDWK) _____ __________ Input Parameters JW (Integer*4 Array) YBOS Array that the target bank is read into. LUNIT (Integer*4) I/O logical unit for the desired disk file NAME (Character) Bank name STRNUM (Integer*4) Start bank number STROFF (Integer*4) Offset to start bank number in bin sear. OFFSET (Integer*4) Offset from STRNUM to target bank ______ __________ Output Parameters INDWK (Integer*4) Index to a work bank holding the target bank index and bin. sear. offsets. This work bank index is specific to a given bank name and I/O channel. It is the users reposibility to maintain its uniqueness. ________ _____ Function Value BDSEAR (Integer) Status Flag N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The disk file must have already been opened by BDOPEN. 3. The index to target bank, and the offsets in the binary search work bank to the target and start banks are located in a work bank pointed to by INDWK. The offsets in the INDWK work bank are used to avoid binary searching for STRNUM in the case of second, third... calls to BDSEAR (if STROFF is 0, a binary search for STRNUM will result; if STROFF JW(INDWK+2) or JW(INDWK+3), no binary search is needed). JW(INDWK+1) = Target bank index JW(INDWK+2) = offset to the start bank's entry in the Disk CDF-156 YBOS (V4.00) Page 191 SUBPROGRAMS FOR DISC BASED INPUT/OUTPUT file dictionary. JW(INDWK+3) = offset to the target bank's entry in the Disk file disctionary. example!!!!!! CDF-156 YBOS (V4.00) Page 192 SUBPROGRAMS FOR NAMED BANK VALIDATION ___________ ___ _____ ____ __________ 22 SUBPROGRAMS FOR NAMED BANK VALIDATION A common problem in code making use of ybos banks is for the header of one named bank to be inadvertently overwritten when storing data in the preceeding bank. Header, here, refers to the first four words of the named bank (name, number, pointer, and number of data words). Serveral routines have been written to detect when a named bank header has been corrupted. Another common problem is for an extended bank type header to have inconsistencies. A routine has been written to detect these problems as well. The following subprograms are available:- BVALID Validate YBOS array named bank region BVALON Turn normal bank validation mode on BVALOF Turn any bank validation mode off BVALST Set an alternate validation mode BVALEX Examine bank validation mode BCHECK Check extended bank header for consistency CDF-156 YBOS (V4.00) Page 193 SUBPROGRAMS FOR NAMED BANK VALIDATION 22.1 BVALID - Validate YBOS Array Named Bank Region This function validated the named bank region of the input Ybos array JW. _______ ________ Calling Sequence STATUS = BVALID(JW) _____ __________ Input Parameters JW YBOS array name ______ __________ Output Parameters None ________ _____ Function Value BVALID (Integer) YESUCC Success YEBDBK Header bank name word corrupted YENONR Header bank number word invalid YEBDCH Corrupted bank chain YEBDLU Corrupted blink work bank YEBDBS Corrupted binnary search bank N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The YEBDCH error (Corrupted bank chain) implies that the primary bank location mechanism has been corrupted. Usually this error is reported when the bank number or next bank pointer header words have been corrupted. 3. The YEBDLU error (Corrupted blink work bank) implies that a direct lookup work bank, created by BLINK, holds inaccurate information about the location of a named bank, or lacks information for the named bank. 4. The YEBDBS error (Corrupted binnary search bank) implies the the mechanism for locating banks of a given name for which there are more that IYMAXN banks is corrupt. CDF-156 YBOS (V4.00) Page 194 SUBPROGRAMS FOR NAMED BANK VALIDATION 22.2 BVALON - Turn On Bank Validation Mode This function turns normal bank validation on for all subsequent Ybos function calls. Normal bank validation implies that function calls will fail if named bank validation finds errors. _______ ________ Calling Sequence STATUS = BVALON(JW) _____ __________ Input Parameters JW YBOS array name ______ __________ Output Parameters None ________ _____ Function Value BVALON (Integer) YESUCC Success N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. Bank validation mode means that all Ybos functions will call BVALID prior to performing its specific operation. Since this is very time consuming, bank validation mode should be used as a dubugging tool only. 3. To turn bank validation off, call BVALOF CDF-156 YBOS (V4.00) Page 195 SUBPROGRAMS FOR NAMED BANK VALIDATION 22.3 BVALOF - Turn Off Bank Validation Mode This function turns bank validation off for all subsequent Ybos function calls. _______ ________ Calling Sequence STATUS = BVALOF(JW) _____ __________ Input Parameters JW YBOS array name ______ __________ Output Parameters None ________ _____ Function Value BVALOF (Integer) YESUCC Success N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. Bank validation mode means that all Ybos functions will call BVALID prior to performing its specific operation. Since this is very time consuming, bank validation mode should be used as a dubugging tool only. 3. To turn bank validation on, call BVALON CDF-156 YBOS (V4.00) Page 196 SUBPROGRAMS FOR NAMED BANK VALIDATION 22.4 BVALST - Select an Alternate Bank Validation Mode This function turns normal or continue mode bank validation on for all subsequent Ybos function calls. Normal bank validation implies that function calls will fail if named bank validation finds errors. Continue mode bank validation implies that function calls will continue and possibly succeed even if bank validation finds errors. _______ ________ Calling Sequence STATUS = BVALST(JW,NEWMOD,OLDMOD) _____ __________ Input Parameters JW YBOS array name NEWMOD (INTEGER) Desired bank validation mode. NEWMOD = 0 implies all bank validation is turned off. NEWMOD = 1 implies normal bank validation will be turned on. NEWMOD = 2 implies continue mode bank validation will be turned on. ______ __________ Output Parameters OLDMOD (INTEGER) Old bank validation mode. ________ _____ Function Value BVALST (Integer) YESUCC Success N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. Bank validation mode means that all Ybos functions will call BVALID prior to performing its specific operation. Since this is very time consuming, bank validation mode should be used as a dubugging tool only. CDF-156 YBOS (V4.00) Page 197 SUBPROGRAMS FOR NAMED BANK VALIDATION 22.5 BVALEX - Examine Named Bank Validation Flag This function returns the named bank validation flag. _______ ________ Calling Sequence STATUS = BVALEX(JW,FLAG) _____ __________ Input Parameters JW YBOS array ______ __________ Output Parameters FLAG Named bank validation flag. FLAG = 0 implies all bank validation is turned off. FLAG = 1 implies normal bank validation is turned on (ybos function calls will fail if bank validation finds errors) FLAG = 2 implies continue mode bank validation is turned on (ybos function calls will continue and possibly succeed even if bank validation finds errors) N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. CDF-156 YBOS (V4.00) Page 198 SUBPROGRAMS FOR NAMED BANK VALIDATION 22.6 BCHECK - Check Extended Bank Header for Consistency This function checks the new ybos extended bank header for consistency and completeness. No printout is performed (other than calls to BWARN). _______ ________ Calling Sequence STATUS = BCHECK(JW,NAME,NR) _____ __________ Input Parameters JW YBOS array name. NAME (Characte*4) Name of bank to be checked NR (Integer) Number of bank to be checked ______ __________ Output Parameters None ________ _____ Function Value BCHECK (Integer) YESUCC Success YENOBK Non-existant bank name YENONR Non-existant bank number YEBKNG Negative bank length YEBKOV Insufficient space for bank YERSUS User location already reserved YEBTIL Unrecognized bank id YEGRIL Unrecognized group id YECHKF Internal Consistency check failure YESTOF Stack Limit exceeded YENOTA Data Not Alligned YEBNKP Bank padded with extra words N.B. 1. The array name JW may be either the basic YBOS array or a secondry YBOS array. 2. This function steps through the extended bank header and makes sure that the bank type and group type words are among those defined in Ybos$library:bnktyp.inc. It also checks that the number of words required by the extended bank header actually exist in the bank. CDF-156 YBOS (V4.00) Page 199 SUBPROGRAMS FOR YBOS ARRAY FREE SPACE MONITORING ___________ ___ ____ _____ ____ _____ __________ 23 SUBPROGRAMS FOR YBOS ARRAY FREE SPACE MONITORING Several subprograms are available for examining the current free space in a YBOS array, and lowest value free space has reached in the life of the YBOS array. They are the following:- BMNSPR Report lowest Free Space Value BMNSPI Set lowest Free Space header word to its initial value BFRSPC Report current Free Space value BSPACR Report Length of array CDF-156 YBOS (V4.00) Page 200 SUBPROGRAMS FOR YBOS ARRAY FREE SPACE MONITORING 23.1 BMNSPR - Report Lowest Free Space Value. This subprogram returns the lowest value that Free Space has reached in the input YBOS array. Free Space is defined as the amount of deleted named bank and work bank words plus the size of the GAP. _______ ________ Calling Sequence STATUS = BMNSPR(JW,MINSPC) _____ __________ Input Parameters JW YBOS array name. ______ __________ Output Parameters MINSPC (Integer) Minimum Free Space Value ________ _____ Function Value BMNSPR (Integer) YBOS Status Flag N.B. 1. The array name JW may be either the basic YBOS array or a secondry YBOS array. 2. MINSPC is the lowest value Free Space has reached since the Free space YBOS header word has been initialized (either during YBOS initialization or by a call to BMNSPI). 3. If the array has not been initialized, the YECORR status is returned and MINSPC is set to 0. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 201 SUBPROGRAMS FOR YBOS ARRAY FREE SPACE MONITORING 23.2 BMNSPI - Initialize Lowest Free Space YBOS Header Word. This subprogram sets the lowest free space ybos header word to its initial value of JW(IYLENG)-JW(IYNSYS) (array length minus the number of ybos header words). _______ ________ Calling Sequence STATUS = BMNSPI(JW) _____ __________ Input Parameters JW YBOS array name. ______ __________ Output Parameters NONE ________ _____ Function Value BMNSPI (Integer) YBOS Status Flag N.B. 1. The array name JW may be either the basic YBOS array or a secondry YBOS array. 2. If the array has not been initialized, the YECORR status is returned. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 202 SUBPROGRAMS FOR YBOS ARRAY FREE SPACE MONITORING 23.3 BFRSPC - Report Current Free Space Value. This subprogram returns the current value that Free Space in the input YBOS array. Free Space is defined as the amount of deleted named bank and work bank words plus the size of the GAP. _______ ________ Calling Sequence STATUS =BFRSPC(JW,CURR) _____ __________ Input Parameters JW YBOS array name. ______ __________ Output Parameters CURR (Integer) Curent Free Space Value ________ _____ Function Value BFRSPC (Integer) YBOS Status Flag N.B. 1. The array name JW may be either the basic YBOS array or a secondry YBOS array. 2. If the array has not been initialized, the YECORR status is returned and CURR is set to 0. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 203 SUBPROGRAMS FOR YBOS ARRAY FREE SPACE MONITORING 23.4 BSPACR - Report Length Of YBOS Array. This subprogram returns the length of the input YBOS array. _______ ________ Calling Sequence STATUS =BSPACR(JW,LENG) _____ __________ Input Parameters JW YBOS array name. ______ __________ Output Parameters LENG (Integer) Length of the array ________ _____ Function Value BSPACR (Integer) YBOS Status Flag N.B. 1. The array name JW may be either the basic YBOS array or a secondry YBOS array. 2. If the array has not been initialized, the YECORR status is returned and LENG is set to 0. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 204 UTILITY SUBPROGRAMS _______ ___________ 24 UTILITY SUBPROGRAMS Several general utility subprograms are available. They are the following:- BAHEAD Print all Bank Headers BCONV Convert YBOS Banks to and from VAX representation BDUMP Dumps YBOS bank according to the extended bank header BERROR Return Error Code for last YBOS Call BERLEV Specify new Error Level BERMES Print a warning message BGRBEX Return Named Bank garbage collection flag BIOERR Print a warning message BOPTN Specify special option for next YBOS Call BOSDP Dump YBOS array BOSTA Print status of array BPUNIT Specify new YBOS Print Unit BPLIMT Specify new YBOS Bank print limit BPREST Reset the ybos bank print count BVERSN Check YBOS version number BWLIMT Specify new YBOS Error Message limit NAMIND Get name-index for specified bank name YBERMS Print an error message BWRTOF Switch to YBOS readonly mode BWRTON Switch out of YBOS readonly mode BCHINT Convert a Character*4 variable to Integer*4 BINTCH Convert a Integer*4 variable to Charactewrtonr*4 CDF-156 YBOS (V4.00) Page 205 UTILITY SUBPROGRAMS 24.1 BAHEAD - Print all Bank Headers This subprogram is used to print the bank headers for all named banks on the currently specified YBOS Print Unit. _______ ________ Calling Sequence STATUS = BAHEAD(JW) _____ __________ Input Parameters JW YBOS array name. ______ __________ Output Parameters None ________ _____ Function Value BAHEAD (Integer) YESUCC Success N.B. 1. The array name JW may be either the basic YBOS array or a secondry YBOS array. 2. YBOS maintains a count of the number of banks that have been printed. When this count reaches a preset limit (default 100) then no further banks will be printed. This limit may be modified from its default setting of 100 by a call to subprogram BPLIMT. 3. The currently specified YBOS Print Unit (default 6) may be modified by a call to subprogram BPUNIT. 4. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 206 UTILITY SUBPROGRAMS 24.2 BCONV - Convert YBOS Banks to and from VAX Representation This function converts ybos banks to/from the VAX variable representation from/to a non vax (target) variable representation. _______ ________ Calling Sequence STATUS = BCONV(JW,SOURCE,DESTIN,NWORDS,MODE) _____ __________ Input Parameters JW YBOS array name. SOURCE (array) Bank to be converted DESTIN (array) Output array for converted array NWORDS (integer) Inclusive bank length MODE (Integer) = 0 VAX to target representation = 1 Target to VAX representation ______ __________ Output Parameters None ________ _____ Function Value BCONV (Integer) YESUCC Success YENOBK Non-existant bank name YENONR Non-existant bank number YEBKNG Negative bank length YEBKOV Insufficient space for bank YERSUS User location already reserved YEBTIL Unrecognized bank id YEGRIL Unrecognized group id YECHKF Internal Consistency check failure YESTOF Stack Limit exceeded YENOTA Data Not Alligned YEBNKP Bank padded with extra words N.B. 1. The array name JW may be either the basic YBOS array or a secondry YBOS array. 2. The SOURCE parameter is an array (possilbly a portion of a ybos array) whose contents is the bank to be converted. SOURCE(1) must be the integer representation of the bank name, SOURCE(2) the bank number, etc. 3. The DESTIN parameter is an array (possilbly a portion of a ybos array) whose contents will (upon return) be the converted contents of SOURCE. DESTIN and SOURCE may be the same array. CDF-156 YBOS (V4.00) Page 207 UTILITY SUBPROGRAMS 4. The NWORDS parameter is the inclusive (including header words) bank length. 5. The MODE parameter determines the direction of coversion. 1) BCONV called on a VAX does nothing. 2) BCONV called on the target node: Mode = 0 - Convert from VAX to target variable representation Mode = 1 - Convert from target to VAX variable representation CDF-156 YBOS (V4.00) Page 208 UTILITY SUBPROGRAMS 24.3 BDUMP - Dumps YBOS Bank According to the Extended Bank Header This function dumps a ybos bank according to its extended bank header, in the process of dumping it also checks the ybos extended bank header for consistency and completeness. _______ ________ Calling Sequence STATUS = BDUMP(JW,NAME,NR) _____ __________ Input Parameters JW YBOS array name. NAME (Characte*4) Name of bank to be checked NR (Integer) Number of bank to be checked ______ __________ Output Parameters None ________ _____ Function Value BDUMP (Integer) YESUCC Success YENOBK Non-existant bank name YENONR Non-existant bank number YEBKNG Negative bank length YEBKOV Insufficient space for bank YERSUS User location already reserved YEBTIL Unrecognized bank id YEGRIL Unrecognized group id YECHKF Internal Consistency check failure YESTOF Stack Limit exceeded YENOTA Data Not Alligned YEBNKP Bank padded with extra words N.B. 1. The array name JW may be either the basic YBOS array or a secondry YBOS array. 2. This function steps through the extended bank header and makes sure that the bank type and group type words are among those defined in Ybos$library:bnktyp.inc. It also checks that the number of words required by the extended bank header actually exist in the bank. Finally, it Dumps the bank contents formatted according to the extended bank header. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, CDF-156 YBOS (V4.00) Page 209 UTILITY SUBPROGRAMS STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 210 UTILITY SUBPROGRAMS 24.4 BERROR - Return Error Code for last YBOS Call This subprogram may be used to return the Error Code produced by the previous YBOS Call as an alternative to accessing the 2nd element of the appropriate YBOS array. _______ ________ Calling Sequence STATUS = BERROR(JW,ERROR) _____ __________ Input Parameters JW YBOS array ______ __________ Output Parameters ERROR (Integer) Error Code ________ _____ Function Value BERROR (Integer) YESUCC Success N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. CDF-156 YBOS (V4.00) Page 211 UTILITY SUBPROGRAMS 24.5 BERLEV - Specify new YBOS Error Level This subprogram may be used to control the amount of diagnostic printing produced when an error occurs within YBOS (e.g. insufficient space to create a new bank). _______ ________ Calling Sequence STATUS = BERLEV(JW,LEVEL) _____ __________ Input Parameters JW YBOS array LEVEL (Integer) Error Level ______ __________ Output Parameters None ________ _____ Function Value BERLEV (Integer) YESUCC Success N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The Error Level LEVEL may take on the following values:- Level 0 Suppress all Error Message Reporting. The Function Value and JW(2) element may still be used to determine whether an error has occurred. Level 1 Print a message giving details of the nature of the error, the subprogram in which it occurred, and the particular Bank affected if appropriate. Level 2 As Level 1 but the contents of the YBOS array are dumped as well, omitting the bank contents. Level 3 As Level 2 but including the contents of all banks. The default is Level 1. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, CDF-156 YBOS (V4.00) Page 212 UTILITY SUBPROGRAMS STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 213 UTILITY SUBPROGRAMS 24.6 BERMES - Print A Warning Message This subroutine is used to print a warning message from the user level. _______ ________ Calling Sequence CALL BERMES(NAMCAL,NAMEYB,ICODE,LUNIT) _____ __________ Input Parameters NAMCAL Name of the calling program NAMEYB Name of the guilty ybos routine ICODE Error code LUNIT Logical unit to dump message to ______ __________ Output Parameters None N.B. 1. The ICODE parameter must be a standard ybos error as defined in Ybos$library:errcod.inc. CDF-156 YBOS (V4.00) Page 214 UTILITY SUBPROGRAMS 24.7 BGRBEX - Examine Named Bank Garbage Collection Flag This function returns the named bank garbage collection flag. _______ ________ Calling Sequence STATUS = BGRBEX(JW,FLAG) _____ __________ Input Parameters JW YBOS array ______ __________ Output Parameters FLAG Named bank garbage collection flag. FLAG = 0 implies no garbage collection has occured FLAG = 1 implies garbage collection has occured N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The internal garbage collection flag is zeroed after FLAG is assigned its origincal value. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 215 UTILITY SUBPROGRAMS 24.8 BIOERR - Return I/O Error Code This subroutine returns the I/O error code for a hardware detected error. _______ ________ Calling Sequence CALL BIOERR(JW,ERRCOD) _____ __________ Input Parameters JW YBOS array ______ __________ Output Parameters ERRCOD Hadware error code N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The ERRCOD parameter is that which is returned from a standard fortran read or write. CDF-156 YBOS (V4.00) Page 216 UTILITY SUBPROGRAMS 24.9 BOPTN - Specify Special Option This subprogram may be used to specify a special YBOS option before calling a YBOS subprogram. It should immediately preceed the required subprogram call. _______ ________ Calling Sequence STATUS = BOPTN(JW,OPTION) _____ __________ Input Parameters JW YBOS array OPTION (Integer) Option Value ______ __________ Output Parameters None ________ _____ Function Value BOPTN (Integer) YESUCC Success N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The specified option setting is valid only for the duration of a single YBOS call, being reset to the default on return. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 217 UTILITY SUBPROGRAMS 24.10 BOSDP - Print YBOS Array This subprogram prints the contents of the specified YBOS array on the currently spcified YBOS Print Unit. The datawords are printed as Integer quantities. _______ ________ Calling Sequence STATUS = BOSDP(JW) _____ __________ Input Parameters JW YBOS array ______ __________ Output Parameters None ________ _____ Function Value BOSDP (Integer) YESUCC Success N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The YBOS option subprogram BOPTN may be used to specify special options. This subprogram should be called immediately prior to accessing BOSDP, thus:- STATUS = BOPTN(JW,OPTION) STATUS = BOSDP(...) where OPTION is an Integer having the following meanings:- OPTION = 0 Print bank headers and contents OPTION >< 0 Print bank headers only The default is for all bank headers and contents to be printed. 3. YBOS maintains a count of the number of banks that have been printed. When this count reaches a preset limit (default 100) then no further banks will be printed. This limit may be modified from its default setting of 100 by a call to subprogram BPLIMT. 4. The currently specified YBOS Print Unit (default 6) may be modified by a call to subprogram BPUNIT. CDF-156 YBOS (V4.00) Page 218 UTILITY SUBPROGRAMS 5. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 219 UTILITY SUBPROGRAMS 24.11 BOSTA - Print YBOS Status This subprogram prints the status of the specified YBOS array (YBOS Header words only). _______ ________ Calling Sequence STATUS = BOSTA(JW) _____ __________ Input Parameters JW YBOS array name ______ __________ Output Parameters None ________ _____ Function Value BOSTA (Integer) YESUCC Success N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 220 UTILITY SUBPROGRAMS 24.12 BPUNIT - Specify Print Unit This subprogram specifies the current YBOS Print Unit on which printout of banks will occur as a result of calls to NPRNT, BOSDP etc. _______ ________ Calling Sequence STATUS = BPUNIT(JW,LUNIT) _____ __________ Input Parameters JW YBOS array name LUNIT (Integer) Print Unit number ______ __________ Output Parameters None ________ _____ Function Value BPUNIT (Integer) YESUCC Success YEILUN Illegal Unit Number N.B. 1. The array JW may be either the basic YBOS array in COMMON/BCS/ or a secondary array. Only printout of banks in that array will be affected by the call. The default YBOS Print Unit is 6. 2. A print unit of 0 will cause bank printing to be switched off. CDF-156 YBOS (V4.00) Page 221 UTILITY SUBPROGRAMS 24.13 BPLIMT - Specify Print Limit This subprogram specifies a new bank limit for printouts. Only the specified number of banks will be printed, further requests will be ignored. _______ ________ Calling Sequence STATUS = BPLIMT(JW,LIMIT) _____ __________ Input Parameters JW YBOS array name LIMIT (Integer) Print limit ______ __________ Output Parameters None ________ _____ Function Value BPLIMT (Integer) YESUCC Success N.B. 1. The array JW may be either the basic YBOS array in COMMON/BCS/ or a secondary array. Only printout of banks in that array will be affected by the call. 2. The default is for a maximum of 100 banks to be printed. CDF-156 YBOS (V4.00) Page 222 UTILITY SUBPROGRAMS 24.14 BPREST - Reset Bank Print Count This subprogram sets the bank limit for printouts as the default. Only the default number of banks will be printed, further requests will be ignored. This action effectively sets the banks print count to zero. _______ ________ Calling Sequence STATUS = BPREST(JW) _____ __________ Input Parameters JW YBOS array name ______ __________ Output Parameters None ________ _____ Function Value BPREST (Integer) YESUCC Success N.B. 1. The array JW may be either the basic YBOS array in COMMON/BCS/ or a secondary array. Only printout of banks in that array will be affected by the call. 2. The default is for a maximum of 100 banks to be printed. 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 223 UTILITY SUBPROGRAMS 24.15 BVERSN - Check YBOS Version Number This subprogram returns the current ybos version number. _______ ________ Calling Sequence STATUS = BVERSN(VERSN) _____ __________ Input Parameters None ______ __________ Output Parameters VERSN (real) YBOS version number ________ _____ Function Value BVERSN (Integer) YESUCC Success N.B. 1. Note that VERSN is a real variable. CDF-156 YBOS (V4.00) Page 224 UTILITY SUBPROGRAMS 24.16 BWLIMT - Specify Warning Message Limit This subprogram specifies a new limit for warning or error messages. Only the specified number of messages will be reported, further errors will be ignored. _______ ________ Calling Sequence STATUS = BWLIMT(JW,LIMIT) _____ __________ Input Parameters JW YBOS array name LIMIT (Integer) Warning limit ______ __________ Output Parameters None ________ _____ Function Value BWLIMT (Integer) YESUCC Success N.B. 1. The array JW may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The default is for a maximum of 100 warnings to be reported. CDF-156 YBOS (V4.00) Page 225 UTILITY SUBPROGRAMS 24.17 NAMIND - Get Name-index for Bank This subprogram returns the name-index for the specified bank. _______ ________ Calling Sequence IND = NAMIND(JW,NAME) _____ __________ Input Parameters JW YBOS Array NAME (Character*4) Bank Name ______ __________ Output Parameters None ________ _____ Function Value NAMIND (Integer) NAME-index N.B. 1. The array JW may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. The Name-index NAMI is defined such that JW(NAMI) contains the index to the first bank with the corresponding name (first means bank with the lowest number). 3. The name-index for a given name will never change throughout a given job (even though the location of the bank may change). CDF-156 YBOS (V4.00) Page 226 UTILITY SUBPROGRAMS 24.18 YBERMS - Print A Warning Message This subroutine is used to print a warning message from _______ ________ the user level. Calling Sequence CALL YBERMS(NAMCAL,NAMEYB,ICODE,LUNIT) _____ __________ Input Parameters NAMCAL Name of the calling program NAMEYB Name of the guilty ybos routine ICODE Error code LUNIT Logical unit to dump message to ______ __________ Output Parameters None N.B. 1. The ICODE parameter must be a standard ybos error as defined in Ybos$library:errcod.inc. CDF-156 YBOS (V4.00) Page 227 UTILITY SUBPROGRAMS 24.19 BWRTOF - Place YBOS Array in Readonly Mode This function placed the input array, JW, in readonly mode for all subsequent Ybos function calls. _______ ________ Calling Sequence STATUS = BWRTOF(JW) _____ __________ Input Parameters JW YBOS array name ______ __________ Output Parameters None ________ _____ Function Value BWRTOF (Integer) YESUCC Success N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. To get out of readonly mode, call BWRTON 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 228 UTILITY SUBPROGRAMS 24.20 BWRTON - Take YBOS Array out of Readonly Mode This function takes the input array, JW, out of readonly mode for all subsequent Ybos function calls. _______ ________ Calling Sequence STATUS = BWRTON(JW) _____ __________ Input Parameters JW YBOS array name ______ __________ Output Parameters None ________ _____ Function Value BWRTON (Integer) YESUCC Success N.B. 1. The JW array may be either the basic YBOS array in COMMON/BCS/ or a secondary array. 2. To get into readonly mode, call BWRTOF 3. A call to BVALON prior to using this routine will result in named bank validation taking place upon calling this routine. For example, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off) CDF-156 YBOS (V4.00) Page 229 UTILITY SUBPROGRAMS 24.21 BCHINT - Convert Character*4 Variable To Integer*4 This function converts a Character*4 variable into the equivalent Integer*4 Variable. _______ ________ Calling Sequence STATUS = BCHINT(STRING) _____ __________ Input Parameters STRING (Character*4) Input string ______ __________ Output Parameters None ________ _____ Function Value BCHINT (Integer) Equivalent 4 character integer N.B. 1. BCHINT does not free you from having to declare STRING as BNKTAS in any bank type headers. CDF-156 YBOS (V4.00) Page 230 UTILITY SUBPROGRAMS 24.22 BINTCH - Convert Integer*4 Variable To Character*4 This function converts an Integer*4 variable into the equivalent Character*4 Variable. _______ ________ Calling Sequence STATUS = BINTCH(INTG) _____ __________ Input Parameters INTG (Character*4) Input integer ______ __________ Output Parameters None ________ _____ Function Value BINTCH (Integer) Equivalent Character*4 value APPENDIX A ______ __ _____ _____ FORMAT OF NAMED BANKS The structure of a named bank is as follows:- Word (Integer) Contents Description IND-3 NAME Bank Name (4 ASCII Characters) IND-2 NR Bank Number IND-1 Index to next bank with same name IND ND Length of Bank IND+1 Contents word 1 IND+2 Contents word 2 ... ... IND+ND Contents word ND N.B. (a) Named banks are Integer oriented. All of the bank header words are Integer and the Length of Bank word always specifies an integral number of Integer words. Note that this implies that a variable of type INTEGER must be capable of storing at least 4 characters. The internal representation of the user's data within the data area of the bank need not be Integer, being at the choice of the Application Programmer. (b) The Length of Bank word specifies the No. of words _________ ___ following in the Bank (i.e. it does not include itself). (c) All indices point to the Bank Length word of the bank (IND). Appendix D describes the extended Bank Header setup for Bank Type descriptors etc. APPENDIX B ______ __ ____ _____ FORMAT OF WORK BANKS The structure of work bank is as follows:- Word (Integer) Contents Description IND-3 NAME Bank Name (4 ASCII Characters) IND-2 NT Total number of words of the bank IND-1 IND Pointer to index of bank IND ND Number of data words IND+1 Data word 1 IND+2 Data word 2 ... ... IND+ND Data word ND N.B. (a) All work banks are Integer oriented. Thus their total length is always an integral number of Integer words. The internal representation of the user's data within the data area of the bank need not be Integer, being at the choice of the Application Programmer. (b) As previously noted the name for a work bank has no function other than as a debugging aid. If required the name should be setup explicitly by setting IW(IND-3) to the desired Hollerith string. (c) The total number of words of the bank NT allows the possibility of decreasing (and in some cases increasing) the number of data words in the bank without moving other work banks. (d) The Pointer to index of bank is used to update the index IND automatically during garbage collections, etc. (e) The number of data words ND may be less than or equal to NT-4. ______ __ ____ _____ FORMAT OF WORK BANKS Page B-2 Each work bank contains a pointer to the index of the bank. This pointer enables the bank to be automatically tracked if it is moved during garbage collections. Consider the following code fragment:- C C Create a Work Bank with ND Data words C C Arguments to WBANK are:- C C JW YBOS Array Name C IND Returned Index to the Bank....STATIC variable C ND No. of Datawords in Bank C STATUS = WBANK(JW,IND,ND) JND = IND C C Perform Garbage Collection on Workbanks C STATUS = WGARB(JW) ..... This code fragment will create a work bank such that variable IND points to the bank - i.e. JW(IND) contains the no. of datawords, JW(IND+1) is the first dataword etc. If the workbank is moved through the action of the garbage collection, the contents of the variable IND will be modified such that JW(IND) still contains the no. of datawords etc. However, JND will not be updated in this manner, and an attempt to access the contents of the workbank via JW(JND) etc. may cause unpredictable results. YBOS allows work banks to be locked temporarily such that movement of them is inhibited (see WLOCK and WUNLK). APPENDIX C ____ _______ BANK STORAGE The layout of storage for a YBOS array is as follows:- +---------------------------+ | System Data | +---------------------------+ | Indices for Named Banks | +---------------------------+ | | Named Bank | | +---------------------------+ | | Named Bank | | Region of named banks +---------------------------+ | | Named Bank | | +---------------------------+ | | | | Free Space | | | +---------------------------+ | | Work Bank | | +---------------------------+ | | Work Bank | | Region of work banks +---------------------------+ | | Work Bank | | +---------------------------+ | Named banks are stored in the low index part of each array, sequentially created banks having increasing indices, while work banks are stored from the high index part of the array, sequentially created banks having decreasing indices. During garbage collection operations named banks will be shuffled towards decreasing indices while work banks will be shuffled towards increasing indices so as to maximise the free space. Within each array the first words are used for system data, to which the user has limited access via function calls. APPENDIX D ____ _____ BANK TYPES D.1 EXTENDED BANK HEADER FOR BANK TYPE DESCRIPTION The extended Bank Header associated with the Bank Type Descriptor has the following format:- Word (Integer) Contents Description IND-3 NAME Bank Name (4 ASCII Characters) IND-2 NR Bank Number IND-1 Index to next bank with same name IND ND Length of Bank IND+1 Bank Type IND+2 Group 1 Type (if appropriate) ..... INDDAT-1 Group n Type (if appropriate) INDDAT First Data Word ..... ... IND+ND Last Data Word Where:- (a) IND is the Bank Index returned by the relevant YBOS subprograms (BLOCAT, MLINK and NLINK). (b) INDDAT is the Bank Data Index returned, in addition to IND, by BLOCAT etc. (c) The Bank Name, Number, Pointer and Length words are unchanged. (d) The Bank Type word describes the internal data format of the Bank, whether it contains Integer, Integer*2, Real*4 quantities or a mixture of them etc. It is always present, and is described in detail in the next section. Banks may be split into two categories - Mono-Type and Mixed-Type. A Mono-Type Bank contains data of only one datatype (Integer, Real*4 etc.). A Mixed-Type Bank contains data of differing datatypes. ____ _____ BANK TYPES Page D-2 EXTENDED BANK HEADER FOR BANK TYPE DESCRIPTION (e) Bank Group Type words will only exist for Mixed-Type Banks (see above). They describe the detailed sub-structure of the Group of datawords. (f) Data words are segregated into Groups having the identical datatype (Integer, Real etc.). For Mono-Type Banks there is only one Group and the data format is completely described by the Bank Type word; the Group Type word is redundant and is therefore omitted. The first dataword is at Index IND+2 and INDDAT is set to this value. For Multi-Type banks with mixed datatypes, the Index to the first dataword (INDDAT) depends on the number of Group Type words present (i.e. the number of Group Types). D.2 FORMAT OF THE BANK TYPE AND GROUP TYPE WORDS The Bank Type Word has the following Bit assignments:- Bits 0-7 Bank/Group Type ID 8-15 All zero 16-31 No. of Group Type Words following Note that for a Mono-Type Bank (all datawords having the same datatype), no Group Type words are necessary since the Data Type word completely specifies the Bank format. The Group Type Word has the following Bit assignments:- Bits 0-7 Bank/Group Type ID 8-15 Zero or Groups per Entry 16-31 No. of Datawords (or No. of Entries) where the unit of a "word" is always Integer (assumed to be Integer*4). For a Group of 10 Integer*2 items the No. of Datawords will be set to 5. The Following Bank/Group Type IDs have been defined:- Bank/Group Type ID Descriptor Description 0 Mixed Mode 1 I2 16 Bit Integer (Integer*2) 2 AS 8 Bit ASCII Characters 3 I4 32 Bit Integer (Integer) 4 R4 32 Bit VAX F Reals (Real*4) 5 VD 64 Bit VAX D Reals (Real*8) 6 VG 64 Bit VAX G Reals (Real*8) 7 VH 128 Bit VAX H Reals (Real*16) 8 BY 8 Bit Bytes ____ _____ BANK TYPES Page D-3 FORMAT OF THE BANK TYPE AND GROUP TYPE WORDS 64 Entry Count ID (Group Type only) These are also declared in a Parameter Definition File to be "Included" into each program module that needs to access the Bank Type information (see later section of this Appendix). For a Bank containing only Integer data, the Bank Type word is set to 3, no Group Type words are present and the first dataword commences at Index IND+2. Similarly, for other Mono-Type Banks, the first dataword is at Index IND+2 and INDDAT is set to this value. For a Mixed-Type Bank (mixed datatypes), bits 0-15 of the Bank Type word are set to zero, while bits 16-31 specify how many Group Type words follow. As many Group Types follow as are necessary to describe the detailed data structure of the Bank. A frequent situation is where the Bank is most logically organised as containing several different Entries, each Entry having both Integer and Real datawords. This situation is dealt with by the "Entry Count" Group Type (Type 64). An example detailing the use of this Bank Type follows. D.2.1 Mono-Type Bank Example Consider the situation of a Bank containing 10 Real*4 quantities. The Bank has the following format:- Bits Word 16-31 8-15 0-7 Description IND-3 Bank Name IND-2 Bank Number IND-1 Bank Pointer IND 11 Bank Length IND+1 0 0 4 Bank Type (R*4) INDDAT IND+2 First R*4 Dataword ........ IND+11 Last R*4 Dataword The STRING argument in BTYBLD for this example would be: R4 or 1R4 . ____ _____ BANK TYPES Page D-4 FORMAT OF THE BANK TYPE AND GROUP TYPE WORDS D.2.2 Simple Mixed-Type Bank Example Consider a Bank having 20 Integer words followed by 15 Real*4 words. The Bank Format is as follows:- Bits Word 16-31 8-15 0-7 Description IND-3 Bank Name IND-2 Bank Number IND-1 Bank Pointer IND 38 Bank Length IND+1 2 0 0 Bank Type (Mixed) IND+2 20 0 3 Group Type (I*4) IND+3 15 0 4 Group Type (R*4) INDDAT IND+4 First I*4 Dataword ......... IND+23 Last I*4 Dataword IND+24 First R*4 Dataword ......... IND+38 Last R*4 Dataword The STRING argument in BTYBLD for this example would be: 20I4,15R4 . Note that there are 2 Group Type words corresponding to the 2 datatypes, the first Group Type word corresponding to the 20 Integer quantities etc. ____ _____ BANK TYPES Page D-5 FORMAT OF THE BANK TYPE AND GROUP TYPE WORDS D.2.3 More Complex Mixed-Type Bank Example Consider the example of a Bank having 4 Entries, the first 2 Entries each having 1 Integer words and 1 Real*4 words (in that sequence), the next 2 Entries each having 1 Integer word and 2 nested Entries; each of these nested Entries having 1 Integer words and 1 Real*4 words (in that sequence). The format of the Bank Type and Group Type words would be:- Bits Word 16-31 8-15 0-7 Description IND-3 Bank Name IND-2 Bank Number IND-1 Bank Pointer IND 23 Bank Length IND+1 8 0 0 Bank Type (Mixed) IND+2 2 2 64 Group Type (Entry Loop) IND+3 1 0 3 Group Type (I*4) IND+4 1 0 4 Group Type (R*4) IND+5 2 4 64 Group Type (Entry Loop) IND+6 1 0 3 Group Type (I*4) IND+7 2 2 64 Group Type (Entry Loop) IND+8 1 0 3 Group Type (I*4) IND+9 1 0 4 Group Type (R*4) INDDAT IND+10 I*4 Data of 1st Entry IND+11 R*4 Data of 1st Entry IND+12 I*4 Data of 2nd Entry IND+13 R*4 Data of 2nd Entry IND+14 I*4 Data of 3rd Entry IND+15 I*4 Data of 3rd Entry/1st Nest IND+16 R*4 Data of 3rd Entry/1st Nest IND+17 I*4 Data of 3rd Entry/2nd Nest IND+18 R*4 Data of 3rd Entry/2nd Nest IND+19 I*4 Data of 4th Entry IND+20 I*4 Data of 4th Entry/1st Nest IND+21 R*4 Data of 4th Entry/1st Nest IND+22 I*4 Data of 4th Entry/2nd Nest IND+23 R*4 Data of 4th Entry/2nd Nest The STRING argument in BTYBLD for this example would be: 2(I4,R4),2(I4,2(I4,R4)) . ____ _____ BANK TYPES Page D-6 BANK TYPE PARAMETER DEFINITION FILE D.3 BANK TYPE PARAMETER DEFINITION FILE A Parameter Definition File is available for the Bank Type definitions. It can be "Included" into each program module that requires access to the Bank Type descriptor words. For VAX installations this file is in YBOS$Library:BnkTyp.Inc For non-VAX installations, the location of this file should be determined by consulting the local YBOS expert. The following Parameters are defined:- Name Value Description Data Type Descriptor BNKTMX 0 Mixed Bank Type -- BNKTI2 1 Integer*2 Bank Type I2 BNKTAS 2 ASCII Character Bank Type AS BNKTI4 3 Integer*4 Bank Type I4 BNKTR4 4 Real*4 Bank Type R4 BNKTVD 5 VAX D Real*8 Bank Type VD BNKTVG 6 VAX G Real*6 Bank Type VG BNKTVH 7 VAX H Real*16 Bank Type VH BNKTBY 8 Byte Bank Type BY BNKTEC 64 Entry Count Bank/Group Type -- APPENDIX E _______ ___ ________ ______ _______ LOGICAL AND PHYSICAL RECORD FORMATS ________ ______ _________ E.1 PHYSICAL RECORD STRUCTURE Each physical record has a physical record header followed by data from logical records. The format is:- Word (32 Bits) Definition 0 Length of Physical Record (LPR) 1 Length of Physical Record Header (LPH) 2 Physical Record Number (NPR) 3 Displacement to first logical record (LRD) 4 (LPH) ) ... ) Data from previous logical record (if any) LRD-1 ) LRD Start of first logical record ... Data LPR Last dataword 1. All entries in the Physical Record Header are 32 Bit quantities and displacements are 32 Bit displacements. _________ 2. The Length of Physical Record contains an exclusive count of the number of 32 Bit words following in the physical record (i.e. not including itself). _________ 3. The Length of Physical Record Header is an inclusive count of the number of 32 Bit words in the Physical Record Header and is set to 4 in the current implementation. It may be used as the displacement to the first dataword (either from a previous logical record, or the wordcount for a logical record that immediately follows this Header) in the physical record. 4. The Physical Record Number identifies each physical record on tape, beginning from 0. _______ ___ ________ ______ _______ LOGICAL AND PHYSICAL RECORD FORMATS Page E-2 PHYSICAL RECORD STRUCTURE 5. Displacement to first word of logical record points to the first word (wordcount) of the first logical __________ record commencing in this physical record relative to word 0. Thus in the case where a logical record immediately follows this Physical Record Header the Displacement is set to 4. _______ ___ ________ ______ _______ LOGICAL AND PHYSICAL RECORD FORMATS Page E-3 LOGICAL RECORD STRUCTURE _______ ______ _________ E.2 LOGICAL RECORD STRUCTURE The Logical Record Structure is as follows:- Length of Logical Record One 32 Bit word Bank "LRID" Variable No. of 32 Bit words ....... ....... Bank "ZZZZ" Variable No. of 32 Bit words _________ The Length of the Logical Record is an exclusive count of the number of 32 Bit words in the Record (i.e. not including itself). Apart from this Length word the Logical Record consists solely of YBOS Banks. Note that there are two special cases:- Length = 0 This signifies that the length of the logical record was not known at creation time and must therefore be calculated from the information contained in the physical record headers. Length = -1 This signifies a "null" logical record and that the next true logical record commences at the beginning of the next physical record (after the physical record header). APPENDIX F ________ EXAMPLES F.1 MAIN PROGRAM IN STANDARD EVENT PROCESSING The MAIN program below reads one event at a time from logical unit 10, calls processing subprograms and add extra data to the event and then writes the event to logical unit 20. All banks of the event are then dropped and, after a garbage collection, the process is repeated. COMMON/BCS/IW(10000) C C Initalize YBOS and open logical units C STATUS = BOS77(10000,0) STATUS = BLOPEN(10,2048) STATUS = BLOPEN(20,2048) C C Read one event from unit 10, check for EOF. C Note that the 'E' Bank Set will contain all C Banks from the Logical Record after the call. C If 'E+' had been used instead of 'E', then the C Bank Set would have contained both the Banks C in the Logical Record and any other Banks that C were already contained in the 'E' Set. C 100 STATUS = BLREAD(10,IW,'E',NWORDS) if (IW(2) .eq. 3) go to 500 C C Call processing subprograms C ..... ..... ..... C C add bank 'BERT' and delete banks 'CARL' and 'DAVE' C STATUS = BLIST(IW,'E+','BERT') STATUS = BLIST(IW,'E-','CARLDAVE') C C Write event to unit 20 and drop banks etc. C ________ EXAMPLES Page F-2 MAIN PROGRAM IN STANDARD EVENT PROCESSING STATUS = BLWRIT(20,IW,'E') STATUS = BDROP(IW,'E') STATUS = BGARB(IW) go to 100 C C end of file - close units etc. C 500 STATUS = BLCLOS(10) STATUS = BLCLOS(20) stop end ________ EXAMPLES Page F-3 SIMPLE HISTOGRAM PACKAGE F.2 SIMPLE HISTOGRAM PACKAGE The following example shows how a simple histogramming package may be set up. subprogram BHIST(NR,N,XA,XB) C C Book histogram NR with N bins between XA and XB C COMMON/HCS/KW(1) real XW(1) equivalence (KW(1),XW(1)) C C Check already booked C if (MLINK(KW,'HIST',NR) .ne. 0) go to 100 C C Create histogram bank. The format is:- C C 1 N = Number of Bins C 2 XA = Lowest Channel Left Edge C 3 XB = Highest Channel Right Edge C 4 DX = Bin Width C 5 Content outside Low C 6 Content outside High C 7 Content first Bin C ... ... C 6+N Content last Bin C IND = MBANK(KW,'HIST',NR,N+6) if (IND .eq. 0) go to 100 KW(IND+1) = N XW(IND+2) = XA XW(IND+3) = XB XW(IND+4) = (XB-XA)/FLOAT(N) C C Return to caller C 100 return end ________ EXAMPLES Page F-4 SIMPLE HISTOGRAM PACKAGE subprogram EHIST(NR,X) C C add entry X to histogram NR C COMMON/HCS/KW(1) real XW(1) equivalence (KW(1),XW(1)) C C Find histogram bank C IND = MLINK(KW,'HIST',NR) if (IND .ne. 0) then I = 1.0 + (X-XW(IND+2))/XW(IND+4) if (I .lt. 1) I = -1 if (I .gt. KW(IND+)) I = 0 C C add 1.0 to bin content C XW(IND+6+I) = XW(IND+6+I)+1.0 endif return end