14 SUBPROGRAMS FOR NAMED BANK INTERNALS
These subprograms (added in Version 3.00) allow the
Application Programmer to access quantities within a YBOS
Header without knowing the details of the format of the
Header. In particular, they allow the Index to the Data for a
Named Bank conforming to the Bank Type specifications to be
determined. The following subprograms are available:-
BDATA Return Data Index from Bank Index
BDLEN Return Length of Data
BLENG Return Length of Bank
BNAME Return Bank Name
BNEXT Return Index of Next Bank
BNUMB Return Number of Bank
BTYPE Return Bank Type Word etc.
BTPACK Pack Bank/Group Type Word
BTUNPK Unpack Bank/Group Type Word
BTYBLD Build a Bank Type Header
Note that these subprograms only return the Error Code as
the function value. They do not set the 2nd element of the
appropriate YBOS array, neither do they allow BERROR to be
used to determine the Error Code. This is to allow their use
in the situation where a YBOS bank is passed to a subprogram
as an array. Within the subprogram the bank should be treated
just like any normal array and the subprogram has no knowledge
that the array in in fact a portion of a larger YBOS array.
14.1 BDATA - Return Data Index from Bank Index
This subprogram returns the Data Index for the Bank
having the specified Bank Index. It only operates correctly
for Named Banks conforming to the Bank Type format described
earlier.
Calling Sequence
STATUS = BDATA(JW,IND,INDDAT)
Input Parameters
JW Secondary YBOS array name.
IND (Integer) Index to the bank (Bank Index).
Output Parameters
INDDAT (Integer) Index to the data (Data Index).
Function Value
BDATA (Integer) YESUCC Success
N.B.
1. BDATA performs no checks to determine whether IND
corresponds to a valid Bank. The results will be
undefined if IND does not correspond to a Bank or
corresponds to a Bank not conforming to the Bank Type
specifications.
2. INDDAT is defined such that JW(INDDAT) contains the
first dataword following the Bank Header.
3. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
the appropriate YBOS array, neither does it allow
BERROR to be used to determine the Error Code.
14.2 BDLEN - Return Length of Data
This subprogram returns the Length of the Data for the
named Bank with the specified Bank Index. It only operates
correctly for Banks conforming to Bank Type format described
earlier.
Calling Sequence
STATUS = BDLEN(JW,IND,LENDAT)
Input Parameters
JW Secondary YBOS array name.
IND (Integer) Index to the bank (Bank Index).
Output Parameters
LENDAT (Integer) Length of the Data
Function Value
BDLEN (Integer) YESUCC Success
N.B.
1. BDLEN performs no checks to determine whether IND
corresponds to a valid Bank. The results will be
undefined if IND does not correspond to a Bank or
corresponds to a Bank not conforming to the Bank Type
specifications.
2. LENDAT is the Length of the data in Integer words
(excluding the Bank Header words).
3. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
the appropriate YBOS array, neither does it allow
BERROR to be used to determine the Error Code.
14.3 BLENG - Return Length of Bank
This subprogram returns the Length of the Bank (including
extended Bank Header words) for the named Bank with the
specified Bank Index. It operates correctly for all Banks.
Calling Sequence
STATUS = BLENG(JW,IND,LENBNK)
Input Parameters
JW Secondary YBOS array name.
IND (Integer) Index to the bank (Bank Index).
Output Parameters
LENBNK (Integer) Length of the Bank
Function Value
BLENG (Integer) YESUCC Success
N.B.
1. BLENG performs no checks to determine whether IND
corresponds to a valid Bank. The results will be
undefined if IND does not correspond to a Bank.
2. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
the appropriate YBOS array, neither does it allow
BERROR to be used to determine the Error Code.
BNAME - Return Bank Name
This subprogram returns the Bank Name having the
specified Bank Index. It operates correctly for all Named
Banks.
Calling Sequence
STATUS = BNAME(JW,IND,NAME)
Input Parameters
JW Secondary YBOS array name.
IND (Integer) Index to the bank (Bank Index).
Output Parameters
NAME (Character*4) Bank Name
Function Value
BNAME (Integer) YESUCC Success
N.B.
1. BNAME performs no checks to determine whether IND
corresponds to a valid Bank. The results will be
undefined if IND does not correspond to a Bank.
2. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
the appropriate YBOS array, neither does it allow
BERROR to be used to determine the Error Code.
14.5 BNEXT - Return Index of next Bank
This subprogram returns the Bank Index for the next Bank
of the same Name as the Bank having the specified Bank Index.
It operates correctly for all Named Banks.
Calling Sequence
STATUS = BNEXT(JW,IND,INDNXT)
Input Parameters
JW Secondary YBOS array name.
IND (Integer) Index to the bank (Bank Index).
Output Parameters
INDNXT (Integer) Index to the next Bank
Function Value
BNEXT (Integer) YESUCC Success
N.B.
1. BNEXT performs no checks to determine whether IND
corresponds to a valid Bank. The results will be
undefined if IND does not correspond to a Bank.
2. INDNXT will be set to the Index of the next Bank in
the Bank Chain for the current Bank Name. Thus its
Bank Number will be greater than the current Bank's.
3. INDNXT will be set to zero if there is no "next" Bank
(i.e. the Bank with Index IND is the bank with the
highest Bank Number of the current Bank Name).
4. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
the appropriate YBOS array, neither does it allow
BERROR to be used to determine the Error Code.
14.6 BNUMB - Return Bank Number
This subprogram returns the Number for the Bank having
the specified Bank Index. It operates correctly for all Named
Banks.
Calling Sequence
STATUS = BNUMB(JW,IND,BNKNUM)
Input Parameters
JW Secondary YBOS array name.
IND (Integer) Index to the bank (Bank Index).
Output Parameters
BNKNUM (Integer) Bank Number
Function Value
BNUMB (Integer) YESUCC Success
N.B.
1. BNUMB performs no checks to determine whether IND
corresponds to a valid Bank. The results will be
undefined if IND does not correspond to a Bank.
2. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
the appropriate YBOS array, neither does it allow
BERROR to be used to determine the Error Code.
BTYPE This subprogram returns the unpacked Bank Type (i.e. separated into the components of Bank Type ID and No. of Group words), together with returning the Index to the First Group Type Word (if present) for the Bank having the specified Bank Index. It only operates correctly for Named Banks conforming to the Bank Type format described earlier.
Calling Sequence
STATUS = BTYPE(JW,IND,BNKTYP,NGROUP,INDGRP)
Input Parameters
JW Secondary YBOS array name.
IND (Integer) Index to the bank (Bank Index).
Output Parameters
BNKTYP (Integer) Bank Type ID
NGROUP (Integer) No. of Group Words
INDGRP (Integer) Index to 1st Group Word
Function Value
BTYPE (Integer) YESUCC Success
N.B.
1. BTYPE performs no checks to determine whether IND
corresponds to a valid Bank. The results will be
undefined if IND does not correspond to a Bank or
corresponds to a Bank not conforming to the Bank Type
specifications.
2. INDGRP is defined such that JW(INDGRP) contains the
first Group Type Word. This word (and the subsequent
ones if necessary) may be unpacked into their
components via BTUNPK.
3. INDGRP will be set to zero if there are no Group Type
Words (NGROUP zero).
4. The Bank Type ID is defined in Appendix D. An
Include File giving Parameter Declarations for the
various Bank Types is also available (see Appendix
D).
5. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
the appropriate YBOS array, neither does it allow
BERROR to be used to determine the Error Code.
BTPACK
Pack Bank Type or Group Type Words
This subprogram returns the Bank Type or Group Type word
given the individual components.
Calling Sequence
STATUS = BTPACK(BNKTYP,NGROUP,NWORDS,BGWORD)
Input Parameters
BNKTYP (Integer) Bank/Group Type ID
NGROUP (Integer) No. of Groups per Entry
NWORDS (Integer) No. of Datawords or Entries
Output Parameters
BGWORD (Integer) Bank/Group Type Word
Function Value
BTPACK (Integer) YESUCC Success
N.B.
1. The Bank Type ID is defined in Appendix D. An
Include File giving Parameter Declarations for the
various Bank Types is also available (see Appendix
D).
2. The value of the NGROUP Parameter depends on the
details of the Bank/Group Type Word BGWORD being
constructed:-
(a) NGROUP should be zero for a Bank Type Word.
(b) NGROUP should be zero for a normal Group Type
Word (i.e. for a non-Entry Count Type).
(c) NGROUP should be the No. of Groups within each
Entry for an Entry Count Group Type Word.
3. The value of the NWORDS Parameter depends on the
details of the Bank/Group Type Word BGWORD being
constructed:-
(a) NWORDS should be set to the No. of Groups if
BGWORD represents a Bank Type Word.
(b) NWORDS should be set to the No. of Datawords for
the current Group if BGWORD represents a normal
Group Type Word (i.e. for a non-Entry Count
Type).
(c) NWORDS should be set to the No. of Entries if
BGWORD represents an Entry Count Group Type Word.
4. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
any YBOS array, neither does it allow BERROR to be
used to determine the Error Code.
BTUNPK
Unpack Bank Type or Group Type Words
This subprogram returns the unpacked Bank Type or Group
Type words (i.e. separated into their components) for the
specified Word.
Calling Sequence
STATUS = BTUNPK(BGWORD,BNKTYP,NGROUP,NWORDS)
Input Parameters
BGWORD (Integer) Bank/Group Type Word
Output Parameters
BNKTYP (Integer) Bank/Group Type ID
NGROUP (Integer) No. of Groups per Entry
NWORDS (Integer) No. of Datawords or Entries
Function Value
BTUNPK (Integer) YESUCC Success
N.B.
1. The Bank Type ID is defined in Appendix D. An
Include File giving Parameter Declarations for the
various Bank Types is also available (see Appendix
D).
2. The returned value of the NGROUP Parameter depends on
the details of the Bank/Group Type Word BGWORD:-
(a) NGROUP will always be zero for a Bank Type Word.
(b) NGROUP will always be zero for a normal Group
Type Word (i.e. for a non-Entry Count Type).
(c) NGROUP is the No. of Groups within each Entry for
an Entry Count Group Type Word.
3. The returned value of the NWORDS Parameter depends on
the details of the Bank/Group Type Word BGWORD:-
(a) NWORDS will be set to the No. of Groups if BGWORD
represents a Bank Type Word.
(b) NWORDS will be set to the No. of Datawords for
the current Group if BGWORD represents a normal
Group Type Word (i.e. for a non-Entry Count
Type).
(c) NWORDS will be set to the No. of Entries if
BGWORD represents an Entry Count Group Type Word.
4. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
any YBOS array, neither does it allow BERROR to be
used to determine the Error Code.
BTYBLD
Build A Bank Type Header
This subprogram returns the index to the first data word
of a work bank that holds the desired bank type header.
Calling Sequence
STATUS = BTYBLD(JW,STRING,INDX,INDD,NDAT)
Input Parameters
JW (Array) Ybos Array name
STRING (Character) Header descriptor string
Output Parameters
INDX (Integer) The index to the work bank
INDD (Integer) The index to the first header word
NDAT (Integer) The number of data words in the named bank
Function Value
BTYBLD (Integer) Status flag
N.B.
1. The JW array may be either the basic YBOS array in
COMMON/BCS/ or a secondary array.
2. The header descriptor, STRING, is much like a fortran
format statement. It consists of a combination of
data type descriptors, commas, numbers, and
parenthesis. The parenthesis are used to indicate
entry loops, the commas seperate descriptor elements.
Numeric characters are used to indicate the number of
words of the specified data type; for example, 8I2
means 8 integer*2 words. BTYBLD will determine the
number of 32 bit words required .
3. A STRING filled with one or more blanks and nothing
else will result in JW(INDD) being set to zero.
4. The following is a list of allowable data tye
descriptors and a sample call to BTYBLD along with
its results.
Data Type Data Type Descriptor
INTEGER*2 I2
ASCII CHARACTER AS
INTEGER*4 I4
REAL*4 R4
VAX D REAL*8 VD
VAX G REAL*8 VG
VAX H REAL*16 VH
BYTE BY
Sample: STATUS = BTYBLD(JW,'26I2,5(R4,2I2),34I4',INDX,INDD,NDAT)
Results: BITS
WORD 16-31 8-15 0-7 Description
JW(INDD) 5 0 0 Bank type mixed
JW(INDD+1) 13 0 1 Group type I2
JW(INDD+2) 5 2 64 Entry loop
JW(INDD+3) 1 0 4 Group type R4
JW(INDD+4) 1 0 1 Group type I2 (End loop)
JW(INDD+5) 34 0 3 Group type I4
NDAT = 57
5. See Appendix D for several more examples.
6. The INDD and NDAT arguments are designed to be used
in a call to BMAKE as follows (see section 12.7 for a
description of BMAKE):
STATUS = BMAKE(JW,NAME,NR,NDAT,JW(INDD),IND,INDDAT).
7. It is the user's responsibility to drop the work bank
holding the type header. Drop the work bank with
WDROP as follows:
STATUS = WDROP(JW,INDX,1)
8. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
SUBPROGRAMS FOR ALIAS NAME MANIPULATIONS
These subprograms (added in Version 3.00) allow the
Application Programmer to declare, and later reference, long
Alias Names for Banks. The following subprograms are
available:-
BDECAL Declare Alias Name for Bank
BALIAS Get Alias Name from Basic Name
BBASIC Get Basic Name from Alias Name
BCANAL Drop the specified Alias Name
BLOCAL Locate Bank using Alias Name
BMAKAL Create a Bank using Alias Name
15.1 BDECAL - Declare Alias Name for Bank
This subprogram declares a long Alias Name for the specified
basic Bank Name. Only one such Alias may be thus defined.
Calling Sequence
STATUS = BDECAL(JW,BASIC,ALIAS)
Input Parameters
JW Secondary YBOS array name.
BASIC (Character*4) Basic Bank Name
ALIAS (Character) Alias Bank Name
Output Parameters
None
Function Value
BDECAL (Integer) YESUCC Success
YEDUPA Duplicate Alias Name
N.B.
1. The basic name BASIC must be a 4 character name.
2. The Alias Name ALIAS will be truncated to a maximum
of 32 characters.
3. The Alias translation is only setup for the specified
JW Array. If this translation is desired for more
than one array, BDECAL should be called for each
array.
4. The translation is only valid for the duration of one
program. These translation tables are not written
out as part of the logical record structure following
the Bank Header. Programs wanting to use Alias Names
should always define them themselves, rather than
assume that they are part of the input data stream.
5. Only one Alias Name may be defined for each Basic
Bank Name. If more than one declaration is made for
the same Bank Name, them only the last one is
effective.
6. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
15.2 BALIAS - Get Alias Name from Basic Bank Name
This subprogram returns the Alias Name for the specified
Basic Bank Name.
Calling Sequence
STATUS = BALIAS(JW,BASIC,ALIAS)
Input Parameters
JW Secondary YBOS array name.
BASIC (Character*4) Basic Bank Name
Output Parameters
ALIAS (Character) Alias Bank Name
Function Value
BALIAS (Integer) YESUCC Success
YENOBK Illegal Bank Name
YEILLA No Alias exists
N.B.
1. The basic name BASIC must be a 4 character name.
2. If no Bank with the specified name exists, ALIAS will
be set to ASCII spaces and the error function value
will be returned.
3. If no Alias Name has been declared, then ALIAS will
be set equal to BASIC, padded out with trailing
spaces if necessary, and an error function value will
be returned.
4. The actual Alias Name will be padded out with
trailing spaces if ALIAS is longer than the actual
name.
5. The Alias translation is only setup for the specified
JW Array. If this translation is desired for more
than one array, BALIAS should be called for each
array.
6. The translation is only valid for the duration of one
program; thus these translation tables are not
written out as part of the logical record structure
following the Bank Header. Programs wanting to use
Alias Names should always define them themselves,
rather than assume that they are part of the input
data stream.
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)
15.3 BBASIC - Get Basic Bank Name from Alias Name
This subprogram returns the basic bank name from the
specified Alias Name.
Calling Sequence
STATUS = BBASIC(JW,ALIAS,BASIC)
Input Parameters
JW Secondary YBOS array name.
ALIAS (Character) Alias Bank Name
Output Parameters
BASIC (Character*4) Basic Bank Name
Function Value
BBASIC (Integer) YESUCC Success
YEILLA Illegal Alias Name
N.B.
1. The basic name BASIC must be a 4 character name.
2. The Alias Name ALIAS will be truncated, or padded
out, to a maximum of 32 characters for the purposes
of making a name match.
3. If the specified Alias Name ALIAS does not exist,
then BASIC will be set to ASCII spaces, and an error
function value will be returned.
4. If ALIAS is 4 characters long, then BASIC will be set
equal to ALIAS.
5. The Alias translation is only setup for the specified
JW Array. If this translation is desired for more
than one array, BBASIC should be called for each
array.
6. The translation is only valid for the duration of one
program; thus these translation tables are not
written out as part of the logical record structure
following the Bank Header. Programs wanting to use
Alias Names should always define them themselves,
rather than assume that they are part of the input
data stream.
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)
15.4 BCANAL - Drop The Specified Alias Name
This subprogram drops the specified Alias Name.
Calling Sequence
STATUS = BCANAL(JW,ALIAS)
Input Parameters
JW Secondary YBOS array name.
ALIAS (Character) Alias Bank Name
Output Parameters
None
Function Value
BCANAL (Integer) YESUCC Success
YEILLA Illegal Alias Name
N.B.
1. The Alias Name ALIAS will be truncated, or padded
out, to a maximum of 32 characters the purposes of
making a name match.
2. Alias names are only valid for the duration of one
program; thus these translation tables are not
written out as part of the logical record structure
following the Bank Header. Programs wanting to use
Alias Names should always define them themselves,
rather than assume that they are part of the input
data stream.
3. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
15.5 BLOCAL - Locate a Named Bank using Alias Name
This subprogram may be used to locate previously created
banks using the Alias Name previously defined by a call to
BDECAL.
Calling Sequence
STATUS = BLOCAL(JW,NAME,NR,IND,INDDAT)
Input Parameters
JW Secondary array name.
NAME (Character) Bank Alias or Basic Name.
NR (Integer) Bank Number.
Output Parameters
IND (Integer) Index to the bank
(or zero if non-existent).
INDDAT (Integer) Index to the Data within Bank
Function Value
BLOCAL (Integer) YESUCC Success
YENOBK Non-existent Bank
YEILLA Illegal Alias Name
N.B.
1. If the Argument NAME consists of a 4 character name,
then no Alias Name translation occurs and BLOCAL is
identical in function to BLOCAT. Note that in this
case BLOCAT is the preferred method since this has
less overhead.
2. The argument NAME will be truncated or padded out
with trailing spaces before performing the Alias
translation (unless it is 4 characters long). An
exact match must be made with an already existing
Alias Name or a non-existent bank return will be
made.
3. Other notes are as for BLOCAT.
4. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
15.6 BMAKAL - Create a Bank using Alias Name
This subprogram is similar to BMAKE except that the ALias
Name may be used to create (or modify) the bank. The Bank
thus defined will be created with an extended Bank Header
conforming to the Bank Type specifications described in an
earlier Section.
Calling Sequence
STATUS = BMAKAL(JW,NAME,NR,ND,TYPE,IND,INDDAT)
Input Parameters
JW Secondary YBOS array name.
NAME (Character) Alias Name or Bank Name.
NR (Integer) Bank Number.
ND (Integer) No. of datawords.
TYPE (Integer Array) Bank Type specifiers
Output Parameters
IND (Integer) Index to the Bank
INDDAT (Integer) Index to the Data within Bank
Function Value
BMAKAL (Integer) YESUCC Success
YEILLA Illegal Alias Name
YEBKNG Negative Bank Length
YEOVRF Insufficient Space
for new Bank
YEBKSP Insufficient Space
to extend Bank
N.B.
1. If the Argument NAME consists of a 4 character name,
then no Alias Name translation occurs and BMAKAL is
identical in function to BMAKE. Note that in this
case BMAKE is the preferred method since this has
slightly less overhead.
2. The argument NAME will be truncated or padded out
with trailing spaces before performing the Alias
translation (unless it is 4 characters long). An
exact match must be made with an already existing
Alias Name or a non-existent bank return will be
made.
3. Other notes are as for BMAKE.
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)
16 SUBPROGRAMS FOR WORK BANKS
Work banks are created at the high index part of the
array and are identified by an index IND (being a local
variable). Access to the data contained within a work bank
should always be done directly with the index IND. Garbage
collection is done automatically, if necessary, with update of
all indices. The following subprograms are available:-
WBANK Create work bank or change length.
WDATA Return index to data of work bank
WDLEN Return data length of work bank.
WDROP Drop work bank(s).
WGARB Perform garbage collection for work banks.
WLENG Return total length of work bank.
WLOCK Lock work banks.
WPRNT Print work bank(s).
WSETD Set new data length of work bank.
WUNLK Unlock work banks.
16.1 WBANK - Create a Work Bank
This subprogram is used to create a work bank of the
specified length or to change the length of an already
existing work bank.
Calling Sequence
STATUS = WBANK(JW,IND,ND)
Input Parameters
JW YBOS Array name.
IND (Integer) The index of a previously
existing work bank length. Must be STATIC!!
ND (Integer) The work bank length.
Output Parameters
IND (Integer) The index to the work bank.
Function Value
WBANK (Integer) YESUCC Success
YEOVRF Insufficient Space
YERSUS Negative Bank Length
N.B.
1. The array name JW may be either the basic YBOS array
or a secondary YBOS array.
2. The variable IND should be preset to zero before
attempting to create a new work bank. If IND is
non-zero and does not point to an already existing
work bank it is considered to be zero. If, however
IND points to an already existing work bank then the
length of that work bank will be altered.
3. An attempt to extend a work bank while the work banks
are locked (via a call to WLOCK) may fail because
YBOS is unable to move work banks in this mode of
operation.
4. The Bank length ND should specify the length in
Integer words.
5. The YBOS option subprogram BOPTN may be used to
specify special options. This subprogram should be
called immediately prior to accessing WBANK, thus:-
STATUS = BOPTN(JW,OPTION)
STATUS = WBANK(JW,...)
where OPTION is an Integer having the following
meanings:-
OPTION = 0 Datawords preset to zero
OPTION >< 0 Datawords not preset
In the case where an already existing bank is
being extended then only the data words in the new
region will be preset to zero if appropriate.
6. If there is insufficient space, IND will be set to
zero and an error function value will be returned.
In this case the Application Program should attempt a
named bank garbage collection (remembering to
relocate all named banks afterwards) and retry. If
this fails, the Program should terminate cleanly.
7. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
16.2 WDATA - Return Data Index from Bank Index
This subprogram returns the Data Index for the Work Bank
having the specified Bank Index.
Calling Sequence
STATUS = WDATA(JW,IND,INDDAT)
Input Parameters
JW Secondary YBOS array name.
IND (Integer) Index to the bank (Bank Index).
Output Parameters
INDDAT (Integer) Index to the data (Data Index).
Function Value
WDATA (Integer) YESUCC Success
N.B.
1. WDATA performs no checks to determine whether IND
corresponds to a valid Bank. The results will be
undefined if IND does not correspond to a Bank or
corresponds to a Bank not conforming to the Bank Type
specifications.
2. INDDAT is defined such that JW(INDDAT) contains the
first dataword following the Bank Header.
3. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
the appropriate YBOS array, neither does it allow
BERROR to be used to determine the Error Code.
16.3 WDLEN - Return Length of Data
This subprogram returns the Length of the Data for the
Work Bank with the specified Bank Index.
Calling Sequence
STATUS = WDLEN(JW,IND,LENDAT)
Input Parameters
JW Secondary YBOS array name.
IND (Integer) Index to the bank (Bank Index).
Output Parameters
LENDAT (Integer) Length of the Data
Function Value
WDLEN (Integer) YESUCC Success
N.B.
1. WDLEN performs no checks to determine whether IND
corresponds to a valid Bank. The results will be
undefined if IND does not correspond to a Work Bank.
2. LENDAT is the Length of the data in Integer words.
It excludes the Bank Header words and any extent
remaining in the work bank data area.
3. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
the appropriate YBOS array, neither does it allow
BERROR to be used to determine the Error Code.
16.4 WDROP - Delete a Work Bank
This subprogram is used to drop (delete) an already
existing work bank.
Calling Sequence
STATUS = WDROP(JW,IND,NDIM)
Input Parameters
JW Array name.
IND (Integer) Index (or index array of
work bank(s).
NDIM (Integer) The size of the index array
(in Integer words).
Output Parameters
IND (Integer) Index (or index array) set
to zero.
Function Value
WDROP (Integer) YESUCC Success
N.B.
1. The array name JW may be either the basic YBOS array
or a secondary YBOS array.
2. This subprogram may be used to delete multiple work
banks by specifying the index as an array IND(NDIM),
where each array element is an index to an existing
work bank. For deletion of a single work bank then
IND need not be dimensioned but NDIM should be set to
1.
3. On return the index IND (or all elements in an index
array IND(NDIM)) will be set to zero.
4. A garbage collection is not performed immediately
after dropping work banks, but by other YBOS
subprograms if their space requirements cannot be
met. The user may perform an explicit garbage
collection by a call to WGARB.
5. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
16.5 WGARB - Work Bank Garbage Collection
This subprogram performs an explicit garbage collection
on just the work bank area of the specified YBOS array. Any
dropped work banks are identified and work banks are shuffled
towards increasing indices so as to remove holes. The indices
for any shuffled work banks are updated.
Calling Sequence
STATUS = WGARB(JW)
Input Parameters
JW YBOS array name
Output Parameters
None
Function Value
WGARB (Integer) YESUCC Success
N.B.
1. The array name JW may be either the basic YBOS array
or a secondary YBOS array.
2. The action of WGARB is not affected by whether the
work banks are locked or not (via WLOCK etc.). Thus
WGARB may cause movement of work banks if there are
previously dropped work banks to be discarded.
3. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
16.6 WLENG - Return Length of Bank
This subprogram returns the Length of the Bank (including
extended Bank Header words) Data for the Work Bank with the
specified Bank Index.
Calling Sequence
STATUS = WLENG(JW,IND,LENBNK)
Input Parameters
JW Secondary YBOS array name.
IND (Integer) Index to the bank (Bank Index).
Output Parameters
LENBNK (Integer) Length of the Bank
Function Value
WLENG (Integer) YESUCC Success
N.B.
1. WLENG performs no checks to determine whether IND
corresponds to a valid Work Bank. The results will
be undefined if IND does not correspond to a Bank.
2. LENBNK is the Length of the data area in Integer
words (excluding the Bank Header words). It includes
both the occupied data area and any unoccupied
extent.
3. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
the appropriate YBOS array, neither does it allow
BERROR to be used to determine the Error Code.
16.7 WLOCK - Lock Work Banks
This subprogram will cause the work banks to be locked
such that YBOS will not attempt to move them so as to gain
extra work space. While in this locked mode of operation work
banks may only be moved by an explicit WGARB.
Calling Sequence
STATUS = WLOCK(JW)
Input Parameters
JW Array name.
Output Parameters
None
Function Value
WLOCK (Integer) YESUCC Success
N.B.
1. The array name JW may be either the basic YBOS array
or a secondary YBOS array.
2. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
16.8 WPRNT - Print a Work Bank
This subprogram is used to print the specified work bank
or banks on the currently specified YBOS Print Unit. The
datawords are printed as Integer quantities.
Calling Sequence
STATUS = WPRNT(JW,IND,NDIM)
Input Parameters
JW Array name.
IND (Integer) Index (or index array of
work bank(s).
NDIM (Integer) The size of the index array
(in Integer words).
Output Parameters
None
Function Value
WPRNT (Integer) YESUCC Success
N.B.
1. The array name JW may be either the basic YBOS array
or a secondary YBOS array.
2. This subprogram may be used to print multiple work
banks by specifying the index as an array IND(NDIM),
where each array element is an index to an existing
work bank. For printing of a single work bank then
IND need not be dimensioned but NDIM should be set to
1.
3. The YBOS option subprogram BOPTN may be used to
specify special options. This subprogram should be
called immediately prior to accessing WPRNT, thus:-
STATUS = BOPTN(JW,OPTION)
STATUS = WPRNT(JW,...)
where OPTION is an Integer having the following
meanings:-
OPTION = 0 Print header and contents (default).
OPTION >< 0 Print header only
4. YBOS maintains a count of the number of banks that
have been printed. When this count reaches a preset
limit (default 100) then no further banks will be
printed. This limit may be modified from its default
setting of 100 by a call to subprogram BPLIMT.
5. The currently specified YBOS Print Unit (default 6)
may be modified by a call to subprogram BPUNIT.
6. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
16.9 WSETD - Set new Data Length of Work Bank
This subprogram allows the Length of the Data Area of the
specified Work Bank to be modified.
Calling Sequence
STATUS = WSETD(JW,IND,LENDAT)
Input Parameters
JW Secondary YBOS array name.
IND (Integer) Index to the bank (Bank Index).
LENDAT (Integer) Length of the Bank
Output Parameters
None
Function Value
WSETD (Integer) YESUCC Success
YEOVRF Insufficient Space
YEBKNG Negative Bank Length
N.B.
1. If the new data length exceeds the maximum length of
the work bank (as returned by a call to WDLEN) error
YEOVRF will be reported and no modification of the
bank will be performed. WBANK should be called in
order to extend the work bank if so desired.
2. If a negative data length is specified error YEBKNG
will be reported and no modification of the bank will
be performed.
3. This subprogram only returns the Error Code as the
function value. It does not set the 2nd element of
the appropriate YBOS array, neither does it allow
BERROR to be used to determine the Error Code.
16.10 WUNLK - Unlock Work Banks
This subprogram may be used to cancel the work bank
locking caused by a call to WLOCK. After a call to WUNLK,
YBOS is free to move work banks when necessary in an attempt
to gain enough work space.
Calling Sequence
STATUS = WUNLK(JW)
Input Parameters
JW Array name.
Output Parameters
None
Function Value
WUNLK (Integer) YESUCC Success
N.B.
1. The array name JW may be either the basic YBOS array
or a secondary YBOS array.
2. By default, work banks are unlocked.
3. A call to BVALON prior to using this routine will
result in named bank validation taking place upon
calling this routine. For example,
STATUS = BVALON(JW) (Turn validation on)
STATUS = .... (Call the routine)
STATUS = BVALOF(JW) (Turn validation off)
next page