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