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