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 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. 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. 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. 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. 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. 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)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. 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)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) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off)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) 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.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 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)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. 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)BMAKE - Create a N amed 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. 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) 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 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) 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:- 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. 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)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. 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 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)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 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 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, STATUS = BVALON(JW) (Turn validation on) STATUS = .... (Call the routine) STATUS = BVALOF(JW) (Turn validation off)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). 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) 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 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) 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. 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) 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) 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) 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:- 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) 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 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) 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) 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 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)next page